在大规模软件开发过程中，上下文丢失一直是 AI 编程助手面临的核心挑战。当开发者结束一次 Claude Code 会话后，所有关于项目结构、已解决 bug、设计决策的关键信息都会随之消散。Claude-mem 作为一款专为 Claude Code 设计的持久记忆插件，通过自动化的会话捕获、智能压缩与上下文注入机制，为这一问题提供了系统化的解决方案。本文将从技术实现角度深入剖析其核心架构与关键流程。
生命周期钩子与会话捕获机制
Claude-mem 的会话捕获能力建立在其精心设计的生命周期钩子系统之上。该系统包含六个核心钩子，分别对应 Claude Code 会话的不同阶段，形成完整的监控与数据采集链条。
第一个关键钩子是 Context Hook（SessionStart），它在会话启动时立即执行，负责启动 Bun 工作进程并从数据库中注入上一次会话的上下文信息。这一注入过程是可配置的，开发者可以指定每次新会话加载的历史观察数量，在上下文完整性与 token 消耗之间取得平衡。第二个钩子是 New Hook（UserPromptSubmit），它在用户提交提示词时触发，负责在数据库中创建新的会话记录，并将原始用户提示保存至 FTS5 全文索引表中，为后续搜索提供基础数据。
最核心的数据采集发生在 Save Hook（PostToolUse） 阶段。根据架构文档记载，这个钩子在一次完整的编码会话中会触发超过一百次，每次 Claude 执行工具操作后都会将工具执行的详细数据发送至工作进程进行 AI 压缩处理。这种高频采集机制确保了不会遗漏任何关键的开发动作，无论是代码修改、文件读取还是测试执行。随后的 Summary Hook（Stop） 在 Claude 停止响应时触发，生成包含用户请求、系统完成结果以及 AI 提取的结构化学习内容的最终摘要。最后的 Cleanup Hook（SessionEnd） 负责标记会话完成，使系统准备好为下一次会话提供上下文注入。
基于 Agent SDK 的 AI 语义压缩算法
Claude-mem 的核心创新在于其 AI 压缩算法的实现。该系统并未采用传统的无损压缩技术，而是利用 @anthropic-ai/claude-agent-sdk 构建了一套语义压缩框架，能够在保留关键信息的同时大幅减少 token 消耗。
从技术实现角度来看，工作进程中的 sdk/worker.ts 文件包含主循环逻辑，它接收来自 Save Hook 传递的观察数据批次，使用自定义的 XML 提示模板进行处理。SDK 的迭代推理循环和工具处理能力使得压缩过程能够智能识别冗余信息，同时保留如 bug 修复记录、设计决策等关键细节。处理流程采用 XML 提示构建器和响应解析器的组合架构，提示模板定义在 sdk/prompts.ts 中，而解析逻辑则位于 sdk/parser.ts。
这种语义压缩策略的核心优势在于其有损但高效的特性。与简单的文本截断或标记删除不同，AI 压缩能够理解会话内容的语义结构，将分散的观察数据提炼为结构化的学习摘要。例如，当 Claude 在一次会话中多次尝试解决同一个问题时，压缩算法能够识别这种模式并将最终成功的解决方案作为核心学习内容保存，同时丢弃中间失败的尝试记录。
混合存储架构与渐进式披露策略
为了支持高效的上下文检索与语义搜索，Claude-mem 构建了层次化的数据库架构。基础层采用 SQLite 3 配合 bun:sqlite 驱动程序，存储会话记录、原始观察数据和压缩后的摘要信息。SQLite 的 FTS5 虚拟表提供全文搜索能力，支持按关键词快速检索历史内容。对于需要语义理解的高级搜索场景，系统集成了 ChromaDB 作为向量数据库，将观察内容转换为高维向量表示，实现基于相似度的语义检索。
渐进式披露是 Claude-mem 在上下文管理上的核心策略。这一策略体现在多个层面：首先，在会话启动时的上下文注入采用分层加载机制，仅在必要时加载完整细节；其次，通过 MCP 工具实现的 3 层工作流程 ——search、timeline、get_observations—— 确保了检索过程的渐进性。初始搜索仅返回紧凑的索引信息（约 50-100 tokens / 结果），当开发者确定相关记录后再获取时间线上下文，最后才获取完整观察详情。这种设计能够在典型场景下实现约 10 倍的 token 节省。
MCP 工具与 3 层检索工作流
Model Context Protocol（MCP）在 Claude-mem 的上下文注入机制中扮演着关键角色。系统提供了四个核心 MCP 工具，形成了完整的检索能力集合。search 工具接受自然语言查询和过滤条件，返回符合条件的观察记录 ID 列表。timeline 工具获取特定观察记录周围的时间线上下文，帮助理解事件发生的背景。get_observations 工具根据 ID 列表批量获取完整的观察详情，这是唯一会消耗大量 tokens 的操作。
三个工具的调用顺序构成了 3 层工作流程的完整闭环。开发者在进行项目历史查询时，通常先使用 search 工具获取广泛的索引，然后根据返回的 ID 集合筛选出最相关的记录，接着使用 timeline 工具查看这些记录发生时的上下文环境，最后才调用 get_observations 获取必要的完整细节。这种设计不仅优化了 token 消耗，更重要的是帮助开发者逐步聚焦于真正相关的信息，避免在海量历史数据中迷失方向。
工程化参数与监控建议
在生产环境中部署 Claude-mem 时，开发者需要关注几个关键配置参数以平衡功能与性能。工作进程默认监听端口为 37777，可通过环境变量进行自定义配置。上下文注入的观察数量默认为 10 条，但可根据项目规模和上下文窗口限制进行调整。SQLite 数据库位于 ~/.claude-mem/claude-mem.db，其存储增长主要取决于会话频率和观察数据的保留策略。
对于长期运行的大型项目，建议定期监控数据库体积并设置合理的保留策略。Web 查看器 UI（localhost:37777）提供了实时的内存流可视化和 token 成本显示功能，开发者应利用这些监控能力识别异常行为。此外，<private> 标签的使用是保护敏感信息的有效手段，在涉及密钥、密码或其他保密信息的会话中应主动标记相关内容以排除在压缩和存储流程之外。
资料来源：本文技术细节参考 Claude-mem GitHub 仓库（thedotmack/claude-mem）及官方架构文档。