What Claude Code Auto Memory Actually Saves
You correct Claude on how you want tests written. Nobody writes it down. A few days later, in a fresh session, the test comes out your way.
That is auto memory. It is a different system from the CLAUDE.md you spent an afternoon writing. Claude Code has two memory systems now, written by two different authors.
Two authors, two jobs
CLAUDE.md is yours. You write the instructions, and Claude reads them whenever a session opens. Auto memory is Claude's. It writes notes to itself while it works, and those load on open as well.
Treat the two as one system and you get the confusion people keep describing: rules go into a file, the file grows, and the agent still asks why you turned down the obvious approach. The file was never holding that. It holds what you remembered to write down.
What Claude writes down
Auto memory stores four kinds of notes, marked with a type field in each memory file:
user: your role, expertise, and working preferences.feedback: corrections you gave Claude and approaches you confirmed.project: ongoing work, deadlines, and decisions Claude cannot derive from the code or git history.reference: where to find things outside the project, such as an issue tracker or a dashboard.
Claude skips anything it can read from the codebase, and it skips anything your CLAUDE.md files already say. It also does not save something every session. It decides whether a fact would be useful in a later conversation, which means the write is a judgment call rather than a dump.
Where the files live
Each project gets a memory directory at ~/.claude/projects/<project>/memory/. The project path comes from the git repository, so every worktree and subdirectory inside one repo shares a single directory. MEMORY.md is an index with one line per memory, and each memory gets its own topic file beside it. The files are plain markdown, so you can open, edit, or delete any of them yourself, and /memory browses them from inside a session.
Two details about that directory matter more than the path. It is machine-local, so your laptop and your desktop each keep their own copy. And it outlives the transcripts: Claude Code deletes old session transcripts after its retention period, and the memory directory is excluded from that sweep. Transcripts get cleaned up, the notes stay. That is the intended role split, with memory as the durable layer.
Auto memory is on by default in local sessions. To check or turn it off, open /memory in a session and use the toggle, which writes autoMemoryEnabled to ~/.claude/settings.json. For a single project, set autoMemoryEnabled to false in that project's settings. For a machine-wide off switch, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
The 200 line ceiling is the design
Every conversation opens with the first 200 lines of MEMORY.md, or the first 25KB, whichever comes first. Nothing past that threshold loads.
When the file nears a limit, Claude Code reminds Claude to shorten it: one line per entry, detail moved into topic files, stale entries merged or dropped. When it goes over, the write still succeeds but Claude Code returns an error telling Claude to rewrite the index, because everything past the cap is dropped on the next load. The topic files are not loaded at startup at all. Claude reads them on demand, with normal file tools, when it needs the detail.
That is a deliberate shape. The index stays small enough to be read every session, and detail gets fetched only when it is relevant. A memory built that way holds pointers to recurring facts. It is not a log of the work.
Where it stops
The edges are worth knowing before you lean on it.
Per repository. The directory is keyed to the git repo. The index your frontend repo loads does not contain the decisions from your API repo.
Per machine. Nothing syncs. A second laptop or a cloud task starts from its own directory.
Per agent. The main conversation's auto memory does not load into a subagent, with the exception of a fork, which inherits the parent conversation. A subagent with memory enabled keeps a separate directory.
None of that is a defect. A local note-taking system behaves like a local note-taking system, and the trade buys speed and privacy.
The limit that shows up in daily work is narrower. Auto memory is good at how you work and thin on what the work was. The project type can hold a deadline and a decision, but the index is capped, so the entry is a line. A line is enough to remind you a decision exists, and not enough to carry the reasoning, the option you turned down, and the constraint that made the call right.
What to do with the split
Keep CLAUDE.md for rules you would otherwise retype. Let auto memory handle preferences and stable project facts. Then put the work record somewhere that is not tied to one repository or one machine.
MemoryRouter does that job for Claude Code. Hooks recall relevant memory before your prompt from a vault stored on the server, then capture one prompt and one final answer from each completed turn. Recall searches the whole vault and ranks by relevance, so a decision captured in one repository is available when you open another. The same vault is reachable from Codex, OpenClaw, and the hosted connectors. The Claude Code documentation covers install and verification, and the Claude Code page is the short version.
Two boundaries, stated plainly. Capture starts at install, so it does not backfill old sessions. If one project should stay out of the vault, an empty .memoryrouterignore file turns capture off there.
The test
Pick a decision you made two weeks ago in a different repository, one where you rejected an approach for a specific reason. Open a session in another repo and ask why that approach was rejected.
A guess means you are asking a per-repo index to carry cross-repo history. Start a 14-day trial and give that job to something built for it. It costs $20 a month after the trial.