Auto Memory
Knowledge
Claude's Own Notes
While you consciously define rules in CLAUDE.md, Claude Code has a second memory system: Auto Memory. Here Claude itself writes notes about things it learns while working with you -- and reads them back automatically in the next session.
The memory file is located at:
~/.claude/projects/<repo-hash>/memory/MEMORY.md
The path is derived from the repository path. All worktrees of the same repo share a memory directory -- so if you learn something in a feature branch, Claude knows it in the main branch too.
iLoading Limit
At session start, the first 200 lines of the memory file are loaded. Keep your memory file compact so that the most important entries are at the top.
What Does Claude Remember?
Typical contents that Claude saves in Auto Memory:
- Build commands: "For this project,
npm run generatemust run before the build" - Debug insights: "The error in the auth middleware was caused by missing CORS headers"
- Your preferences: "User prefers short commit messages without emoji"
- Project quirks: "The API under /legacy still uses Express v4 syntax"
- Successful strategies: "For MDX errors, always check mdx-components.tsx first"
Cross-Session Learning
What makes Auto Memory special: It bridges the gap between sessions. Without Memory, Claude forgets everything it learned at the end of each session. With Memory, Claude builds a growing understanding of your project and your working style.
Session 1: You explain to Claude that tests in this project run with pnpm vitest run instead of npm test. Claude remembers this.
Session 2: Claude already knows to use pnpm vitest run -- without you having to say it again.
*Observe Memory in Action
With the /memory command, you can view and edit Claude's current memory file. This way you see exactly what Claude has remembered and can correct false or outdated entries.
Understanding
Controlling and Disabling Memory
Auto Memory is active by default but can be controlled in various ways:
/memory-- Opens the memory file for manual editingautoMemoryEnabled: false-- Disables Auto Memory in the settings- Manual deletion -- The memory file under
~/.claude/projects/can be deleted at any time
Memory Scopes for Subagents
When you work with subagents (more on this in a later module), they can have their own memory directories. There are three scopes:
| Scope | Description | Path |
|---|---|---|
| user | Global user memories | ~/.claude/memory/ |
| project | Project-specific memories | ~/.claude/projects/<repo>/memory/ |
| local | Only for this subagent | In the agent's working directory |
Memory vs. CLAUDE.md -- When to Use What?
| CLAUDE.md | Auto Memory | |
|---|---|---|
| Who writes | You | Claude |
| Purpose | Fixed rules and context | Learned insights |
| Shared via Git | Yes (project root) | No (local) |
| Structure | Organized by you | Managed by Claude |
| Example | "Use pnpm instead of npm" | "User prefers detailed explanations" |
The two systems complement each other perfectly: CLAUDE.md contains the rules you consciously define. Auto Memory collects the insights that emerge from daily collaboration.
Why do all worktrees of the same repo share a memory directory?