When using Claude Code, you may notice a message in its chain-of-thought (CoT) saying something like "I'll record this in memory."
"Memory? I didn't set anything up." If that's your reaction, you're not alone. This is Claude Code's auto memory feature in action, and the file behind it is MEMORY.md.
The Basics of MEMORY.md
MEMORY.md is managed by Claude Code's auto memory feature. It's created per project at the following path:
~/.claude/projects//memory/
├── MEMORY.md # Index (loaded every session)
├── debugging.md # Topic files (loaded on demand)
├── api-conventions.md
└── ... There are two ways information gets recorded:
- Explicit recording: Tell Claude Code "remember this" or "don't forget," and it writes to memory
- Automatic recording: When Claude Code finds a debugging solution or learns a build command quirk, it proactively saves information it judges useful for future sessions
MEMORY.md is loaded at the start of every session, so learnings from the previous session carry over to the next.
How It Differs from CLAUDE.md
Both MEMORY.md and CLAUDE.md are loaded at session start, but they serve different roles.
| CLAUDE.md | MEMORY.md | |
|---|---|---|
| Created by | Developer (human) | Claude Code (agent) |
| Editing | Not edited unless instructed | Claude Code edits proactively |
| Location | Within project folder | ~/.claude/projects/ (user folder) |
| Nature | Project "constitution" | Agent's "working notes" |
| Git tracked | Typically committed | Not tracked (machine-local) |
| Team sharing | Suitable | Not suitable |
| Authority | Loaded as context | Same authority as CLAUDE.md |
The key point is that MEMORY.md is machine-local. Even within the same Git repository, different content accumulates per developer and per machine. It's not the right place for information you want to share across your team.
Use Cases
Here are typical scenarios where MEMORY.md shines:
- Absorbing environment differences: When your team mixes Windows and macOS, recording file path differences and command variations in MEMORY.md helps the agent produce environment-appropriate output
- Temporary tool restrictions: Tell Claude Code "don't use this tool for now" during debugging, and the restriction persists across sessions via MEMORY.md
- Build and test quirks: Special flags for build commands or environment-specific test procedures are learned automatically
Organizing Information in Team Development
Understanding MEMORY.md's characteristics helps you organize where information belongs in a team setting.
Team-shared information (committed to the repository)
- CLAUDE.md: Coding conventions, architecture policies, workflow definitions
- ADR documents / sqlew: Design decisions and their rationale (the "Why"), with structured querying
Machine/environment-specific information (stays local)
- MEMORY.md: Machine-specific paths, personal working notes, temporary constraints
By maintaining this separation, you avoid mixing "shared design knowledge" with "personal working context."
References
- "How Claude remembers your project" — Claude Code Docs — https://code.claude.com/docs/en/memory
