第 16 期：Q&A (一) 架构与数据流深度解惑

⏱ 预计阅读 10 分钟 更新于 2026/5/7
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

本期场景：作为《Claude-Mem 完全实战指南》的官方完结与补充，我们整理了高频出现的硬核技术问题。本期专注解答架构设计、数据一致性与运行时的底层逻辑。

Q1：上下文隔离 (Workspace Context Separation)

问：Claude-Mem 是如何区分不同项目（Workspace）的记忆上下文的？如果在两个终端同时打开不同项目会冲突吗？

答：绝对不会冲突。

Claude-Mem 巧妙地使用了“执行路径散列化”策略。每当 Claude Code 的生命周期钩子被触发时，系统会获取当前的终端工作目录（cwd，如 /Users/eric/work/blog），并将其计算为一个唯一的 workspace_id（通常是一串哈希值）。

所有的 Observation、Timeline 和 Metadata 在存入底层的 SQLite 和 ChromaDB 时，都会强制带上这个 workspace_id 作为外键。

当你在项目 A 发起 search() 查询时，检索层会自动且隐式地附加 WHERE workspace_id = 'A' 的过滤条件。因此，多终端并发运行不同项目时，数据是完全物理隔离的。

Q2：双库一致性 (Database Consistency)

问：SQLite（存储结构化数据）和 ChromaDB（存储向量数据）是如何保持一致性的？如果有一方文件损坏该如何恢复？

答：Claude-Mem 采用的是 "SQLite 作为唯一真实数据源 (Single Source of Truth)" 的架构策略。

每次写入记忆时：

  1. 先写入 SQLite（极快，支持 ACID 事务）。
  2. 成功后，将提取的文本异步提交给 Embedding 模型。
  3. 拿到向量后，再插入 ChromaDB。

如果电脑意外断电导致 ChromaDB 向量库损坏，或者你觉得搜索精度下降，恢复过程非常简单： 由于 SQLite 包含了所有原始文本数据，你只需要直接删除破损的向量目录，然后触发重建：

# 1. 删除向量数据目录
rm -rf ~/.claude-mem/chroma/

# 2. 从 SQLite 全量读取文本并重新生成 Embeddings
npx claude-mem rebuild-index

系统会在后台静默完成一致性修复，期间不影响你的常规开发。

Q3：运行时选型 (Bun vs Node.js)

问：为什么底层的 Worker Service 选择了 Bun，而不是生态更成熟的 Node.js 或性能更高的 Rust？

答：这是一个平衡了分发成本与后台驻留性能的决策：

  1. 极致冷启动与极低常驻内存：Worker 是在后台默默驻留的服务（Port 37777）。Bun 的内存碎片管理和启动速度优于 Node.js，更适合做本地轻量级守护进程。
  2. 开箱即用的 SQLite 极速绑定：Bun 内置了 bun:sqlite，它直接使用了高度优化的 C API 绑定。在 Node.js 中使用 SQLite 通常需要编译 node-sqlite3（经常遇到 node-gyp 报错）或使用性能一般的 wasm 方案。Bun 让数据库读写速度提升了 3-5 倍，且无需用户本地配置 C++ 编译环境。
  3. 原生 TypeScript 支持：无需额外的 tsc 编译步骤或 ts-node，降低了 CLI 分发复杂度和冷启动时间。

Q4：离线与重试 (Async Summarization)

问：异步压缩机制在遇到大模型 API 限流（429）或网络断开时会发生什么？会不会丢数据？

答：不会丢失任何数据。

Claude-Mem 设计了类似数据库 WAL（Write-Ahead Log）的稳健机制。原始的历史对话（Raw Transcript）会第一时间无损落盘到本地的序列表（Queue Table）中。

Worker 会在后台开启一个消费队列：

  • 遇到 429 报错：触发指数退避策略（Exponential Backoff），等待 2s、4s、8s... 后重试提取。
  • 遇到断网：任务会保留在队列中，状态标记为 pending。
  • 关机/重启：由于数据已经落盘，下次启动 Worker 时，它会在启动自检阶段读取数据库中状态为 pending 的记录，继续完成大模型摘要和向量化。

