Developer guide
Claude Code Memory: How It Works, Where It's Stored, and How to Extend It
How Claude Code memory works: CLAUDE.md vs auto memory, where MEMORY.md lives, how to view, clear, or turn it off, why it forgets your last session, and when a plugin helps.
01
Claude Code has two memory systems: CLAUDE.md, which you write, and auto memory, which Claude writes.
02
Auto memory lives in ~/.claude/projects/<project>/memory/, and only the first 200 lines or 25 KB of MEMORY.md load at startup.
03
Memory is not chat history. To pick up a past conversation, use claude --continue or claude --resume.
01
Quick answer
Claude Code memory is two sets of Markdown files that load at the start of every session. CLAUDE.md holds instructions you write. Auto memory holds notes Claude writes for itself from your corrections and preferences.
Start with Claude Code's native memory. It covers project rules and personal preferences on one machine. Add a plugin or MCP memory server only when other AI tools need the same memory, when notes should point back to their sources, or when memory has to outlive one machine.
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What goes in it | Instructions: build commands, conventions, "always do X" rules | Learnings: your preferences, corrections, ongoing decisions |
| Scope | Project, user, or organization | One folder per Git repository |
| Loaded at startup | The whole file (aim for under 200 lines) | First 200 lines or 25 KB of MEMORY.md |
| Shared with teammates | Yes, if you commit the project file | No, it stays on your machine |
02
Where Claude Code stores memory
Auto memory is stored in ~/.claude/projects/<project>/memory/. The project name comes from the Git repository, so auto memory is per repository and shared across worktrees and subdirectories. Outside a Git repo, the project root is used instead.
MEMORY.md is an index with one line per memory, and each memory is its own topic file. Topic files are not loaded at startup; Claude opens them when it needs them.
Auto memory is machine-local. It is not synced to other computers or cloud sessions. To keep it somewhere else, set autoMemoryDirectory in settings.json to an absolute path or a path that starts with ~/.
~/.claude/projects/<project>/memory/
├── MEMORY.md # index, loaded every session
├── user_role.md # one memory per file
├── feedback_testing.md
└── ...03
Where CLAUDE.md files live
Claude Code loads CLAUDE.md files from your working directory and every folder above it, and combines them. A CLAUDE.md in a subfolder loads only when Claude works with files in that subfolder.
| File | Location | Use it for |
|---|---|---|
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Team rules, commands, and architecture notes. Commit it. |
| Personal, this project | ./CLAUDE.local.md | Your own sandbox URLs or test data. Add it to .gitignore. |
| Personal, all projects | ~/.claude/CLAUDE.md | Preferences you want in every project |
| Rules | .claude/rules/*.md | One topic per file, optionally limited to certain paths |
| Shared with other agents | ./AGENTS.md | Read in place of CLAUDE.md when the project has no CLAUDE.md (Claude Code v2.1.277+). Or keep CLAUDE.md and add the line @AGENTS.md to it. |
| Organization | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux/WSL: /etc/claude-code/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Company-wide instructions managed by IT |
04
Claude Code memory vs CLAUDE.md: what goes where
Put something in CLAUDE.md when it is a rule everyone on the project should follow in every session. Let auto memory hold what Claude learns about how you work.
When you tell Claude "remember that the API tests need a local Redis", it saves that to auto memory. To put it in CLAUDE.md instead, say "add this to CLAUDE.md" or edit the file yourself.
- CLAUDE.md: build and test commands, coding standards, naming rules, architecture decisions.
- Auto memory: your preferences, corrections you gave Claude, ongoing work Claude can't see in the code.
- Neither: multi-step procedures belong in a skill, and anything that must always happen belongs in a hook.
05
How to view, clear, or turn off Claude Code memory
Run /memory inside a session. It lists every CLAUDE.md and memory location, opens files in your editor, has an auto memory on/off toggle, and can open the auto memory folder.
Everything is plain Markdown. To clear auto memory, delete the topic files you no longer want and their lines in MEMORY.md. Claude Code cleans up old session transcripts, but memory files stay until you or Claude remove them.
- See what loaded: /context lists the CLAUDE.md files in this session under Memory files.
- Turn off auto memory everywhere: use the toggle in /memory, which saves autoMemoryEnabled to your user settings.
- Turn it off for one project: set "autoMemoryEnabled": false in that project's .claude/settings.json.
- Turn it off with an environment variable: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
{
"autoMemoryEnabled": false
}06
Why Claude Code doesn't remember your last session
Memory and conversation history are different things. A new session starts with an empty context window plus your memory files. It does not include what you said yesterday unless Claude saved it to auto memory.
To continue an earlier conversation, resume it instead of starting a new one. To carry decisions forward without replaying a whole transcript, write them down at the end of the session: ask Claude to update CLAUDE.md, or use a handoff tool.
claude --continue # reopen the most recent conversation in this folder
claude --resume # pick one from a list
/resume # switch conversations from inside a session07
Auto memory not working, or Claude ignoring CLAUDE.md
Memory files are context, not enforced settings. Claude reads them and tries to follow them, but vague or conflicting instructions get followed inconsistently.
- Run /context and check Memory files. If a CLAUDE.md is missing there, Claude can't see it.
- Remember that a CLAUDE.md in a subfolder loads only when Claude works in that subfolder.
- Keep MEMORY.md under 200 lines and 25 KB. Anything past that isn't loaded at startup.
- Look for conflicting rules across CLAUDE.md files and .claude/rules/. Claude may pick either one.
- Make instructions specific: "use 2-space indentation" works better than "format code nicely".
- If something must happen every time, such as before each commit, use a hook instead of a memory file.
- Check that autoMemoryEnabled or CLAUDE_CODE_DISABLE_AUTO_MEMORY hasn't turned auto memory off.
08
Claude Code memory plugins and MCP servers
Native memory has limits by design. It stays on one machine, each repository gets its own folder, tools such as Cursor or Codex can't read it, and notes don't point back to where they came from.
If those limits matter, add a memory tool. The common options solve different problems, so pick by what you're missing. GitHub star counts are from October 2026.
| Option | How it works | Good for |
|---|---|---|
| Native auto memory | Claude writes short Markdown notes per repository | Preferences and corrections on one machine |
| claude-mem (about 97,000 stars) | Records what the agent does each session, compresses it with AI, and injects relevant context into later sessions | Automatic session recall without writing notes |
| An MCP memory server | Stores memories behind MCP tools that any compatible client can call | Sharing memory between Claude Code, Cursor, Codex, and other MCP clients |
| Wenlan | Local MCP memory plus wiki pages that cite their sources and flag when a source changes | Project decisions and knowledge you want to read, check, and share across tools |
09
Add Wenlan to Claude Code
Wenlan is an open-source desktop app and Claude Code plugin. It keeps memory on your computer, turns related notes into wiki pages that cite their sources, and serves the same memory to Cursor, Codex, Claude Desktop, and other MCP clients.
Install the plugin, restart Claude Code if asked, then run /wenlan. Test one capture and one recall before relying on it for real project memory.
/plugin marketplace add wenlan-app/wenlan
/plugin install wenlan@7xuanlu-wenlan
/wenlan
/capture This project uses Wenlan for local AI work memory.
/recall local AI work memory10
The daily Wenlan loop in Claude Code
Wenlan does not replace /memory or CLAUDE.md. Keep stable project rules in CLAUDE.md, and use Wenlan for the part that keeps changing: decisions, lessons, gotchas, and project status that must reach the next session or another tool.
The plugin adds a short loop around real work. Most serious sessions need /brief at the start and /handoff at the end.
Claude Code runs the plugin and calls MCP tools; it does not store Wenlan's memory. Wenlan's local daemon owns the memory store, separate from CLAUDE.md and auto memory, and writes readable artifacts under ~/.wenlan: distilled pages in ~/.wenlan/pages, session logs and a read-only project-status receipt in ~/.wenlan/sessions, and local git history in ~/.wenlan/.git. Use Wenlan commands and tools for writes, review, distill, and delete rather than editing the database directly, and run ~/.wenlan/bin/wenlan status to check the daemon.
- /brief: load project status, recent handoffs, preferences, and relevant memories before edits begin.
- /capture: save one durable idea, such as a decision, gotcha, or constraint, and why it matters.
- /recall: look up a specific past decision or gotcha.
- /handoff: write what changed and what is still open, and store durable captures for the next session.
- /wenlan distill: turn repeated captures into wiki pages that cite their sources.
/brief
/capture <one durable project fact and why it matters>
/recall <specific prior decision or gotcha>
/handoffShare Claude Code memory with your other AI tools
Install the Wenlan plugin, run /wenlan, then test one capture and recall before adding real project context.
FAQ