在大型语言模型辅助编程场景中，一个核心痛点始终存在：每次启动新的 Claude Code 会话时，模型对项目上下文的理解几乎为零。无论是上周调试了三个小时的内存泄漏问题，还是前天重构的复杂业务逻辑，一旦会话结束，这些宝贵的经验便随之消散。传统解决方案往往是让用户在每次会话开始时手动粘贴背景信息，但这种做法既繁琐又难以规模化。claude-mem 的出现正是为了解决这一困境：通过自动化的会话捕获与智能上下文注入，让 Claude Code 能够在新的会话中「记住」之前的编码历史。
理解 claude-mem 的工程架构，关键在于把握其「外部观察、后台处理、适时注入」的核心设计原则。整个系统不修改 Claude Code 的内部行为，而是通过生命周期钩子从外部观察会话进程，在后台完成资源密集型的 AI 压缩工作，最终在适当时机将压缩后的上下文注入新会话。这种架构设计面临的首要挑战是性能与功能的平衡：AI 摘要生成通常需要 5 到 30 秒的时间，显然不能让主会话等待这么长时间。因此，claude-mem 采用了钩子与 Worker 服务分离的双层架构，将快速的钩子执行与耗时的 AI 处理解耦开来。
claude-mem 的钩子系统包含六个生命周期钩子和一个预钩子，覆盖了 Claude Code 会话的完整生命周期。智能安装预钩子运行在 SessionStart 之前，负责依赖检查和 Worker 服务的启动，它通过版本缓存机制避免重复安装，首次安装后再次运行仅需约 10 毫秒。SessionStart 阶段会依次执行上下文注入钩子和用户消息钩子：上下文注入钩子从 SQLite 数据库中检索最近的会话摘要和观察记录，按照渐进式披露的格式输出到标准输出，这些内容随后被自动注入到 Claude Code 的上下文窗口中。用户消息钩子则负责显示首次设置提示和查看器 UI 链接，为用户提供友好的使用体验。
UserPromptSubmit 钩子在用户提交提示时触发，负责初始化会话跟踪。它会立即在数据库中创建新的会话记录，并将原始用户提示保存以支持全文搜索。重要的是，这个钩子会 SuppressOutput，确保其运行不影响用户的正常交互。PostToolUse 钩子是整个捕获系统的核心，它在每次工具执行完成后立即运行，接收工具名称、输入和输出信息，并将其快速入队到观察队列表中。整个入队过程控制在 20 毫秒以内，保证了对主会话的零感知影响。Stop 钩子在会话停止时触发，利用 Claude Agent SDK 对收集到的观察记录进行 AI 压缩，生成结构化的摘要信息。最后，SessionEnd 钩子负责标记会话完成，并执行优雅的清理操作。
Worker 服务是 claude-mem 架构中承担重负载的组件，它运行在 Bun 运行时之上，通过 HTTP API 与钩子进行通信。Worker 服务监听 37777 端口，提供健康检查、会话管理、观察入队和获取等端点。当 PostToolUse 钩子将观察记录写入队列后，Worker 服务每秒钟轮询一次队列，调用 Claude Agent SDK 对观察内容进行语义压缩。压缩后的结果包括原始请求、调查过程、发现的关键信息、完成的工作以及后续步骤，这些结构化数据被存储在 SQLite 数据库中供后续检索使用。Bun 运行时在此处的优势在于其快速的启动时间和低内存占用，同时内置的进程管理能力可以自动重启崩溃的 Worker 实例。
上下文注入的策略设计体现了 claude-mem 对 Token 成本控制的深思熟虑。系统默认检索最近 10 个会话摘要和 50 条观察记录，但这些信息并非全部展开显示，而是以渐进式披露的索引形式呈现。每个索引条目仅占用约 50 到 100 个 Token，包含 ID、时间戳、类型标识和标题。用户或 Claude 模型可以通过 mem-search 技能使用 MCP 搜索工具进一步获取详细信息：首先是 compact index 级别的 search 操作，然后是获取时间线上下文，最后才获取完整观察详情。这种三层工作流能够实现约 10 倍的 Token 节省。对于上下文注入的时机，系统将其配置为可调参数，开发者可以通过 CLAUDE_MEM_CONTEXT_OBSERVATIONS 环境变量控制注入的观察数量上限。
在工程实践中，有几个关键参数值得关注。钩子超时设置对系统稳定性至关重要：SessionStart 相关钩子设置为 300 秒以容纳首次安装的耗时，UserPromptSubmit、PostToolUse 和 SessionEnd 钩子则采用 120 秒的默认超时。Worker 服务的健康检查间隔默认为 1 秒，这平衡了响应速度与资源消耗。数据库方面，系统使用 SQLite 的 FTS5 全文搜索功能配合 Chroma 向量数据库实现混合检索，结合关键词匹配与语义相似度提供精准的上下文召回。隐私控制方面，用户可以使用<private>标签标记敏感内容，使其被排除在存储之外，但原始提示仍会保留在本地 SQLite 数据库中。
监控与调试是确保系统可靠运行的重要环节。启用 Claude Code 的 debug 模式可以查看钩子的详细执行日志，包括匹配器匹配、命令执行和返回状态等信息。常见的排查场景包括：检查钩子是否通过/hooks菜单注册成功、验证匹配器模式的正确性、测试钩子命令的手动执行以及检查文件权限设置。当观察到会话未正常结束时，应检查 Worker 服务状态和数据库连接情况。Worker 服务的日志可以通过npm run worker:logs命令查看，这对于定位观察处理失败的原因尤为重要。
claude-mem 的架构设计为 AI 编程助手的持久化记忆提供了可参考的实现范式。其核心启示在于：通过严格的非侵入式设计确保主系统的稳定性，通过钩子与 Worker 的分离实现性能与功能的平衡，通过渐进式披露策略控制 Token 成本。这套架构的工程参数 —— 从 20 毫秒的钩子响应目标到 300 秒的安装超时，从 50 条默认观察注入到三层检索工作流 —— 为类似系统的构建提供了可量化的参考基准。
资料来源：GitHub 仓库 https://github.com/thedotmack/claude-mem，钩子架构文档 https://docs.claude-mem.ai/hooks-architecture