What it is

File-based memory in Claude Code is a persistent store of Markdown files living under a project-scoped directory — ~/.claude/projects/<sanitized-git-root>/memory/, resolved by getAutoMemPath() (claude-code/src/memdir/paths.ts:223), overridable via an env var or settings. Each memory is its own .md file with frontmatter, classified into a four-type taxonomy — user / feedback / project / reference (claude-code/src/memdir/memoryTypes.ts:14) — capturing only context not derivable from the current project state. A single MEMORY.md at the directory root is not a memory but an index: one line per topic file (claude-code/src/memdir/memdir.ts:227).

There are two distinct reading paths. At system-prompt build time, loadMemoryPrompt() (claude-code/src/memdir/memdir.ts:419) injects the behavioral instructions (via buildMemoryLines, claude-code/src/memdir/memdir.ts:199) and — for the agent-memory builder — the MEMORY.md index itself, read synchronously and truncated (claude-code/src/memdir/memdir.ts:272). That index is the袖中目录册: always present, deliberately small. The second path is relevance recall: on each user turn, a secondary Claude model reads the directory's file headers and selects the handful most relevant to what the user just asked, and those files are injected as system-reminder attachments. This page reads that second path.

How it works

On each user turn, startRelevantMemoryPrefetch (claude-code/src/utils/attachments.ts:2361) kicks off the recall as a non-blocking async prefetch — but only if auto-memory is enabled and the tengu_moth_copse flag is on (claude-code/src/utils/attachments.ts:2367), the prompt contains more than one word (claude-code/src/utils/attachments.ts:2379), and the session hasn't already blown its cumulative byte budget (claude-code/src/utils/attachments.ts:2384). The work happens inside findRelevantMemories (claude-code/src/memdir/findRelevantMemories.ts:39): it calls scanMemoryFiles (claude-code/src/memdir/memoryScan.ts:35), which reads every .md recursively (claude-code/src/memdir/memoryScan.ts:40) except MEMORY.md (claude-code/src/memdir/memoryScan.ts:42), extracts each file's frontmatter from the first 30 lines (claude-code/src/memdir/memoryScan.ts:51), sorts newest-first by mtime (claude-code/src/memdir/memoryScan.ts:72), and caps at 200 files (claude-code/src/memdir/memoryScan.ts:73). The result is a MemoryHeader[] (claude-code/src/memdir/memoryScan.ts:13).

These headers become a text manifest (claude-code/src/memdir/memoryScan.ts:84) handed to selectRelevantMemories (claude-code/src/memdir/findRelevantMemories.ts:77) — the 学徒. It issues a sideQuery to a Sonnet model (claude-code/src/memdir/findRelevantMemories.ts:98) with max_tokens: 256 and a JSON-schema output (claude-code/src/memdir/findRelevantMemories.ts:108), under a system prompt instructing it to pick at most five files it is certain will help, and to skip reference/API docs for tools the model is already using successfully (claude-code/src/memdir/findRelevantMemories.ts:18, claude-code/src/memdir/findRelevantMemories.ts:23). Crucially, the returned filenames are filtered against the set actually present in the manifest (claude-code/src/memdir/findRelevantMemories.ts:83, claude-code/src/memdir/findRelevantMemories.ts:130) — a hallucinated or malformed selection silently collapses to empty rather than reaching for a nonexistent file.

The selected paths flow to getRelevantMemoryAttachments (claude-code/src/utils/attachments.ts:2196), which drops anything the model already read via FileReadTool or surfaced on a prior turn (claude-code/src/utils/attachments.ts:2233) and slices to the final five (claude-code/src/utils/attachments.ts:2234). Then readMemoriesForSurfacing (claude-code/src/utils/attachments.ts:2279) reads each file through readFileInRange capped at 200 lines and 4096 bytes with truncateOnByteLimit (claude-code/src/utils/attachments.ts:2294; constants at claude-code/src/utils/attachments.ts:269 and claude-code/src/utils/attachments.ts:277), appending a "this file was truncated — use FileReadTool to see the rest" note when cut (claude-code/src/utils/attachments.ts:2305) — the誊抄截断与"取原卷"小笺. Each gets a header: for memories older than a day, memoryHeader prepends a staleness caveat (claude-code/src/utils/attachments.ts:2327) built by memoryFreshnessText (claude-code/src/memdir/memoryAge.ts:33), whose age is floor-rounded and clamped at zero (claude-code/src/memdir/memoryAge.ts:7) because models reason about "47 days ago" but not raw timestamps (claude-code/src/memdir/memoryAge.ts:15).

