在 AI 驱动的软件开发中，Claude Code 已成为许多工程师的日常助手。然而，一个长期存在的痛点是：每个会话都是孤立的，AI 无法记住昨天的调试过程、上周的架构决策或上个月的性能优化经验。claude-mem 插件应运而生，它通过 AI 压缩算法捕获会话记录，并智能注入相关上下文到未来会话，实现了工程会话的长期记忆。本文将从工程实现角度，深入剖析其压缩算法与注入机制的核心细节。
AI 压缩算法：五阶段上下文压缩
claude-mem 的压缩并非传统的数据压缩，而是基于 Claude agent-sdk 的上下文压缩（context compaction）。该算法通过五个阶段实现高效记忆保留：
- 监控阶段：实时追踪会话中的 token 使用量，包括用户消息、AI 响应和工具执行结果。
- 阈值检测：当累计 token 使用超过可配置的
context_token_threshold时触发压缩。根据任务类型，建议阈值范围为 5k-20k（频繁压缩的串行处理任务）或 50k-100k（低频压缩的多阶段工作流）。 - 总结请求：系统自动注入用
<summary></summary>标签包装的用户消息，请求 Claude 生成会话摘要。 - 摘要生成：Claude 模型分析当前会话历史，生成结构化摘要，遵循选择性保留原则 —— 保留完成状态、关键决策、下一步行动等核心信息，丢弃详细的工具原始输出（如完整的知识库文章、冗长的分类结果）。
- 历史替换：用生成的摘要替换整个消息数组，释放 token 空间，同时保持会话连续性。
这一过程通过tool_runner API 的compaction_control参数实现自动化管理。选择性保留策略确保了压缩后的上下文仍包含足够信息供后续会话参考，避免了因过度压缩导致的上下文断裂。
智能上下文注入：项目感知与时效性逻辑
压缩后的记忆如何被智能地注入到新会话？claude-mem 通过SessionStart hook 实现了一套精密的注入机制：
当启动新的 Claude Code 会话时，系统首先基于项目路径进行相关性检测，查询数据库获取同一项目内最近的观察记录（默认 50 条）。这种基于项目边界的相关性假设简化了算法复杂度，虽然可能遗漏跨项目的语义相关性，但在工程实践中具有较高的实用价值。
注入的上下文以时间线格式呈现，包含观察标题、会话标记和文件分组信息。关键的摘要显示逻辑确保了信息的时效性：只有当最近一次摘要生成时间晚于最后一次观察时间时，完整的摘要详情（包括调查内容、学习要点、完成事项和下一步行动）才会显示。例如，如果最后一次观察发生在 14:00，摘要生成于 14:05，则摘要详情可见；反之，如果摘要生成于 14:00 而新观察发生在 14:05，则摘要详情被隐藏，避免展示过时信息。
渐进式披露：三层 token 优化策略
为平衡上下文丰富度与 token 使用效率，claude-mem 采用了渐进式披露的三层架构：
第一层：索引显示（会话启动时） 仅显示观察标题和时间线标记，token 成本约 50-200。这提供了会话概览，帮助 AI 快速理解项目近期活动脉络。
第二层：按需详情（通过 MCP 工具） 当 AI 需要深入了解特定细节时，可自然询问如 “我们上次如何实现认证功能？”，系统通过 MCP 搜索工具获取完整观察详情，token 成本约 100-500 每条。
第三层：完美召回（直接代码访问） 在需要时，AI 可直接读取源文件、原始转录数据，获得完整历史上下文。
这种分层策略确保了在有限的上下文窗口内，既能提供足够的引导信息，又能在需要时访问完整细节。
可落地工程参数与监控要点
核心参数配置
- 压缩阈值：
context_token_threshold应根据任务类型调整。对于需要频繁参考历史的调试会话，建议设置较低阈值（5k-10k）；对于长期架构设计任务，可提高至 50k 以上。 - 观察数量：默认检索最近 50 条观察，可根据项目复杂度调整。大型项目可增至 100 条，小型项目可减至 20 条以节省 token。
- 摘要生成触发：除了会话结束时的自动生成，也可通过手动命令触发，确保关键决策点被及时记录。
监控指标
- 摘要质量评估：定期检查生成的摘要是否准确捕捉了会话核心内容，特别是技术决策和问题解决方案。
- 相关性命中率：统计注入的上下文在新会话中被实际引用的比例，评估基于项目路径的相关性检测效果。
- token 使用效率：监控各层披露的实际 token 消耗，优化阈值设置以平衡信息密度与成本。
风险与限制
尽管 claude-mem 提供了强大的记忆功能，工程师仍需注意其局限性：AI 压缩可能过度简化复杂技术细节；基于项目路径的相关性检测可能遗漏跨项目但有语义关联的上下文；摘要生成质量依赖于模型的理解能力，可能存在偏差。
结语
claude-mem 通过将 AI 压缩算法与智能上下文注入相结合，为 Claude Code 用户提供了接近人类工程师的长期记忆能力。其工程实现中的五阶段压缩、项目感知注入和渐进式披露策略，展示了如何在实际约束（token 限制、计算成本）下构建有效的 AI 辅助系统。随着 agent-sdk 的不断演进，这类记忆系统的精度和效率有望进一步提升，最终实现 AI 与工程师的无缝协作。
资料来源
- GitHub - thedotmack/claude-mem：核心插件实现
- Claude Agent SDK Workshop by Thariq Shihipar：agent-sdk 架构与压缩机制
- Claude-Mem Documentation - Getting Started：上下文注入与渐进式披露细节