Auto Memory in Claude Code

Problem: Your CLAUDE.md is in place with project rules, but Claude keeps asking the same things about build commands, test conventions, and weird debugging quirks. Instructions cover what you want Claude to do. They miss what Claude already learned about your repo.

Quick Win: See if auto memory is already running. Inside any Claude Code session, run /memory. A selector opens showing your CLAUDE.md files and an auto-memory toggle. The toggle is on by default, which means Claude has been quietly taking project notes for you.

# Find your project's auto memory directory
ls ~/.claude/projects/

See directories listed? Claude has notes waiting. Keep reading to learn what goes in them, how to work with them, and how they sit alongside your CLAUDE.md system. If your memory files feel bloated after many sessions, look at Auto Dream, the consolidation feature that cleans up and reorganizes whatever Auto Memory writes.

What Auto Memory Actually Is

Auto memory is a persistent folder where Claude logs learnings, patterns, and insights while it works. Here is the key split: CLAUDE.md is your instructions to Claude. MEMORY.md is Claude's notes to itself about your project.

CLAUDE.md is where you write things like "use pnpm, not npm" or "write tests before code." Auto memory is where Claude jots down its own observations: "build command is pnpm build, tests live in __tests__/, API uses Express with middleware in src/middleware/."

Do not confuse this with Session Memory, which stores conversation-level summaries for cross-session recall. Auto memory works one level deeper. It holds durable project knowledge that sticks around no matter which conversation created it.

Three Memory Systems, Side By Side

Claude Code now runs three separate memory systems. Knowing which one to reach for saves you from doing the same work twice or picking the wrong tool.

The best setup runs all three together. CLAUDE.md lays down the rules. Auto memory records what Claude learns along the way. Session Memory holds the thread between sessions.

Where The Files Live

Every project gets its own memory folder, anchored to the git repo root:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Main index, loaded every session
├── debugging.md       # Detailed debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any topic files Claude creates

A couple of storage details worth knowing:

• The git repo root is what defines the project path. Every subdirectory inside the same repo shares one memory folder. Run Claude from src/api/ and you hit the same memory as running from the repo root.
• Git worktrees each get their own folder. This is on purpose. Different worktrees usually hold different branches in different states.
• Outside of a git repo, the working directory plays the role of the repo root.

What Gets Written Down

While Claude works on your project, it files notes under a few categories:

Project patterns: build commands, test conventions, code style choices. Run your test suite once and Claude records the command plus any special flags it needed.

Debugging insights: fixes for tricky bugs and common error roots. Spend time chasing a CORS issue or a webpack config knot? Claude writes the solution down.

Architecture notes: key files, how modules relate, important abstractions. Claude maps the territory once so it does not have to rediscover your layout every session.

Your preferences: how you communicate, your workflow habits, your tool picks. Claude notices the patterns you lean on.

MEMORY.md works as a short index. As notes pile up, Claude moves the detail into topic files like debugging.md or patterns.md. That keeps the main file under 200 lines, since only the first 200 lines load at startup.

How To Use It

Just Let It Run

The easiest path: leave it alone. Auto memory is on by default. Claude reads and writes memory files in the background as you work. You will notice it during sessions when Claude touches files inside the memory folder.

Save Something Specific

Tell Claude outright what to store:

"remember that we use pnpm, not npm"
"save to memory that the API tests require a local Redis instance"
"note that the staging environment uses port 3001"

Claude drops these into the right memory file right away.

Browse And Edit

During any session, run /memory to open the memory file selector. This lists every memory file (CLAUDE.md, auto memory, local config) and lets you open any of them in your system editor.

You can also read them from the shell:

# List all memory files for a project
ls ~/.claude/projects/<project>/memory/
 
# Read the main memory index
cat ~/.claude/projects/<project>/memory/MEMORY.md
 
# Read a specific topic file
cat ~/.claude/projects/<project>/memory/debugging.md

These are plain markdown files. Edit them whenever. Delete entries that have gone stale. Reorganize as the project grows.

Configuration And Control

Auto memory ships on by default. Here is every knob you can turn:

Per-Session Toggle

Run /memory and flip the auto-memory toggle. Quickest way to switch it on or off for your current workflow.

Kill It For Every Project

Drop this in your user settings:

// ~/.claude/settings.json
{ "autoMemoryEnabled": false }

Kill It For One Project

Drop this in the project settings:

// .claude/settings.json
{ "autoMemoryEnabled": false }

Environment Variable Override

CLAUDE_CODE_DISABLE_AUTO_MEMORY beats every other setting. It is the right pick for CI pipelines, automation, and managed deployments:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # Force off
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # Force on

This overrules both the /memory toggle and settings.json, so it works as a hard kill switch.

When To Reach For What

Three memory systems, one decision framework:

Reach for CLAUDE.md when you want hard rules. Coding standards, architecture calls, required commands, team conventions. CLAUDE.md loads in full at startup and sits at high priority. If you want a pattern followed every time, it goes here.

Reach for auto memory when you want Claude to pick things up as it goes. Patterns that surface during real work, debugging fixes, quiet preferences. You do not have to plan for everything in advance.

Reach for Session Memory when you need conversation continuity. Session Memory keeps the thread of what you discussed and decided in each session. It is the "what did we do yesterday" layer.

Reach for the rules directory when your CLAUDE.md has outgrown one file. Split your instructions into focused files under .claude/rules/ for cleaner structure without losing priority.

The overlap is on purpose. Auto memory picks up the things you forgot to put in CLAUDE.md. Session Memory carries the context that project-level notes cannot. Stack them and you get layered memory covering rules, project knowledge, and conversation history.

Best Practices

Keep MEMORY.md under 200 lines. Only the first 200 lines load at startup. Claude is told to stay concise by pushing detail into topic files. If you edit by hand, respect the same cap.

Review your memory files now and then. Like any notes, they go stale. After a big refactor or architecture shift, skim the files and delete what is no longer true.

Do not double up between CLAUDE.md and auto memory. If something needs to be a rule, put it in CLAUDE.md. If it is a pattern that might shift, let auto memory carry it.

Save the critical stuff explicitly. When you crack a nasty bug or lock in a big architecture call, tell Claude to remember it. Do not bet on Claude catching everything on its own.

Turn auto memory off in CI. Automation does not need Claude stacking notes about your build box. Set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in your CI config.

Pair it with context engineering. Auto memory is one layer of a bigger context engineering strategy. The more care you put into what Claude knows at startup, the more every session gives back.

Next Steps

• Set up your CLAUDE.md memory system for persistent project instructions
• Understand Session Memory for cross-session conversation continuity
• Learn context management strategies to work within token limits
• Explore the rules directory for modular project instructions
• Read about context engineering for production AI memory systems

Auto memory closes the gap between what you tell Claude and what Claude works out on its own. CLAUDE.md owns the "do it this way" rules. Auto memory owns the "I noticed this about your project" knowledge. Run them together and you explain yourself less and ship more.