Hivemind 深度教學

把 6 種 coding agent（Claude Code / Codex / OpenClaw / Cursor / Hermes / pi）的 session trace 統一捕捉到 Deeplake，背景 worker 自動挖 pattern → 寫 SKILL.md → 跨 agent 注入。在 LoCoMo benchmark 上省 25% cost / 1.7× token / 31% turn。

1. 專案定位（Why this project）

Hivemind 解決的是「團隊內 agent 知識孤島」問題。傳統作法：

Prompt library / ~/.claude/commands/ — 手寫、靜態、不會自己生
各 agent 各自記憶（Claude Code memory、Codex 沒記憶）— 互不通氣
Sub-agent / multi-agent orchestration — 只解決單 session 內部，不跨 session、不跨人

Hivemind 的差異化是 「trace mining → automatic skill codification → cross-agent propagation」三段式：

Capture：用各 agent 原生 hook（Claude Code SessionStart/PreToolUse/Stop、Codex ~/.codex/hooks.json、Cursor ~/.cursor/hooks.json…）抓 raw trace 到 Deeplake sessions table
Codify：背景 worker 在 Stop / SessionEnd 觸發，問 Haiku「這段活動有沒有值得保留的 pattern」，符合就生 SKILL.md 寫進 <project>/.claude/skills/<name>/
Propagate：團隊成員 hivemind skillify pull 拉同事的 skill；SessionStart 注入 rules + how-to block

為什麼值得讀：

對本 AI-Knowledge Template 來說，hivemind 的 skillify worker 與 continuous-learning-v2 / instinct 系統高度同構，可比對設計差異
VFS-backed Goals/KPIs（~/.deeplake/memory/goal/<owner>/<status>/<uuid>.md）的 path-as-state 設計值得借鏡
LoCoMo 25% cost / 1.7× token 是「記憶系統值不值得做」的 hard number 參考點

2. 安裝指南（Installation）

2.1 最小安裝（個人 / 測試用）

1# 1. Node ≥ 22.0.0 必備（package.json 強制）
2node --version  # 應顯示 v22+
3
4# 2. 全域安裝 npm package
5npm install -g @deeplake/hivemind
6
7# 3. 跑 install command（自動偵測本機已裝的 agent，wire 起 hook）
8hivemind install

安裝後會做：

掃描 ~/.claude/ / ~/.codex/ / ~/.cursor/ / ~/.hermes/ / ~/.openclaw/ / ~/.pi/ 判斷哪些 agent 在
對每個 detected agent 寫對應的 hook config（細節見 docs/ARCHITECTURE.md）
開瀏覽器跑 device flow 登入（拿 token、存到 ~/.deeplake/creds.json，chmod 0600）

2.2 Headless / CI 安裝

1HIVEMIND_TOKEN=<your-token> hivemind install
2# 或
3hivemind install --token <your-token>

從 https://deeplake.ai 帳號設定拿 token；沒 token 時 non-interactive shell 會 skip 登入但 hook 還是裝好，之後 hivemind login 補。

2.3 指定單一 agent

1hivemind install --only claude
2hivemind claude install   # 等價寫法

支援的 --only 值：claude / codex / cursor / hermes / pi / openclaw。

2.4 啟用 semantic search（選用，+600 MB）

1hivemind embeddings install
2# 或一次裝齊
3hivemind install --with-embeddings

跑 nomic-embed-text-v1.5 daemon，768-dim embedding 與 BM25 lexical 混合檢索。不裝也可用，會 silently fall back 到 BM25-only。

3. 核心架構解析（Core Architecture）

3.1 高層架構圖


flowchart TB
  subgraph Agents["6 種 AI coding agent"]
    CC[Claude Code]
    CX[Codex]
    OC[OpenClaw]
    CR[Cursor 1.7+]
    HM[Hermes]
    PI[pi]
  end

  subgraph Capture["Capture 層"]
    H1[SessionStart / UserPromptSubmit / PreToolUse]
    H2[PostToolUse / Stop / SessionEnd]
  end

  subgraph Core["Hivemind Core (TypeScript)"]
    SC[src/cli/ — unified CLI]
    SH[src/hooks/ — 各 agent hook handler]
    SE[src/embeddings/ — nomic daemon protocol]
    SM[src/mcp/ — MCP server]
    SR[src/commands/ — auth/login/session-prune]
  end

  subgraph Storage["Deeplake Storage"]
    SS[sessions table — raw trace]
    MS[memory table — summaries + VFS]
    RS[hivemind_rules table]
    EMB[768-dim nomic embeddings]
  end

  subgraph Outputs["Codified outputs"]
    SK[SKILL.md → project/.claude/skills/]
    GO[Goals + KPIs in VFS]
    GR[Codebase graph]
  end

  Agents -->|hook fires| Capture
  Capture --> SH
  SH --> SC
  SC -->|HTTPS + TLS| Storage
  Storage -->|skillify worker poll| SK
  Storage -->|recall query| Agents
  SE -->|optional| EMB
  EMB -->|hybrid retrieval| SS

