Auto memory lets Claude Code keep running project notes. Where the files sit, what gets written, how /memory toggles it, and when to pick it over CLAUDE.md.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
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.
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.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
Stop configuring. Start building.
SaaS builder templates with AI orchestration.
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.
| Aspect | CLAUDE.md | Auto Memory | Session Memory |
|---|---|---|---|
| Who writes it | You | Claude | Claude |
| What it contains | Instructions and rules | Project patterns and learnings | Conversation summaries |
| Scope | Per-project or global | Per-project | Per-session |
| Loaded at startup | Full file | First 200 lines of MEMORY.md | Relevant past sessions |
| Priority | High (treated as instructions) | Background reference | Background reference |
| Storage | ./CLAUDE.md or ~/.claude/CLAUDE.md | ~/.claude/projects/<project>/memory/ | ~/.claude/projects/<project>/<session>/session-memory/ |
| Best for | Standards, architecture decisions, commands | Build patterns, debugging insights, preferences | Continuity between work sessions |
| Shared with team | Yes (via git) | No (local only) | No (local only) |
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.
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 createsA couple of storage details worth knowing:
src/api/ and you hit the same memory as running from the repo root.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.
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.
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.
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.mdThese are plain markdown files. Edit them whenever. Delete entries that have gone stale. Reorganize as the project grows.
Auto memory ships on by default. Here is every knob you can turn:
Run /memory and flip the auto-memory toggle. Quickest way to switch it on or off for your current workflow.
Drop this in your user settings:
// ~/.claude/settings.json
{ "autoMemoryEnabled": false }Drop this in the project settings:
// .claude/settings.json
{ "autoMemoryEnabled": false }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 onThis overrules both the /memory toggle and settings.json, so it works as a hard kill switch.
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.
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.
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.