Last updated: January 2026
Every AI coding tool has the same annoying problem: you close the session, open a new one, and the AI has no idea what you were working on. You end up re-explaining your project structure, your build commands, your testing conventions. Every. Single. Time.
Anthropic shipped a fix for this in Claude Code. It’s called auto memory, and after a couple of weeks of use, it genuinely changes the workflow.
What Auto Memory Actually Does
When you’re working with Claude Code, it now quietly takes notes. Build commands you run, debugging patterns it discovers, code style preferences you mention, architecture decisions it picks up on. All of this gets written to a local MEMORY.md file that loads automatically at the start of your next session.
The key distinction: this isn’t CLAUDE.md, which is the file you write to give Claude instructions. Auto memory is Claude’s own notebook. You tell it “remember that we use pnpm, not npm” and it writes that down. Next session, it already knows.
Think of CLAUDE.md as the employee handbook you hand to a new hire. Auto memory is the personal notes they scribble in the margins after their first week.
How It Works Under the Hood
Each project gets its own memory directory at ~/.claude/projects/<project>/memory/. The path is derived from your git repo root, so all subdirectories within the same repo share one memory store. Worktrees get separate directories.
The structure looks like this:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Main index, loaded every session
├── debugging.md # Detailed debugging notes
├── api-conventions.md # API patterns
└── ... # Whatever else Claude finds worth notingHere’s the clever part: only the first 200 lines of MEMORY.md get loaded into context at startup. Claude is instructed to keep this file concise and move detailed notes into separate topic files that it reads on demand. So your context window doesn’t get bloated with every little thing Claude has ever learned about your project.
CLAUDE.md vs Auto Memory vs Rules
Claude Code now has a surprisingly layered memory system. Here’s how the pieces fit together:
| Type | Who writes it | Scope | Loaded when |
|---|---|---|---|
| CLAUDE.md | You | Project (shared via git) | Every session |
| CLAUDE.local.md | You | Project (private, gitignored) | Every session |
| .claude/rules/*.md | You | Project (can be path-scoped) | Every session or on file access |
| Auto memory | Claude | Per-user, per-project | First 200 lines at startup |
| User CLAUDE.md | You | All your projects | Every session |
The rules directory is worth calling out. You can now create modular rule files scoped to specific file patterns:
---
paths:
- "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation
- Use the standard error response formatThis only kicks in when Claude is working with files matching those paths. Clean separation of concerns.
What The evaluation has Noticed After Two Weeks
The difference is most obvious on larger projects. Consider a codebase with a non-standard build system and some quirky testing conventions. Before auto memory, every new Claude Code session started with me typing out the same context. Now Claude just knows that make test-integration needs a local Redis instance running, that The workflow uses a custom ESLint config, and that the API module has its own deployment pipeline.
It’s not perfect. Sometimes Claude saves things that are too specific to one debugging session and not useful long-term. You can always edit the memory files directly or use the /memory command to open them in your editor.
Managing It
Auto memory is on by default. A few ways to control it:
/memorycommand during a session to view, edit, or toggle it"autoMemoryEnabled": falsein~/.claude/settings.jsonto disable globally"autoMemoryEnabled": falsein.claude/settings.jsonfor a specific projectCLAUDE_CODE_DISABLE_AUTO_MEMORY=1environment variable to force it off (useful for CI)
You can also tell Claude what to remember explicitly. “Remember that we use Vitest, not Jest” works exactly how you’d expect.
Why This Matters
The “session amnesia” problem is the single biggest friction point in AI-assisted coding. GitHub Copilot doesn’t have persistent memory. Cursor has some project indexing but nothing like explicit memory management. Claude Code is the first major tool to give the AI a proper notebook that accumulates knowledge over time.
It’s a small feature in terms of implementation. But it changes the relationship from “disposable assistant” to something closer to a team member who actually learns your codebase.
If you’re evaluating AI coding tools, these might help: