How Claude Code's Memory Actually Persists Across Sessions

A session that begins with nothing

Every Claude Code session opens the same way: an empty conversation, a model that remembers nothing about the last one. There is no session-to-session weight update, no hidden cache of yesterday’s corrections. Anthropic’s own documentation states the starting condition plainly — each session begins with a fresh context window, and two separate mechanisms carry anything forward from the last one: files the developer writes, and notes the tool writes about itself ^[1].

“Memory” in this system does not mean what it means in a database or an operating system. Nothing is retained by default; persistence is a behavior someone opts into, by putting text somewhere the tool has agreed to read at the start of every session. The rest of this article is about that agreement: which places those are, what order they load in, what that order does and does not guarantee, what it costs, and what Anthropic documents about writing it well.

The angle matters because “hierarchy” is a loaded word in software. In most systems it implies override — a more specific rule replaces a more general one, the way a local git config beats the global one. Claude Code’s own documentation uses hierarchy language throughout, and it is easy to read that vocabulary and assume the same override semantics. The mechanics underneath are different, and the difference changes what a team can and cannot rely on the system to do.

Four scopes, one load order

Claude Code recognizes four places a memory file can live, and documents them as a single ordered list running from broadest scope to narrowest. At the top is a managed policy file, deployed by an organization’s IT or DevOps team to a fixed operating-system path — /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, an equivalent path under Program Files on Windows — intended for company-wide coding standards, security policy, and compliance language that applies to every user on that machine ^[1]. Below that sits a user file at ~/.claude/CLAUDE.md, for an individual’s personal preferences across every project they touch. Below that, a project file at ./CLAUDE.md or ./.claude/CLAUDE.md, checked into source control and shared with a team. And at the bottom, a local file, ./CLAUDE.local.md, meant to stay out of version control entirely, for a developer’s own sandbox URLs or test fixtures.

The documentation is explicit that this list is ordered “from broadest scope to most specific, so a project instruction appears in context after a user instruction” ^[1]. That phrase — “appears in context after” — is the first hint that something other than classic override is happening, and it is the subject of the next section.

Two structural details round out the picture. First, the walk is not limited to these four named locations: Claude Code also reads CLAUDE.md files from every directory between the filesystem root and wherever a session was launched, and it will pick up further CLAUDE.md files in subdirectories on demand, the moment Claude reads a file that lives there ^[1]. A monorepo can therefore accumulate a stack of these files five or six deep without anyone having designed a “four-tier” system at all — the four named scopes are the well-known stops on a walk that is really just “every directory on the way to here.” Second, the managed policy file is described differently from the rest: its precedence is stated as absolute, it “cannot be excluded by individual settings,” and it is the one tier the documentation frames in genuinely enforceable terms, because an organization deploying it controls the machine, not just the prompt ^[1]. That distinction — between a scope backed by filesystem permissions and a scope that is just text arriving earlier — turns out to matter more than the four-tier diagram suggests.

Concatenation, not override

Here is the mechanism, stated as directly as the documentation states it: “All discovered files are concatenated into context rather than overriding each other” ^[1]. Every CLAUDE.md and CLAUDE.local.md file found along the walk from the filesystem root down to the working directory is loaded in full. None of them is dropped because a more specific one exists. The four-scope table is not a precedence ladder in the sense a systems engineer would normally use that word — it is a concatenation order. Files closer to the root are read first; files closer to the working directory are read last; within a single directory, CLAUDE.local.md is appended after CLAUDE.md, so a developer’s own notes are the last thing read at that level ^[1].

Reading order is not a small thing — position within a prompt shapes how strongly a model weighs an instruction. But it is a different guarantee than override, and the gap shows up the moment two files disagree. If a user-scope file says two-space indentation and a project file says four spaces, the documentation’s own troubleshooting guidance does not say the project rule wins by rule; it says Claude “may pick one arbitrarily” and recommends removing the conflict by hand ^[1]. A real override system needs no such caveat, because nothing is left to arbitrate once the specific rule replaces the general one. Claude Code’s memory system needs it because nothing is ever replaced — everything is still sitting in the window, and a probabilistic model is doing the arbitrating a human should have done.

This is where the managed policy tier’s stricter language earns its keep. The documentation separates what CLAUDE.md files do from what settings do in one load-bearing sentence: “Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer” ^[1]. For anything that must hold with certainty — blocking a dangerous command, guaranteeing a check runs before every commit — the documented advice is a PreToolUse hook or a permissions rule, both of which execute as code, not prompt ^[1]. CLAUDE.md’s hierarchy governs what gets read and in what order; it does not, on its own, govern what gets obeyed.

What actually loads before a word is typed

Anthropic ships an interactive walkthrough of a representative session specifically to make this loading concrete, breaking startup context down by component with illustrative token counts: a system prompt around 4,200 tokens, an auto-memory index around 680 tokens, environment information around 280 tokens, MCP tool names around 120 tokens with full schemas deferred until needed, then a global CLAUDE.md around 320 tokens and a project CLAUDE.md around 1,800 tokens in that particular worked example ^[4]. The documentation is careful to call these “representative numbers” rather than fixed constants — actual figures move with every project’s own files — but the shape they describe is stable and worth writing down as an identity:

where $M_i$ is the token count of the $i$-th memory file discovered along the walk from the filesystem root to the working directory, summed over however many, $k$, are found. Every term is committed before the developer types a word. The point is not the specific numbers; it is that $T_{\mathrm{start}}$ is arithmetic settled at launch, and every additional CLAUDE.md file anyone commits to a repository is a term someone chose to add to it, permanently, for the rest of that session.

The same documentation points to /context as the way to check the real figure for an actual session, and to a companion command, /doctor, that inspects a checked-in CLAUDE.md and proposes trims — cutting content Claude can already derive from the codebase while keeping the pitfalls and non-default conventions it cannot infer ^[1]. That such a command exists is itself evidence of how the mechanism behaves: a tool built to trim a memory file is a tool built for a budget memory competes inside, not a policy layer sitting outside it.

A second channel, written by the tool itself

CLAUDE.md is not the only persistence mechanism, and the second one is instructive because it is built the opposite way. Auto memory lets Claude keep notes for itself across sessions — build commands it worked out the hard way, debugging insight, a preference it was corrected on — without a developer writing anything ^[1]. It lives in a per-project directory keyed to the git repository, so every worktree of the same repo shares one memory store, and it is organized around a single entry point, MEMORY.md, that acts as an index into topic files Claude creates as needed, such as debugging.md or api-conventions.md ^[1].

What keeps this channel from becoming its own runaway budget line is a hard limit rather than a soft one: only the first 200 lines of MEMORY.md, or the first 25 kilobytes, whichever is smaller, load at session start, and anything past that point is silently dropped on the next load ^[1]. As the index nears that ceiling the tool is instructed to shorten it — move detail into topic files, merge stale entries — and a write that exceeds the ceiling still succeeds but returns an error telling it to rewrite the index down ^[1]. Topic files themselves are not loaded at startup; they are read on demand, only when needed ^[1]. It is a genuinely different design from CLAUDE.md, which loads in full “regardless of length, though shorter files produce better adherence” ^[1] — one channel is capped by the system that reads it, the other only by the discipline of whoever writes it.

Writing a file that actually gets followed

Anthropic’s guidance on authoring CLAUDE.md is unusually specific for what is, mechanically, just a markdown file loaded into a prompt, and the specificity follows directly from everything above: because nothing here is enforced, adherence depends entirely on how the instructions are written. The headline number is a length target — “under 200 lines per CLAUDE.md file,” with the explicit warning that “longer files consume more context and reduce adherence” ^[1]. The best-practices guide sharpens this into a rule of thumb: for every line, ask whether removing it would actually cause Claude to make a mistake, and if the answer is no, cut it, because “bloated CLAUDE.md files cause Claude to ignore your actual instructions” ^[2].

The same guide gives a concrete table of what belongs and what doesn’t: bash commands Claude cannot guess, code style rules that differ from language defaults, testing instructions, repository etiquette, and non-obvious gotchas belong; anything Claude can already work out by reading the code, or standard language conventions, do not ^[2]. Specificity is treated as measurable, not a style preference — “use 2-space indentation” is the model example of an instruction concrete enough to verify, against “format code properly” as one that is not ^[2]. The documentation even permits leaning on emphasis explicitly, noting that words like “IMPORTANT” or “YOU MUST” can measurably improve adherence ^[2] — a telling admission that this is a prompt engineered for compliance, not a config file parsed for correctness.

Structural tools exist for content that does not belong in every session’s fixed cost at all. Path-scoped rules, kept in .claude/rules/ with frontmatter naming the file glob they apply to, load only when Claude works with a matching file ^[1]. Skills go further, staying out of context entirely until invoked or judged relevant ^[2]. Both exist for the reason auto memory’s cap exists: the fixed-cost portion of a session is the resource everyone is actually managing, whatever the vocabulary of scopes makes it look like.

The trade-off: nearly free in dollars, expensive in attention

This is where the two costs a memory system incurs need to be pulled apart, because they move in opposite directions and conflating them is the most common way to misjudge the trade-off.

The dollar cost of re-reading the same CLAUDE.md content every turn is close to solved. Anthropic’s prompt caching system lets a stable prefix — system prompt, memory files, tool definitions, anything identical from one request to the next — be written to a cache once and then reused. A cache write costs a documented 1.25 times the base price of an input token; a cache read, on every subsequent turn that reuses it, costs a documented one-tenth of that base price ^[5]. For a stable prefix of $T_p$ tokens reused across $n$ turns of a session, against a per-token base price $c$, the total cost of that prefix is

where the final sum covers each turn’s own variable content. Past the first turn, every further read of the same CLAUDE.md content costs a tenth of an uncached read — caching is specifically recommended for exactly this kind of content, described in the documentation as “stable, reusable content like system instructions, background information, large contexts” ^[5]. In dollar terms, a project memory file that stays identical across a long session is nearly free after its first turn.

None of that touches the second cost: the tokens are still physically present in the window on every turn, whether or not the model needed them for that particular question. Anthropic’s own context-engineering guidance names this as the scarcer resource, describing context as “a critical but finite resource for AI agents” and pointing to attention spread thin across an ever-larger set of token-to-token relationships that scale quadratically with length ^[3]. The documented consequence is what Anthropic calls context rot: as token count grows, a model’s ability to use everything inside the window accurately degrades, even though nothing has been deleted ^[3]. That is a vendor’s own characterization of its product’s limits, worth reading as exactly that — a claim made by the party with every incentive to understate it.

Independent measurement backs the general shape of the claim, if not any single number from it. Chroma’s study, evaluating eighteen frontier models including several in the Claude family across needle-in-a-haystack retrieval, a long-context question-answering benchmark, and a repeated-word task, found that “models do not use their context uniformly; instead, their performance grows increasingly unreliable as input length grows” — shuffled, unstructured context sometimes outperformed logically coherent context of the same length, and accuracy at a fixed position declined simply as the surrounding window grew larger ^[6]. A different research group, different tasks, arrived independently at the picture Anthropic’s own documentation describes: length itself is a cost, separate from whatever it costs in cache-adjusted dollars.

Put the two halves together and the trade-off comes into focus. A CLAUDE.md file under the recommended line count is a standing claim on a resource that degrades non-uniformly as it fills, not a one-time toll paid at session start. Caching answers “how much does it cost to keep reading this,” a solved, quantified problem. It does not answer “how much of the model’s attention does this take from the file it actually needs right now” — the problem length guidance, path-scoped rules, and skills exist to manage instead.

What survives when the window fills

Long sessions eventually fill the context window regardless of how disciplined the memory files are, and Claude Code compacts automatically when that happens, replacing the conversation history with a structured summary ^[4]. What happens next to each memory mechanism is not uniform, and the difference is a direct, practical consequence of the loading-order distinction made earlier in this article.

The documentation lays out the aftermath mechanism by mechanism: the system prompt is untouched, since it was never part of message history; the project-root CLAUDE.md and any unscoped rules are re-injected, read fresh from disk; auto memory is likewise re-injected ^[4]. But path-scoped rules and nested CLAUDE.md files in subdirectories are not automatically restored — they are “lost until a matching file is read again,” reloading only the next time Claude touches a file in that subdirectory ^[4]. An instruction that seems to vanish after compaction usually has one of three explanations: it was only ever said in conversation, it lives in a nested file that hasn’t reloaded yet, or it is a path-scoped rule that hasn’t matched a file since the reset ^[1].

This is the clearest demonstration that the four-scope hierarchy does real engineering work, not just organizes a settings screen. Content at the project root is durable across the one event most likely to erase things — a context reset — because the loading mechanism specifically re-reads that location. Content one directory down is not durable in the same way, by design, because reloading everything on every file touch would defeat the point of scoping it at all. Where a team puts an instruction is not a filing choice; it decides which resets that instruction survives.

How this compares to what other agents do

Claude Code’s design is one answer to a problem every coding agent has, and it is useful to see it against others that were not built by the same company.

