claude-mem — 跨会话持久记忆系统

为 Claude Code 打造的持久记忆压缩系统，自动捕获工具调用观察、用 AI 生成语义摘要，并在未来会话中注入相关上下文。

项目概览

子文档目录

• 01-Hooks 生命周期 — 6 个生命周期钩子的触发时机与数据流向
• 02-Worker 服务与 AI 处理 — WorkerService 核心协调器、多 AI 提供商抽象
• 03-搜索架构 — SQLite FTS5 + Chroma 混合检索
• 04-安装与多平台集成 — 安装流程与多 IDE 集成
• 05-进阶设计亮点 — 五个值得反复研读的架构决策
• 06-记忆如何在对话中体现 — 自动注入与主动搜索两条路径
• 07-思考与展望 — 设计哲学与可迁移模式

我的核心收获

1. Hook 是零侵入的信息高速公路：claude-mem 没有修改 Claude Code 任何代码，纯粹通过标准 lifecycle hook + stdout JSON injection 实现了完整的记忆注入。{"hookSpecificOutput": {"additionalContext": "..."}} 这个协议极其优雅——一个 JSON 字段就能向 Claude 的上下文追加任意内容。

2. “边缘处理"是隐私保护的正确姿势：<private> 标签在 hook 层（最靠近用户输入的地方）就被剥离，不进入任何异步队列。同时 Worker 层还有第二道防线。这是 defense-in-depth + fail-safe 原则的教科书式实践。

3. 3 层搜索工作流是 token 工程的精华：search 返回摘要索引（~75 tokens/条），timeline 展开上下文，get_observations 才拉全文。通过 __IMPORTANT 元工具把工作流强制写入 LLM 系统提示，从架构层面约束消费端行为。

4. Corpus 知识库用 AI 会话 ID 作为编译缓存：prime 一次知识库就拿到 session_id，后续 query 用 resume 复用，避免每次重传几十 KB 文档。

5. uid % 100 端口分配是小决策里的大智慧：随机端口每次变化需要持久化；固定端口多用户冲突。uid 模运算同时满足"稳定"和"多用户隔离”。