Q5：【Mermaid 时序图】钩子流转全景

问：从在终端触发 on_turn_end 钩子，到 Worker 最终将记忆写入数据库，完整的流转是怎样的？

答：这是一个涉及本地脚本、HTTP 通信与异步大模型调用的复杂链路，具体流程如下：

sequenceDiagram
    participant User as 用户 (终端)
    participant CC as Claude Code
    participant Hook as 本地 Hook 脚本
    participant Worker as Bun Worker (37777)
    participant DB as SQLite / Chroma
    participant LLM as 大模型 API (Gemini/Claude)

    User->>CC: 输入提示词并执行
    CC->>Hook: 触发 on_turn_end (传入 transcript)
    Hook->>Worker: POST /api/observations (传递原始日志)
    
    rect rgb(236, 253, 245)
        Note right of Worker: Fast Path (毫秒级响应)
        Worker->>DB: 1. 将原始日志存入 Pending 队列表
        Worker-->>Hook: 200 OK (释放用户终端)
    end
    Hook-->>CC: 钩子执行完毕，等待下一次输入
    
    rect rgb(254, 252, 232)
        Note right of Worker: Slow Path (后台异步处理)
        Worker->>LLM: 2. 请求压缩与提取 (Context Engineering)
        LLM-->>Worker: 返回结构化 JSON (概要, Tag, 实体)
        Worker->>DB: 3. 更新 SQLite (存入正式 Observation)
        Worker->>LLM: 4. 请求 Embeddings (向量化)
        LLM-->>Worker: 返回 float32 数组
        Worker->>DB: 5. 写入 ChromaDB
        Worker->>DB: 6. 标记 Pending 任务为 Completed
    end

图解：由于 Fast Path 的存在，无论后台的大模型压缩多慢，你的终端永远不会被卡住。

Q6：检索遗漏 (Progressive Disclosure 盲点)

问：为什么有时候 Progressive Disclosure（三层渐进式检索）会“找不到”明明存在于数据库里的历史代码片段？

答：这通常是由**“语义弥散”或“Token 预算过滤”**引起的。

  1. 语义弥散 (第一层漏检)：向量检索基于语义。如果你搜索具体的变量名 userId_v2，而当时存入时的摘要是 "重构了认证模块"，语义距离可能很远，导致它排在了 Top K 之外。
  2. 摘要过度折叠 (第二层误判)：即便第一层查到了，但在摘要展开阶段，AI 可能认为 "重构了认证模块" 这句话无法解答你的具体 Bug，从而决定放弃触发第三层（读取原始长文本），导致代码片段“隐身”。

💡 修复方案：

  • 精确指令：在提示词中强力引导，例如：“使用 search 工具，强制查询关键字 userId_v2，并且一次性将 limit 设置为 20”。
  • 直接指定：如果记得大致的时间或 ID，使用 get_observations([id]) 直接穿透防线读取底层数据。

Q7：缓存维护 (Vector DB Maintenance)

问：随着项目迭代，废弃代码越来越多，如何手动清理或重建本地的 ChromaDB 向量缓存以防被旧逻辑干扰？

答：长生命周期项目中，废弃代码（Dead Code）的向量污染是不可避免的。你可以通过以下步骤进行主动“遗忘”：

  1. 软废弃 (推荐)：使用 Make Plan + Do 找出废弃模块相关的 observation_ids，然后通过 MCP 调用将它们的标记打上 deprecated: true 的 metadata。检索层在过滤时会降低这些数据的权重。
  2. 按时间轴修剪：
    # 清理 2024 年 1 月 1 日之前的早期探索记录
npx claude-mem prune --before "2024-01-01"
  3. 核弹级重建：如果项目经历了伤筋动骨的大重构（如 Vue 迁移到 React），建议清空向量库并利用现有最新的代码库生成一份新的架构快照存入。这比保留乱七八糟的过渡期历史更高效。

下一期预告：在第 17 期中，我们将进入 Skills 与 MCP 的疑难杂症排查，为你解答 "Connection Refused" 等高频连接错误，并提供一份解决大目标跑偏的检查点拉回方案。