Memory System 是 Claude Code 的
「跨会话神经元」—— 它如何把
"用户偏好 + 项目上下文 + 反馈"
持久化在文件系统里？

01Memory System 是什么

一句话定义：让模型在每次新对话中"记住"用户偏好、项目上下文、反馈历史的、基于文件系统的持久化知识库。 与对话上下文（轮内）、CLAUDE.md（项目级人工编辑）相比，记忆系统的核心特征是：跨会话、模型自动写入、类型受限、按需召回。

1.1 核心设计理念

1.2 五条核心设计原则

1.3 记忆系统在整体架构中的位置

图 1.1 — 记忆系统通过三条独立通道向模型传递信息，分别对应不同位置和缓存策略

02存储 · 目录结构 + 路径解析

记忆持久化在文件系统中，目录结构按"用户级根 → 项目隔离 → 子模式"三层组织。 路径解析有严格的优先级链路与安全约束，能抵御目录遍历攻击与跨项目污染。

2.1 默认目录结构

2.2 路径解析优先级（getAutoMemPath()）

位于 src/memdir/paths.ts，是一个 memoize(by projectRoot) 函数：

图 2.1 — 路径解析优先级链路（src/memdir/paths.ts:216-228）

2.3 路径校验：六道安全约束

validateMemoryPath() 拒绝以下情形（paths.ts:106-145）：

2.4 启用判定链（isAutoMemoryEnabled()）

// src/memdir/paths.ts:30-54
export function isAutoMemoryEnabled(): boolean {
  const envVal = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY
  if (isEnvTruthy(envVal)) return false       // 1. 显式禁用
  if (isEnvDefinedFalsy(envVal)) return true     // 2. 显式启用
  if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) // 3. --bare 模式关闭
    return false
  if (isEnvTruthy(process.env.CLAUDE_CODE_REMOTE) // 4. CCR 无持久存储
      && !process.env.CLAUDE_CODE_REMOTE_MEMORY_DIR)
    return false
  const settings = getInitialSettings()             // 5. settings.json
  if (settings.autoMemoryEnabled !== undefined)
    return settings.autoMemoryEnabled
  return true                                       // 6. 默认开启
}

2.5 文件格式

---
name: 用户角色偏好
description: 数据科学家，关注可观测性
type: user
---

用户是数据科学家，目前专注于
可观测性/日志方向。

在解释代码时，应从数据分析的角度
出发，利用用户已有的领域知识构建
心智模型。

- [用户角色偏好](user_role.md) —
  数据科学家，关注可观测性
- [集成测试策略](feedback_testing.md) —
  必须用真实数据库
- [Auth 重写背景](project_auth_rewrite.md) —
  合规驱动
- [Pipeline Bug 追踪](reference_linear_ingest.md) —
  Linear INGEST 项目

03类型 · 封闭四类型分类法

记忆被严格限制为四种类型，专门承载"无法从当前项目状态直接推导"的上下文信息。 定义在 src/memdir/memoryTypes.ts，是整个系统最核心的设计约束。

3.1 四种记忆类型

3.2 什么不应该保存（WHAT_NOT_TO_SAVE_SECTION）

3.3 召回侧约束（WHEN_TO_ACCESS_SECTION）

3.4 召回后的"信任校验"约束（TRUSTING_RECALL_SECTION）

// 标题措辞影响明显（来自 memory-prompt-iteration.eval.ts 评测验证）：
// "Before recommending"（决策点动作提示）3/3 通过
// 抽象标题 "Trusting what you recall" 仅 0/3

## Before recommending from memory

A memory that names a specific function, file, or flag is a claim that
it existed *when the memory was written*. It may have been renamed,
removed, or never merged. Before recommending it:

- If the memory names a file path: check the file exists.
- If the memory names a function or flag: grep for it.
- If the user is about to act on your recommendation
  (not just asking about history), verify first.

"The memory says X exists" is not the same as "X exists now."

A memory that summarizes repo state (activity logs, architecture
snapshots) is frozen in time. If the user asks about *recent* or
*current* state, prefer `git log` or reading the code over recalling
the snapshot.

04写入 · 主代理 + 后台提取双路径

记忆写入有两条互补路径：主代理在对话中根据系统提示词的指导主动写入； 后台提取代理在每个回合结束时补漏分析。两者通过 hasMemoryWritesSince 守卫互斥， 保证不重复也不遗漏。

图 4.1 — 双路径写入机制：主代理直接写 + 后台代理补漏，互斥守卫

4.1 路径一：主代理直接写入

