Hivemind (Activeloop) 架构分析

[!info] 知识库定位 这是一篇 项目案例 / 架构分析，重点记录”这个项目如何落地某些概念和工具”。 通用概念链接到 related_concepts；工具评估和使用方法链接到 related_tools。

Activeloop 出品的跨 Agent 共享记忆平台——为 Claude Code、OpenClaw、Codex、Cursor、Hermes、pi 等编码 Agent 提供统一的会话捕获、模式挖掘和技能传播基础设施。核心理念：“一个工程师的 Agent 周一解决了迁移难题，周二团队里每个 Agent 都能执行这个模式。“

核心问题与约束

Hivemind 试图解决一个现实问题：编码 Agent 之间的经验无法传递。每个 Agent session 是孤立的——A 工程师的 Claude Code 解决了一个棘手的 bug，B 工程师的 Cursor 完全不知道。

核心约束包括：

数据依据：docs/ARCHITECTURE.md 中每个 Agent 的 Integration Mechanism 表格，README.md 中的配置变量列表。

架构全景

graph TB
    subgraph "Agent 层（6 种异构客户端）"
        CC["Claude Code<br/>Marketplace Plugin"]
        CX["Codex<br/>hooks.json"]
        CR["Cursor 1.7+<br/>hooks.json"]
        OC["OpenClaw<br/>Native Extension"]
        HM["Hermes<br/>Shell Hooks + Skill"]
        PI["pi<br/>Extension API + AGENTS.md"]
    end

    subgraph "Hivemind 核心（共享层）"
        Hooks["Hook 适配层<br/>src/hooks/"]
        Core["共享核心<br/>src/ — API Client / Auth / Config / SQL"]
        MCP["MCP Server<br/>src/mcp/"]
        Embed["Embedding Daemon<br/>src/embeddings/<br/>nomic-embed-text-v1.5"]
        CLI["统一 CLI<br/>src/cli/ — install / skillify / rules"]
    end

    subgraph "存储与后处理层"
        DL["Deeplake 云存储<br/>sessions / memory / skills 表"]
        VFS["虚拟文件系统<br/>~/.deeplake/memory/"]
        WikiWorker["Wiki Worker<br/>后台摘要生成"]
        SkillWorker["Skillify Worker<br/>后台模式挖掘"]
    end

    CC --> Hooks
    CX --> Hooks
    CR --> Hooks
    OC --> Hooks
    HM --> Hooks
    HM --> MCP
    PI --> Hooks

    Hooks --> Core
    Core --> DL
    Core --> VFS
    Core --> WikiWorker
    Core --> SkillWorker
    WikiWorker --> DL
    SkillWorker --> DL
    Embed --> DL

    style Hooks fill:#f9f,stroke:#333,stroke-width:2px
    style Core fill:#bbf,stroke:#333,stroke-width:2px
    style DL fill:#fbb,stroke:#333,stroke-width:2px

架构风格：适配器-中枢-管道（Adapter-Hub-Pipeline）

Hivemind 采用三层架构，核心是一个适配器模式 + 后台管道处理的组合：

1. 适配器层（Adapter）：每种 Agent 一个 Hook 适配器（src/hooks/claude/、src/hooks/codex/、src/hooks/cursor/ 等），将异构的 Agent 事件统一转化为 Hivemind 内部事件格式。
2. 中枢层（Hub）：共享核心模块（src/）提供统一的 API Client、认证、配置和 SQL 工具，所有适配器共享同一套 Deeplake 交互逻辑。
3. 管道层（Pipeline）：后台 Worker（Wiki Worker + Skillify Worker）异步处理捕获的数据，生成摘要和技能。

为什么选这个风格：Agent 生态高度异构，适配器模式是唯一可行的解法——每个 Agent 的扩展机制完全不同。中枢层保证了”写一次存储逻辑，6 种 Agent 复用”。管道模式让捕获和后处理解耦，不阻塞 Agent 的主循环。

