title: "Auto Memory" description: "How Claude accumulates knowledge across sessions — without you writing anything" section: "Core" readTime: "6 min" badge: "NEW"

Auto Memory

Auto memory lets Claude accumulate knowledge across sessions automatically. Claude writes notes for itself — build commands, debugging insights, architecture patterns, code style preferences — so it doesn't start from zero each time.

Auto Memory vs CLAUDE.md

Both load at the start of every session. They serve different purposes:

Use CLAUDE.md to guide behavior. Use auto memory to let Claude learn from corrections without manual effort.

How It Works

When Claude encounters something worth remembering — a build command that worked, a recurring mistake it made, a pattern specific to your codebase — it writes a note to the memory directory.

Storage location: ~/.claude/projects/<project>/memory/

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions discovered
└── build-commands.md  # Verified commands for this project

MEMORY.md acts as an index. The first 200 lines or 25KB load at session start. Topic files (debugging.md, etc.) are not loaded at startup — Claude reads them on demand when needed.

All files are plain markdown. You can read, edit, or delete them anytime.

Auto memory is machine-local — not synced across machines or cloud environments. All worktrees in the same git repo share one memory directory.

Manage Memory with /memory

The /memory command in any session:

• Lists all CLAUDE.md, CLAUDE.local.md, and rules files loaded
• Shows a link to open the auto memory folder
• Lets you toggle auto memory on or off
• Opens any file in your editor

When you tell Claude to remember something:

Always use pnpm, not npm
Remember: the API tests require a local Redis instance running on port 6380

Claude saves it to auto memory. To add to CLAUDE.md instead, say: "Add this to CLAUDE.md."

Enable / Disable

Auto memory is on by default.

Toggle via settings:

{
  "autoMemoryEnabled": false
}

Or via environment variable:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

Custom Storage Location

Store auto memory outside the project directory:

// ~/.claude/settings.json
{
  "autoMemoryDirectory": "~/my-claude-memory"
}

Must be an absolute path or start with ~/. This setting is accepted in policy and user settings only — not project settings (to prevent a cloned repo from redirecting memory writes).

What Gets Remembered

Claude doesn't save something every session. It writes notes when information would be genuinely useful in a future conversation. Examples of what gets saved:

• npm run dev fails on this machine — use pnpm dev instead
• This project uses src/lib/db.ts as the single database client — never import Prisma directly
• The staging environment uses port 8080, not 3000
• Tests in __tests__/integration/ require docker compose up first

Subagent Memory

Subagents can maintain their own auto memory. Enable it in the subagent's .agent.md definition. Each subagent gets its own memory directory scoped to its role.

Auditing Memory

Since all memory files are plain markdown, you can audit them directly:

# See what Claude has saved about this project
cat ~/.claude/projects/$(basename $PWD)/memory/MEMORY.md
 
# Edit a topic file
code ~/.claude/projects/$(basename $PWD)/memory/debugging.md
 
# Clear all memory for this project
rm -rf ~/.claude/projects/$(basename $PWD)/memory/

Or use /memory in a session and select the auto memory folder.

Related

• Agent Development Kit — The full 6-layer model
• Skills — Instruction modules you write
• Hooks — Deterministic lifecycle automation