Claude Code Memory Architecture: How CLAUDE.md, Auto Memory, and Runtime Evidence Shape Agent Context

Don't Look at "Memory" First — Watch How It Enters Context

The investigation starts in src/utils/claudemd.ts. getMemoryFiles() reads files in a fixed order: organization-hosted CLAUDE.md, user-global CLAUDE.md, then walking the filesystem from root to the current working directory collecting project-level CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md. If Auto Memory is enabled, its MEMORY.md entry point is appended last.

All these files are concatenated into context in that order. Files closer to the current directory appear later, and local files sit after project-level ones at the same layer. Later position influences model attention but does not create a deterministic override semantic. The official docs state plainly: if two rules conflict, Claude may pick either arbitrarily.

Later ≠ Override.

The model sees a flat context block, not a resolved configuration tree. Proximity and specificity only raise the probability of correct adoption; they do not establish a forced precedence.

Several small implementation details control token bloat: CLAUDE.md can use @path to include other text files; @ inside Markdown code fences is ignored.

HTML comments are stripped during auto-injection.

Rules under .claude/rules/ can scope themselves to specific file globs via paths.

CLAUDE.md : Team-Authored Entry Navigation

Facts already discoverable in the repository (source code, config, tests) should not be copied wholesale into CLAUDE.md. It belongs to the "hard to infer without being told" category: uncommon build entry points, historical module boundaries, mandatory checks after editing certain file types. These are human-curated, team-reviewed, and evolve with Git.

The loading order (org → user → project → local) reflects this layering. For monorepos, nested project-level CLAUDE.md files are more practical than piling everything at the root.

But "in the repo" ≠ "always correct." Renamed commands, moved modules, branch switches — stale lines still load. The docs explicitly warn to clean conflicts and expired content. Saving tokens is secondary; the real risk is the model receiving two equally plausible but contradictory answers.

In practice, CLAUDE.md acts as navigation: it marks entry routes and no-go zones; the actual current structure is still best read live.

Auto Memory: Not a Second CLAUDE.md

The writer changes to Claude, and the content boundary shifts accordingly. Official docs list four categories: user preferences, user feedback, project background not derivable from code, and external system entry points. The reconstructed memoryTypes.ts draws a cleaner line: code structure, file paths, Git history, debugging fixes, and anything already in CLAUDE.md are excluded from Auto Memory.

Questions the repository can answer stay with the repository.

MEMORY.md

is an index, not a long note. Detailed content lives in topic files. On each new session, only the first 200 lines or 25 KB of the index (whichever comes first) are loaded; topic files are fetched on demand. truncateEntrypointContent() enforces this: line-truncate, then byte-truncate, and nudge Claude to move overflow into topic files. A separate experimental findRelevantMemories() scans topic-file headers and selects context-relevant sections — not yet a stable contract in all public builds, but the design direction is clear: keep the entry light, pull details lazily.

If the second half of MEMORY.md isn't loaded, it simply wasn't in this session's context — not "Claude remembers but isn't thinking of it." Existence, recall, and correctness are three distinct states.

Current Facts Come from the Worksite

One might expect a CURRENT.md file. The source does not create one. The live evidence stream — files read, command output, test results — constitutes the continuously changing current facts. src/context.ts seeds the session with date and Git info at startup. A notable comment: the Git snapshot captured at launch does not auto-update during the session . Even system-injected "current state" grows stale. After edits or branch switches, the original Git summary remains frozen at session start. To know "what's true now," you must re-read files, re-run git status, or execute real tests.

This is the dividing line between the Agent Loop and static memory. CLAUDE.md tells Claude what to watch for.

Auto Memory reminds it of past encounters.

File reads, command output, test results, and external system responses tell it what's happening right now .

Every tool call returning to context gives the model a chance to correct prior judgments.

The docs note: after switching branches, Claude sees the new branch's files but the chat history remains. Context can simultaneously hold "last branch's discussion" and "this branch's source code." Relying on chat impressions alone easily conflates history with present.

Current fact is not a fixed layer — it's an evidence stream that must be continuously re-fetched.

After Compression, the Past Reloads

Long sessions inevitably compress. The reconstructed code shows an interesting handling: after the main session compresses, it clears the getUserContext and memory-file caches, causing CLAUDE.md, Rules, and Auto Memory to reload in subsequent context.

Session flow gets summarized; long-term instructions re-inject. They live on separate persistence chains.

Reloading solves "is it still visible?" — not "is it still current?" Old rules re-read are still old rules; expired Auto Memory accurately recalled is just expired experience more accurately returned.

Reload ≠ Auto-refresh.

The hard problem is invalidation: who detects obsolescence, who updates, and will the next startup still inject it? The author advises against "every bug fix → permanent rule" as a blanket habit:

If a bug reveals a lasting boundary → CLAUDE.md.

If already covered by stable tests → leave facts in code/tests.

If just a one-off debugging clue → Auto Memory, then correct or delete when evidence changes.

Without an expiration mechanism, memory only accumulates, repeatedly resurfacing stale experience in new sessions.

Memory Guides; Hard Gates Enforce

The official docs repeatedly emphasize a boundary: CLAUDE.md and Auto Memory are context, not mandatory configuration.

This clarifies memory's role: provide context so the model understands team conventions and avoids re-exploration. But for high-impact actions — deletes, publishes, production writes, sensitive directories — executability must not hinge on whether the model "remembered" a reminder.

In Claude Code, those constraints belong in permissions, Sandbox, PreToolUse hooks, and the repo's own tests and CI.

Prompts influence choice; deterministic mechanisms guard the gate.

Architecturally, memory never works alone. Above: context loading. Below: tool execution and permission boundaries. Middle: shifting live evidence. Studying only Markdown organization misses the other half of the reliability chain.

The Longer You Use It, the More You Subtract

A long-time Claude Code user shared reducing their CLAUDE.md from 107 lines to 69 by splitting core rules, reference material, and dynamic state — the must-read-on-every-startup set actually shrank.

The exact numbers don't matter. The pattern: with experience, developers learn what deserves persistence and what doesn't need to appear every time.

Claude Code team member Thariq Shihipar mentioned in an interview they continuously run memory experiments because the right design is often counter-intuitive. At the time, Claude Tag still used one Markdown file per channel, feeding session experience back into shared memory.

Even the product team is still iterating. External claims of "a knowledge graph makes the agent smarter the more you use it" can be viewed more skeptically. Graphs connect relations, RAG retrieves candidates, summaries extend long sessions — but none automatically turn old information into current fact.

What's worth borrowing from Claude Code are the explicit boundaries it draws:

Humans write durable instructions.

Claude stores cross-session experience.

Tools return live evidence.

Permissions and CI constrain high-impact actions.

Conflicts between these layers exist, and no perfect priority table resolves them all. But when things break, you know where to look: missing load, failed recall, expired content, or a case that belonged to a hard gate all along.

Closing

Tracing the loading chain simplifies the mental model of Claude Code "memory." CLAUDE.md is not an encyclopedia. Auto Memory is not a fact database. They do the same modest job: let Claude enter a new session without starting from zero every time.

Once tools execute, source code, config, Git, command output, and test results continuously rewrite the model's situational judgment. Memory shortens the on-ramp; when it clashes with freshly read code or fresh test results, the new evidence wins. Deletes, publishes, and other high-impact moves remain the domain of permissions and CI.