3.2 Per-agent integration mechanism

Agent	Mechanism	主要 hook
Claude Code	Marketplace plugin（`hivemind` bundle）	`SessionStart` / `UserPromptSubmit` / `PreToolUse` / `PostToolUse` / `Stop` / `SubagentStop` / `SessionEnd`
Codex	`~/.codex/hooks.json`	`SessionStart` / `UserPromptSubmit` / `PreToolUse(Bash)` / `PostToolUse` / `Stop`
OpenClaw	Native extension `~/.openclaw/extensions/hivemind/`	`agent_end` capture / `before_agent_start` recall / contracted tools (`hivemind_search/read/index`)
Cursor (1.7+)	`~/.cursor/hooks.json`	`sessionStart` / `beforeSubmitPrompt` / `postToolUse` / `afterAgentResponse` / `stop` / `sessionEnd`
Hermes	Skill `~/.hermes/skills/hivemind-memory/`	recall via grep on `~/.deeplake/memory/`
pi	`~/.pi/agent/AGENTS.md` + skill	recall via grep on `~/.deeplake/memory/`

3.3 Monorepo 結構

 1hivemind/
 2├── src/                    ← 共用核心（API client / auth / config / SQL utils）
 3│   ├── hooks/              ← Claude Code hooks
 4│   ├── hooks/codex/        ← Codex hooks
 5│   ├── hooks/cursor/       ← Cursor hooks
 6│   ├── hooks/hermes/       ← Hermes shell hooks
 7│   ├── hooks/pi/           ← pi wiki-worker
 8│   ├── embeddings/         ← nomic embed-daemon + protocol
 9│   ├── mcp/                ← MCP server (Hermes + 未來 MCP client)
10│   ├── commands/           ← auth, auth-creds, auth-login, session-prune
11│   └── cli/                ← unified `hivemind install` CLI
12├── claude-code/            ← Claude Code 插件（marketplace）
13├── codex/                  ← Codex 插件（npm）
14├── cursor/                 ← Cursor 插件（npm）
15├── hermes/                 ← Hermes 插件（npm）
16├── openclaw/               ← OpenClaw 插件（ClawHub）
17├── pi/                     ← pi extension source（raw .ts，pi 載入時編譯）
18├── mcp/                    ← MCP server build output
19└── bundle/                 ← unified `hivemind` CLI build output

3.4 Trace lifecycle 資料流


flowchart LR
  A[Agent session start] -->|SessionStart hook| B[Inject rules + how-to]
  B --> C[User prompt]
  C -->|UserPromptSubmit| D[capture event]
  C --> E[Agent thinks]
  E -->|PreToolUse| F[capture tool call]
  E --> G[Tool runs]
  G -->|PostToolUse| H[capture tool response]
  H --> E
  E --> I[Agent responds]
  I -->|Stop / SessionEnd| J[capture final + trigger skillify worker]
  J --> K[Background worker]
  K -->|every N turns / 50 msg / 2hr| L[ask Haiku: worth keeping?]
  L -->|yes| M[generate SKILL.md]
  L -->|yes| N[generate wiki summary]
  M --> O[write to project/.claude/skills/]
  N --> P[write to ~/.deeplake/memory/summaries/]

4. Helper Scripts 詳細用法（Scripts in scripts/）

4.1 scripts/audit-openclaw-bundle.mjs（7.1KB）

對 OpenClaw bundle 做 5 項 critical 靜態掃描（issue #169 明示 ClawHub 因此 reject hivemind plugin），確保上架前不會被 ClawHub 退件。CI 應 gate 在 audit:openclaw 步驟。

4.2 scripts/ensure-tree-sitter.mjs（4.3KB）

postinstall hook — 安裝 tree-sitter native binding（用於 codebase graph 的 symbol 解析）。v0.7.61 的 fix 把 scripts/ 包進 npm tarball，避免 postinstall 找不到此檔。

4.3 scripts/pack-check.mjs（998B）

npm publish 前檢查 tarball 內容（避免漏檔、避免誤包 .env 等敏感檔）。

4.4 scripts/sync-versions.mjs（3.3KB）

跨 monorepo 同步版本號（root package.json + claude-code/ + codex/ + cursor/ + hermes/ + openclaw/ 一次推到同一版本）。release pipeline 主要工具。

