Claude Code Auto Memory: How It Works and How to Use It
A practical guide to Claude Code's auto memory feature — how it works, how it differs from CLAUDE.md, and how to share knowledge across projects.
Claude Code recently shipped a feature called auto memory — a persistent memory system that lets Claude remember patterns, lessons, and context across sessions. Instead of re-explaining your project architecture every time you start a new conversation, Claude picks up where it left off.
Here’s how it works and how to get the most out of it.
What Is Auto Memory?
Auto memory is a persistent directory where Claude automatically saves learnings as you work. Each project gets its own memory directory:
1
2
3
4
5
~/.claude/projects/<project-path>/memory/
├── MEMORY.md # Concise index (loaded every session)
├── debugging.md # Detailed debugging notes
├── ci-lessons.md # CI/CD lessons learned
└── patterns.md # Architecture patterns
The key file is MEMORY.md — the first 200 lines of this file are loaded into Claude’s system prompt at the start of every session. Think of it as Claude’s scratchpad for the project.
Topic files like debugging.md or ci-lessons.md aren’t loaded at startup. Claude reads them on demand when the context is relevant.
How It Differs from CLAUDE.md
This is the most common point of confusion. Both files influence Claude’s behavior, but they serve different purposes:
| MEMORY.md | CLAUDE.md | |
|---|---|---|
| Who writes it | Claude (automatically) | You (manually) |
| Purpose | Claude’s notes to itself — patterns learned, debugging insights | Your instructions to Claude — rules, conventions, commands |
| Loaded | First 200 lines only | Full file |
| Shared with team | No (local to your machine) | Yes (committed to git) |
| Location | ~/.claude/projects/<project>/memory/ |
Project root |
CLAUDE.md is your instruction manual for Claude. It tells Claude how to work on your project — what commands to run, what patterns to follow, what to avoid.
MEMORY.md is Claude’s own notebook. It records what it learned while working — that your CI pipeline needs IPv4 for database connections, that your Docker healthcheck fails with localhost on Alpine, that your Trigger.dev tasks need separate env vars from Dokploy.
They complement each other. CLAUDE.md sets the rules, MEMORY.md builds institutional knowledge.
Telling Claude What to Remember
You don’t need any special syntax. Just say it in natural language:
- “Remember that we always use pnpm instead of npm”
- “Save to memory that the staging DB is on port 5433”
- “Add to your memory that tests require Redis running locally”
Claude updates MEMORY.md (or creates a linked topic file) using its normal file editing tools. You can also edit the file directly — it’s just markdown.
The /memory command opens a file selector where you can browse and edit your memory files and CLAUDE.md in one place.
Sharing Memory Across Projects
Auto memory is per-project only. There’s no global auto memory location. But Claude Code has a hierarchy of instruction files that lets you share knowledge at different scopes:
| Scope | Location | Applies To |
|---|---|---|
| Global (you) | ~/.claude/CLAUDE.md |
All your projects |
| Project (team) | ./CLAUDE.md in repo root |
Everyone on this repo |
| Project rules | ./.claude/rules/*.md |
Everyone on this repo |
| Auto memory | ~/.claude/projects/<project>/memory/ |
Just you, this project only |
For patterns you want everywhere — coding preferences, tool conventions, common debugging approaches — create a user-level CLAUDE.md:
1
~/.claude/CLAUDE.md
Anything in this file loads automatically for every project you work on, regardless of which repo you’re in.
The 200-Line Limit
Only the first 200 lines of MEMORY.md load into Claude’s context at session start. This is intentional — it keeps the system prompt lean and forces concise documentation.
The recommended pattern:
- MEMORY.md acts as a concise index with summaries and links
- Topic files hold the detailed notes
For example:
1
2
3
4
5
6
7
8
9
10
# Project Memory
## Architecture
- Monorepo: packages/ + apps/
- Trigger.dev for job processing
- Cloudflare R2 for PDF storage
## CI/CD Lessons — see [ci-lessons.md](ci-lessons.md)
## Deployment Notes — see [deployment.md](deployment.md)
Claude reads the topic files on demand when it needs the details, so nothing is lost — it’s just not loaded upfront.
Enabling Auto Memory
Auto memory is being rolled out gradually. If you don’t see it in your sessions, force it on with an environment variable:
1
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0
Yes, it’s a double negative — DISABLE=0 means “don’t disable.” Set it to 1 to turn auto memory off.
The feature was introduced in Claude Code v2.1.32, with enhancements for configurable memory scopes in agents added in v2.1.33.
Key Takeaways
- Auto memory persists across sessions — Claude remembers what it learned last time without you re-explaining
- MEMORY.md is Claude’s notebook, CLAUDE.md is your instruction manual — they complement each other
- 200-line limit on MEMORY.md encourages concise summaries with links to detailed topic files
- Tell Claude what to remember in plain English — no special syntax needed
- Per-project only — use
~/.claude/CLAUDE.mdfor knowledge you want shared across all projects - Enable with
CLAUDE_CODE_DISABLE_AUTO_MEMORY=0if it’s not showing up
Resources
Published: February 2026