If you've spent any real time with Claude Code, you know this pain: you open a fresh session and it's forgotten everything you taught it yesterday. I'd tell it over and over not to dump a pile of emojis into my writing because it looks too AI — and the next morning, fresh session, emojis everywhere again.
Turns out there's a fix built for exactly this, called Auto Memory. I'd already written about CLAUDE.md for setting project rules by hand, but Claude Code's memory system is bigger than just CLAUDE.md. Auto Memory quietly records your corrections and preferences as you work, so next session you don't have to say them again.
Auto Memory needs Claude Code v2.1.59 or newer. Check with
claude --version
.
A lot of people mix these two up, so let's get it straight first.
| CLAUDE.md | Auto Memory | |
|---|---|---|
| Who writes it | You | Claude, automatically |
| What's in it | Instructions and rules | Learned lessons and patterns |
| Scope | Project / user / org | Per working tree |
| Fully loaded every session | First 200 lines / 25KB only | |
| Best for | Code conventions, workflow, architecture | Build commands, debugging notes, preferences |
In short: CLAUDE.md is the set of rules you write for Claude on purpose — "use 2-space indentation," "write commit messages in English." Auto Memory is what Claude picks up on its own while working with you. You don't write it; it does.
Auto Memory is basically Claude taking its own notes. When you correct it, or tell it whether an approach worked, Claude decides whether that's worth remembering for later. If it is, it saves it.
So when I told it:
Don't use so many emojis, it looks too AI
it saved that as a memory file, and every new session loads it back. Now it remembers I don't like emoji soup.
It doesn't save everything, though — one-off discussions or things irrelevant to future work don't get written down.
Here's the thing that trips everyone up. Your project has a .claude/
folder, but Auto Memory files are not in there. The project .claude/
only holds settings (settings.json
, settings.local.json
) and rules.
The actual memory lives under your home directory:
/Users/ray/my-project/.claude/ <- project settings, inside your repo
/Users/ray/.claude/projects/-Users-ray-my-project/memory/ <- Auto Memory, under your home dir
Both paths contain .claude
, but one is in your project and one is in your home directory — don't mix them up. If you peek into your project's .claude/
and only find settings.local.json
, that's normal. The memory was never there.
The memory path is derived from your git repo, so subdirectories and worktrees of the same repo share one memory. And it's machine-local — it does not sync to other machines or cloud environments.
If you want it somewhere else, set autoMemoryDirectory
(Policy / Local / User level only — not project level, on purpose, so a shared repo can't redirect your memory somewhere shady):
{
"autoMemoryDirectory": "~/my-custom-memory-dir"
}
~/.claude/projects/<project>/memory/
├── MEMORY.md # index, loaded every session
├── debugging.md # debugging notes
├── api-conventions.md # API design decisions
└── ... # other topic files Claude creates
MEMORY.md
is the index — Claude uses it to track which memories exist and which file each one lives in. Only the first 200 lines / 25KB of MEMORY.md
loads at session start, so Claude keeps it lean and pushes detail into separate topic files. Those topic files aren't loaded on startup; Claude reads them on demand. So your memory can grow without bloating context every single time.
(That 200-line cap is only for MEMORY.md
. CLAUDE.md always loads in full — though shorter still means better adherence.)
When you see "Writing memory" or "Recalled memory" in the Claude Code UI, that's it updating or reading memory files. You don't have to do anything; it handles it.
/memory
~/.claude/projects/
. Add, edit, or delete whatever you want./memory
, set "autoMemoryEnabled": false
, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
.And in case you were wondering: /compact
does not wipe it. The files are on disk, not in the conversation. Compacting only squeezes the chat history; MEMORY.md
and CLAUDE.md get re-read from disk and injected back afterward.
That's the whole thing. It's a small feature, but once you stop repeating yourself every session it's hard to go back.