File-Based Memory
Stores memory as plain text files — typically Markdown — that are loaded into the LLM's context at the start of each session. These files contain project context, instructions, conventions, and learned patterns. They're version-controllable, human-editable, and live alongside the code they describe.
This is the dominant memory pattern in coding agents.
Structure
Memory files are loaded in full into the system prompt or early context. The agent (or user) can also write back to these files, creating a feedback loop where the agent accumulates knowledge over time.
Mechanism
- Write Path
- Read Path
- Lifecycle
- User manually edits files (project conventions, preferences, instructions)
- Agent writes to memory files when it learns something worth persisting
- Files are organized hierarchically: global, per-project, per-directory
- Plain text format — Markdown is the standard
- Version controlled via git alongside the codebase
- Files are loaded in full into the system prompt at session start
- Hierarchical loading: global files first, then project-specific, then directory-specific
- No retrieval step — everything in the file is included
- File size is bounded by what fits in the context window alongside other content
- Created: Manually by user or automatically by agent
- Updated: Edited by user or agent as knowledge evolves
- Persists: Indefinitely — lives on the filesystem and in version control
- Shared: Committed to git, shared across the team
- Maintained: User or agent prunes outdated content to stay within size limits
Key Characteristics
- Human-readable and editable — plain Markdown anyone can modify
- Version controllable — lives in git, reviewable in PRs
- Team-shareable — committed to the repo, everyone gets the same context
- Loaded in full — no retrieval or ranking, everything is included
- Size-limited — file must fit in context alongside the actual task
When to Use
- You're building coding agents or developer tools
- Project conventions, patterns, and instructions need to persist across sessions
- Memory should be shared across team members via version control
- You want humans and agents to co-maintain the knowledge base
- The total memory content is small enough to load in full (typically under 200 lines)