Claude Code Memory: What It Remembers, Where It Lives, How to Clear It

November 2, 2026

Claude Code carries files between sessions, never the conversation itself. Each session begins with a fresh context window and picks up two things from earlier work: the CLAUDE.md files you write, and the notes Claude writes for itself, called auto memory.

Claude Code's memory is plain markdown you can open, edit and delete. Knowing which file holds what is how you fix a Claude that keeps forgetting a rule, or one that keeps acting on a note that stopped being true.

What Claude Code remembers between sessions

Six kinds of stored state, and a new session loads three of them by itself: your CLAUDE.md files, rules without a paths field, and the auto memory index.

All of it is context. Claude reads it and weighs it, and nothing in these files can stop an action, so a rule that must hold every time goes in a PreToolUse hook. CLAUDE.md is the layer you control completely, and writing one that works is a separate job: see how to write a CLAUDE.md Claude follows.

What a new session forgets

The conversation: every message, file read and correction you typed in chat. /clear starts fresh on a new task while keeping project memory, and the conversation you left stays on disk for /resume.

Resuming is a different thing from memory. It reloads the old session itself: the messages, tool calls and results, the model, and the agent it ran as. A session that was compacted reopens at its last summary. Launch flags like --mcp-config or --add-dir aren't restored, so pass them again. On Pro, Max and Ultra plans, resuming a long conversation after a long break or on a different model can bring up a dialog that estimates the share of your 5-hour usage limit the saved conversation alone would use.

Resume when the next step needs the reasoning, like a bug you were halfway through. Start fresh when it needs only the conclusions, and make sure they're stored before you leave. Auto memory doesn't save something every session, so say "remember that we chose Postgres for the queue" out loud, or ask Claude to add it to CLAUDE.md. For choosing between /clear and /compact, read the Claude Code best practices.

How auto memory decides what to keep

Claude saves four kinds of notes and skips everything else. Each memory file records its kind in a type field: user for your role and preferences, feedback for corrections and approaches you confirmed, project for deadlines and decisions it can't read from the code, and reference for where outside information lives, such as an issue tracker. It leaves out anything derivable from the codebase and anything your CLAUDE.md already says.

You can watch it work. "Saved 2 memories" or "Recalled 2 memories" in the interface means Claude is writing to or reading from the memory folder right then. Claude Code records the write time in a modified front-matter field. Check it before trusting an old note.

MEMORY.md is an index, one line per memory, and the detail sits in topic files that load on demand. Past the read limit a write still succeeds, but Claude gets an error telling it to rewrite the index, because the overflow is dropped at the next load.

Scope is one git repository. Every worktree and subfolder of a repo shares a single memory folder, and the files never leave your machine, so another computer or a cloud session starts with none of it.

Keep it on: it picks up your corrections without you writing anything down. Notes don't expire, though. MEMORY.md and topic files stay until you or Claude edits or deletes them, so a note about a deadline or a renamed folder outlives the fact.

Check what a session actually loaded

Run two commands in the session, then two in your shell:

/context
/memory

