claude-mem 源码分析：记忆如何在对话中体现

Fri, 08 May 2026 06:00:00 +0000

06 — 记忆如何在对话中体现

核心问题：claude-mem 装好后，我在正常对话时"记忆"究竟是怎么发挥作用的？它怎么知道何时搜索、搜什么、如何注入到上下文里？

两条完全独立的路径

记忆在对话中通过两条机制体现，分工明确：

	路径一：自动注入	路径二：主动搜索
触发者	Claude Code Hook 机制（机器触发）	Claude 自己（LLM 判断后调用 MCP 工具）
时机	会话开始时，一次性	对话中途，按需多次
内容	近期会话摘要 + 项目相关 observations	精准历史记录（由搜索词决定）
Claude 的角色	被动接收（醒来时记忆已在上下文里）	主动调用 MCP 工具
数据密度	有限（避免撑爆 context window）	3 层递进：索引 → 时间线 → 全文

路径一：自动注入（你不感知，Claude 也不选择）

触发时机：每次 Claude Code 开始新会话（claude 启动），或 /clear、/compact 之后。

sequenceDiagram
    participant CC as Claude Code
    participant Hook as SessionStart Hook
    participant Bun as bun-runner.js
    participant Worker as Worker HTTP API
    participant DB as SQLite / Chroma

    CC->>Hook: 会话启动，触发 SessionStart
    Hook->>Bun: bun-runner.js worker-service.cjs hook claude-code context
    Bun->>Worker: GET /api/context/inject?projects=...
    Worker->>DB: 查 session_summaries（最近 10 条）
    Worker->>DB: 查 observations（最近 50 条，按项目过滤）
    DB-->>Worker: 返回摘要 + observations
    Worker-->>Bun: 返回格式化的 context 文本
    Bun-->>CC: stdout JSON：
{"hookSpecificOutput":{"additionalContext":"..."}}
    CC->>CC: 把 additionalContext 塞进系统提示头部
    Note over CC: Claude 醒来时，历史记忆已经在上下文里

关键点：Claude 不需要"决定"搜不搜，记忆已经在那里了。你看到 Claude 说"上次我们在做 X"，就是这条路径的效果。

注入的内容来自 src/services/context/ContextBuilder.ts 的 generateContext() 函数，它从 ContextConfigLoader 读取限额配置，然后调用 ObservationCompiler 拼装输出。

路径二：主动搜索（Claude 被"教会"的行为）

触发时机：你问了涉及历史的问题（“上周那个 bug 怎么解决的”、“之前的方案是什么”）。

为什么 Claude 会主动搜索：

安装时注册了 mem-search MCP 技能。其中的 __IMPORTANT 元工具描述本身就是一段指令文本，注入进 Claude 的工具列表说明里：

1
2
3

当用户询问过去的工作、历史决策、之前的代码时，
必须先用 search → timeline → get_observations 三层工作流，
不要直接回答——先查。

💡 Tip 这是一个"prompt injection via tool description"技巧 MCP 工具描述字段对 Claude 来说和系统提示的效力等同。__IMPORTANT 工具的 description 就是工作流规范本身——架构设计即使用规范，API 即文档，无需额外指导。

搜索结果进入上下文的方式，是 MCP 工具调用的标准返回值路径，不走 hook 注入。

记忆里存的是什么

三类数据，层级递进：

