Two systems share the name “memory.” Neither one is a promise.
Search “claude code memory” and you will land on people asking two different things: how CLAUDE.md works, and whether Claude Code remembers anything on its own. As of the current docs, the second question has a real answer. There is a second memory system now, separate from CLAUDE.md, and it writes itself.
I went and read exactly what it stores, what it skips, and what its own troubleshooting page admits about reliability. Then I checked that against what happens when a pull-based memory system meets a real codebase, because this site already measured that once.
Two systems, not one
Claude Code ships two things that both get called “memory,” and they do different jobs. CLAUDE.md is the file you write. Auto memory is notes Claude writes about you, without being asked, based on your corrections and the things you tell it not to forget.
Anthropic’s own docs put it plainly: CLAUDE.md holds “instructions and rules,” Auto memory holds “learnings and patterns.” Both load at the start of every session. Both, in the docs’ own words, are treated “as context, not enforced configuration.”
That second sentence is the whole story of why Claude Code ignores your CLAUDE.md, and it applies to Auto memory just as much. I am not re-running that argument here. Go read it if a written rule keeps getting skipped. This post is about the newer half: what Auto memory actually holds, and where that stops being enough.
What Auto memory actually stores
Auto memory writes four kinds of notes, and the type is recorded as a type field in the file’s own frontmatter:
user: your role, expertise, working preferencesfeedback: corrections you gave, approaches you confirmedproject: ongoing work, deadlines, decisions the code itself can’t showreference: where to find something outside the project, like a tracker or dashboard
It deliberately skips two categories: anything Claude can derive from the codebase (architecture, file paths, how a bug got fixed), and anything your CLAUDE.md already says. The idea is a memory that fills the gap CLAUDE.md leaves, not a second copy of it.
Where it lives is worth knowing if you’ve never looked: ~/.claude/projects/<project>/memory/, one MEMORY.md index plus a topic file per memory. Run /memory in a session to browse it. All of it is plain markdown, so nothing here is a black box you have to trust.
The part that changes how you should use it: only the first 200 lines or 25KB of MEMORY.md, whichever comes first, load at session start. Everything past that threshold does not load. Topic files are not loaded automatically either. Claude only opens one when it decides, mid-session, that it needs to. The index is a table of contents Claude has to choose to consult, not a payload that arrives whether it’s read or not.
One more scope detail that matters if you run parallel agents: Auto memory is shared across every worktree of the same repository, but it is machine-local, and it does not reach subagents unless the subagent is a fork of the main conversation. A freshly spawned worker agent, editing a file it has never seen, starts with none of it.
Same failure mode, and this site already measured it
Auto memory is a pull mechanism: it sits in a file, and something in the session has to decide to go read it. That’s a different claim from “it doesn’t exist.” It’s the claim that existing is not the same as arriving, and this site instrumented that gap once, on a different memory system built for exactly this job.
That instrument logged 368 files edited over two weeks of real work, and checked, for every single edit, whether stored memory ever spoke.
Files edited in the window
every file actually touched, the full scope of the test
Files where memory ever delivered anything
13%. The other 319 were edited with memory contributing nothing, not once
The full method, the two instrumentation bugs found along the way, and the 24.6% delivery rate on the edits that did have something stored: that’s the measured delivery-rate study, not repeated here.
A second post on this site ran the same question a different way: build the memory file by hand, then watch whether it gets read. The lessons kept arriving, the reading didn’t. 121 entries written in 18 days, then zero added across the next 55 commits, while seven real defects shipped in that stretch. Not because there was nothing left to learn. Because every lesson had a better home once one existed, and a file sitting there is not the same thing as a file consulted.
Neither study is about Auto memory specifically. Both are about the same shape of system: knowledge stored, retrieval left to whether the agent thinks to look. Auto memory has the same shape. Nothing about a feature writing its own notes changes whether reading them is optional.
What to put in memory, and what not to
The four Auto memory types are actually a decent sortation, once you attach stakes to each one:
| Kind of fact | Memory is fine | Move it to a hook or gate |
|---|---|---|
Your preferences, style, workflow (user, feedback) | Yes. Missed once, you just repeat it | n/a |
Where to find something (reference) | Yes. Low cost if skipped | n/a |
| A decision that must never be silently violated | No. A rule read on a schedule you don’t control isn’t a rule | PreToolUse hook, lint rule, or pre-commit check |
| Something the agent already got wrong once | Write it down anyway. It’s cheap and sometimes it helps | If it happens a second time, that’s the signal to stop trusting memory and build the gate |
The line is not “memory is bad.” It’s that memory has no floor. A hook runs on every edit, session one or session fifty, whether or not the agent is paying attention. A memory file runs on attention, and attention is exactly the thing that varies. Put low-stakes context in memory. Put anything that would hurt if it silently got skipped somewhere that can’t skip it.
Sources
- Claude Code docs, How Claude remembers your project: the CLAUDE.md vs. Auto memory split, the four memory types, the 200-line/25KB load limit, and the “context, not enforced configuration” line quoted above
- Claude Code docs, Hooks: the
PreToolUsehook that runs regardless of what Claude decides
Related:
- Your Coding Agent Has Memory. Does It Actually Arrive?: the full delivery-rate study this post pulls one figure from
- Claude Code Repeats the Same Mistakes: Memory Won’t Fix It: 121 entries written, then 55 commits that added nothing
- Why Claude Code Ignores Your CLAUDE.md (and the Fix): the written-instructions half of this same problem