牺牲了什么：适配器层随着新 Agent 加入会持续膨胀；每个 Agent 的 hook 集合不完全一致（例如 Codex 缺少 SubagentStop），导致跨 Agent 的捕获粒度有差异。

核心模块解析

数据依据：docs/ARCHITECTURE.md 的 Monorepo Structure 部分，package.json 的 files 字段。

数据流分析

flowchart LR
    subgraph "Capture 阶段"
        A1["Agent Session<br/>prompt / tool call / response"]
        A2["Hook 触发<br/>PostToolUse / SessionEnd"]
        A3["写入 sessions 表<br/>Deeplake SQL"]
    end

    subgraph "Codify 阶段（后台异步）"
        B1["Wiki Worker<br/>摘要生成"]
        B2["Skillify Worker<br/>模式挖掘"]
        B3["写入 memory 表<br/>+ 768 维 embedding"]
        B4["写入 SKILL.md<br/>本地 + skills 表"]
    end

    subgraph "Propagate 阶段"
        C1["SessionStart<br/>auto-pull"]
        C2["symlink fan-out<br/>~/.claude/skills/ → 各 Agent skill root"]
        C3["Rules 注入<br/>SessionStart 时注入团队规则"]
    end

    subgraph "Recall 阶段"
        D1["用户自然语言查询"]
        D2["混合检索<br/>BM25 + 语义搜索"]
        D3["返回相关<br/>摘要 / 技能 / 规则"]
    end

    A1 --> A2 --> A3
    A3 --> B1 --> B3
    A3 --> B2 --> B4
    B4 --> C1 --> C2
    C3 --> D1
    D1 --> D2 --> D3
    A3 --> D2

核心循环：Capture → Codify → Propagate → Compound。每轮循环让 Agent 的能力在前一轮基础上累积。

数据依据：README.md 的 “How it works” 段落，docs/SKILLIFY.md 的 skill 生成流程。

关键架构决策

决策 1：宿主 Agent CLI 作为 AI 后端（而非独立 API Key）

• 背景：Wiki Worker 和 Skillify Worker 需要调用 LLM 来生成摘要和判断是否值得保留模式
• 决策：Shell out 到宿主 Agent 自己的 CLI（claude -p、codex exec、pi --print 等），复用用户已有的认证和配额
• 原因：零配置——用户不需要额外注册 API Key、不需要管理额外账单、不需要担心不同 Provider 的认证差异
• 代价：依赖宿主 Agent CLI 的可用性和性能；如果 Agent CLI 不支持 headless 模式就无法使用
• 风险：不同 Agent CLI 的输出格式和稳定性不同，Wiki Worker 需要为每种 CLI 做适配；CLI 调用的延迟比直接 API 调用高

数据依据：docs/SKILLIFY.md 的 “Per-agent gate CLI” 表格，docs/SUMMARIES.md 的 “How a summary is generated” 部分。

决策 2：Deeplake 作为统一存储层（而非自建数据库）

• 背景：需要存储结构化的会话数据、向量 embedding、技能文件，且要支持云端同步和 BYOC
• 决策：使用 Activeloop 自家的 Deeplake 作为存储后端，通过 SQL 接口操作
• 原因：Deeplake 原生支持张量数据（适合存储 embedding）、支持多种云存储后端（GCS/Azure/S3）、提供 SQL 查询接口；同时这是自家产品，技术栈完全可控
• 代价：强耦合到 Deeplake 生态；用户需要理解 Deeplake 的概念模型（table、VFS 等）
• 风险：Deeplake 的 SQL 实现有 quirks（如 docs/SKILLIFY.md 提到的 “UPDATE-coalescing quirk”，所以 skills 表采用 append-only 策略，从不 UPDATE）

数据依据：README.md 的 “Security & storage” 部分，docs/SKILLIFY.md 中关于 append-only 策略的说明。

决策 3：自适应多 Agent Hook 适配（而非统一协议）

