Claude Code auto memory: where it lives, what loads, and how to check it worked

Two different things get called Claude Code memory. A CLAUDE.md file is an instruction file you write and keep in the repository. Auto memory is a set of notes Claude writes for itself as it works: a preference you corrected, a project fact that is not in the code, a pointer to an issue tracker. The notes live on your machine, in a folder tied to the project. At the start of a session, Claude Code loads only the index of that folder. The rest waits on disk until Claude asks for it.

That split explains most surprises. A note can exist and still not be in the session. An index can be present and still be clipped. A session can be pointed at a different store entirely and look as if nothing was ever saved.

Checked against each tool's documentation on 26 October 2026.

Status, 26 October 2026: Claude Code still has no in-session receipt that says whether the auto memory index loaded whole, was truncated, or was not loaded at all. That is an open issue (#82056). Sessions in git worktrees are also reported to load the project's memory inconsistently (#81833). The checks below work whether or not those are fixed in your version.

The two stores, side by side#

Both are context, not configuration. Claude reads them and tries to follow them, but neither is enforced. The memory documentation says to use a PreToolUse hook when an action must be blocked regardless of what Claude decides. A hook is a command or request Claude Code runs at a lifecycle event, such as before a tool call. A permission rule is the other enforcement layer (permissions): it allows, asks about, or denies a tool or command, and Claude Code enforces it rather than the model.

Where the files live#

Each project gets a memory directory at ~/.claude/projects/<project>/memory/. The <project> part is derived from the git repository, so the docs say every worktree and every subdirectory of one repository shares a single directory. Outside a git repository, the project root is used instead.

Auto memory is keyed to the repository. Session transcripts, the saved records of conversations, are keyed to the working directory. That is why worktrees share auto memory but have separate entries in the session picker.

The folder has one index and one file per memory:

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per memory, loaded into every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...                 # Any other topic files Claude creates

MEMORY.md is the index. It tells Claude what exists and where the detail lives. Each topic file holds one memory. If a memory file begins with YAML frontmatter, Claude Code records the last write time in a modified field, so you can see how current the fact is.

The store is machine-local. The docs say it is not shared across machines or cloud environments. Session transcripts are deleted after cleanupPeriodDays (30 days by default), but the memory directory is excluded from that sweep. Notes stay until you or Claude edit or delete them.

What loads at the start of a session#

Claude Code loads the first 200 lines of MEMORY.md, or the first 25 KB, whichever comes first. Nothing else in the folder loads at launch. Topic files are read on demand, when Claude needs one.

That makes the index a map with a hard edge. If a memory's one-line entry is past the cut, Claude does not know the topic file exists and will not go looking for it. The store can be complete on disk and incomplete in the session.

Claude Code measures the index after Claude writes to it. If the file is near a limit, the docs say Claude Code reminds Claude to shorten it. If it is over a limit, the write still succeeds, but Claude gets an error telling it to rewrite the index, because everything past the limit is dropped on the next load. The docs describe that notice as a message to Claude. They do not describe a warning in the CLI. A report says the reminder appeared only in the model's context, after a write, and never in the terminal (#82056).

Auto memory is re-injected after compaction, along with the project-root CLAUDE.md. Compaction is the pass that replaces older turns with a summary when the context window, the working text the model can see at once, is nearly full. A summary does not erase the memory store.

Check 1: Is auto memory on, and which store is it using?#

Open /memory. It lists your instruction files and memory locations, has the auto memory toggle, and offers to open the auto memory folder. The toggle writes autoMemoryEnabled to ~/.claude/settings.json.

Auto memory is on by default in local sessions. The docs say it is off by default in self-hosted environments. You can disable it for one project with autoMemoryEnabled: false in that project's settings, or everywhere with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

One exception catches people running nested sessions: if you turn auto memory off in a background session, or in a session that another Claude Code session started, the toggle cannot turn it back on. It reads "off · can't be turned on here". Run claude directly in a terminal to change it.

/memory also shows the path it opened. If you launched from a worktree and the path points at the main checkout, that is the shared store the docs describe. If the folder is missing, compare the path with the project you think you are in. If the folder exists and MEMORY.md is there, but the session acts as if it has no memory, that matches the inconsistent worktree loading reported in #81833.

Check 2: Did the index fit?#

Open the auto memory folder from /memory, then measure the index. Use the path /memory opened for <project> (or run ls ~/.claude/projects/ to list the project directories on disk):

wc -l ~/.claude/projects/<project>/memory/MEMORY.md
wc -c ~/.claude/projects/<project>/memory/MEMORY.md

Compare the result with 200 lines and 25 KB. If the file is over either limit, the tail is not in the next session, even though the file still contains it. Keep the index to one line per memory and move detail into topic files. That is what the 200-line design expects.

The same folder is the place to look for stale notes. Open a topic file, read its modified timestamp if it has one, and edit or delete it. Auto memory is plain markdown. There is no database to migrate and no separate correction command.

Check 3: What actually reached this session?#

Run /context. It shows a live breakdown of the context window and lists the CLAUDE.md and auto memory files that loaded. If the memory file is absent there, it did not load, and asking the model to remember harder will not help. It cannot recall a note that is not in its context.

The second check is behavioural. Ask, without letting the model use a tool: "Quote the first line of my auto memory index. If you do not have it in context, answer NOT LOADED." A model with the index loaded can quote it. A model without it may read the file and answer anyway, so say "without reading any files" and watch for a tool call. If it says NOT LOADED, believe it.

One caveat about switching sessions. In a report measured on v2.1.283, /resume <id> inside a running session kept the CLAUDE.md and MEMORY.md copy that the process had loaded earlier, even after the files changed on disk. claude --resume <id> from the shell, or /clear before resuming, reloaded both. That is an open issue (#97722, open, updated 26 October 2026). If you switched sessions to pick up a memory change, check /context again rather than assuming the new file is in front of the model. The resume guide covers the command and picker side.

Why it can look as if nothing was saved#

Claude decides what is worth remembering. The docs say it skips anything it can derive from the codebase, and anything a CLAUDE.md file already says, and that it does not save something every session. A session that ends without a memory write is normal.

The visible signs are the "Saved N memories" and "Recalled N memories" messages. They refer to files in the project memory folder, not to a hidden model state. If you need a decision kept, say so and check the file, or put it in CLAUDE.md or a handoff file instead.

Three failures look the same from inside a session:

• The note was never written, because Claude did not judge it worth saving.
• The note was written to another project's store, because the session's project path differed.
• The note exists, but its index line is past the 200-line or 25 KB cut, or the index did not load.

The checks above separate them. /memory shows the store it is using. Compare that path with the project you expected, and browse the folder: that separates a note that was never written from one written elsewhere. The line and byte counts answer the third.

Make it more reliable#

• Keep standing rules in CLAUDE.md. Auto memory is for learnings and preferences. The docs put instructions, workflows, and architecture in CLAUDE.md. A rule that must hold every time is better in a file that loads at launch, or in a hook or permission rule that does not depend on the model.
• Keep MEMORY.md short. One line per memory, detail in topic files. A smaller index is less likely to be clipped and leaves more room for the work.
• Correct the file, not the chat. Edit or delete the topic file through /memory. The next session reads the folder from disk. A correction typed into a conversation is gone with that conversation.
• Check after a switch. A new session, /clear, or claude --resume re-reads the index. An in-session /resume may not.
• Treat it as machine-local. If the next session is on another machine, auto memory will not be there. Use a file in the repository or a shared store. The sync guide covers the options.

Where to go next#

For the rest of the set, see the Claude Code guides hub.

• Why your nested CLAUDE.md or path-scoped rule never loaded covers the other half of Claude Code's instruction loading.
• What a Claude Code subagent can and can't see explains why the main session's memory does not follow a subagent.
• How to check what your coding agent actually remembered separates capture, load, and use across both agents.
• Persistent memory for Claude Code and Codex compares the wider set of mechanisms.
• Context compaction covers what a long session drops, and what survives.