4.2 路径二：后台提取代理（extractMemories）

4.2.1 运行时机与门控

位于 src/services/extractMemories/extractMemories.ts，在每个完整查询循环结束时（模型产出最终响应且无工具调用时），通过 handleStopHooks → stopHooks.ts 触发。

4.2.2 完美分叉模式（runForkedAgent）

图 4.2 — 后台提取代理的完整执行序列

4.2.3 工具权限收紧（createAutoMemCanUseTool）

分叉代理使用受限的 canUseTool 函数（extractMemories.ts:171-222）：

4.2.4 节流与协调

4.2.5 高效写入策略（提取提示词）

提取提示词（prompts.ts 的 opener()）显式指导分叉代理"两轮完成"：

// extractMemories/prompts.ts:39
You have a limited turn budget. FileEditTool requires a prior
FileReadTool of the same file, so the efficient strategy is:

  turn 1 — issue all FileReadTool calls in parallel for
            every file you might update;
  turn 2 — issue all FileWriteTool/FileEditTool
            calls in parallel.

Do not interleave reads and writes across multiple turns.

You MUST only use content from the last ~N messages to update your
persistent memories. Do not waste any turns attempting to investigate
or verify that content further — no grepping source files, no reading
code to confirm a pattern exists, no git commands.

同时预注入 memory 目录清单（formatMemoryManifest 输出），避免分叉代理浪费一回合执行 ls。

05KAIROS · 按日追加日志模式

当 feature('KAIROS') 启用且 getKairosActive() 为 true 时，记忆写入方式改变： 不再实时维护 MEMORY.md 索引，改为按日期追加日志，夜间由独立 /dream 流程蒸馏。

5.1 设计动机

5.2 路径模式 vs 具体日期路径

// memdir/memdir.ts:325-345 buildAssistantDailyLogPrompt
const logPathPattern = join(memoryDir,
    'logs', 'YYYY', 'MM', 'YYYY-MM-DD.md')

// 这里用"路径模式"而非"当天具体路径"：
// 该提示词会被 systemPromptSection('memory', ...) 缓存，
// 不会在日期变化时自动失效。
// 模型应从 date_change 附件（午夜滚动时追加在尾部）
// 获取当前日期，而不是依赖 user-context 消息；
// 后者故意保持滞后以保住跨午夜的提示词缓存前缀。

5.3 KAIROS 写入流程

图 5.1 — KAIROS 模式：写入实时化 → 蒸馏批量化

5.4 何时记录什么（KAIROS 提示词节选）

另外：用户明确要求记住的任何事。

06索引 · MEMORY.md 的双层架构

MEMORY.md 是记忆系统的入口文件，始终被加载到模型上下文中。 采用"索引/详情"两层架构：索引始终可见，详情按需加载。

6.1 双层架构

6.2 截断保护（truncateEntrypointContent）

位于 src/memdir/memdir.ts:58-104，采用双重截断策略：

图 6.1 — 双重截断保护机制：先按行 → 再按字节

6.3 截断后的 WARNING 提示

// memdir/memdir.ts:88-94
const reason =
  wasByteTruncated && !wasLineTruncated
    ? `${formatFileSize(byteCount)} (limit: ${formatFileSize(MAX_ENTRYPOINT_BYTES)})
       — index entries are too long`
    : wasLineTruncated && !wasByteTruncated
      ? `${lineCount} lines (limit: ${MAX_ENTRYPOINT_LINES})`
      : `${lineCount} lines and ${formatFileSize(byteCount)}`

// 末尾追加：
> WARNING: MEMORY.md is {reason}. Only part of it was loaded.
  Keep index entries to one line under ~200 chars; move detail
  into topic files.

6.4 索引加载链路

通过 claudemd.ts 的 getMemoryFiles() 函数（memoize），作为 AutoMem 类型的记忆文件，注入到用户上下文的 claudeMd 字段中：

// claudemd.ts:980-998
if (isAutoMemoryEnabled()) {
  files.push({ path: getAutoMemEntrypoint(),
               type: 'AutoMem', ... })
}
if (feature('TEAMMEM') && teamMemPaths!.isTeamMemoryEnabled()) {
  files.push({ path: teamMemPaths!.getTeamMemEntrypoint(),
               type: 'TeamMem', ... })
}

格式化为文本时，AutoMem 会标注 "(user's auto-memory, persists across conversations)"，TeamMem 会标注 "(shared team memory, synced across the organization)"。

07召回 · 三种触发机制

记忆召回有三种独立机制，分别服务于不同的场景。它们互为补充，不会冗余。