• 背景：6 种 Agent 的扩展机制完全不同——Plugin / hooks.json / Shell Hooks / Extension API / AGENTS.md
• 决策：为每种 Agent 编写独立的适配器，在 src/hooks/ 下各自实现，共享核心逻辑
• 原因：现实是 Agent 生态没有统一的扩展协议；试图定义一个通用协议会牺牲每个 Agent 的最佳集成点。拥抱碎片化，在核心层统一
• 代价：每新增一个 Agent 需要编写一套新的 Hook 适配器（约 200-400 行 TypeScript）；维护成本随 Agent 数量线性增长
• 风险：某个 Agent 大幅改动 hook 机制时，适配器需要同步更新；不同 Agent 的生命周期事件粒度不一致导致功能差异

数据依据：docs/ARCHITECTURE.md 的 Integration Model 表格。

决策 4：本地 Embedding Daemon 作为可选组件

• 背景：语义搜索需要 embedding，但 embedding 模型的依赖体积约 600MB
• 决策：Embedding Daemon 默认关闭，通过 hivemind embeddings install 显式安装；关闭时静默降级为 BM25/lexical-only 搜索
• 原因：600MB 的依赖对很多用户是门槛；lexcial search 对大多数场景已经足够
• 代价：不安装 embedding 时语义搜索不可用，搜索质量下降；需要用户理解两种搜索模式的差异
• 风险：用户可能不知道自己没安装 embedding，搜索体验不如预期但不报错

数据依据：README.md 的 “Semantic search (optional)” 部分。

请求链路

场景：一次 Skill 自动挖掘的完整流程

sequenceDiagram
    participant Agent as Claude Code
    participant Hook as Hook 适配器
    participant Core as 共享核心
    participant DL as Deeplake
    participant CLI as 宿主 CLI (claude -p)
    participant FS as 本地文件系统

    Note over Agent: 每隔 20 轮或 SessionEnd 触发

    Hook->>Core: 触发 Skillify Worker
    Core->>DL: 查询最近 10 个 sessions<br/>(新于 watermark)
    DL-->>Core: 返回 session 数据

    Core->>Core: 过滤：仅保留 prompt + assistant text<br/>(丢弃 tool calls / thinking)

    Core->>Core: 组装 gate prompt<br/>+ 现有 skills + 10 条对话 + 决策规则

    Core->>CLI: claude -p haiku --permission-mode bypassPermissions
    CLI-->>Core: JSON verdict: KEEP / MERGE / SKIP

    alt KEEP 或 MERGE
        Core->>FS: 写入 SKILL.md<br/>(<project>/.claude/skills/<name>/)
        Core->>DL: INSERT INTO skills 表<br/>(append-only, 不 UPDATE)
        Core->>Core: 更新 watermark
    else SKIP
        Core->>Core: 更新 watermark, 不写文件
    end

场景：SessionStart 时 auto-pull 技能

sequenceDiagram
    participant Agent as 任意 Agent
    participant Hook as SessionStart Hook
    participant DL as Deeplake
    participant FS as 本地文件系统

    Agent->>Hook: SessionStart 触发
    Hook->>DL: 查询 skills 表（所有作者的最新版本）
    DL-->>Hook: 返回技能列表

    Hook->>FS: 写入 ~/.claude/skills/<name>--<author>/SKILL.md
    Hook->>FS: symlink fan-out<br/>→ ~/.agents/skills/<br/>→ ~/.hermes/skills/<br/>→ ~/.pi/agent/skills/

    Note over Hook: 5 秒超时，失败静默吞掉
    Hook-->>Agent: 完成（不阻塞启动）

数据依据：docs/SKILLIFY.md 的 “How a skill is generated” 和 “Auto-pull at SessionStart” 部分。

架构质量评估

架构风险与改进建议

[!danger] 风险点