ls ~/.claude/projects/*/memory/MEMORY.md
wc -l -c ~/.claude/projects/<project>/memory/MEMORY.md

1. /context gives a live breakdown of the context window, including which CLAUDE.md and auto memory files loaded. Look under Memory files. A file missing there is one Claude never saw.
2. /memory lists every CLAUDE.md location for your user and project, holds the auto memory toggle, and offers to open the auto memory folder. Pick any file and it opens in your editor.
3. The ls line shows which projects on this machine have an index at all.
4. wc prints the line and byte count. Over 200 lines or 25KB, the bottom of the file was invisible at startup.

A subfolder CLAUDE.md won't show in /context until it loads, and then a Loaded line with its path appears in the terminal. To log every load with the reason, add an InstructionsLoaded hook, which fires for each CLAUDE.md and rules file as it enters context; the setup is the same as for any event in our Claude Code hooks guide. When Claude ignores something you're sure you told it, start with /context.

A prompt to tidy auto memory

Paste this into a session in the project whose notes you want cleaned. Claude reports first and changes nothing until you approve:

Audit your auto memory for this project. Read MEMORY.md and every
topic file in the memory folder.

For each memory, give me one line: file name, type, modified date,
and one verdict:
- KEEP: still true and not stated anywhere else
- MERGE: says the same as another memory (name which one)
- DROP: already in a CLAUDE.md or .claude/rules file, derivable from
  the code or git history, or about a file, command or deadline that
  no longer exists (check before you say so)
- CHECK: you can't tell whether it's still true

Then draft a new MEMORY.md: one line per entry, detail moved into
topic files, under 200 lines.

Don't edit, merge or delete anything until I reply with the
verdicts I approve.

The criteria are the ones Claude Code itself uses when it reminds Claude to shorten the index: one line per entry, detail in topic files, stale entries merged or dropped. Run it when wc shows the index near 200 lines, or after the project changes direction.

How to turn auto memory off

Flip the toggle in /memory, or set it in a settings file or the environment:

• In a session: the switch in /memory saves autoMemoryEnabled to ~/.claude/settings.json.
• One project: put "autoMemoryEnabled": false in that project's settings.
• From the environment: set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Setting it to 0 forces auto memory on even when --bare or autoMemoryEnabled: false would disable it.

Off means Claude doesn't read from or write to the auto memory directory. Existing notes stay on disk. In a background session, or one another Claude Code session started, the toggle can switch memory off and can't switch it back on. Start claude in your own terminal for that.

To keep the notes somewhere else, set autoMemoryDirectory to an absolute path or one starting with ~/. To wipe a project, run claude purge <path>. It deletes that project's transcripts and auto memory after printing the plan and asking you to confirm, and --dry-run prints the plan alone.

Turn it off per project for a repo where Claude should know only what's committed, such as a shared demo. Turn it off globally only if you don't want any notes you didn't write yourself.

What survives /compact

What loaded at startup comes back from disk. What lived only in the conversation becomes part of the summary. The docs list what happens to each kind of content:

To steer the summary, give /compact a focus, as in /compact focus on the auth bug fix. A rule that must survive every compaction belongs in the project-root CLAUDE.md or in a rule with no paths line.

Memory in subagents

Subagents don't get your auto memory, and each one can keep its own. Only a fork inherits the parent conversation. The memory front-matter field gives an agent a folder of its own, in one of the three scopes from the table above:

---
name: code-reviewer
description: Reviews changed code for bugs and repo conventions. Use after edits.
memory: project
---
Before a review, check your memory for issues you've seen in this repo.
After it, save any new recurring issue to your memory.

With memory set, the agent's system prompt carries the first 200 lines or 25KB of its own MEMORY.md, and Read, Write and Edit are switched on so it can maintain the folder. Anthropic suggests project as the default, since that folder can go into version control. Turning auto memory off disables the field too.

Give memory to agents that do the same job over and over, like a reviewer. Leave it off any agent that must stay read-only, because the field hands it write access. The other fields are in our guide to Claude Code subagents.

When a memory plugin is worth adding

When you need to search what happened in past sessions. Built-in memory keeps conclusions, and transcripts are kept for resuming and deleted after cleanupPeriodDays, 30 days unless you change it.

Claude-Mem is a community plugin that records each session, summarizes it and feeds the relevant parts back next time. Add it for long projects where you keep asking "how did we fix that last month?". For preferences and corrections, auto memory already does the job.

One name clash to clear up: the memory tool in Anthropic's API docs belongs to apps you build on the API. There, Claude requests the file operations and your application runs them. It isn't a Claude Code setting.

Sources

• Anthropic, How Claude remembers your project, Claude Code Docs, accessed November 2026
• Anthropic, Explore the context window, Claude Code Docs, the section on what survives compaction, accessed November 2026
• Anthropic, Manage sessions, Claude Code Docs, accessed November 2026
• Anthropic, Create custom subagents, Claude Code Docs, for the memory field and its three scopes, accessed November 2026
• Anthropic, Explore the .claude directory, Claude Code Docs, accessed November 2026
• Anthropic, Settings reference, Claude Code Docs, entries for autoMemoryEnabled, autoMemoryDirectory and cleanupPeriodDays, accessed November 2026
• Anthropic, Memory tool, Claude Platform Docs, accessed November 2026