Auto Memory in Claude Code: Let AI Write and Recall Your Project Notes Automatically

Claude Code Overview

Claude Code is Anthropic’s command‑line AI programming assistant. It runs directly in a terminal, can read and write files, execute shell commands, run tests, and even submit code. Unlike IDE plugins, it operates on the whole project context—e.g., it parses pom.xml, configuration files, and the directory layout for Java projects.

Limitations of the Original Memory Model

Before version v2.1.59, Claude Code could only retain information within the current session. Users had to maintain a CLAUDE.md file at the project root containing static rules and commands. This file required manual updates, grew unwieldy, and could not capture experiential knowledge.

Auto Memory Feature (v2.1.59, February 2026)

Auto Memory automatically writes useful project information to local markdown files without any configuration.

What Auto Memory Captures

Project patterns: build commands, test conventions, directory structure.

Debugging experience: common pitfalls, troubleshooting steps, and solutions.

Architecture notes: key files, module relationships, important abstractions.

Personal preferences: coding style, tool choices, workflow habits.

You can also ask Claude to remember explicit facts, e.g., “Remember this project uses pnpm instead of npm.” Those statements are appended to the memory files.

Memory File Layout

~/.claude/projects/<project‑path>/memory/
├── MEMORY.md          # Main index (first 200 lines auto‑loaded each session)
├── debugging.md       # Debugging notes
├── api-conventions.md # API design conventions
└── …                  # Additional topic‑specific files

Key characteristics :

Files are stored locally and never committed to Git.

Memory is isolated per Git repository, preventing cross‑project leakage.

Only the first 200 lines of MEMORY.md are loaded automatically; excess content is split into topic files.

CLAUDE.md vs MEMORY.md

Author : CLAUDE.md is written by the user; MEMORY.md is generated by Claude.

Content : CLAUDE.md holds static rules and commands; MEMORY.md captures experience, patterns, and preferences.

Version control : CLAUDE.md is typically committed to the repository; MEMORY.md remains private.

Maintenance : CLAUDE.md requires manual edits; MEMORY.md updates automatically.

Both files are loaded together when a session starts, so they complement each other without conflict.

Using Auto Memory

Verify Your Version

claude update
claude --version

Auto Memory requires Claude Code v2.1.59 or newer.

View Memory Status

Inside any Claude Code session, type: /memory The tool displays a panel showing the auto‑memory status and paths to the user memory, project memory, and the auto‑memory folder.

Confirm That Memory Is Active

Start a Claude Code session and ask it to perform a task (e.g., generate a Spring Boot endpoint).

Observe a line such as Recalled X memories (ctrl+o to expand) in the terminal.

Press Ctrl+O to expand and see which memories were loaded.

Close the session, reopen it, and ask “What build tool does this project use?” A correct answer confirms that Auto Memory persisted the information.

Manage Memory Files Directly

Memory files are ordinary markdown files that you can edit with any editor. Example to open the main file:

# Open the main memory file
open ~/.claude/projects/<project>/memory/MEMORY.md
# Or use the /memory command inside a Claude session

Disable Auto Memory

You can turn off Auto Memory at different scopes:

Per‑project (place in .claude/settings.json inside the project):

{
  "autoMemoryEnabled": false
}

Globally (place in ~/.claude/settings.json):

{
  "autoMemoryEnabled": false
}

CI/CD environments (environment variable takes precedence):

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Memory Hierarchy

Claude Code resolves requests by consulting memory layers from most general to most specific. Higher‑specificity layers override lower ones.

Organization‑level : system‑wide directory managed by IT/operations, shared across the organization.

Project memory : ./CLAUDE.md (team‑maintained, version‑controlled via Git).

Project rules : ./.claude/rules/*.md (team‑maintained, version‑controlled).

User memory : ~/.claude/CLAUDE.md (personal preferences applied to all projects).

Project‑local memory : ./CLAUDE.local.md (personal notes scoped to the current project).

Auto Memory : ~/.claude/projects/<project>/memory/ (automatically generated by Claude, private to the user and the specific project).

Conclusion

Auto Memory eliminates the “cold start” problem for new Claude Code sessions. After a few days of use, the assistant can immediately recall recent work, unresolved bugs, and project conventions, making AI‑driven pair programming faster and more productive.