1. 全量捕获的隐私风险：默认捕获完整 prompt、tool input/output、assistant response。包括 HIVEMIND_CAPTURE=false 需要用户主动设置，且按 session 级别（无法按工具或内容类型过滤）。依据：README.md 的 DATA COLLECTION NOTICE 表格。

2. Deeplake SQL Quirks：skills 表被迫采用 append-only 策略（从不 UPDATE）来规避 Deeplake 的 “UPDATE-coalescing quirk”。这意味着 skills 表会持续膨胀，清理策略不明确。依据：docs/SKILLIFY.md。

3. 宿主 CLI 依赖链：Wiki Worker 和 Skillify Worker 都依赖宿主 Agent 的 CLI 可用。如果用户的 claude CLI 版本不兼容或未安装，这些后台功能静默失败。依据：docs/SKILLIFY.md 的 “Per-agent gate CLI” 表格。

4. 跨项目技能冲突：同一 (name, author) 组合来自不同项目时在磁盘上冲突，后拉取的覆盖先拉取的（虽然保留了 .bak）。依据：docs/SKILLIFY.md 的 “Cross-project caveat” 段落。

[!tip] 改进建议

1. 细粒度捕获控制（优先级：高）：增加按工具类型或内容模式的过滤规则（如”不捕获包含 API key 的 tool input”），而非只有全局开关。
2. Skills 表清理策略（优先级：中）：引入 version-based GC，定期清理被 MERGE 替代的旧版本行。
3. CLI 可用性检测（优先级：中）：在 Worker 启动前检查宿主 CLI 是否可用和版本是否兼容，不可用时明确通知用户而非静默失败。
4. Embedding 状态提示（优先级：低）：在搜索结果中标注”语义搜索未启用”提示，避免用户困惑于搜索质量。

可复用架构经验

值得借鉴的模式：

• 适配器-中枢模式处理生态碎片化（适用条件：需要集成多种异构客户端，且无法控制它们的扩展协议）— src/hooks/ 下每个 Agent 一个适配器，src/ 共享核心。这种模式让 Hivemind 在 Agent 生态快速演化时保持灵活。
• Shell out 复用宿主 CLI 做 AI 推理（适用条件：工具需要调用 LLM 但不想引入额外 API Key 管理负担）— Wiki Worker 和 Skillify Worker 都通过 claude -p / codex exec 等调用 LLM。用户零配置，代价是延迟和 CLI 可用性依赖。
• 后台 Worker + Watermark 的增量处理（适用条件：需要从大量历史数据中异步挖掘模式）— Skillify Worker 用 watermark 文件跟踪已处理的 session，每次只处理增量数据。~/.deeplake/state/skillify/<project>.json。
• Symlink Fan-out 实现跨 Agent 技能分发（适用条件：多种工具共享同一套技能文件但各自读取路径不同）— hivemind skillify pull 写入 ~/.claude/skills/ 然后通过 symlink 分发到 ~/.agents/skills/、~/.hermes/skills/ 等目录。
• 静默降级策略（适用条件：可选功能不应阻塞主流程）— Embedding Daemon 不安装时 BM25 fallback；auto-pull 失败时静默跳过；VFS 操作失败时不崩溃。

值得警惕的反模式：

• 静默吞掉所有错误（出现场景：auto-pull 和 Worker 执行中）— 虽然保证不阻塞，但用户完全无法感知功能是否真正在工作。应该在某处提供”最后同步状态”的可观测性。
• Append-only 无清理（出现场景：skills 表的写入策略）— 规避了 UPDATE quirk 但引入了数据膨胀，长期运行后需要手动干预或引入 GC 机制。

关联概念

架构风格：适配器模式 · 管道-过滤器架构 · 事件驱动架构 技术选型：TypeScript · esbuild · Deeplake · tree-sitter 相关项目：Claude Code · Hermes Agent · Petals 通用概念：RAG · MCP · Agent Memory · Embedding · BM25 · 混合检索 工具笔记：Deeplake