在 Claude Code 持续工作的编码会话中，如何让 AI 在新会话开始时准确复用历史上下文，一直是工程实践的核心挑战。Claude-Mem 作为 Claude Code 的持久记忆插件，通过一套精细的上下文注入机制解决了这一难题。该机制的核心在于：基于相关性评分筛选记忆内容、在有限的 Token 预算内实现渐进式披露、以及通过六个生命周期钩子协同完成会话上下文的完整重建。
一、相关性评分：混合搜索策略的工程实现
Claude-Mem 的记忆筛选并非简单的关键词匹配，而是采用了混合搜索策略，将全文搜索（FTS5）与语义向量搜索（ChromaDB）相结合，为每条历史观察计算相关性分数。这种设计的工程价值在于：FTS5 能够精准匹配文件路径、函数名、技术术语等结构化信息，而 ChromaDB 的向量嵌入则捕捉语义层面的关联，例如将 “认证失败” 与 “登录流程优化” 判定为高相关。
具体实现上，当新会话启动时，context-hook 会调用 worker service 的搜索接口。Worker service 首先对用户当前的任务描述进行向量化，然后并行查询 FTS5 虚拟表与 ChromaDB 向量库。两套结果集通过加权融合算法重新排序，最终输出按相关性降序排列的记忆候选列表。配置文件中可调整 relevance_threshold 参数控制最小相关性阈值，默认值为 0.65，低于此分数的观察将被直接过滤。
这套机制的优势在于它能够区分 “精确匹配” 与 “语义关联” 两种不同层次的记忆调用。对于调试场景，精确的文件路径和错误日志往往比泛化的语义描述更有价值；而在进行代码重构时，历史上的相似实现则可能提供更具启发性的参考。混合搜索策略确保了这两个维度不会被遗漏。
二、Token 预算分配：渐进式披露模式
即便筛选出了高相关性的记忆，Token 成本仍是不可忽视的限制因素。Claude-Mem 为此设计了三阶段渐进式披露模式（Progressive Disclosure），通过分层加载控制单次上下文注入的 Token 消耗。
第一层为索引层（Search），每次调用仅返回记忆的紧凑索引，包含观察 ID、时间戳、类型标签和摘要片段， Token 消耗控制在每条结果 50 至 100 之间。第二层为时间线层（Timeline），在用户锁定感兴趣的记忆 ID 后，系统加载该观察前后各 15 分钟的上下文片段，帮助用户理解记忆发生时的完整场景。第三层为详细内容层（Get Observations），当用户明确需要查看某条记忆的完整信息时，才从数据库提取原始观察内容，每次调用 Token 消耗约为 500 至 1000。
这种设计的核心理念与前端工程中的 “按需加载” 一致：不在会话开始时一次性注入全部记忆，而是让 AI 在推理过程中自主决定需要深入了解哪些历史片段。根据官方文档，采用渐进式披露后，每个会话可节省约 2250 Token 的上下文开销。更重要的是，这种模式避免了信息过载 —— 当 AI 一次性接收过多历史细节时，其注意力容易被分散，导致关键信息被淹没在噪声之中。
三、会话上下文重建：生命周期钩子的协作流程
上下文注入并非单点操作，而是贯穿整个会话周期的系统工程。Claude-Mem 定义了六个生命周期钩子，每个钩子负责特定的上下文处理任务，共同构成会话上下文重建的完整链路。
SessionStart 阶段的 context-hook 是上下文注入的起点。该钩子在新会话启动时触发，首先检查 worker service 是否已启动（若未启动则通过 Bun 自动拉起），随后从 SQLite 数据库中读取历史观察的摘要，按照相关性排序后注入当前会话的系统提示词。这一过程支持通过 CLAUDE_MEM_CONTEXT_OBSERVATIONS 配置项控制注入的记忆条数，默认值为 10 条。
UserPromptSubmit 阶段的 new-hook 负责记录用户本次会话的目标意图。用户在会话中提交的每次 Prompt 都会被完整保存至 FTS5 虚拟表，形成可检索的会话轨迹。这一设计使得未来的新会话能够通过搜索历史问题描述，找到相似的任务上下文，实现 “久别重逢” 式的知识延续。
PostToolUse 阶段的 save-hook 是记忆捕获的主力。该钩子会在每次工具执行后触发，将工具调用的输入、输出、错误信息等数据发送至 worker service，由 Claude Agent SDK 进行结构化提取与摘要生成。观测数据经过 AI 处理后，以语义片段的形式写入数据库，为后续会话提供原材料。
Stop 阶段的 summary-hook 负责生成会话级别的整体总结。当用户终止会话或 AI 停止响应时，该钩子会调用 worker service 对本次会话的所有观察进行整合，提炼出本次会话的目标、完成情况、关键决策和未解决问题。这份总结成为下一轮会话最具价值的上下文入口。
最后，SessionEnd 阶段的 cleanup-hook 标记会话状态为完成，但不删除数据。值得注意的是，若用户执行 /clear 命令清理会话，cleanup-hook 会跳过执行，以确保正在进行的工作不被意外中断。
四、工程化配置参数与调优建议
在实际部署中，以下几个配置参数直接影响上下文注入的效果与成本：
Token 预算控制方面，CLAUDE_MEM_CONTEXT_TOKEN_LIMIT 决定了单次会话注入的 Token 上限，建议根据模型上下文窗口大小进行动态计算 —— 若使用 200K 上下文窗口的模型，可将上限设置为 30K 至 50K，为当前任务保留充足的空间。
相关性阈值方面，relevance_threshold 的取值需权衡召回率与精确度。代码调试场景可适当降低阈值（0.5 左右）以获取更多参考案例；而代码审查场景则应提高阈值（0.8 以上）以确保注入的记忆与当前任务高度相关。
记忆分层策略方面，memory_ttl_days 定义了观察的保留期限，默认值为 90 天。对于长期维护的项目，建议将此值设为 180 天以上，并在每月底执行一次记忆归档，将超过一年的观察迁移至独立的归档数据库。
向量搜索配置方面，若项目规模较大（观察数量超过 10000 条），建议启用 ChromaDB 的分区功能，按功能模块或代码仓库划分向量集合，避免单集合过大导致搜索延迟上升。
五、总结
Claude-Mem 的上下文智能注入机制，本质上是一套记忆筛选、信息压缩与按需加载的系统工程。通过混合搜索实现精准的相关性评分，借助渐进式披露控制 Token 成本，并以六个生命周期钩子串联起记忆的捕获、存储、检索与复用的完整闭环。这套机制解决了大模型在长程任务中上下文衰减的核心痛点，使得 Claude Code 能够在跨越数周甚至数月的项目周期内保持连贯的上下文理解能力。对于需要在复杂代码库中持续工作的开发团队而言，理解并善用这一机制，将显著提升 AI 辅助编程的效率与准确性。
参考资料
- Claude-Mem 官方架构文档：https://docs.claude-mem.ai/architecture/overview
- GitHub 仓库：https://github.com/thedotmack/claude-mem