Auto Memory: How Claude Learns Across Sessions

The Forgotten Correction

You correct Claude on something. It always runs npm ci but this project uses pnpm install. You tell it. Claude nods, adjusts, does the right thing for the rest of the session. Next session, same mistake. You correct it again. Same story. The correction never sticks because it was made in conversation, not written into persistent context.

This is the problem auto memory solves. Instead of you manually transcribing every correction into CLAUDE.md, Claude writes those notes for itself. When you say "always use pnpm, not npm" and Claude saves that to memory, it will know on the next session without you having to say it again.

Two Complementary Systems

Auto memory and CLAUDE.md are parallel systems that work together. Both load at the start of every session. Both shape how Claude behaves. But they serve different purposes:

CLAUDE.md is for instructions. Auto memory is for learnings. They are complementary because CLAUDE.md cannot capture everything Claude learns through working with you — it can only capture what you think to write explicitly.

MEMORY.md and Topic Files

Auto memory for each project lives in ~/.claude/projects/<project>/memory/. The <project> path is derived from the git repository root, so all worktrees and subdirectories within the same repo share one auto memory directory.

The directory contains a MEMORY.md file and optional topic files:

~/.claude/projects/my-project/memory/
├── MEMORY.md
├── debugging.md
├── api-conventions.md
└── build-commands.md

MEMORY.md is the index. It contains a concise summary of what Claude has learned, with references to the topic files that hold more detail. Topic files like debugging.md or api-conventions.md hold the full notes on specific subjects.

This distinction matters for loading: only MEMORY.md loads at session start. Topic files do not load automatically — Claude reads them on demand when it needs the information, using its file reading tools. This architecture keeps the startup context lean even if Claude has accumulated extensive notes on a project over many sessions.

The Startup Loading Limit

The first 200 lines of MEMORY.md, or the first 25KB — whichever comes first — load at session start. Content beyond that threshold is not loaded automatically. Claude is designed to keep MEMORY.md concise by moving detailed notes into separate topic files and keeping the index file well under the limit.

This limit applies only to MEMORY.md. CLAUDE.md files are loaded in full regardless of length (though shorter files produce better adherence). The separation between the two systems means you can have extensive accumulated knowledge in topic files without paying the startup context cost for all of it.

What Claude Decides to Remember

Claude does not save something to memory after every session. It makes a judgment about whether the information would be useful in a future conversation. Build commands it discovered, debugging patterns that solved persistent problems, code style preferences you corrected it on, architectural decisions that shaped how it approached the codebase — these are the kinds of things Claude saves.

Claude also updates memory during a session, not just at the end. When you see "Writing memory" or "Recalled memory" in the interface, Claude is actively reading or updating files in the memory directory based on something that came up in the current conversation.

The /memory Command

To see and manage everything Claude has saved about a project, run /memory. This command lists all CLAUDE.md, CLAUDE.local.md, and rules files loaded in the current session, shows the auto memory toggle, and provides a link to open the auto memory folder.

Everything in auto memory is plain markdown that you can edit or delete directly. If Claude learned something incorrect — the wrong command, a preference you no longer have, a pattern that no longer applies — open the file from /memory and fix or delete it. The next session will start with the corrected information.

To ask Claude to remember something explicitly, say it in conversation: "always use pnpm install, not npm install." Claude will save it to auto memory. To add something to CLAUDE.md instead — for instructions you want to share with the team or that should be explicitly governed — say "add this to CLAUDE.md" and Claude will update the file directly.

Configuration

Auto memory is on by default. To disable it, toggle it off from /memory or set autoMemoryEnabled: false in your project settings. The environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 also disables it for a session.

To store auto memory in a non-default location — useful for shared network drives or synced directories — set autoMemoryDirectory to an absolute path in your settings file. The ~/ prefix is also supported.

In multi-agent projects where you use Claude Code with subagents, each subagent can maintain its own auto memory using the enable-persistent-memory configuration in the agent definition. This allows specialized subagents — a security reviewer, a testing expert, an API design specialist — to accumulate their own domain-specific knowledge independently of the main session memory.