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

• 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

Read Path

• 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

Lifecycle

• 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)