Every Claude Code session starts with an empty context window. Auto memory is one of the two ways knowledge carries over between sessions: notes Claude writes for itself as it works, loaded back at the start of the next session. The other way is CLAUDE.md, which you write.
How it works
As it works, Claude saves notes of four kinds, recorded as a type in each memory file’s frontmatter:
user: your role, expertise and working preferences;feedback: corrections you gave and approaches you confirmed;project: ongoing work, deadlines and decisions that cannot be read from the code or git history;reference: where to find things outside the project, such as an issue tracker or a dashboard.
It skips what it can work out from the codebase (architecture, file paths) and what your CLAUDE.md already says, and it does not save something every session.
The notes live on your machine in ~/.claude/projects/<project>/memory/. The <project> part comes from the git repository, so all worktrees and subdirectories of one repo share one memory directory. The directory holds an index, MEMORY.md, with one line per memory, plus one topic file per memory.
At the start of every session, the first 200 lines or 25 KB of MEMORY.md (whichever comes first) are loaded into the context. Topic files are not loaded upfront; Claude reads them when it needs them. When you see “Saved 2 memories” or “Recalled 2 memories” in the interface, Claude is writing to or reading from that directory.
CLAUDE.md vs auto memory
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Instructions and rules | Learnings and patterns |
| Scope | Project, user or organization | One repository, shared across its worktrees |
| Loaded | Every session | Every session, first 200 lines or 25 KB of MEMORY.md |
| Good for | Coding standards, workflows, architecture | Your preferences, corrections, context the code cannot show |
Both are context, not enforced configuration: Claude follows them, but nothing forces it to. To block an action no matter what, use a hook.
What to do about it
- Look at it. Run
/memoryto list your CLAUDE.md files and memory locations, open the auto memory folder, and toggle auto memory on or off. The files are plain markdown; edit or delete anything. - Ask for it. “Remember that the API tests need a local Redis” goes to auto memory. “Add this to CLAUDE.md” goes to CLAUDE.md instead. Rules that must always hold belong in CLAUDE.md.
- Turn it off for a project with
"autoMemoryEnabled": falsein that project’s settings, or everywhere withCLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
Gotchas
- It costs context. The loaded part of
MEMORY.mdsits in every session’s context, next to CLAUDE.md. Claude Code reminds Claude to keep the index short and move detail into topic files. - Machine-local. Memory is not shared across machines or cloud environments.
- Not loaded into subagents. A subagent does not get the main conversation’s auto memory, except a fork, which copies the parent conversation.
- Notes can go stale. Claude Code adds a
modifiedtimestamp to memory files with frontmatter so you and Claude can see how current a note is.
Related
- Claude projects and memory: the same idea in the Claude chat apps.
- Context window: where the loaded memory ends up.
- Managing context: keeping CLAUDE.md and memory lean.
- One task per session: why memory makes fresh sessions cheap.