The prefetch is bound in query.ts with the using keyword (claude-code/src/query.ts:301). At the post-tools collect point, the loop consumes the result only if it has already settled — otherwise it skips with zero wait and retries next iteration (claude-code/src/query.ts:1599); settledAt is stamped by a .finally() (claude-code/src/utils/attachments.ts:2420), and [Symbol.dispose] aborts any in-flight request on every generator exit path (claude-code/src/utils/attachments.ts:2410). When consumed, the relevant_memories attachment (claude-code/src/utils/attachments.ts:500) is rendered by wrapping each memory in a <system-reminder> (claude-code/src/utils/messages.ts:3708, via claude-code/src/utils/messages.ts:3101) — the quiet placing of copied pages on the desk.

Why it matters

Two design tensions are resolved here. First, capacity vs. relevance: you cannot load an entire growing memory directory into every prompt, but you also cannot guess in advance which memory a given turn needs. The split — a tiny always-present index in the system prompt plus a per-turn LLM ranker over file headers — lets the store grow without inflating the prompt, spending a cheap Sonnet call to pick the few files worth their tokens. Bytes are bounded at three levels: 5 files × 4 KB per turn (claude-code/src/utils/attachments.ts:277), a 200-line/4096-byte per-file cap (claude-code/src/utils/attachments.ts:269), and a 60 KB session-total budget that gates off prefetching once exceeded (claude-code/src/utils/attachments.ts:288) — naturally reset by compaction, since collectSurfacedMemories recomputes from the live transcript (claude-code/src/utils/attachments.ts:2251).

Second, latency vs. correctness. Recall must never make the user wait, so it runs as a prefetch chained to the turn's abort controller (claude-code/src/utils/attachments.ts:2390) and is consumed only when ready (claude-code/src/query.ts:1599) — the 学徒 slips pages onto the desk in the master's pauses, never freezing the consultation. And because a memory is a point-in-time observation, not live state, every stale file carries a freshness caveat (claude-code/src/memdir/memoryAge.ts:33), reinforced by the drift guidance baked into the system prompt (claude-code/src/memdir/memoryTypes.ts:201) — the medical record's "verify against the current pulse before prescribing." The recentTools suppression (claude-code/src/memdir/findRelevantMemories.ts:23, fed by claude-code/src/utils/attachments.ts:2465) is the same instinct: don't hand the doctor the manual for the instrument already in his hand — but do hand over its known defects. Finally, because memory is files on disk that the model can be told to write, the team-memory write path resolves symlinks on the deepest existing ancestor and rejects any path escaping the directory (claude-code/src/memdir/teamMemPaths.ts:228, claude-code/src/memdir/teamMemPaths.ts:241, claude-code/src/memdir/teamMemPaths.ts:249), even rejecting dangling symlinks via lstat (claude-code/src/memdir/teamMemPaths.ts:136) — the rule that a filed record may not secretly be a paper-chain leading out of the room. The read-time path has its own traversal guard in isAutoMemPath (claude-code/src/memdir/paths.ts:274).

Read the source

• The two-stage shape: index load at loadMemoryPrompt (claude-code/src/memdir/memdir.ts:419) and buildMemoryPrompt (claude-code/src/memdir/memdir.ts:272); recall at findRelevantMemories (claude-code/src/memdir/findRelevantMemories.ts:39).
• The ranker: scanMemoryFiles (claude-code/src/memdir/memoryScan.ts:35) → selectRelevantMemories calling Sonnet (claude-code/src/memdir/findRelevantMemories.ts:77, claude-code/src/memdir/findRelevantMemories.ts:98) → validity filter (claude-code/src/memdir/findRelevantMemories.ts:130).
• Surfacing: dedup + slice (claude-code/src/utils/attachments.ts:2196), truncation (claude-code/src/utils/attachments.ts:2279), staleness header (claude-code/src/utils/attachments.ts:2327, claude-code/src/memdir/memoryAge.ts:33), and system-reminder injection (claude-code/src/utils/messages.ts:3708).
• The non-blocking machinery: prefetch start (claude-code/src/utils/attachments.ts:2361), using-bound handle (claude-code/src/query.ts:301), settle-or-skip collect (claude-code/src/query.ts:1599).
• The guardrails: byte budgets (claude-code/src/utils/attachments.ts:269, claude-code/src/utils/attachments.ts:277, claude-code/src/utils/attachments.ts:288) and symlink-escape rejection (claude-code/src/memdir/teamMemPaths.ts:228, claude-code/src/memdir/teamMemPaths.ts:136).