Auto memory is a directory Claude Code writes for itself, holding notes it decided were worth keeping: build commands, debugging insights, architecture notes, workflow habits. You do not author it, and it is on by default.
MEMORY.md is the index in that directory. Topic files are any other markdown beside it (debugging.md, api-conventions.md) - unlimited in size, and read on demand rather than at startup.
Where it lives and what loads
| Property | Auto memory | CLAUDE.md |
|---|---|---|
| Who writes it | Claude | You |
| Location | ~/.claude/projects/<project>/memory/ | Your repo |
| In version control | No, machine-local | Yes, at project scope |
| Loaded per session | First 200 lines or 25KB of MEMORY.md | In full, any length |
| Scope | Per repository, shared across worktrees | Project, user, or org |
Two consequences follow from that table. <project> is derived from the git repository, not the working directory, so every worktree and subdirectory of one repo shares a single store. And because it is machine-local and never synced, a teammate on the same CLAUDE.md runs a differently shaped agent.
The index is the part that silently fails: everything past 200 lines or 25KB stops loading, so a bloated MEMORY.md drops its own tail. A write that lands near the limit gets a reminder to compact; a write that lands over it returns an explicit error. It is one line item in the startup tax you pay before typing.
/memory # browse the store and open a file
/memory trim # index over its read limit? drop old entries
/context # what actually loaded this sessionSeparate stores
Subagents do not inherit the main conversation’s auto memory - see subagent context isolation. A fork is the exception, since it duplicates the current conversation rather than starting fresh. A subagent declaring memory: user | project | local gets its own directory (~/.claude/agent-memory/<name>/, .claude/agent-memory/<name>/, or .claude/agent-memory-local/<name>/) under the same index rule.
Turning it off
{
"autoMemoryEnabled": false,
"autoMemoryDirectory": "~/my-memory-dir"
}Both settings work at user or project scope; CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 disables it for one invocation. At project scope autoMemoryDirectory is honored only after you accept the workspace trust dialog, the same gate that governs hooks. Disabling auto memory also disables subagent memory - the memory field becomes a no-op.
Measured, a rule planted in auto memory held 3/3 when nothing contradicted it and 0/3 when the prompt did - the same score the identical rule posted in CLAUDE.md. It is a knowledge layer, not an enforcement one: knowledge vs rule. Full audit walkthrough and the benchmark: Claude follows its own memory until you contradict it.