精读: Claude Code 记忆系统

编排/Harness 视角见 Agent 框架 · Claude Code 架构精读

调研元信息

一句话定位

Claude Code 的记忆系统是一个文件 index + 按需 LLM 检索的两层架构：MEMORY.md 作为索引全量注入 system prompt，每个用户 turn 再由 Sonnet 从最多 200 个记忆文件中选出 ≤5 个注入上下文——整个读路径是 LLM 驱动的语义匹配，而非向量检索 [源码]。

日常类比

想象一个图书馆管理员。图书馆有一本很薄的目录册（MEMORY.md），最多 200 行、25KB——每本书只占一行，写着书名和一句话简介。你进入图书馆时，管理员把整本目录册摊在桌上（system prompt 注入）。当你提出具体问题时，管理员（Sonnet）从目录中挑出最多 5 本相关的书翻开给你看（每本最多 200 行/4KB）。与此同时，后台有个”记录员”（extractMemories）在你每次对话结束后悄悄记笔记，把值得保存的内容写成新的书放回书架。

类比边界：真实图书馆的目录不会自动截断，也不需要一个 AI 来决定给你看哪本书。

记忆类型标注

本文主要讨论 User memory（~/.claude/projects/*/memory/ 下的自动记忆文件），兼及 Agent profile（CLAUDE.md）与 User memory 的边界，以及 Working memory（session transcript）如何通过 extractMemories 转化为持久记忆。

架构总览

Claude Code 的记忆系统分为三个子系统：memdir（记忆目录管理与 prompt 构建）、extractMemories（后台提取代理）、和 autoDream（后台整合/做梦） [源码]。

flowchart TB
    subgraph read_path["读路径"]
        direction LR
        BOOT[Session 启动] --> LOAD["loadMemoryPrompt()<br/>读 MEMORY.md<br/>截断 200行/25KB"]
        LOAD --> SYS[注入 System Prompt]

        TURN[用户发送消息] --> PREFETCH["startRelevantMemoryPrefetch()"]
        PREFETCH --> SCAN["scanMemoryFiles()<br/>扫描 ≤200 个 .md"]
        SCAN --> SELECT["findRelevantMemories()<br/>Sonnet 选 ≤5 个文件"]
        SELECT --> READ_MEM["readMemoriesForSurfacing()<br/>每文件 ≤200行/4KB"]
        READ_MEM --> INJECT["附件注入上下文"]
    end

    subgraph write_path["写路径"]
        direction LR
        STOP["stopHooks<br/>模型最终响应后"] --> EXTRACT["extractMemories<br/>forked agent, maxTurns=5"]
        EXTRACT --> WRITE["写 topic .md + frontmatter"]
        WRITE --> UPDATE["更新 MEMORY.md 索引"]

        STOP --> DREAM["autoDream<br/>≥24h & ≥5 sessions"]
        DREAM --> CONSOLIDATE["整合/去重/优化"]
    end

    subgraph storage["存储层"]
        MEM_DIR["~/.claude/projects/*/memory/"]
        INDEX["MEMORY.md (index)"]
        FILES["topic-name.md (content)"]
        MEM_DIR --> INDEX
        MEM_DIR --> FILES
    end

    SYS -.-> INDEX
    INJECT -.-> FILES
    UPDATE -.-> INDEX
    WRITE -.-> FILES

读路径: 双阶段注入

Claude Code 的读路径有两个注入时机，覆盖了”广度 + 深度”两种需求 [源码]。

阶段 1: System Prompt 注入（广度）

flowchart LR
    START[Session 开始] --> CHECK{auto memory<br/>启用?}
    CHECK -->|是| LOAD["readFileSync(MEMORY.md)"]
    LOAD --> TRUNC["truncateEntrypointContent()"]
    TRUNC --> BUILD["buildMemoryPrompt()"]
    BUILD --> CACHE["systemPromptSection('memory', ...)"]
    CACHE --> SYSPROMPT[System Prompt]
    CHECK -->|否| SKIP[不注入]

MEMORY.md 截断规则 [源码]：

每行建议长度：约 150 字符。MEMORY.md 的设计意图是”每条记忆只占一行的目录”——正文存在独立的 topic .md 文件中 [源码]。

阶段 2: 每 turn 按需检索（深度）

flowchart LR
    USER[用户消息] --> PREFETCH["startRelevantMemoryPrefetch()"]
    PREFETCH --> EXTRACT_TEXT[提取用户文本]
    EXTRACT_TEXT --> CHECK_BUDGET{session 累计<br/>≤ 60KB?}
    CHECK_BUDGET -->|超限| SKIP[跳过]
    CHECK_BUDGET -->|未超| SCAN["scanMemoryFiles()"]
    SCAN --> FORMAT["formatMemoryManifest()"]
    FORMAT --> SONNET["Sonnet sideQuery<br/>json_schema output<br/>max_tokens=256"]
    SONNET --> FILTER[过滤已展示过的]
    FILTER --> READ["readMemoriesForSurfacing()"]
    READ --> ATTACH["作为 relevant_memories 附件注入"]

scanMemoryFiles 的工作方式 [源码]：

findRelevantMemories (Sonnet 选择器) [源码]：

Sonnet 收到的输入是格式化的记忆清单（- [type] filename (timestamp): description），输出是 { selected_memories: string[] } 的 JSON。关键规则：

• 只选确信有用的，不确定就不选，可以返回空列表
• 如果用户正在使用某个工具，不要选该工具的 API 文档（已经在用了），但要选 warnings/gotchas/known issues
• alreadySurfaced 参数过滤已展示过的路径，让 5 个名额花在新候选上

读取限制 [源码]：

与 mem0 检索的对照

