Claude Code auto memory, and where it stops.

What auto memory actually is

Claude Code has two memory systems that both load at the start of every session, and the difference between them is who does the writing. CLAUDE.md is instructions you write. Auto memory is notes Claude writes for itself, based on your corrections and preferences, without being asked.

Claude saves four kinds of note, recorded as a type field in each file's frontmatter:

• user — your role, expertise, and working preferences.
• feedback — corrections you gave, and approaches you confirmed.
• project — ongoing work, deadlines and decisions it can't derive from the code or git history.
• reference — where to find things outside the project, like an issue tracker or a dashboard.

It deliberately skips anything derivable from the codebase — architecture, file paths, the fix for a bug it just debugged — and anything your CLAUDE.md already says. It also doesn't save every session. It writes when it judges something would be useful later.

Where the files live

Each project gets its own directory:

~/.claude/projects/<project>/memory/
├── MEMORY.md           # index, one line per memory
├── user_role.md        # one memory
├── feedback_testing.md # one memory
└── ...

The <project> segment is derived from the git repository, so every worktree and subdirectory of the same repo shares one memory directory. Outside a git repo it falls back to the project root. You can move it with the autoMemoryDirectory setting, and browse it from inside a session with /memory.

Two things about loading are worth knowing, because they explain most of the surprise people have with it. Only the first 200 lines or 25KB of MEMORY.md load at session start, whichever comes first — anything past that is silently not there. And topic files don't load at startup at all. Claude reads them on demand with its normal file tools when it decides it needs them. MEMORY.md is an index, and it has to stay an index.

It is better than people expect

It is worth saying plainly, because the rest of this page is about limits: auto memory solves a real problem and it solves it with no effort from you. The single most common complaint about coding agents — that you correct the same thing every session — is exactly what the feedback type is for. If you work alone, on one repository, on one machine, with Claude Code and nothing else, auto memory plus a tidy CLAUDE.md is a complete answer and you do not need anything on this website.

That is not a rhetorical concession. It is most people.

The four boundaries

Each of these is a design decision rather than a defect. They only matter when your setup crosses one.

1. It is machine-local

The files are not shared across machines or cloud environments. A laptop, a desktop and a cloud dev box working on the same repository accumulate three separate memories that never meet. Nothing syncs them, and there is no team view — a colleague working on the identical codebase starts from nothing.

2. It is per-repository

Because the directory key comes from the git repo, memory does not travel between repositories. That is correct behaviour for most work and wrong for the case where a decision spans a service and its client, or where the same architectural constraint governs four repos in an organisation. Learning it in one teaches the others nothing.

3. It is Claude Code only

Auto memory lives in Claude Code's own directory, in Claude Code's own format. Codex and Cursor have no path to it, and their own equivalents are equally private. If you use more than one agent on a project — which is increasingly normal — each one learns separately and none of them benefit from what the others found out.

4. The index has a ceiling

The 200-line, 25KB read limit on MEMORY.md is a real bound on how much can be present at the start of a session. Claude Code actively pushes back against exceeding it: as the file approaches a limit it reminds Claude to shorten the index and move detail into topic files, and past the limit it returns an error telling Claude to rewrite the index, because everything beyond it is dropped on the next load. Detail is meant to live in topic files that load on demand.

This is a sensible design for a curated index. It is not a design for hundreds of accumulated findings that you want to search rather than pre-load.

Auto memory and project memory side by side

They are not alternatives

The framing that gets this wrong is treating it as a choice. Auto memory is unbeatable at the thing it does: capturing your preferences and corrections with zero effort, on the machine where you gave them. It should stay on.

What it is not built to be is the durable, shared, searchable record of a project — the reason a constraint exists, the approach that was tried in March and failed, the decision a teammate made while you were on holiday. That record needs to outlive one machine, one repository and one tool, which is precisely the set of things auto memory scopes itself to.

A workable split: let auto memory hold how you like to work, keep CLAUDE.md short and about how to behave in this repo, and put what the team has learned somewhere every agent and every person can search. That last one is what an MCP memory server is for.

Turning it off, if you want to

Auto memory is on by default. There are three ways to change that: toggle it from /memory in a session, which writes autoMemoryEnabled to your user settings; set autoMemoryEnabled to false in one project's settings to disable it there only; or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in the environment.

Most people shouldn't. If the worry is what it has recorded, the better move is to look: the files are plain markdown you can read, edit or delete, and /memory opens the folder.

Related reading

• Persistent memory for Claude Code — the full picture across sessions.
• How to make Claude Code remember context across sessions — the five mechanisms and how they layer.
• CLAUDE.md vs persistent project memory — what belongs in each.
• Sharing context between Claude Code and Codex — the cross-tool boundary in detail.

FAQ

Where does Claude Code store auto memory?

In a per-project directory at ~/.claude/projects/<project>/memory/. The <project> path is derived from the git repository, so every worktree and subdirectory of the same repo shares one directory. It contains a MEMORY.md index plus one markdown file per topic. You can point it somewhere else with the autoMemoryDirectory setting, and browse it from a session with /memory.

Is Claude Code auto memory on by default?

Yes. Auto memory is on by default. You can toggle it from /memory in a session, set autoMemoryEnabled to false in settings.json to turn it off for one project, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to disable it by environment variable.

What is the difference between CLAUDE.md and auto memory?

You write CLAUDE.md; Claude writes auto memory. CLAUDE.md holds instructions and rules you want followed. Auto memory holds learnings Claude picks up from your corrections and preferences. Both load at the start of every session, and both are context rather than enforced configuration.

Does Claude Code auto memory sync across machines or teams?

No. Auto memory is machine-local. The files are not shared across machines or cloud environments, and there is no team view. A laptop and a cloud dev box working on the same repository build two separate memories that never meet.

Can Codex or Cursor read Claude Code's auto memory?

No. Auto memory is a Claude Code feature stored in Claude Code's own directory. Another agent has no path to it. If you use more than one coding agent on the same project, anything one of them learns stays invisible to the others unless it is written somewhere both can read.

How much of MEMORY.md is loaded into a session?

The first 200 lines or the first 25KB, whichever comes first. Anything past that is not loaded at session start. Topic files are not loaded at startup at all; Claude reads them on demand when it needs them, so the index is the part that has to stay short.