Claude Code quietly shipped something I've been waiting for: agents that learn between sessions. Not "memory" in the chatbot sense — actual persistent knowledge stores that agents write to disk and carry forward into future work.
There are two flavors. Auto memory is for the main Claude session itself. Subagent memory is for individual subagents you define. Both use the same architecture under the hood, and both are worth understanding if you're building anything with agents that needs to get smarter over time.
Auto memory is a persistent directory where Claude records patterns, insights, and project-specific knowledge as it works. This is different from CLAUDE.md files (which are instructions you write for Claude). Auto memory is notes Claude writes for itself.
The stuff it captures is practical: build commands, test conventions, debugging solutions, architecture notes, your preferences. Things the agent discovers through experience rather than things you tell it upfront.
Each project gets its own memory directory at ~/.claude/projects/<project>/memory/. The <project> path is derived from the git repo root, so all subdirectories within the same repo share one memory directory. (Git worktrees get separate ones. Outside a git repo, it falls back to the working directory.)
The structure looks like this:
~/.claude/projects/<project>/memory/
├── MEMORY.md # The entrypoint — loaded every session
├── debugging.md # Detailed debugging patterns
├── api-conventions.md # API design decisions
└── ... # Whatever topic files Claude creates
Here's the key constraint: only the first 200 lines of MEMORY.md get injected into Claude's system prompt at session start. Everything beyond that? Not loaded automatically. Claude is instructed to keep MEMORY.md concise by moving detailed notes into separate topic files — debugging.md, patterns.md, whatever makes sense.
Those topic files aren't loaded at startup either. Claude reads them on demand using standard file tools when it needs deeper context. So MEMORY.md acts as an index, and the topic files are the detailed reference material.
This means the agent has to be an editor, not just an appender. That's a design choice worth paying attention to.
Auto memory files are just markdown — you can edit them directly, or use /memory to open the file selector. You can also just tell Claude:
"remember that we use pnpm, not npm"
"save to memory that the API tests require a local Redis instance"
Auto memory is still in gradual rollout. You can force it on or off:
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 # Force ON
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # Force OFFNote the double-negative: DISABLE=0 means "don't disable." When neither is set, you're at the mercy of the rollout.
This is where it gets interesting. The memory frontmatter key gives any custom subagent its own persistent directory that survives across conversations. The subagent builds up knowledge over time — codebase patterns, recurring issues, architectural decisions — and that knowledge loads into its context the next time it's invoked.
Drop memory into the YAML frontmatter:
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---
You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.It also works with CLI-defined agents:
claude --agents '{
"code-reviewer": {
"description": "Reviews code for quality and best practices",
"prompt": "You are a code reviewer...",
"memory": "user"
}
}'| Scope | Path | Git-committable? | When to use |
|---|---|---|---|
user |
~/.claude/agent-memory/<agent-name>/ |
No | Learnings that apply across all your projects |
project |
.claude/agent-memory/<agent-name>/ |
Yes | Project-specific knowledge, shareable with team |
local |
.claude/agent-memory-local/<agent-name>/ |
No | Project-specific, but personal |
The docs recommend user as the default. That makes sense for most cases — a code reviewer that learns your style should carry that everywhere. Use project when the knowledge is codebase-specific and you want your team to benefit from it. Use local for the same, minus the version control.
The project scope is the most novel piece here. A subagent's accumulated knowledge about your specific codebase gets committed alongside the code. New contributors (human or agent) inherit that institutional knowledge on their first session.
Three things change automatically:
- The subagent's system prompt gets instructions for reading and writing to the memory directory
- The first 200 lines of
MEMORY.mdin that directory are loaded into context at startup (same 200-line constraint as auto memory) - Read, Write, and Edit tools are auto-enabled so the agent can manage its memory files
The subagent then follows the same pattern: MEMORY.md as a concise index, topic files for detailed knowledge, on-demand reads when it needs more.
The agent will write something to memory by default, but the quality depends heavily on what you tell it to do. A few patterns worth trying:
Give the memory structure. Don't let the agent free-write into a junk drawer. Define sections in the system prompt:
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---
You are a code reviewer. Maintain your memory with these sections:
## MEMORY.md structure
- **Patterns**: Recurring code patterns and conventions in this codebase
- **Known Issues**: Tech debt and recurring problems
- **Architecture**: Key decisions and their rationale
- **Style**: Codebase-specific style beyond what linting catches
Move detailed notes into topic files. Keep MEMORY.md as an index under 200 lines.Ask it to check memory before starting work: "Review this PR, and check your memory for patterns you've seen before."
Ask it to update memory after finishing: "Now that you're done, save what you learned to your memory."
Over time, the loop compounds. The agent gets better at reviewing this specific codebase because it's building up a knowledge base from every review it does.
| Auto Memory | Subagent Memory | |
|---|---|---|
| Who writes it | Main Claude session | Individual subagents |
| Scope options | Per-project, user-scoped only | user, project, or local |
| Storage root | ~/.claude/projects/<project>/memory/ |
Varies by scope |
| Startup loading | First 200 lines of MEMORY.md | First 200 lines of MEMORY.md |
| Topic files | On-demand | On-demand |
| Git-committable | No | Yes (project scope) |
| Control mechanism | CLAUDE_CODE_DISABLE_AUTO_MEMORY env var |
memory frontmatter key per agent |
| Curation | Agent self-curates | Agent self-curates |
Same architecture, different scoping. The biggest difference: subagent memory can be committed to version control and shared with your team. Auto memory stays local to you.
The 200-line curation constraint is the part I'm most curious about. The agent has to decide what's worth keeping — and there's no built-in quality control beyond the system prompt you write. Over enough sessions, does MEMORY.md stay sharp or does it drift toward noise?
The project-scoped subagent memory is the feature with the most potential. When agents are learning about your codebase and committing those learnings alongside the code, you get a flywheel: better context → better agent work → better learnings → better context. But you also get a new kind of code review: is the agent's memory accurate? Is it drifting? Are different team members' agents converging on the same insights, or diverging in ways that signal gaps in your documentation?
That's the piece I want to explore next — what tooling could sit on top of these primitives to close the loop between agent memory and project-level knowledge.