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

Auto Memory

Auto memory lets Claude accumulate knowledge across sessions automatically. Claude writes notes for itself — your preferences, corrections you gave it, decisions about ongoing work, where to find outside information — 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 learns something worth keeping — a preference you stated, a correction you gave, a decision about ongoing work — it writes a note to the memory directory.

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

The <project> path is derived from the git repository, so all worktrees and subdirectories of the same repo share one directory. Outside a git repo, the project root is used instead.

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per memory, loaded every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...                 # Any other topic files Claude creates

MEMORY.md acts as an index. The first 200 lines or 25KB (whichever comes first) load at session start; anything past that is not loaded. Topic files are not loaded at startup — Claude reads them on demand with its normal file tools.

After Claude writes to MEMORY.md, Claude Code checks it against those limits. Near a limit, it reminds Claude to shorten the index (one line per entry, detail in topic files, drop stale entries). Over a limit, the write still succeeds but Claude is told to rewrite the index, since everything past the limit would be dropped on the next load.

When you see "Saved 2 memories" or "Recalled 2 memories" in the interface, Claude is writing to or reading from this directory.

All files are plain markdown. You can read, edit, or delete them anytime. Memory files are excluded from the cleanupPeriodDays transcript cleanup — they stay until you or Claude removes them.

Auto memory is machine-local — not synced across machines or cloud environments.

Memory Types

Claude records the kind of each note as a type field in the memory file's frontmatter:

Claude Code also stamps a modified field (ISO 8601 timestamp) into a memory file's frontmatter each time Claude writes it, so you and Claude can tell how current a fact is (v2.1.214+).

Manage Memory with /memory

The /memory command in any session:

• Lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes
• Lets you toggle auto memory on or off
• Provides an option to open the auto memory folder
• Opens any file in your editor (creating it first if it doesn't exist yet)

To see which CLAUDE.md and rules files actually loaded at launch, run /context.

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 in local sessions. Sessions in a self-hosted environment run with it off by default.

The /memory toggle saves autoMemoryEnabled to your user settings (~/.claude/settings.json). To turn it off for a single project, set it in that project's settings:

{
  "autoMemoryEnabled": false
}

Or via environment variable:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

Setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 forces auto memory on, even when --bare mode or autoMemoryEnabled: false would otherwise disable it.

Custom Storage Location

Store auto memory outside the default directory:

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

Must be an absolute path or start with ~/. The setting is read from any settings scope (user, project, local, policy, or --settings). When it comes from a project's .claude/settings.json or .claude/settings.local.json, Claude Code only honors it under the same workspace-trust rule as hooks in settings files — so a cloned repo can't silently redirect 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. It skips anything it can derive from the codebase (architecture, file paths, debugging fixes) and anything your CLAUDE.md files already say. Examples of what gets saved:

• You prefer pnpm over npm in every project
• You asked for integration tests to hit a real database, not mocks
• The billing migration is frozen until the Q4 release — don't touch migrations/billing/
• Bugs are tracked in the Linear "PLATFORM" project; on-call dashboards live in Grafana

Subagent Memory

Subagents can maintain their own persistent memory. Enable it with the memory frontmatter field in the subagent's definition file (for example .claude/agents/code-reviewer.md):

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

With memory enabled, the subagent's system prompt includes the first 200 lines or 25KB of its own MEMORY.md, and Read, Write, and Edit are enabled so it can manage its memory files. If auto memory is turned off, the memory field has no effect.

The main conversation's auto memory is not loaded into subagents — except a fork, which inherits the parent conversation.

Auditing Memory

Since all memory files are plain markdown, you can audit them directly. The easiest route is /memory in a session, then select the auto memory folder.

From a shell, find your project's folder under ~/.claude/projects/ (the folder name is derived from the repository path, not just the directory name):

# List project folders, then pick the one for this repo
ls ~/.claude/projects/
 
# See what Claude has saved about this project
cat ~/.claude/projects/<project>/memory/MEMORY.md
 
# Edit a topic file
code ~/.claude/projects/<project>/memory/feedback_testing.md
 
# Clear all memory for this project
rm -rf ~/.claude/projects/<project>/memory/

Related

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