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.

Auto Memory vs CLAUDE.md

A lot of people mix these two up, so let's get it straight first.

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.

What Auto Memory actually 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.

Where it's stored (this is the confusing part)

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"
}

The directory structure

~/.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.)

How do you know it's writing memory?

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.

Managing it

• /memory — the main entry point. See what's loaded, toggle Auto Memory on/off, open the memory folder, or open any file in your editor.
• Just ask — "remember: always use pnpm, never npm" saves a memory. "forget the rule about pnpm" updates or deletes it.
• Edit by hand — they're plain Markdown files under ~/.claude/projects/. Add, edit, or delete whatever you want.
• Turn it off — toggle it in /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.