graph TD
    subgraph DB["SQLite 数据库"]
        OBS["observations 表
（颗粒度：单次工具调用）"]
        SUM["session_summaries 表
（颗粒度：整个会话）"]
        PROM["user_prompts 表
（颗粒度：用户每次提问）"]
    end

    PostTool["PostToolUse Hook
（每次工具调用后）"] -->|"原始 tool_input + tool_output"| AI1["AI 压缩\nbuildObservationPrompt"]
    AI1 -->|"XML 结构化摘要"| OBS

    StopHook["Stop Hook
（会话结束时）"] -->|"last_assistant_message"| AI2["AI 摘要\nbuildSummaryPrompt"]
    AI2 -->|"五段式结构化摘要"| SUM

    UserPrompt["UserPromptSubmit Hook"] -->|"用户输入文本"| PROM

    style OBS fill:#dae8fc,stroke:#6c8ebf
    style SUM fill:#d5e8d4,stroke:#82b366
    style PROM fill:#fff2cc,stroke:#d6b656

Observations — 工具调用的语义提炼

每次 PostToolUse 后，原始的 {tool_name, tool_input, tool_output} 被发给 AI 压缩，产出结构化 XML：

<observation>
  <type>discovery | change | bugfix | decision ...</type>
  <title>发现了 X</title>
  <subtitle>在 Y 文件里</subtitle>
  <facts>
    <fact>具体事实1</fact>
    <fact>具体事实2</fact>
  </facts>
  <narrative>更完整的叙述（可选的详细描述）</narrative>
  <concepts><concept>auth</concept></concepts>
  <files_read><file>src/xxx.ts</file></files_read>
  <files_modified><file>src/yyy.ts</file></files_modified>
</observation>

存的不是原始对话，是 AI 从工具调用里提炼的语义摘要。代码见 src/sdk/prompts.ts 的 buildObservationPrompt()。

Session Summaries — 会话级五段式摘要

Stop Hook 触发后，buildSummaryPrompt() 把最后一条 assistant 消息喂给 AI，产出五段式摘要，存入 session_summaries：

字段	含义
`request`	这次会话用户要做什么
`investigated`	调查了哪些模块/文件
`learned`	关键发现（这是下次最有价值的字段）
`completed`	完成了什么
`next_steps`	下次应该继续做什么

没有完整的 user/assistant 对话历史，只有这五个字段的提炼。

User Prompts — 轻量问题记录

只存用户每次输入的问题文本，用于 timeline 展示，不存 assistant 回答。

记忆会不会失控膨胀？

注入时有硬上限，从 src/shared/SettingsDefaultsManager.ts 的默认值读出：

CLAUDE_MEM_CONTEXT_OBSERVATIONS   = 50   # 注入最多 50 条 observations
CLAUDE_MEM_CONTEXT_SESSION_COUNT  = 10   # 会话摘要最多 10 条
CLAUDE_MEM_CONTEXT_FULL_COUNT     = 0    # 默认只注入摘要，不注全文 narrative
CLAUDE_MEM_SEMANTIC_INJECT        = false # 语义注入默认关闭

ObservationCompiler.ts 里的查询永远带 LIMIT：

SELECT ... FROM observations
WHERE project = ?
ORDER BY created_at_epoch DESC
LIMIT ?   -- = totalObservationCount = 50

结论：注入到 Claude 上下文里的记忆是有界窗口，不随使用时间线性增长。

⚠️ Warning 数据库本身不会自动清理 SQLite 里的历史数据会一直积累（磁盘慢涨），但这不影响注入效率——每次只取最近 N 条。目前代码里没有自动 TTL 或定期清理机制。这是一个有意为之的取舍：存储廉价，查询有上限，永久保留而不主动清理。如果在意磁盘，需要手动管理 ~/.claude-mem/claude-mem.db。

不想被记忆的内容怎么处理

方法一：`<private>` 标签

`1`	`<private>这段内容不会被存入记忆</private>`

在 hook 层（最靠近用户输入处）就被剥离，不进 Worker，不进 DB。见 src/utils/tag-stripping.ts。

方法二：项目排除

summarize.ts 开头有项目过滤判断：

// src/cli/handlers/summarize.ts
if (input.cwd && !shouldTrackProject(input.cwd)) {
  return { continue: true, suppressOutput: true };  // 整个会话都不被记录
}

某些目录（个人文档、敏感项目）可以配置排除，Stop hook 遇到这些目录直接跳过，不生成任何摘要。

核心收获

记忆体现有两套机制，不要混淆：自动注入（session start 时塞进去，被动接收）和主动搜索（MCP 工具调用，Claude 主动发起）。前者无感，后者可观测（你能看到 Claude 在调用 search/timeline/get_observations）。
存的不是聊天记录，是语义提炼：observations 是工具调用的 AI 摘要，summaries 是会话的五段式结构化总结。原始对话内容不被持久化。
上下文窗口里的记忆是有界的：默认最多 50 observations + 10 session summaries，不会随使用时间膨胀。注入的 token 量由配置控制，可以调整。
<private> 标签是边缘防线：在数据产生的最源头就被切断，是隐私保护的正确姿势。

记忆注入 on BenLab的技术笔记