7.1 机制一：索引全量加载

图 7.1 — 索引全量加载链路

7.2 机制二：相关性检索（异步预取）

7.2.1 触发与门控

定义在 src/utils/attachments.ts:2380-2440 的 startRelevantMemoryPrefetch，每轮查询循环开始时通过 using 绑定，作为 Disposable 异步运行。

7.2.2 检索流程详解

图 7.2 — 相关性检索的完整链路

7.2.3 Sonnet 选择器（核心智能筛选）

不是简单关键词匹配，而是用 Sonnet 做语义筛选（findRelevantMemories.ts）：

// findRelevantMemories.ts:19-25 SELECT_MEMORIES_SYSTEM_PROMPT
You are selecting memories that will be useful to Claude Code as
it processes a user's query. You will be given the user's query
and a list of available memory files with their filenames and
descriptions.

Return a list of filenames for the memories that will clearly be
useful to Claude Code as it processes the user's query (up to 5).
Only include memories that you are certain will be helpful based
on their name and description.
- If you are unsure if a memory will be useful in processing the
  user's query, then do not include it in your list. Be selective
  and discerning.
- If there are no memories in the list that would clearly be useful,
  feel free to return an empty list.
- If a list of recently-used tools is provided, do not select
  memories that are usage reference or API documentation for those
  tools (Claude Code is already exercising them). DO still select
  memories containing warnings, gotchas, or known issues about
  those tools — active use is exactly when those matter.

// sideQuery 调用：独立 API 调用，不消耗主对话 token 预算
const result = await sideQuery({
  model: getDefaultSonnetModel(),
  system: SELECT_MEMORIES_SYSTEM_PROMPT,
  skipSystemPromptPrefix: true,           // 跳过主提示词
  messages: [{ role: 'user', content:
    `Query: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}` }],
  max_tokens: 256,
  output_format: {                        // 结构化输出
    type: 'json_schema',
    schema: { type: 'object',
      properties: { selected_memories: { type: 'array',
                                          items: { type: 'string' } } },
      required: ['selected_memories'] } },
  signal,
  querySource: 'memdir_relevance',
  optional: true,
})

7.2.4 双重去重（alreadySurfaced + readFileState）

7.2.5 文件内容截断（双限）

// attachments.ts:269-289
const MAX_MEMORY_LINES = 200
// Line cap alone doesn't bound size (200 × 500-char lines = 100KB).
// 5 files × 4KB = 20KB/turn 才是真正的硬上限
const MAX_MEMORY_BYTES = 4096

export const RELEVANT_MEMORIES_CONFIG = {
  // 会话累计 60KB（约 3 次完整注入），
  // 之后停止预取 — 最相关的记忆已经在上下文中了。
  // 扫描消息（而非 toolUseContext）能让 compact 自然重置计数。
  MAX_SESSION_BYTES: 60 * 1024,
}

截断时附加提示，模型可决定是否用 FileReadTool 拉取完整文件：

// attachments.ts:2323-2326
const content = truncated
  ? result.content +
    `\n\n> This memory file was truncated (${reason}).
       Use the FileReadTool to view the complete file at: ${filePath}`
  : result.content

7.2.6 新鲜度提示（memoryHeader）

每条记忆都附带头信息，超过 1 天的记忆会带"过时警告"：

// attachments.ts:2346-2351 + memoryAge.ts:32-41
function memoryHeader(path: string, mtimeMs: number) {
  const staleness = memoryFreshnessText(mtimeMs)
  return staleness
    ? `${staleness}\n\nMemory: ${path}:`
    : `Memory (saved ${memoryAge(mtimeMs)}): ${path}:`
}

// memoryFreshnessText 对超 1 天的记忆生成：
// "This memory is N days old. Memories are point-in-time
// observations, not live state — claims about code behavior
// or file:line citations may be outdated. Verify against
// current code before asserting as fact."

7.3 机制三：嵌套记忆（Nested Memory）

7.3.1 触发机制

图 7.3 — 嵌套记忆触发机制

7.3.2 关键字段

08API 请求 · 三条注入通道详解

记忆系统的三层架构在 API 请求中体现为三条独立的注入通道， 各有不同的位置、内容、缓存策略和 compact 行为。

8.1 三通道全景对比

8.2 通道一：systemPromptSection('memory') 的缓存机制

// constants/prompts.ts:770
const dynamicSections = [
  systemPromptSection('session_guidance', () => ...),
  systemPromptSection('memory', () => loadMemoryPrompt()),  // ← 这里
  ...
]

