Claude-Mem 增量上下文注入算法：实时相关性评分与渐进式披露架构

在 AI 辅助编程的持续会话中，上下文管理面临着一个核心挑战：如何在有限的注意力预算内，智能地注入最相关的历史信息？Claude-Mem 作为 Claude Code 的持久化记忆插件，通过一套精心设计的增量上下文注入算法，实现了跨会话的知识连续性。本文将深入分析其核心机制 —— 渐进式披露架构与实时相关性评分系统。

渐进式披露：上下文作为货币的哲学

传统 RAG（检索增强生成）系统往往在会话开始时倾泻所有历史上下文，导致严重的 “上下文污染” 问题。根据 Claude-Mem 文档的数据，传统方法中仅有约 6% 的注入上下文真正相关，浪费了 94% 的注意力预算。

Claude-Mem 采用了截然不同的哲学：渐进式披露。这一信息架构模式的核心原则是 “先展示存在性与检索成本，让代理基于相关性和需求决定获取什么”。系统将上下文访问分为三个层次：

1. 层一（索引）：展示轻量级元数据（标题、日期、类型、令牌计数）
2. 层二（详情）：仅在需要时获取完整内容
3. 层三（深度挖掘）：必要时读取原始源文件

这种架构模拟了人类的工作模式：我们先扫描标题再阅读文章，查看目录再深入章节，检查文件名再打开文件。在技术实现上，每个 SessionStart 钩子提供一个紧凑的索引格式：

### 2025年12月16日

**通用**
| ID | 时间 | 类型 | 标题 | 令牌 |
|----|------|------|------|------|
| #2586 | 12:58 AM | 🔵 | 上下文钩子文件存在但为空 | ~51 |
| #2587 | ″ | 🔵 | 上下文钩子脚本文件为空 | ~46 |

**src/hooks/context-hook.ts**
| ID | 时间 | 类型 | 标题 | 令牌 |
|----|------|------|------|------|
| #2591 | 1:15 AM | ⚖️ | 标准错误消息传递已放弃 | ~155 |

实时相关性评分：代理驱动的决策机制

Claude-Mem 的相关性评分机制与传统预计算算法不同，它采用了代理驱动的实时决策模型。系统不预先计算相关性分数，而是提供足够的信息让 AI 代理自行评估。

语义压缩与类型标注

系统的索引条目通过语义压缩技术，将完整观察压缩为约 10 个词的描述性标题。好的标题具备以下特征：

• 具体性：识别确切问题
• 可操作性：清晰说明要做什么
• 自包含：无需阅读完整观察即可理解
• 可搜索：包含关键术语
• 已分类：图标指示类型

类型图标系统提供了视觉扫描和语义分类：

• 🔴 关键点：关键边缘情况或陷阱
• 🟡 问题 - 解决方案：错误修复或变通方案
• 🔵 工作原理：技术解释
• 🟢 变更内容：代码 / 架构变更
• 🟤 决策：架构决策
• ⚖️ 权衡：有意识的妥协

成本可见性与 ROI 决策

每个索引条目都显示近似的令牌计数（如～155、~203），而不是精确计数。这一设计决策基于以下考量：

• 传达规模（50 vs 500）而不提供虚假精确度
• 映射到人类直觉（小 / 中 / 大）
• 允许代理预算注意力
• 鼓励成本意识的检索

代理基于当前任务上下文、所需信息类型以及预算限制，构建决策树：

当前任务是否与钩子相关？ → 是
当前任务是否与超时相关？ → 是
当前任务是否与 npm 相关？ → 是
155 令牌很便宜 → 获取它

SessionStart 钩子：增量注入的工程实现

上下文注入的核心发生在 SessionStart 钩子中，具体由 context-hook.js 脚本执行。其技术实现遵循严格的异步非阻塞模式。

钩子处理流程

1. 输入解析：接收包含 session_id、cwd（当前工作目录）和 source（启动源）的 JSON 输入
2. 健康检查：等待工作进程可用（最长 10 秒，采用指数退避重试）
3. 上下文获取：调用 GET http://127.0.0.1:37777/api/context/inject?project={project}
4. 格式化输出：将上下文格式化为渐进式披露索引的 Markdown

配置参数与调优

系统通过 CLAUDE_MEM_CONTEXT_OBSERVATIONS 环境变量控制注入的观察数量，默认值为 50。这一参数平衡了上下文覆盖范围与索引大小之间的关系。在实际部署中，建议根据项目复杂性和会话频率进行调整：

• 小型项目：20-30 个观察
• 中型项目：40-50 个观察
• 大型企业项目：70-100 个观察（需注意索引令牌成本）

异步处理管道

关键的设计模式是扩展进程从不阻塞（fire-and-forget HTTP）。工作进程异步处理观察，使用事件驱动队列：

扩展进程 → HTTP POST（2秒超时） → 工作进程队列 → SDK 代理处理 → 数据库存储

这种架构确保了 Claude Code 的响应性，即使在后端处理大量观察时也不会影响用户体验。

混合搜索架构：语义相似性与时间上下文的平衡

Claude-Mem 采用混合搜索架构，结合了 FTS5 全文搜索和 Chroma 向量数据库。这一设计在语义相似性和时间上下文之间取得了平衡。

