Claude Code Auto Memory Explained: How AI Learns Across Sessions
Introduction
Claude Code v2.1.32 introduced Auto Memory, a feature that automatically manages knowledge across sessions. While the existing CLAUDE.md serves as an instruction file that users write manually, Auto Memory is notes that Claude writes for itself.
Project build commands, debugging patterns discovered along the way, architectural quirks of the codebase — Claude records these automatically and applies them immediately in the next session. This article covers everything from the technical underpinnings of Auto Memory to practical usage tips.
How Auto Memory Works
Directory Structure
Auto Memory is stored in a dedicated directory for each project:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Index file (auto-loaded every session)
├── debugging.md # Detailed debugging pattern notes
├── api-conventions.md # API design insights
└── ... # Topic files created by Claude as needed
The <project> path is derived from the Git repository root, so all subdirectories within the same repository share the same memory directory. Git worktrees get separate directories, and non-Git directories use the current working directory as the key.
Two-Tier Loading Strategy
One of Auto Memory's most notable design decisions is its two-tier loading strategy, which avoids wasting the context window:
- MEMORY.md (first 200 lines): Automatically injected into the system prompt at the start of every session. Functions as an index containing project summaries and references to topic files
- Topic files: Not loaded at startup. Claude reads them on-demand using standard file reading tools when it determines they're relevant
This design ensures continuity of core knowledge without squandering precious context window space.
What Claude Records
Information that Claude automatically records during work falls into four broad categories:
| Category | Examples |
|---|---|
| Project Patterns | Build commands, test conventions, code style |
| Debugging Insights | Solutions to tricky problems, common error causes |
| Architecture Notes | Key files, module relationships, major abstractions |
| User Preferences | Communication style, workflow habits |
CLAUDE.md vs. Auto Memory
Claude Code's overall memory system provides six memory locations in a hierarchical structure:
| Memory Type | Location | Managed By | Scope |
|---|---|---|---|
| Enterprise Policy | /etc/claude-code/CLAUDE.md | IT/DevOps | Organization-wide |
| Project Memory | ./CLAUDE.md | Team | Repository |
| Project Rules | .claude/rules/*.md | Team | Repository |
| User Memory | ~/.claude/CLAUDE.md | Individual | All projects |
| Local Memory | ./CLAUDE.local.md | Individual | Current project |
| Auto Memory | ~/.claude/projects/<project>/memory/ | Claude | Current project |
CLAUDE.md is "instructions the user gives to Claude." Auto Memory is "learning notes Claude writes for itself." The two are complementary — define explicit rules in CLAUDE.md and let Auto Memory accumulate project-specific tacit knowledge.
Practical Usage
The /memory Command
Running /memory during a session opens a file selector that lets you edit MEMORY.md and CLAUDE.md files directly in your system editor. The Auto Memory entry point is also available as a selection.
Explicit Memory Instructions
You can directly tell Claude to remember specific information:
"Remember that we use pnpm"
"Save to memory that API tests require a local Redis instance"
"Remember that this project uses ESM module format"
Environment Variable Control
Auto Memory is being rolled out gradually. You can control it explicitly via environment variables:
# Force enable
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0
# Force disable
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1Note the double-negative naming: DISABLE=0 means "don't disable" = enable. If you don't set the variable at all, it's automatically determined by the gradual rollout.
Best Practices for MEMORY.md
The golden rule is to keep MEMORY.md under 200 lines. Move detailed information into topic files and link to them from MEMORY.md:
# Project Memory
## Build & Test
- Build: `pnpm build`, Test: `pnpm test`
- Details → debugging.md
## Architecture
- Next.js 15 App Router + Tailwind CSS
- Details → architecture.mdComparison with Other AI Agents' Memory Features
"AI writing its own notes" isn't unique to Claude Code. As of 2026, major AI coding agents each take their own approach to cross-session memory.
| Tool | Instruction File | AI-Written Notes | Key Feature |
|---|---|---|---|
| Claude Code | CLAUDE.md | Auto Memory (memory/) | Two-tier loading, 200-line index |
| Gemini CLI | GEMINI.md | save_memory (within GEMINI.md) | Auto-appends to a dedicated section in the instruction file |
| Codex CLI | AGENTS.md | In development | Three-tier instruction hierarchy, .override.md support |
| Windsurf | Rules settings | Memories | IDE-integrated, user-defined + automatic memory |
| Cursor | .cursorrules | None | Notepad feature for context retention |
| Cline | External integrations | None | Session-only, supplemented by external tools |
Gemini CLI's save_memory
Gemini CLI uses the save_memory tool to automatically append facts to the ## Gemini Added Memories section in ~/.gemini/GEMINI.md. It's the approach most similar to Claude Code's Auto Memory, but differs in that memory lives inside the instruction file. Claude Code separates memory into its own memory/ directory, enabling structured organization via topic files.
Codex CLI's AGENTS.md
OpenAI Codex CLI manages AGENTS.md at three levels: global, project, and subdirectory. It has arguably the most refined instruction hierarchy, but as of now, it's user-written only. An AI-driven auto-learning feature is being discussed in Issue #8368 but hasn't been formally implemented.
Windsurf's Memories
Windsurf offers IDE-integrated memory with both user-defined and automatic memory capabilities. Its ability to remember project details and repository-specific rules across sessions is conceptually close to Auto Memory.
Relationship with MCP Memory Tools
Before Auto Memory, maintaining cross-session memory required setting up an MCP (Model Context Protocol) memory server yourself.
| MCP Memory Tool | Overview |
|---|---|
Serena (write_memory/read_memory) | Save and restore project context and design decisions by memory name |
| Basic Memory | Build a local Markdown knowledge base, referenced via MCP |
| OpenMemory (Mem0) | Local-first shared memory layer, cross-tool coordination |
| mcp-memory-service | Persistent memory with vector search |
All of these were developed to solve the same problem: "AI forgets everything when the session changes."
Cases Where Auto Memory Makes These Unnecessary
Auto Memory natively covers the primary use cases of these MCP memory tools:
- Recording project patterns → Auto Memory records automatically
- Accumulating debugging insights → Categorized into topic files
- Learning user preferences → Applied automatically
- Maintaining cross-session context → MEMORY.md loaded every session
No installation, configuration, or maintenance of MCP servers required — the same functionality works out of the box.
When MCP Memory Tools Are Still Needed
Auto Memory isn't a silver bullet. The following cases still benefit from MCP memory tools:
- Cross-tool memory sharing: Auto Memory is exclusive to Claude Code. If you need to share memory with Cursor or Windsurf, tools like OpenMemory are necessary
- Semantic search via vector embeddings: Auto Memory is file-based. For semantic similarity search across large knowledge bases, mcp-memory-service has the edge
- Team knowledge sharing: Auto Memory is personal (under
~/.claude/). To share tacit knowledge across a team, you need CLAUDE.md or external tools
For Serena specifically, memory is a secondary feature — its core value lies in semantic code operations (find_symbol, replace_symbol_body, etc.). Auto Memory replaces Serena's memory capabilities, but its symbol manipulation features remain uniquely valuable.
Summary
Auto Memory represents a major step forward in cross-session context management for AI coding assistants. The two-tier design — a 200-line index plus on-demand topic files — strikes an elegant balance between context window constraints and knowledge persistence.
Other agents are tackling the same challenge: Gemini CLI's save_memory, Windsurf's Memories, and others show that "AI writing its own learning notes" is becoming a 2026 standard. The fact that cross-session memory, previously only achievable through MCP servers, is now available as a native feature also dramatically reduces development environment setup costs.
By using manual CLAUDE.md and Auto Memory in tandem, project-specific tacit knowledge accumulates across sessions rather than being lost, steadily improving the development experience. At ZenChAIne, we use Auto Memory daily and have found it especially impactful for managing project-specific knowledge across multi-repository setups.