What it actually does

As Claude works it saves notes to itself, filed under four kinds — your role and preferences, corrections you gave it, ongoing project context, and pointers to things outside the repository. They live in ~/.claude/projects/<project>/memory/ as plain markdown: a MEMORY.md index plus one file per topic. The index loads at the start of every session; the topic files are read on demand.

Two design choices are worth calling out, because both are correct and both are limits. Claude deliberately skips anything it can derive from the codebase, and it skips anything CLAUDE.md already says. So auto memory is, by construction, the residue: what is true about working with you that is written down nowhere else.

The four boundaries

One repository

Each project gets its own directory, keyed off the git repository. Worktrees of the same repo share it; two repositories never do. A convention you established in one service does not follow you to the next.

One machine

The documentation is explicit that files are not shared across machines or cloud environments. A laptop and a desktop accumulate two different memories of the same person.

One tool

It is Claude Code's, and only Claude Code's. Nothing you did in Codex, Cursor, Gemini CLI, OpenCode or Antigravity is in it, and nothing in it is visible to them.

What Claude chose to write

Claude does not save something every session; it judges what would be useful later. That judgement is usually good, and it is still a filter applied at write time, before anyone knows what will be needed.

The boundary that costs the most

The last one deserves its own paragraph, because it is the difference between two kinds of product rather than a rough edge on one.

Auto memory is a written record. A session index is a recovered one. A note says "prefers the direct connection". The transcript contains the afternoon that produced it: the four configurations, the three failures, and the sentence explaining that transaction pooling rewrites the session so named prepared statements resolve against the wrong backend. No note-taking policy recovers that later, because at write time it was just debugging.

There is also a hard clock on it. Anthropic's documentation says the memory directory is excluded from the retention sweep — and that the transcripts themselves are kept for 30 days by default, set by cleanupPeriodDays. So the notes persist and the evidence behind them expires.

What to pair it with

Keep auto memory on

It costs nothing and it fixes the "I told you last week" complaint within one repository. Nothing here argues for turning it off.

Keep CLAUDE.md for rules

Standing constraints belong somewhere deliberate and reviewable, in version control where your team sees them. Do not wait for Claude to notice a rule.

Index the transcripts

For the part with no mechanism: what was tried, what failed, and why. It works across all six tools and all your machines, because it reads what the tools already wrote.

State decisions out loud

"We are going with the direct connection because prepared statements break in transaction mode" is a sentence every one of these mechanisms can keep. The same decision left implicit in a diff is recoverable by none of them.

Checking what it has

in a session

> /memory
  browse the files, toggle auto memory, open the folder

It is plain markdown, so read it, edit it, delete what is wrong. A memory you cannot audit is a liability, and this one you can.

Index your sessions free What each mechanism keeps

Claude Code has auto memory. Where it stops.