在日常开发中，Claude Code 的会话通常在退出后丢失所有上下文。当重新打开一个新会话时，模型对之前的项目理解、已解决的问题、关键决策完全清零，导致大量重复劳动。claude-mem 插件通过自动捕获会话数据、AI 压缩、上下文注入的完整管道，系统性地解决了这一问题。本文从工程实现角度，解析其核心架构并给出可落地的配置建议。

核心架构：五阶段生命周期管道

claude-mem 的核心设计基于 Claude Code 的生命周期钩子机制。整个系统可以划分为五个阶段，每个阶段对应不同的钩子函数和数据处理逻辑。

第一阶段：会话启动（SessionStart）。当新会话开始时，context-hook 触发。此时系统会检查 Worker Service 是否运行，若未启动则通过 Bun 拉起。随后从 SQLite 数据库中读取历史会话的压缩摘要，根据配置数量注入到当前会话的上下文中。这一过程对用户透明完成，无需手动干预。关键配置项 context.observations 控制注入的历史 observation 数量，默认值通常在 5 到 15 之间，具体数值取决于单次摘要的 token 消耗。

第二阶段：用户提交 prompt（UserPromptSubmit）。new-hook 在每次用户提交指令时触发，负责在数据库中创建新的会话记录，同时保存原始用户 prompt 供全文搜索使用。这一阶段的开销极低，仅涉及基础的 CRUD 操作。

第三阶段：工具执行捕获（PostToolUse）。这是数据捕获的核心阶段。save-hook 在每次工具调用后触发，捕获完整的工具名称、输入参数、输出结果，并将原始数据写入 SQLite。随后异步发送给 Worker Service 进行 AI 压缩处理。在一个典型的编码会话中，这个钩子会触发数百次，因此系统采用了批量写入和异步处理的策略来降低对响应速度的影响。

第四阶段：AI 压缩处理。Worker Service 接收原始 observation 数据后，使用 Claude Agent SDK 调用大模型进行语义理解和压缩。系统会提取关键信息，包括代码变更意图、问题根因、解决方案、文件依赖关系等，生成结构化的压缩摘要。这一步是降低上下文丢失风险的关键所在。

第五阶段：会话结束（SessionEnd）。cleanup-hook 在会话结束时标记会话完成，但不删除数据。这确保了历史上下文可以完整保留到下一个会话。值得注意的是，如果用户使用 /clear 命令清除会话，cleanup-hook 不会触发，这是一种有意的设计选择。

关键技术实现：渐进式披露与三层检索

claude-mem 引入了一个重要的工程概念 —— 渐进式披露（Progressive Disclosure）。这个设计理念解决了长期困扰 AI 助手的一个核心问题：如何在有限的上下文窗口中高效利用历史信息。

传统的做法是将所有历史会话完整注入上下文，但这会导致 token 成本急剧上升。claude-mem 采用了三层检索模式来优化这一过程。第一层是 search 工具，返回紧凑的索引结果，每个结果仅消耗约 50 到 100 个 token，包含观察 ID 和摘要。第二层是 timeline 工具，获取特定观察周围的时间上下文，帮助理解事件链。第三层是 get_observations 工具，仅针对筛选后的 ID 拉取完整详情，每次约 500 到 1000 个 token。

这种设计的核心优势在于 token 节省。官方数据显示，相比直接使用 MCP 工具拉取完整详情，三层模式可以节省约 10 倍的 token 消耗。对于长期维护的项目，这直接决定了是否能够在有限的上下文窗口内保持有效的历史信息覆盖。

可落地配置：参数化控制与监控要点

在实际工程部署中，以下配置参数值得关注。配置文件位于 ~/.claude-mem/settings.json，首次运行时会自动创建默认配置。

上下文注入控制。核心参数 context.observations 决定了每次新会话注入的历史摘要数量。对于小型项目（代码库小于 10 万行），建议设置为 10 到 15；对于大型项目，建议设置为 5 到 8，避免单次会话的上下文过于膨胀。参数 context.token_budget 可以设置单次会话的上下文 token 上限，系统会自动调整注入数量以适配此预算。

AI 压缩粒度。参数 compression.level 控制压缩激进程度，可选值包括 conservative、balanced、aggressive。conservative 模式保留更多原始细节，适合需要精确回忆的调试场景；balanced 是默认值，在信息完整性和 token 效率之间取得平衡；aggressive 模式会进行更强度的摘要，适合上下文窗口紧张的场景。

搜索与检索。参数 search.default_limit 控制单次搜索返回的结果数量，默认值为 10。如果项目历史较短可以适当增加，如果项目规模庞大建议保持默认值以避免信息过载。参数 search.enable_vector 控制是否启用 ChromaDB 向量搜索，启用后可以进行语义相似度匹配，但需要额外的依赖和资源开销。

隐私控制。claude-mem 支持通过 <private> 标签排除敏感内容。在工具使用说明、文件内容中包含该标签的内容不会被存储到数据库中。这是一个实用的安全特性，建议在处理包含密钥、密码、业务敏感信息的会话时启用。

监控与调试。Worker Service 在端口 37777（可配置）提供 Web UI 和 API 端点。通过访问 http://localhost:37777 可以实时查看内存流、观察存储状态、配置参数。关键监控指标包括：数据库文件大小（~/.claude-mem/claude-mem.db），用于评估存储增长趋势；每秒处理的 observation 数量，反映 AI 压缩的处理负载；API 响应延迟，用于评估对会话响应速度的影响。

工程实践建议

在生产环境中部署 claude-mem 时，有几个实践要点值得注意。首先是依赖管理，系统需要 Node.js 18.0 以上版本和 Bun 运行时。首次安装时，系统会自动检查依赖，如果缺失会提示安装。对于企业环境，建议通过内部镜像源预先配置依赖，避免网络问题导致的安装失败。

其次是数据库维护。SQLite 数据库会随着使用时间增长，建议每月检查一次文件大小并进行必要的归档。对于超过一年未访问的历史会话，可以考虑导出为独立备份文件后从主数据库中移除。

第三是版本管理。claude-mem 提供稳定版和 Beta 版两个发布通道。Beta 版包含实验性功能如 Endless Mode，建议先在非关键项目上验证稳定性后再切换生产环境。版本切换可以通过 Web UI 的 Settings 界面完成。

小结

claude-mem 通过五阶段生命周期管道实现了会话上下文的自动捕获与智能压缩，其渐进式披露的三层检索模式在信息完整性和 token 效率之间找到了平衡点。工程落地的关键在于合理配置 context.observations 和 compression.level 参数，同时通过 Web UI 监控数据库增长和处理负载。对于需要长期维护复杂项目的团队，这个插件能够显著降低上下文丢失带来的重复劳动。

参考资料