Claude Code memory: CLAUDE.md, auto memory, and when to use an external store
Every Claude Code session starts with a fresh context window. Two built-in layers carry knowledge forward, and they are easy to confuse. Knowing which one owns a fact, and where both stop, makes the setup easier to trust and to check.
Claude Code has two memory systems
Each Claude Code session begins with an empty context window. Anything it knows about your project at the start of a session arrives through one of two mechanisms that Anthropic’s documentation describes side by side: CLAUDE.md files, which you write, and auto memory, which Claude writes for itself.
The split is about authorship and purpose. CLAUDE.md holds instructions and rules: build commands, conventions, architecture notes, the things you would otherwise explain again. Auto memory holds learnings: your preferences, corrections you have given, and project context that Claude cannot derive from the code. Both are loaded at the start of every conversation.
Both are also context rather than configuration. The documentation is explicit that Claude reads these files and tries to follow them, but that loading an instruction does not enforce it. When something must happen every time, such as a check before a commit, the documented tool is a hook, which runs as a shell command at a fixed point in the session.
Sources: Anthropic, How Claude remembers your project (Claude Code); Anthropic, Hooks guide (Claude Code)
CLAUDE.md: instructions you write and version
CLAUDE.md files can live at several scopes. A project file at ./CLAUDE.md or ./.claude/CLAUDE.md is committed and shared with everyone who works in the repository. A user file at ~/.claude/CLAUDE.md applies to all of your projects. A CLAUDE.local.md at the project root holds personal, project-specific notes and belongs in .gitignore. Organizations can also deploy a managed file that individual settings cannot exclude.
Loading follows the directory tree. When a session starts, Claude Code reads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it, and concatenates them from the filesystem root downward, so the files closest to where you launched are read last. Files in subdirectories are not loaded at launch; each one loads when Claude reads or edits a file in that subdirectory.
Two features keep a growing file manageable. An @path line imports another file, up to four hops deep, which helps organization but does not reduce context, because imported files load at launch too. Files in .claude/rules/ split instructions by topic, and a rule with paths frontmatter loads only when Claude works with matching files. The documentation recommends keeping each CLAUDE.md under about 200 lines, since longer files consume more context and reduce adherence. Running /init generates a starting file from the codebase.
If a repository already uses AGENTS.md for other coding agents, recent versions of Claude Code (v2.1.277 and later) read it as the project instructions when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. When both exist, Claude reads only the CLAUDE.md files by default. A CLAUDE.md that contains an @AGENTS.md import keeps one shared file for every tool. Note that adding a personal CLAUDE.local.md to such a repository counts as a CLAUDE.md and stops AGENTS.md from loading for you unless you change the Project instructions setting.
Sources: Anthropic, How Claude remembers your project (Claude Code); AGENTS.md open format
Auto memory: notes Claude writes for itself
Auto memory lets Claude accumulate knowledge across sessions without you writing anything. It is on by default in local sessions. Claude records four kinds of notes, marked by a type field: user (your role and working preferences), feedback (corrections and approaches you confirmed), project (ongoing work, deadlines, and decisions it cannot derive from the code or git history), and reference (where to find outside information, such as an issue tracker). It skips anything the codebase or your CLAUDE.md files already say, and it does not save something every session.
Each project gets a memory directory at ~/.claude/projects/<project>/memory/, derived from the git repository, so all worktrees and subdirectories of one repository share it. The directory holds a MEMORY.md index with one line per memory and a topic file for each memory. Only the first 200 lines or 25 KB of MEMORY.md, whichever comes first, load at the start of a conversation. Topic files are read on demand, when Claude decides it needs them.
Everything is plain Markdown you can read, edit, or delete. The /memory command lists your memory files, opens the auto memory folder, and toggles the feature, which is stored as autoMemoryEnabled in your settings. Setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off from the environment. Asking Claude to remember something, such as always using pnpm, saves it to auto memory; asking it to add a line to CLAUDE.md puts the instruction in the file you control instead.
One boundary matters more than the others: auto memory is machine-local. The documentation states that these files are not shared across machines or cloud environments. The main conversation’s auto memory is also not loaded into subagents, apart from a fork of the current conversation.
Sources: Anthropic, How Claude remembers your project (Claude Code)
Where the built-in layers stop
CLAUDE.md travels with the repository, and auto memory stays on one machine for one client. That covers a single developer working in Claude Code on one computer well. It leaves three gaps: a laptop and a server that should share what was learned, a second agent such as Codex that should read the same decisions, and a decision that should keep a pointer to the evidence behind it. A Markdown note records what was concluded, not which document revision it came from.
Claude Code reaches outside services through the Model Context Protocol, an open standard for connecting AI applications to tools and data. The documentation recommends the HTTP transport for remote servers, added with a command of the form claude mcp add --transport http <name> <url>. A memory or workspace service connected this way is a separate store that any authorized client can read and write, so the same records can reach several machines and several agents.
The tradeoffs are real. The service must be running, reachable, and authorized, and a protocol name alone does not guarantee a working connection for every client. Anthropic advises verifying that you trust each server before connecting it, because servers that fetch outside content can expose a session to prompt injection. A hosted service receives the records you send. Connecting a store also does not import earlier conversations: useful context still has to be saved deliberately, and checked when it comes back.
Sources: Anthropic, Connect Claude Code to tools via MCP; Model Context Protocol
Decide where each piece of context lives
The layers overlap, so the practical question is which one should own a given fact. One rule prevents most conflicts: keep each fact or rule in exactly one place, and choose the place by how it has to behave.
Choosing where Claude Code context should live
- StartWrite the rules downPut the rules every session needs in a short project CLAUDE.md, and move narrow guidance into path-scoped rules.
- ObserveLet auto memory learnKeep auto memory on for preferences and corrections, then review MEMORY.md with /memory.
- DecideMove shared records outWhen another machine or agent needs the context, or a decision needs its source, store it in an external service.
- CheckTest the layer you rely onStart a fresh session and confirm which files and records actually arrived.
One source of truth per item. A rule duplicated across layers makes conflicts hard to trace.
| What you have | Where it belongs | Why |
|---|---|---|
| A rule every session must see | Project CLAUDE.md, committed | It loads at launch for everyone and changes through review with the code. |
| A personal default across repositories | ~/.claude/CLAUDE.md or ~/.claude/rules/ | It applies in every project without being committed to any of them. |
| Guidance for one part of the codebase | .claude/rules/ with paths frontmatter | It loads only when Claude touches matching files, which saves context. |
| A correction learned while working | Auto memory, reviewed with /memory | Claude captures it without effort, but the note is generated and can go stale. |
| Context another machine or agent must read | An external store over MCP | Auto memory is machine-local and specific to Claude Code. |
| A decision that must keep its source | An external store with source revisions | A claim can point back to the revision behind it, so the evidence stays inspectable. |
| An action that must always run | A hook | Memory is context; a hook executes regardless of what Claude decides. |
| A secret or credential | None of these | Memory files are plain text and external stores can be shared beyond their intended scope. |
In practice the sequence is short. Write the non-negotiable rules into CLAUDE.md first. Leave auto memory on for the softer preferences you are willing to review. Reach for an external store only when context has to cross a machine, a client, or an audit trail. Then check each layer instead of assuming it works.
Sources: Anthropic, How Claude remembers your project (Claude Code); Anthropic, Hooks guide (Claude Code)
Check which layer actually worked
When Claude seems to remember something, it helps to know which mechanism supplied it. A few repeatable checks cover all three layers.
- Instruction check: run /context in a new session and compare the list under Memory files with the CLAUDE.md files you expected. A subdirectory file will not appear there until Claude touches that subdirectory.
- Auto memory check: open /memory, select the auto memory folder, and read MEMORY.md and the topic file you expected. In the interface, messages such as Saved 2 memories or Recalled 2 memories show Claude reading or writing that directory.
- Load tracing: an InstructionsLoaded hook can log which CLAUDE.md and rules files loaded, when, and why, which helps with path-scoped rules.
- Second machine check: open the same repository on another computer and ask about a preference Claude learned on the first. Auto memory is documented as machine-local, so a gap here is expected rather than a bug.
- Negative check: ask about something you never saved. A trustworthy setup reports that it does not know instead of inventing a recollection.
- Compaction check: after /compact, the project-root CLAUDE.md is re-read from disk. An instruction given only in conversation can disappear, which is a sign it belongs in a file.
Recording the input, the saved state, what was loaded, and the final answer turns one convincing demonstration into a pattern you can judge. A failure at any of those steps looks like forgetting, so it matters which step you actually observed.
Sources: Anthropic, How Claude remembers your project (Claude Code)
What no layer promises
None of these mechanisms guarantees that the right context arrives or that Claude follows it. CLAUDE.md loading is predictable, but it reflects only what someone wrote, and instructions compete for attention as files grow. Auto memory is convenient, but it is generated, bounded by the MEMORY.md index limit, and confined to one machine. An external store can serve several machines and agents and keep sources, but it depends on a reachable, trusted, authorized service, and its storage and processing boundaries depend on how it is hosted.
Defaults change between releases. Several behaviors described here, including reading AGENTS.md directly, depend on recent Claude Code versions, so confirm current behavior on the official page before relying on a detail. The goal is not to pick one winner. It is to put each kind of context where it can do its job, then check that it did.
Sources: Anthropic, How Claude remembers your project (Claude Code)