4.5 scripts/verify-install.sh（9KB）

對已安裝環境做端到端驗證：

確認 hivemind --version 可跑
確認每個 detected agent 的 hook config 正確
確認 ~/.deeplake/creds.json 權限 0600、~/.deeplake/ 目錄 0700
確認 trace 能寫進 Deeplake（dry-run）

debug 用主力。新環境裝完一定要跑一次。

5. 應用場景（Use cases）

5.1 多人團隊 + 混用 agent

最大價值場景。team A 用 Claude Code、team B 用 Codex、team C 用 Cursor — 三組人寫的 skill 自動沉澱、自動跨 agent propagate。任何一組搞定 migration pattern，其他兩組明天就會自動拿到。

5.2 資深工程師 pattern 沉澱

senior 不需要主動寫文件 / 寫 prompt library — 只要正常用 agent，hivemind 自動挖出他的高頻 successful pattern → 寫成 SKILL.md → junior 的 agent 自動拉到本地。

5.3 Cross-session debugging

「我上週解過類似的 bug，怎麼解的？」自然語言問 agent，hivemind hybrid retrieval（BM25 + nomic embedding）跨 session 找出當時的 trace 與 fix。

5.4 Goals + KPIs 追蹤

VFS-backed：~/.deeplake/memory/goal/<owner>/in_progress/<uuid>.md。Path 編碼狀態（opened/ → in_progress/ → closed/ 透過 mv 切換），body 是純 markdown 描述。對 claude-code / codex 等支援 VFS 的 runtime 直接 Bash heredoc 寫；cursor / hermes / pi 透過 hivemind goal add CLI fallback。

5.5 Enterprise BYOC 部署

Hivemind Cloud（預設）→ GCS / Azure / S3 / on-prem S3-compatible（contact us）。對受 SOC2 / HIPAA 限制的 enterprise 客戶友善 — trace 不出客戶 perimeter，credentials 在 Deep Lake vault。

6. 資安掃描報告（Security Scan）

6.1 整體評級：🟡 中等風險（可控）

對 enterprise 評估場景，建議在啟用前先確認 §6.3 的緩解措施已落地。對個人 / 內部測試直接用沒問題。

6.2 紅黃綠燈逐項

🔴 高風險（None confirmed）

目前掃描範圍內沒發現未 escape 的 eval() / os.system() / pickle.loads() 等典型 RCE 入口。shell=True / child_process 出現位置全在 test 或 audit script，不在 hot path。

🟡 中風險（3 項）

Workspace 內所有人可讀彼此 trace：README §Data collection notice 直白寫「All users in your Deeplake workspace can read this data」。是 by-design（shared substrate = shared capability），但對「同公司不同 BU」或「contractor / 正職混組」場景要留意 workspace boundary 設定。
Admin notification endpoint 未硬化（issue #131 OPEN）：官方自己標的 follow-up — audit log / sanitation / fanout gating / signing 都還沒上。若要 self-host 跑 admin 通知，先看 #131 進度。

🟢 低風險（多項 — 寫得好的部分）

Credentials 檔權限正確：~/.deeplake/creds.json 寫 0600、config dir 0700（src/commands/auth-creds.ts:62-63、src/notifications/state.ts:52-54），符合 OWASP 建議
Device flow login：不在 env / 不在 code 出現 raw token（README §Code-level controls 強調）
SQL 注入防護：sqlStr() / sqlLike() / sqlIdent() 三層 escape helper，所有 SQL 值都過這層
VFS 命令白名單：~70 個 allowlist builtin（src/hooks/memory-path-utils.ts:9），未識別命令直接拒絕
TLS + AES-256：傳輸與 at-rest 都加密；BYOC 模式下 credentials 在 Deep Lake vault，Hivemind 看不到 raw key
預設 API endpoint hardcoded：https://api.deeplake.ai（src/cli/auth.ts:6 / src/config.ts:56）— 可被 HIVEMIND_API_URL 覆蓋（self-host 用），但預設指向官方，不易被 typo-attack

6.3 部署前 checklist

multi-tenant 邊界：確認 workspace 設定隔離 contractor / 不同 BU
BYOC：enterprise 部署優先選 GCS / Azure / S3 而非 Hivemind Cloud
Issue #131 追蹤：若會用 admin notification，等該 PR merge
跑 verify-install.sh：確認 creds 權限、hook 正確
review skillify 生出的 SKILL.md：自動產的內容可能洩漏內部術語 / repo path — 用 hivemind skillify scope me 先 dry-run

7. FAQ

Q1: 沒裝 embeddings daemon 還能用嗎？ A: 可以，silently fall back 到 BM25 lexical only。retrieval 精度會差一點但功能完整。