The most direct point of comparison is AGENTS.md, an open, markdown-based format for the same purpose — project instructions for an agent — that OpenAI convened an industry working group around in August 2025, since adopted, per the format’s own site, by more than 60,000 open-source projects and read natively by over twenty tools ^[7]. In December 2025, AGENTS.md and Anthropic’s own Model Context Protocol were jointly contributed to a new Agentic AI Foundation under the Linux Foundation, with Anthropic named as a founding contributor and Platinum member alongside OpenAI, Block, Google, and Microsoft ^[10]. Despite that shared governance, Claude Code does not read AGENTS.md by default — its documentation states this without qualification, “Claude Code reads CLAUDE.md, not AGENTS.md,” and recommends a CLAUDE.md that imports it with @AGENTS.md syntax instead ^[1]. That is a characterizable disagreement about whether a shared instruction file or a vendor-specific one is the right default, not a case of one tool simply lagging the other — Claude Code supports the shared format only through an explicit bridge.

A more structural contrast comes from Aider, an open-source terminal coding agent whose approach is closer to automation than authorship. Rather than a human-curated file loaded in full, Aider computes a repository map algorithmically: it parses the codebase with tree-sitter, ranks a dependency graph connecting files to identify the most-referenced classes and functions, and fits as much of the ranked result as it can inside a fixed, user-configurable token budget — 1,000 tokens by default ^[8]. Where CLAUDE.md asks a person to decide what earns a permanent seat in every turn’s context, backed by nothing but a line-count recommendation, Aider enforces a hard token ceiling and lets an algorithm decide what fits inside it. Neither has been benchmarked head to head in a way this article can responsibly rank; they are different bets about who — a developer or a ranking algorithm — is better positioned to choose what a limited window holds.

A wider frame for both comes from LangChain’s account of context engineering, published in July 2025, two months before Anthropic’s own post on the subject, independently arriving at an overlapping taxonomy: strategies that write information outside the window for later use, that select what to pull back in, that compress what is already there, and that isolate work across separate windows entirely ^[9]. Against that taxonomy, CLAUDE.md is a write strategy with little automatic compression; auto memory is a write strategy with a hard compression cap built in; /compact is a compress strategy; and subagents, which run research in their own window and report back only a summary, are an isolate strategy ^[9]. These are not unrelated features — they are Claude Code’s answer to a taxonomy the wider field converged on independently, from a different direction.

What this means in practice, and where it might go

The practical guidance falls out of the mechanics rather than needing to be asserted separately. Put content in project-root CLAUDE.md, not a nested file, if it must survive a long session’s inevitable compaction. Treat the 200-line target as a budget being spent against attention that degrades non-uniformly as it fills, not as a stylistic nicety — the empirical case for that degradation now has support from both the vendor’s own engineering account and an independent multi-model study using unrelated tasks ^{[3] [6]}. Reach for a hook or a settings rule, not a CLAUDE.md instruction, for anything that has to hold every time regardless of what the model decides — the documentation’s own line between the two could not be clearer ^[1]. And treat “hierarchy” as describing read order, never as describing override, because the moment two files disagree, nothing in the mechanism resolves that disagreement except the model’s own judgment in the moment.

Two forward-looking observations, kept separate from the sourced analysis above and labeled clearly as speculation. First: given that auto memory already enforces a hard load cap where CLAUDE.md still relies on a recommendation, and given that LangChain’s taxonomy already treats compression as first-class rather than an afterthought, human-authored memory files across coding agents plausibly converge toward the same treatment within a few years — an enforced or auto-summarized ceiling, not just a length guideline. Horizon: end of 2028. Assumption: context-window growth keeps outpacing attention’s ability to use it uniformly. Indicator: a major vendor shipping an enforced cap on a human-authored instruction file. Disconfirmed if leading coding agents in 2028 still load such files in full with no automatic pruning, the way CLAUDE.md does today.

Second: the AGENTS.md and Model Context Protocol convergence under one foundation, with Claude Code, Codex, and Cursor all represented, makes further consolidation of instruction-file formats plausible, though nothing in the current record commits Claude Code to reading AGENTS.md natively rather than through an import. Horizon: end of 2027. Disconfirmed if major agents still require an explicit bridge file, rather than native support, to share one instruction file by that date.

The mechanism underneath the metaphor

“Memory” and “hierarchy” are both borrowed words, and both carry connotations — permanence, override — that the actual system does not fully deliver. What Claude Code actually does is walk a directory tree, concatenate everything it finds in a fixed order, hold the result inside a budget that a cache can make cheap but cannot make larger, and hand the whole thing to a model as a prompt it is free to weigh, not a policy it is bound to obey. Every part of that sentence is documented, and every part of it is a choice with an alternative visible somewhere else in the field — Aider’s algorithmic budget, AGENTS.md’s shared format, auto memory’s own hard cap sitting right next to CLAUDE.md’s soft one. Understanding the mechanism is what makes the four-scope diagram useful instead of misleading: it tells you what loads and when, and it is silent, by design, on what wins.