写路径: extractMemories — 后台提取

extractMemories 是一个后台 forked agent，在每个完整查询循环结束时（模型产生无工具调用的最终响应时）通过 handleStopHooks 以 fire-and-forget 方式触发 [源码]。

执行流程

flowchart TB
    HOOK["handleStopHooks()"] --> CHECK{auto memory 启用<br/>+ 非远程<br/>+ 非子代理<br/>+ extract mode active}
    CHECK -->|否| SKIP[跳过]
    CHECK -->|是| THROTTLE{节流检查<br/>每 N 轮一次}
    THROTTLE -->|跳过| WAIT[等待下次]
    THROTTLE -->|通过| MUTEX{主代理已写<br/>memory?}
    MUTEX -->|是| ADVANCE[推进游标, 跳过]
    MUTEX -->|否| SCAN["scanMemoryFiles()"]
    SCAN --> PROMPT[构建提取 prompt]
    PROMPT --> FORK["runForkedAgent()<br/>maxTurns=5<br/>共享 prompt cache"]
    FORK --> NOTIFY["appendSystemMessage()<br/>通知主线程"]

关键设计决策

Forked Agent 模式 [源码]：提取代理与主对话共享 prompt cache，极大降低成本（cache hit 可能 > 50%）。这是一个重要的工程优化——如果每次都独立构建完整 prompt，记忆提取的成本会翻倍。

主代理/提取代理互斥 [源码]：hasMemoryWritesSince() 检查主代理是否已经手动写了记忆文件。如果主代理写了（比如用户说”记住这个”），提取代理直接跳过本轮并推进游标。这避免了两个 agent 同时写同一个文件的竞态。

游标机制 [源码]：lastMemoryMessageUuid 作为游标，确保每次运行只处理新增消息。加上 pendingContext 暂存机制——当提取正在运行时有新请求到来，完成后会执行一次 trailing run。

工具权限限制 [源码]：提取代理只能用 Read/Grep/Glob（不限路径）、只读 Bash、以及仅限 memory 目录的 Edit/Write。

提取 Prompt 设计

提取 prompt 的核心指令 [源码]：

• “分析最近 ~N 条消息并更新持久记忆系统”
• 推荐策略：turn 1 并行 Read 所有需要更新的文件，turn 2 并行 Write/Edit
• “只用最近 N 条消息的内容，不要 grep 源码验证”——这是信噪比优化：提取代理应该快速行动，不要花 turn 去验证
• 预注入现有记忆清单，避免创建重复文件

四类型分类法

Claude Code 定义了一套封闭的记忆类型分类 [源码]：

feedback 类型要求包含 **Why:** 和 **How to apply:** 结构——这不是装饰性要求，而是确保记忆有 actionable 信息 [源码]。

什么不该保存

这可能是整个记忆系统中最有教育意义的部分 [源码]：

不应保存的内容：代码模式/架构、文件路径、git 历史、调试方案、CLAUDE.md 已有内容、临时任务状态。即使用户明确要求保存 PR 列表，也应询问”什么是意外或非显而易见的”。

核心原则是不保存 derivable 信息——代码能 grep 到的就不记。这与 DB-Agent-Memory 的 L0→L3 提炼思路不同：DB-Agent-Memory 保存所有层级并做语义晋升，Claude Code 直接拒绝记住可推导的东西 [已有]。

写路径: autoDream — 后台整合

autoDream 是 extractMemories 的补充：前者写新记忆，后者整合已有记忆 [源码]。

触发条件（便宜的先检查）

与 Codex Phase2 的对照

Freshness 与 Staleness 管理

Claude Code 对记忆新鲜度的处理比大多数开源库更细致 [源码]：

memoryAge 模块将 mtime 转换为人类可读格式（”today” / “yesterday” / “47 days ago”），因为模型不擅长日期算术但理解相对时间。

Freshness caveat：超过 1 天的记忆自动附带警告文本——”This memory is N days old. Memories are point-in-time observations…“。这通过 <system-reminder> 标签包裹注入。

设计动机（代码注释）：用户报告说陈旧的 code-state 记忆（含 file:line 引用）被当作事实——引用格式反而让过时信息更权威。加上 staleness caveat 是对这个问题的直接回应 [源码]。

与 Graphiti 时序管理的对照

团队记忆

Claude Code 支持团队记忆——多用户共享的记忆目录 [源码]。

安全设计

团队记忆的安全措施非常重 [源码]：

这套安全设计的深度远超开源记忆项目——因为团队记忆意味着文件写入路径可能被外部输入影响 [源码]。

与 CLAUDE.md（Profile）的边界

关键洞察：CLAUDE.md 中的内容被明确列为”不应保存到 memory 的东西”——这在代码层面划清了 Profile 和 User memory 的边界 [源码]。

关键常量汇总

局限性

1. Sonnet 选型是黑盒：findRelevantMemories 的召回质量完全取决于 Sonnet 对 query 和 frontmatter 的理解——没有可调参数或 fallback 策略。
2. 200 文件上限：超过 200 个记忆文件后，旧文件直接不进入候选集，即使它们仍然相关。
3. MEMORY.md 截断是硬截断：被截断的索引条目对模型完全不可见，可能导致某些记忆”消失”。
4. 每 turn 的 Sonnet 调用成本：在高频交互场景下，记忆检索的 LLM 调用开销可观。
5. Feature gate 密度极高：几乎每个功能都有 tengu_* flag 控制——实际用户体验可能与源码逻辑有差异。
6. extractMemories 的 5-turn 限制：复杂的记忆更新（涉及多文件读取和关联）可能在 5 turn 内完不成。

证据等级汇总

与开源记忆项目对照总表