两层级搜索策略

系统在搜索结果中也实现了渐进式披露：

层级一：索引格式（默认）

search_observations({
  query: "钩子超时",
  format: "index"  // 默认
})

返回约 100 令牌的 3 个结果索引，代理可以扫描并决定获取哪个。

层级二：完整格式（按需）

search_observations({
  query: "钩子超时", 
  format: "full",
  limit: 1  // 仅获取最相关的一个
})

返回约 155 令牌的完整详细信息。

时间上下文处理

虽然系统没有显式的时间衰减算法，但通过多种机制提供时间上下文：

1. 时间戳显示：每个索引条目包含精确的时间信息
2. 按日期分组：观察按日期分组，提供时间局部性
3. 最近上下文搜索：专门的 get_recent_context 工具获取最近会话摘要
4. 时间线搜索：timeline 和 timeline_by_query 操作围绕特定时间点提供统一时间线

未来优化方向：基于嵌入的相关性评分

当前系统将相关性决策完全委托给代理，但文档中提到了未来的增强方向：基于嵌入的相关性评分。

预排序索引

计划中的功能包括使用嵌入预排序索引相关性：

search_observations({
  query: "认证错误",
  format: "index",
  sort: "relevance"  // 基于语义相似性
})

自适应索引大小

系统计划根据会话类型动态调整索引大小：

• SessionStart({ source: "startup" })：显示最后 10 个会话（小索引）
• SessionStart({ source: "resume" })：仅显示当前会话（微索引）
• SessionStart({ source: "compact" })：显示最后 20 个会话（较大索引）

成本预测与预算估计

未来的增强可能包括成本预测功能：

💡 **预算估计：**
- 获取所有 🔴 关键点：~450 令牌
- 获取所有文件相关：~1,200 令牌  
- 获取所有内容：~8,500 令牌

工程实践：部署参数与监控要点

在实际部署 Claude-Mem 的增量上下文注入系统时，以下工程参数和监控点至关重要。

关键配置参数

1. CLAUDE_MEM_CONTEXT_OBSERVATIONS：控制注入的观察数量（默认 50）
2. CLAUDE_MEM_MODEL：用于观察生成的 AI 模型（默认 claude-sonnet-4-5）
3. CLAUDE_MEM_WORKER_PORT：工作进程服务端口（默认 37777）
4. CLAUDE_MEM_LOG_LEVEL：日志详细程度（DEBUG、INFO、WARN、ERROR、SILENT）

性能监控指标

• 浪费比率：相关令牌 / 总上下文令牌 > 80%
• 选择性获取：显示的索引观察数 vs 实际获取的详情观察数（理想比例 50:2-3）
• 任务完成时间：使用索引的会话 vs 不使用索引的会话找到相关上下文的时间
• 深度适当性：简单任务仅需索引，中等任务获取 1-2 个观察，复杂任务获取 5-10 个观察 + 代码阅读

故障排除检查点

1. 工作进程健康：定期检查 http://localhost:37777/health
2. 数据库完整性：sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
3. FTS5 表存在性：确保全文搜索表正确创建
4. 钩子超时配置：SessionStart 钩子超时设置为 300 秒，确保足够时间获取上下文

认知负载理论的应用

Claude-Mem 的渐进式披露架构深深植根于认知负载理论，该系统通过以下方式优化认知处理：

减少外在认知负载

传统 RAG 系统增加了不必要的外在认知负载：

• 扫描不相关的观察
• 过滤噪音
• 记住要忽略的内容
• 在每个部分后重新建立上下文

渐进式披露最小化了这些负载：

• 扫描标题（低努力）
• 仅获取相关内容（定向努力）
• 全神贯注于当前任务

支持相关认知负载

系统通过以下方式支持构建心理模型和模式的相关认知负载：

• 一致的结构（图例、分组）
• 清晰的分类（类型、图标）
• 语义压缩（好标题）
• 明确成本（令牌计数）

结论：智能上下文管理的范式转变

Claude-Mem 的增量上下文注入算法代表了 AI 辅助编程中上下文管理的范式转变。通过将相关性评分决策权交给 AI 代理，而非预先计算的算法，系统实现了真正的自适应上下文管理。

核心创新点包括：

1. 渐进式披露架构：将上下文视为需要明智花费的货币
2. 代理驱动的相关性评估：信任 AI 代理基于完整上下文做出最佳决策
3. 混合搜索策略：平衡语义相似性与时间上下文
4. 成本可见性设计：使令牌经济成为显式决策因素

随着 AI 模型的不断改进，这种 “展示而非告知” 的方法为更智能、更自主的 AI 辅助系统奠定了基础。Claude-Mem 不仅解决了跨会话记忆的技术挑战，更重要的是，它建立了一种尊重代理智能和自主权的上下文交互哲学。

“最好的界面是在不需要时消失，在需要时恰好出现的界面。”

渐进式披露尊重代理的智能和自主权。我们提供地图；代理选择路径。

---

资料来源：

• Claude-Mem 渐进式披露文档：https://docs.claude-mem.ai/progressive-disclosure
• Claude-Mem 钩子架构文档：https://docs.claude-mem.ai/architecture/hooks
• Claude-Mem GitHub 仓库：https://github.com/thedotmack/claude-mem