Complete Guide to Claude Code Auto Memory: From Architecture to Practical Use

What is Auto Memory?

Auto Memory, introduced in Claude Code v2.1.32, is a feature where Claude automatically records and reuses insights discovered during a session.

While the conventional CLAUDE.md is a "manual of instructions" written by the user, Auto Memory is positioned as notes that Claude writes for itself.

Directory Structure

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index (automatically loaded every session)
├── debugging.md       # Debugging patterns
├── api-conventions.md # API design notes
└── ...                # Topic files (loaded on-demand)

• The <project> path is generated from the Git repository root.
• Subdirectories within the same repository share the same memory.
• Git worktrees are treated as separate directories.

The Two-Layer Loading Mechanism

The core of Auto Memory is a two-layer design that avoids wasting the context window.

Layer	Target	Timing	Limits
Layer 1	MEMORY.md	Automatically injected at session start	First 200 lines only
Layer 2	Topic files	Loaded on-demand by Claude when needed	No limit

MEMORY.md functions as a concise index, while details are separated into topic files.

Information Recorded by Claude

Categories that are automatically recorded during work:

• Project Patterns: Build commands, testing conventions, and code styles
• Debugging Insights: Causes of errors and their solutions
• Architecture Notes: Module relationships and important files
• User Preferences: Workflows and tool choices

Differences from CLAUDE.md

CLAUDE.md    → Written by User → Instructions for Claude
Auto Memory  → Written by Claude → Claude's Learning Notes

An overview of memory types:

Type	Location	Manager
Project Memory	./CLAUDE.md	Team
User Memory	~/.claude/CLAUDE.md	Individual
Local Memory	./CLAUDE.local.md	Individual
Auto Memory	~/.claude/projects/*/memory/	Claude

Both complement each other. The best practice is to define explicit rules in CLAUDE.md and let Auto Memory accumulate project-specific implicit knowledge.

Practical Usage

Making it Remember Explicitly

"Remember to use pnpm"
"Save to memory that API tests require Redis"

/memory Command

You can open a file selector with /memory and edit MEMORY.md directly in your editor.

Controlling via Environment Variables

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # Force enable
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # Force disable

Note: The variable name uses a double negative. DISABLE=0 means "Do not disable" = Enable.

Tips for Managing MEMORY.md

The golden rule is to keep it under 200 lines. Separate details into topic files and link them:

# Project Memory

## Build
- `pnpm build` / `pnpm test`
- Details → debugging.md

## Architecture
- Next.js 15 App Router
- Details → architecture.md

Comparison with Other AI Agents

The concept of "AI writing its own notes" is not unique to Claude Code.

Tool	Instruction File	AI Auto Memory	Remarks
Claude Code	CLAUDE.md	Auto Memory	Two-layer loading
Gemini CLI	GEMINI.md	save_memory	Append within GEMINI.md
Codex CLI	AGENTS.md	Under development	3-tier + override
Windsurf	Rule settings	Memories	IDE-integrated
Cursor	.cursorrules	None	Completion via Notepad

Gemini CLI uses the save_memory tool to automatically append to ~/.gemini/GEMINI.md. This is the closest to Auto Memory, though instruction files and memory coexist in the same place.

Codex CLI has a sophisticated hierarchical design for AGENTS.md, but the feature for the AI to write automatically is not yet implemented (discussed in Issue #8368).

Windsurf supports both user-defined and automatic memory, offering a comprehensive solution as an IDE-integrated tool.

Are MCP Memory Tools No Longer Needed?

Before Auto Memory, achieving cross-session memory required an MCP Memory Server.

• Serena — Saves and restores project context using write_memory/read_memory.
• Basic Memory — Builds a knowledge base in local Markdown files.
• OpenMemory (Mem0) — A memory layer shareable across multiple tools.
• mcp-memory-service — Persistent memory with vector search.

Auto Memory natively replaces the primary use cases for these tools (recording patterns, debugging insights, and learning preferences). It works right out of the box without the need to set up an MCP server.

Cases where MCP Memory is still needed

• Sharing between multiple tools: If you want to share memory between Claude Code and Cursor, etc. → OpenMemory
• Vector search: For semantically searching through a massive amount of insights → mcp-memory-service
• Team sharing: Auto Memory is for individuals. Use CLAUDE.md or external tools for team knowledge.

While Auto Memory can replace Serena's memory features, Serena's core symbol operations (like find_symbol) still offer unique value.

Summary

Auto Memory is a practical mechanism that solves the "cross-session memory" challenge for AI coding assistants. With features like Gemini CLI's save_memory and Windsurf's Memories, the paradigm of "AI writing its own learning notes" is becoming the standard for 2026.

Cross-session memory, previously achievable only through MCP memory servers, is now available as a native feature. Since it is in a gradual rollout phase, if it's not yet enabled for you, try it out by setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=0.