Claude Code has auto memory. Where it stops.
Auto memory is on by default, and it keeps notes on your corrections without you ever asking. It's also scoped a lot more narrowly than the word "memory" makes it sound.
What it actually does
As Claude works, it saves notes to itself, filed under four kinds: your role and preferences, corrections you've given 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 only get read on demand.
Two design choices are worth calling out, because both are correct and both are limits at the same time. Claude deliberately skips anything it can derive from the codebase, and it skips anything CLAUDE.md already covers. So auto memory is, by design, the leftover: whatever's true about working with you that's written down nowhere else.
The four boundaries
| One repository | Each project gets its own directory, keyed to the git repository. Worktrees of the same repo share it; two different repositories never do. A convention you set up in one service doesn't follow you to the next. |
| One machine | The documentation is explicit that files aren't shared across machines or cloud environments. Your laptop and your desktop build up two different memories of the same person. |
| One tool | It belongs to Claude Code, and only Claude Code. Nothing you did in another AI coding tool ever makes it in, and nothing in it is visible to them either. |
| What Claude chose to write | Claude doesn't save something every single session; it judges what's likely to be useful later. That judgment is usually good, but it's still a filter applied at write time, before anyone actually knows what will be needed. |
The boundary that costs you the most
The last one deserves its own paragraph, because it's really the difference between two kinds of product, not just 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 holds the entire afternoon that produced it: the four configurations, the three failures, and the exact 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 the time it was written, it was just debugging.
There's also a hard clock running on it. Anthropic's documentation says the memory directory is excluded from the retention sweep, but the transcripts themselves are kept for 30 days by default, set by cleanupPeriodDays. So the notes stick around, and the evidence behind them quietly expires.
What to pair it with
If you are weighing this against an MCP memory server, the three kinds of those are compared here — they are not all the same product.
| Keep auto memory on | It costs nothing, and it fixes the "I told you last week" complaint within a single repository. Nothing here is an argument for turning it off. |
| Keep CLAUDE.md for rules | Standing rules belong somewhere deliberate and reviewable, in version control where your whole team can see them. Don't wait around for Claude to notice a rule on its own. |
| Index the transcripts | For the part with no mechanism at all: what was tried, what failed, and why. It works across all six tools and every machine you use, because it reads what the tools already wrote. |
| State decisions out loud | "We're going with the direct connection because prepared statements break in transaction mode" is a sentence every one of these mechanisms can hold onto. The same decision left implicit in a diff is recoverable by none of them. |
Checking what it already has
> /memory browse the files, toggle auto memory, open the folder
It's plain markdown, so go read it, edit it, delete whatever's wrong. A memory you can't audit is a liability — this one, you actually can.
Questions
| What is auto memory in Claude Code? | Notes Claude saves to itself as it works, covering your role and preferences, corrections you have given, ongoing project context, and pointers to things outside the repository. |
| Where is Claude Code memory stored? | 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 and the topic files are read on demand. |
| Does Claude Code memory work across repositories? | No. Each project gets its own directory keyed to the git repository. Worktrees of the same repository share it and two different repositories never do, so a convention you set up in one service does not follow you to the next. |
| Does it sync between my machines? | No. The documentation is explicit that the files are not shared across machines or cloud environments, so a laptop and a desktop build two separate memories of the same person. |
| What does auto memory deliberately leave out? | Anything derivable from the codebase, and anything CLAUDE.md already covers. It is the leftover by design: what is true about working with you and written down nowhere else. It also only holds what Claude judged worth saving at the time, before anyone knew what would be needed. |
| Should I turn it off? | No. It costs nothing and it fixes the I told you last week complaint inside one repository. Keep standing rules in CLAUDE.md where they are reviewable, and index the transcripts for the part with no mechanism at all: what was tried, what failed, and why. |
More notes
| Context left until auto-compact: what the number counts | The percentage in the status line, what makes it fall, how to move the threshold, and what actually happens to your conversation when it reaches zero. |
| /clear vs /compact in Claude Code | One summarizes the conversation and keeps going. The other starts a fresh one. What each does to the transcript on disk, and which to reach for. |
| Compact instructions: tell /compact what to keep | Compaction decides what survives unless you decide for it. Passing instructions to /compact, and the PreCompact hook that supplies them every time. |