在 Claude Code 的日常使用中，开发者经常面临一个核心痛点：每次新建会话都需要重新向 AI 说明项目背景、已完成的工作和待解决的问题。传统方案依赖手动维护笔记或使用系统提示词，但前者容易被遗忘，后者则面临上下文长度限制。Claude-Mem 作为一款专为 Claude Code 设计的持久化记忆插件，通过自动捕获会话操作、AI 压缩与智能注入三大核心机制，实现了跨会话的上下文无缝衔接。本文将从工程实现角度剖析其架构设计，并给出可落地的部署参数与监控建议。

核心架构：五阶段生命周期钩子

Claude-Mem 的设计哲学是「观察外部化、处理异步化、注入选择化」。整个系统由五个生命周期钩子驱动，分别对应 Claude Code 会话的不同阶段。SessionStart 钩子在每次新会话启动时立即执行，负责从数据库中检索历史记忆并注入到当前上下文的初始位置；UserPromptSubmit 钩子捕获用户提交的原始提示词，用于建立会话意图的语义索引；PostToolUse 钩子监听每一次工具调用，将工具名称、输入参数和输出结果存储为观测数据；Stop 钩子在用户主动停止会话时触发，生成当前会话的语义摘要；SessionEnd 钩子则会标记会话完成并触发后台压缩流程。这种精细化的阶段划分确保了每个环节只承担单一职责，钩子执行时间通常控制在毫秒级别，不会对用户的交互响应产生可感知的延迟。

值得注意的是，Claude-Mem 还包含一个前置的 Smart Install 钩子，用于在插件加载前检查并安装 Bun 运行时和 uv 向量数据库依赖。这个设计避免了因缺失运行时导致的插件初始化失败，同时也为多平台兼容性提供了统一的入口。

异步压缩管道：Worker Service 的后台处理

如果把五个生命周期钩子看作是系统的「感知层」，那么 Worker Service 就是真正的「思考层」。当用户在会话中触发 Stop 或 SessionEnd 钩子时，系统并不会立即执行 AI 压缩 —— 这是因为大语言模型的推理耗时通常是工具执行的数十倍，如果让钩子同步等待压缩完成，用户将被迫长时间等待会话结束。

实际的实现采用了典型的生产者 - 消费者模式：钩子作为生产者，将捕获到的观测数据快速写入 SQLite 数据库并返回，整个过程通常在 100 毫秒以内完成；Worker Service 作为消费者，从数据库中拉取待处理的观测数据，调用 Claude Agent SDK 对其进行语义压缩，生成结构化的摘要后重新写入数据库。这种设计带来了三个关键优势：首先，用户的会话结束操作可以立即返回，体验上几乎无感知；其次，即使压缩过程因网络问题或 API 限流失败，已捕获的原始数据仍然安全存储，后续可以重试；最后，Worker Service 可以独立扩展，支持多实例部署以应对高频使用场景。

Worker Service 默认监听本地端口 37777，除了提供数据库读写接口外，还内置了一个 Web 界面用于实时监控记忆流和调试。在生产环境中，建议通过反向代理将端口暴露给宿主机，并配置防火墙规则仅允许本地访问以保障数据安全。

三层检索工作流：渐进式上下文 Disclosure

Claude-Mem 提供了四个 MCP 工具用于记忆检索，但推荐遵循「三层渐进式 Disclosure」模式以最大化 token 使用效率。第一层是 search 工具，它返回紧凑的结果索引，每个结果仅包含 ID、类型、时间戳和摘要等少量信息，消耗约 50 到 100 个 token。用户可以据此快速筛选出与当前任务相关的记忆片段。第二层是 timeline 工具，它以指定观测 ID 为中心，展示前后时间线上的上下文，帮助理解该操作在项目历史中的位置。第三层是 get_observations 工具，它根据筛选后的 ID 列表拉取完整的观测详情，包括原始工具调用的完整输入输出，消耗约 500 到 1000 个 token 每条。

这种设计遵循了「先过滤后获取」的原则，相比一次性拉取全部记忆的方式，可以节省约 10 倍的 token 消耗。对于上下文窗口有限的模型来说，这一优化直接决定了系统能否在可用的 token 限额内注入足够的历史信息。

部署参数与监控要点

在实际部署中，有几个关键参数需要根据项目规模进行调优。首先是 CLAUDE_MEM_MODE 配置项，它控制生成观测和摘要时使用的语言，默认为英文但支持 code--zh 等本地化模式。其次是 contextWindowSize 设置项，它决定了每次会话启动时注入的历史记忆量，建议根据模型的最大上下文窗口减去系统提示词和安全边界后动态计算。具体的计算公式可以参考官方文档中的渐进式 Disclosure 策略指南。

对于安全敏感的项目，Claude-Mem 支持使用 <private> 标签排除特定内容不被存储，这一机制在钩子层实现，因此即使 Worker Service 不可用，敏感信息也不会被写入数据库。此外，建议在生产环境中配置日志级别为 warn 或 error，避免 debug 级别产生的大量 I/O 操作影响性能。

监控方面，可以定期检查 SQLite 数据库的体积增长趋势 —— 如果发现数据库在短期内异常膨胀，可能说明 PostToolUse 钩子捕获了过量的工具输出，需要调整过滤规则排除大型二进制数据。同时，建议为 Worker Service 配置健康检查端点，确保压缩管道始终处于可用状态。

资料来源：本文核心架构细节参考 Claude-Mem 官方 GitHub 仓库（https://github.com/thedotmack/claude-mem）及官方架构文档（https://docs.claude-mem.ai/architecture/overview）。