Auto memory — what Claude writes about you, and where it lives

Six weeks ago you typed "always use pnpm, not npm" into a session. Claude has used pnpm ever since, so you stopped thinking about it. This morning a teammate cloned the same repository, asked for the same task, and got npm install.

Nothing is broken. The instruction was saved — somewhere you did not choose, in a directory that is not in the repository, on one machine. Lessons 6.1 through 6.3 were about the files you write. This one is the other system.

Two systems, one table

Use CLAUDE.md files when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort. — How Claude remembers your project

Read the Scope row twice:

Both load at the start of every conversation, and both are guidance rather than enforcement — the point Lesson 6.2 made about CLAUDE.md applies here unchanged. To block an action regardless of what Claude decides, the docs send you to a PreToolUse hook, not to either memory system.

The four kinds of note

As it works, Claude saves four kinds of notes for itself. Claude records the kind as a type field in the memory file's frontmatter: — How Claude remembers your project

The exclusions matter as much as the list. Claude skips anything it can derive from the codebase — architecture, file paths, debugging fixes — and anything your CLAUDE.md files already say. Both exclusions come down to one rule: context spent on something Claude can read out of the repository, or already received from a CLAUDE.md, buys nothing. Nor is this a per-session journal. Claude does not save something every session; it decides what is worth remembering based on whether the information would be useful in a future conversation.

Where it lives, and what shares it

Each project gets a directory at ~/.claude/projects/, then the project key, then memory/. The project key is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.

That is a different sharing rule from every file in the last three lessons: a nested CLAUDE.md loads only when Claude reads a file in its own subdirectory, while auto memory is scoped to the repository and follows you into every worktree of it.

You can move the directory: autoMemoryDirectory in settings.json takes an absolute path or one starting with ~/, and is read from any settings scope — user, project, local, policy, or --settings.

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

It also does not age out. Claude Code deletes old session transcripts after the cleanupPeriodDays period but excludes the memory files from that sweep; MEMORY.md and topic files stay until you or Claude edits or deletes them. The transcripts in Lesson 3.5 expire. These do not.

With one qualification: that exemption only became airtight in v2.1.228. Before it, the retention sweep treated folders inside the memory directory as session data and could delete old files beneath them (Explore the .claude directory). MEMORY.md and the topic files beside it sit at the top level and were covered either way — which is to say the flat layout the docs describe, an index plus topic files and nothing nested, is the one that never needed the fix. The directory as a whole goes only after it has been empty for the entire retention period.

The index and the topic files

The directory is not one file. It is an index plus 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

Only the index is loaded at startup, and only the beginning of it:

The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start. — How Claude remembers your project

Topic files such as user_role.md or feedback_testing.md are not loaded at startup at all. Claude reads them on demand with its standard file tools when it needs the information — which is why the index carries one line per memory saying what is stored where. The index is a table of contents that fits in the budget; the detail is a file read away, paid for only when it is used. And when the session compacts, auto memory is on the re-injected half of Lesson 3.2's table: it comes back from disk, because it is on disk.

When the index outgrows its limit

Writing past the limit does not fail loudly. The write succeeds — and then everything past 200 lines or 25KB is dropped every time the index is loaded, so the entries at the end are invisible to the next session.

What you get instead is a message you were never the audience for. Claude Code measures the index after each write and, when the write leaves it over a limit, returns an error telling Claude to rewrite it — the documented example asks for under 140 lines, comfortably clear of the ceiling. That error goes to Claude rather than to a banner in your terminal, so you may notice it only in the transcript; a write that lands near a limit without crossing it gets a milder reminder to compact the index instead (Errors). Only the content that actually loads is measured — frontmatter and block-level HTML comments are stripped first. Before v2.1.210 there was no write-time signal at all. There is one now, and it is still not addressed to you, which is why the remedy below is worth holding as a habit rather than waiting for a warning.

The documented remedy is the shape of the file, not its ambition: keep one line per entry, move detail into topic files, and merge or drop stale entries.

Auditing, editing, turning it off

Everything in the directory is plain markdown you can edit or delete at any time. /memory browses and opens the files from inside a session, including an option to open the auto memory folder; /context tells you what actually loaded into the session you are in. That division — /memory for where files could be, /context for what is really there — is Lesson 6.5's, and it holds here too.

While a session runs, the interface says when the system is active: messages like Saved 2 memories or Recalled 2 memories mean Claude is updating or reading that directory right now.

Turning it off — and back on — has three layers, and the environment variable outranks the settings key:

The env var takes precedence over the settings key for one session, in either direction — the 0 row is the half people miss, and it is how you get memory back in a context that switched it off for you. --safe-mode also starts a session without auto memory, alongside CLAUDE.md, skills and hooks; that is Lesson 6.5's bisecting tool, not a setting you leave on.

Steering what gets written

Here is the honest boundary of this system. You cannot hand Claude a policy describing which categories to save and which to leave alone. Beyond the built-in skip rules — nothing derivable from the codebase, nothing your CLAUDE.md already says — there is no documented knob for what gets recorded. What you have is five levers, all named already: ask ("remember that the API tests require a local Redis instance"), redirect ("add this to CLAUDE.md"), edit or delete the markdown, toggle autoMemoryEnabled, relocate with autoMemoryDirectory. The third is the one that does the real work: audit what is there rather than trying to govern what goes in.

The second is the trap of this lesson. Saying "remember we always use pnpm" feels like setting a team convention and sets nothing of the kind:

When you ask Claude to remember something, like "always use pnpm, not npm" … Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via /memory. — How Claude remembers your project

A convention the team must share is a CLAUDE.md edit, and you have to ask for that one by name.

The line to carry out of here

Auto memory is the only part of your setup that writes itself, and it never leaves the machine that wrote it. Both halves are easy to forget at the wrong moment: the first when you wonder why Claude knows something you never wrote down, the second when you wonder why nobody else does.