Auto memory is a persistent directory where Claude automatically records learnings, patterns, and insights as it works with your project. Unlike CLAUDE.md files which you write and maintain manually, auto memory is written by Claude itself during sessions.

How Auto Memory Works

Location: ~/.claude/projects/<project>/memory/
Entrypoint: MEMORY.md serves as the main file in the auto memory directory
Topic files: Optional additional files for specific subjects (e.g., debugging.md, api-conventions.md)
Loading behavior: The first 200 lines of MEMORY.md are loaded into the system prompt at session start. Topic files are loaded on demand, not at startup.
Read/write: Claude reads and writes memory files during sessions as it discovers patterns and project-specific knowledge

Auto Memory Architecture

graph TD
    A["Claude Session Starts"] --> B["Load MEMORY.md<br/>(first 200 lines)"]
    B --> C["Session Active"]
    C --> D["Claude discovers<br/>patterns & insights"]
    D --> E{"Write to<br/>auto memory"}
    E -->|General notes| F["MEMORY.md"]
    E -->|Topic-specific| G["debugging.md"]
    E -->|Topic-specific| H["api-conventions.md"]
    C --> I["On-demand load<br/>topic files"]
    I --> C

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#fff3e0,stroke:#333,color:#333
    style F fill:#fce4ec,stroke:#333,color:#333
    style G fill:#fce4ec,stroke:#333,color:#333
    style H fill:#fce4ec,stroke:#333,color:#333
    style I fill:#f3e5f5,stroke:#333,color:#333

Auto Memory Directory Structure

~/.claude/projects/<project>/memory/
├── MEMORY.md              # Entrypoint (first 200 lines loaded at startup)
├── debugging.md           # Topic file (loaded on demand)
├── api-conventions.md     # Topic file (loaded on demand)
└── testing-patterns.md    # Topic file (loaded on demand)

Version Requirement

Auto memory requires Claude Code v2.1.59 or later. If you are on an older version, upgrade first:

npm install -g @anthropic-ai/claude-code@latest

Custom Auto Memory Directory

By default, auto memory is stored in ~/.claude/projects/<project>/memory/. You can change this location using the autoMemoryDirectory setting (available since v2.1.74):

// In ~/.claude/settings.json or .claude/settings.local.json (user/local settings only)
{
  "autoMemoryDirectory": "/path/to/custom/memory/directory"
}

Note: autoMemoryDirectory can only be set in user-level (~/.claude/settings.json) or local settings (.claude/settings.local.json), not in project or managed policy settings.

This is useful when you want to:

Store auto memory in a shared or synced location
Separate auto memory from the default Claude configuration directory
Use a project-specific path outside the default hierarchy

Worktree and Repository Sharing

All worktrees and subdirectories within the same git repository share a single auto memory directory. This means switching between worktrees or working in different subdirectories of the same repo will read and write to the same memory files.

Subagent Memory

Subagents (spawned via tools like Task or parallel execution) can have their own memory context. Use the memory frontmatter field in the subagent definition to specify which memory scopes to load:

memory: user      # Load user-level memory only
memory: project   # Load project-level memory only
memory: local     # Load local memory only

This allows subagents to operate with focused context rather than inheriting the full memory hierarchy.

Controlling Auto Memory

Auto memory can be controlled via the CLAUDE_CODE_DISABLE_AUTO_MEMORY environment variable:

Value	Behavior
`0`	Force auto memory on
`1`	Force auto memory off
(unset)	Default behavior (auto memory enabled)

# Disable auto memory for a session
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

# Force auto memory on explicitly
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude

Introduction