Q2: 我不想讓某一段 session 被 capture？ A: HIVEMIND_CAPTURE=false claude 單次關閉，或 shell rc 設成預設關。

Q3: Skillify 的 SKILL.md 怎麼決定要不要生？ A: 背景 worker 每 N turn（預設 HIVEMIND_SKILLIFY_EVERY_N_TURNS=20）抓最近 session 問 Haiku「這段有沒有可重複的 pattern」，yes 才生。可調高 N 減少 API call。

Q4: 跟 Claude Code 內建的 memory 衝突嗎？ A: 不衝突。Claude Code 的 CLAUDE.md / memory/ 是 prompt-level context；Hivemind 是 trace-level history + skill。兩者互補。

Q5: BYOC 模式下，Hivemind 還會看到我的資料嗎？ A: 不會看到 raw bytes。orchestration metadata（哪個 workspace、哪個 session ID）會經過，但 trace 內容直接寫進你的 GCS/S3/Azure，不過 Hivemind 的 server。

Q6: 跟本 AI-Knowledge Template 的 continuous-learning-v2 / instinct 系統能整合嗎？ A: 概念同構但實作正交：hivemind 走 hook + Deeplake，本 template 走 Claude Code skill + Markdown。可以共存（instinct 紀錄本機決策、hivemind 紀錄 raw trace），不要互相 capture（會雙倍 noise）。

8. 進階技巧（Tips）

省 API 成本：把 HIVEMIND_SKILLIFY_EVERY_N_TURNS 從 20 調到 50，skillify 變便宜但 SKILL.md 更新慢
CI / headless：用 HIVEMIND_TOKEN 注入；非互動 shell 沒 token 也能裝 hook、跳過 login
debug：HIVEMIND_DEBUG=1 開 verbose hook log，遇到 hook 沒觸發時必開
plugin-cache pinning：v0.7.x 修了 GC race condition（#189），但若仍想 pin specific bundle，可手動把版本目錄 chmod 0500 + 設 .in_use/<pid> claim
skillify 跨團隊：hivemind skillify scope team 改成 mine 整個 team；hivemind skillify pull 拉同事的；unpull 清掉
rules 跨 agent：hivemind rules add "no DROP TABLE on prod creds" — SessionStart 時注入到所有 connected agent

9. 整合進其他工作流（Integration with this AI-Knowledge Template）

9.1 與 graphify（Layer 4）

graphify 對本地 codebase 建 AST graph，hivemind 對 session trace 建 traversal graph — 兩者互補。可以同時跑：graphify 給「程式碼怎麼長」，hivemind 給「agent 實際碰過哪些檔」。

9.2 與 continuous-learning-v2 / instinct

設計同構：都是「觀察 → 過濾 → codify」。差別在

粒度：instinct 是 atomic decision（單 turn），hivemind 是 multi-turn pattern
儲存：instinct 寫本地 markdown，hivemind 寫 Deeplake tensor
propagate：instinct 個人，hivemind 團隊

可參考 hivemind 的 worker 觸發策略（every N turn / 50 msg / 2hr 三條件 OR）改善本 template 的 instinct 觸發。

9.3 與 paper-tutorial / research-pipeline-v2

10. 重點摘要 Checklist

Hivemind = cross-agent trace capture + skill codification + propagation
6 種 agent 支援：Claude Code / Codex / OpenClaw / Cursor / Hermes / pi
LoCoMo benchmark 數字：25% cheaper / 1.7× fewer tokens / 31% fewer turns
安裝：npm install -g @deeplake/hivemind && hivemind install
預設啟用 capture，機密場景必先 HIVEMIND_CAPTURE=false
資安整體 🟡 中風險（可控）：credentials 權限正確、SQL 防注入、VFS 白名單；但 trace 預設全量上傳、workspace 內互相可讀
BYOC 支援 GCS / Azure / S3 / on-prem
與本 template 的 graphify / instinct / research-pipeline-v2 有清楚分工，可共存但需設機密邊界

11. 進一步閱讀

官方 README：https://github.com/activeloopai/hivemind/blob/main/README.md
Architecture 細節：docs/ARCHITECTURE.md
Skillify 完整流程：docs/SKILLIFY.md
Summaries 流程：docs/SUMMARIES.md
Embeddings 細節：docs/EMBEDDINGS.md
LoCoMo benchmark paper：https://arxiv.org/abs/2402.17753
Activeloop Deep Lake：https://deeplake.ai
本專案 gh-save metadata：inbox/2026-05-29-github-activeloopai-hivemind.md

Hivemind 深度教學 — Cross-Agent 共享記憶與 Skill 自動沉澱引擎

Contents