// systemPromptSections.ts
export function systemPromptSection(name, compute) {
  return { name, compute, cacheBreak: false }  // ← 关键
}

8.3 通道二：MEMORY.md 索引的双路径

图 8.1 — 索引通道有"传统模式"和"moth_copse 模式"两条分支

8.4 通道三：relevant_memories 附件的注入位置

每轮查询循环开始时通过 using 启动预取，在 collect 点（post-tools）消费：

// query.ts 中的简化伪代码
while (true) {
  using prefetch = startRelevantMemoryPrefetch(messages, toolUseContext)
  // prefetch 在主模型 streaming + 工具执行期间异步运行

  // ... 模型采样 + 工具执行 ...

  // collect 点：consume-if-ready or skip-and-retry-next-iteration
  const attachments = prefetch?.settledAt
      ? await prefetch.promise
      : []
  // prefetch never blocks the turn

  // [Symbol.dispose] 在 using 作用域退出时触发
  // — abort 飞行中的请求 + 发出终态遥测
}

8.5 QueryEngine 中的第二处 loadMemoryPrompt 调用

// QueryEngine.ts:325-332
const memoryMechanicsPrompt =
  customPrompt !== undefined && hasAutoMemPathOverride()
    ? await loadMemoryPrompt()
    : null

// ...
const systemPromptParts = [
  customPrompt,
  ...(memoryMechanicsPrompt ? [memoryMechanicsPrompt] : []),
  ...
]

8.6 compact 对记忆的影响

09启用开关 · 五道判定链

记忆系统的不同子能力由多层 feature flag 控制 —— 总开关、build feature、GrowthBook 实验、本地设置共同决定运行时行为。

9.1 主判定链 isAutoMemoryEnabled()

图 9.1 — auto-memory 总开关判定链（paths.ts:30-54）

9.2 各 feature flag 对记忆的影响

9.3 加载分发逻辑（loadMemoryPrompt()）

图 9.2 — loadMemoryPrompt() 的分发逻辑（memdir.ts:414-497）

9.4 穷鬼模式（Poor Mode）的特殊处理

10全链路 · 写入 → 召回完整数据流

把前面的分散概念串起来，看一个完整的端到端故事： 用户说一句话 → 记忆被写入 → 跨会话被召回。

10.1 写入链路（一次完整对话）

图 10.1 — 写入链路：主代理直接写或后台提取代理补漏

10.2 召回链路（新对话开始）

图 10.2 — 召回链路：三通道并行注入

10.3 完整数据流总览

11关键细节 · 你可能不知道但应该知道的

以下这些细节散落在源码各处，如果不通读相关文件很难发现。它们解释了系统的"为什么这样设计"。

// systemPromptSections.ts
export function systemPromptSection(name, compute) {
  return { name, compute, cacheBreak: false }
}

if (hasMemoryWritesSince(messages, lastMemoryMessageUuid)) {
  const lastMessage = messages.at(-1)
  if (lastMessage?.uuid)
    lastMemoryMessageUuid = lastMessage.uuid
  return
}

This memory is N days old. Memories are point-in-time
observations, not live state — claims about code behavior or
file:line citations may be outdated. Verify against current
code before asserting as fact.

getTeamMemPath() = join(getAutoMemPath(), 'team')

turn 1 — issue all FileReadTool calls in parallel
         for every file you might update
turn 2 — issue all FileWriteTool/FileEditTool calls
         in parallel
Do not interleave reads and writes across multiple turns.

const RELEVANT_MEMORIES_CONFIG = {
  MAX_SESSION_BYTES: 60 * 1024,  // ~3 次完整注入
}

const logPathPattern = join(memoryDir,
    'logs', 'YYYY', 'MM', 'YYYY-MM-DD.md')

12源码文件索引

读源码时按这个顺序展开，最容易建立心智模型。

12.1 阅读建议

1. 从 memoryTypes.ts 开始 —— 理解四类型分类法和提示词文案
2. 读 paths.ts —— 理解目录结构、路径优先级、安全约束
3. 读 memdir.ts 的 buildMemoryLines 和 loadMemoryPrompt —— 理解使用说明如何构建
4. 读 memoryScan.ts + findRelevantMemories.ts —— 理解相关性检索机制
5. 读 attachments.ts 的 startRelevantMemoryPrefetch 段落 —— 理解三通道中的"通道 3"
6. 读 extractMemories.ts —— 理解后台提取代理的完整生命周期
7. 最后读 claudemd.ts —— 理解 MEMORY.md 索引如何作为 AutoMem 类型注入用户上下文