Claude Code Now Remembers What It Learns Across Sessions

Anthropic rolled out auto-memory in Claude Code. The feature lets Claude persist what it learns — project context, debugging patterns, preferred approaches — and recall it in future sessions without you writing anything down.

What changed:

Claude automatically saves useful context as it works: build commands, test conventions, code style, architecture notes
Memory persists in a per-project directory at ~/.claude/projects/<project>/memory/
A MEMORY.md file acts as the index; the first 200 lines load into every new session
Claude creates topic files (e.g., debugging.md, api-conventions.md) for detailed notes
Enabled by default — toggle with /memory or disable in settings

CLAUDE.md vs MEMORY.md

The mental model is straightforward. As Thariq Shihipar put it: “Think of CLAUDE.md as your instructions to Claude and MEMORY.md as Claude’s memory scratchpad it updates.”

CLAUDE.md files are things you write and maintain — project architecture, coding standards, team conventions. They’re checked into version control and shared with your team.

Auto memory is what Claude writes for itself. Patterns it noticed, solutions to problems it solved, your preferences it picked up on. It’s local to your machine, per-project, and Claude manages it autonomously.

CLAUDE.md

MEMORY.md (Auto Memory)

You write and maintain

Claude writes and maintains

Checked into git, shared with team

Local to your machine, per-project

Instructions, rules, conventions

Learnings, patterns, debugging insights

Full file loaded every session

First 200 lines of MEMORY.md loaded

How auto-memory works

Claude stores memory in a directory structure per project:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index file, loaded every session
├── debugging.md       # Debugging patterns
├── api-conventions.md # API design notes
└── ...

The <project> path derives from the git repository root, so all subdirectories in the same repo share one memory directory. Git worktrees get separate memory directories.

At session start, Claude loads the first 200 lines of MEMORY.md into its system prompt. Topic files aren’t loaded automatically — Claude reads them on demand when it needs the information. This keeps the context window lean while still giving Claude access to detailed notes.

You can tell Claude to remember specific things: “remember that we use pnpm, not npm” or “save to memory that the API tests require a local Redis instance.” You can also edit memory files directly with /memory.

The full memory hierarchy

Anthropic also documented the complete memory hierarchy. Six levels, from organization-wide policies down to auto-memory:

Managed policy — Organization-wide rules deployed by IT (system-level paths)
Project memory — ./CLAUDE.md, shared via source control
Project rules — .claude/rules/*.md, modular per-topic files
User memory — ~/.claude/CLAUDE.md, personal preferences across all projects
Project memory (local) — ./CLAUDE.local.md, personal project-specific preferences (auto-gitignored)
Auto memory — ~/.claude/projects/<project>/memory/, Claude’s own notes

More specific instructions take precedence over broader ones. CLAUDE.md files in parent directories load at launch; those in child directories load on demand when Claude reads files there.

Disabling auto-memory

Auto-memory is on by default. Three ways to turn it off:

/memory toggle during a session
"autoMemoryEnabled": false in ~/.claude/settings.json (all projects) or .claude/settings.json (single project)
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 environment variable (overrides everything, useful for CI)