swarmvault MCP — 使用場景, 安裝 & 即時演示

為什麼要用

核心特性

30+ input formats: PDFs, docs, code, audio, video, transcripts, images
Typed knowledge graph with community detection and contradiction spotting
Hybrid search: SQLite FTS + semantic embeddings
Offline-capable via heuristic provider (no API keys required)
Installs across 12 agent platforms via swarmvault install --agent <name>

即時演示

實際使用效果

swarmvault.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "swarmvault": {
      "command": "npx",
      "args": [
        "-y",
        "swarmvault"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "swarmvault": {
      "command": "npx",
      "args": [
        "-y",
        "swarmvault"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "swarmvault": {
      "command": "npx",
      "args": [
        "-y",
        "swarmvault"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "swarmvault": {
      "command": "npx",
      "args": [
        "-y",
        "swarmvault"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "swarmvault",
      "command": "npx",
      "args": [
        "-y",
        "swarmvault"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "swarmvault": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "swarmvault"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add swarmvault -- npx -y swarmvault

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： swarmvault

Compound research across months into a queryable wiki

👤 Researchers, analysts doing deep work over time ⏱ ~60 min intermediate

何時使用： You've been researching a topic for weeks and realize your notes are scattered.

前置條件

swarmvault CLI — npm install -g @swarmvaultai/cli
A vault — swarmvault init --obsidian --profile personal-research

步驟

Dump raw sources

Drop everything into raw/: PDFs, saved articles, meeting transcripts, code snippets.✓ 已複製

→ Immutable raw/ folder populated
Compile the wiki

swarmvault compile — generate wiki/ with typed pages and link frontmatter.✓ 已複製

→ Wiki pages created
Query through MCP

Via the MCP: what's the current consensus in my notes about 'post-quantum TLS timeline'? Include contradictions.✓ 已複製

→ Answer with graph-walked citations and flagged contradictions

結果： A growing, queryable research base that gets smarter with every addition.

注意事項

Noisy inputs produce noisy graph — Curate raw/ — delete junk instead of ingesting everything
Over-relying on the graph for 'truth' — Edges tagged 'inferred' or 'ambiguous' are hypotheses, not facts — respect the tags

搭配使用： documentation-server

Turn meeting transcripts into structured team knowledge

👤 Teams doing a lot of recorded meetings ⏱ ~45 min intermediate

何時使用： You have Fathom/Otter transcripts piling up and want to query across them.

步驟

Drop transcripts in raw/

Copy all my Otter transcripts from last quarter into raw/meetings/.✓ 已複製

→ Files in place
Compile

swarmvault compile. Confirm entities (people, projects) were extracted.✓ 已複製

→ Entity count report
Query

What did we decide about the pricing overhaul across all Q1 meetings? Cite each source.✓ 已複製

→ Consolidated answer with source transcripts cited

結果： Institutional memory that survives people leaving.

Build a book-club wiki with cross-book reasoning

👤 Serious readers ⏱ ~90 min intermediate

何時使用： You want the AI to reason across books, not just one at a time.

步驟

Ingest

Drop PDFs + notes for 5 books into raw/; compile.✓ 已複製

→ Wiki with one page per book + concept pages
Cross-reason

Which concepts show up in 3+ books? Identify contradictions between authors.✓ 已複製

→ Concept map with contradictions flagged

結果： A reading practice that compounds.

組合

與其他 MCP 搭配，撬動十倍槓桿

swarmvault + documentation-server

swarmvault for structured wiki; documentation-server for quick-ingest search

Ingest new papers into both — compare retrieval quality and structure.✓ 已複製

swarmvault + logseq

Export vault pages into a Logseq graph

Export wiki/ Markdown into my Logseq pages/ dir with frontmatter preserved.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫	成本
vault_search	query: str, top_k?: int	Main retrieval	free (local)
vault_get_page	slug: str	Full page read	free
vault_graph_neighbors	slug, depth?	Explore concept graph	free
vault_contradictions	topic?: str	Quality check	free
vault_compile	(none)	After adding new raw/	CPU + optional embedding calls
vault_graph_report	scope?: str	Overview of a topic	free

成本與限制

運行它的成本

API 配額: Zero with the heuristic provider; otherwise your LLM provider's limits
每次呼叫 Token 數: Compile can stream large source content through embeddings; search queries 500-2000 tokens typical
費用: Free; optional LLM providers cost normal LLM fees
提示: Use heuristic provider for first-pass compile; upgrade to LLM-backed compile only when quality matters.

安全

權限、密鑰、影響範圍

憑證儲存： Optional LLM provider keys in env/config

資料出站： None by default (heuristic); opt-in provider calls only

Vault content may include sensitive source material — .gitignore the vault dir by default.
Contradiction detection is heuristic; treat flags as 'investigate', not 'definitely wrong'.

故障排查

常見錯誤與修復

Compile fails on a specific PDF

Some PDFs are scanned/image-only. Pre-OCR with ocrmypdf before dropping in raw/.

驗證： pdftotext file.pdf - | head

MCP connection fails after agent install

Re-run swarmvault install --agent <name> and restart the agent; config paths vary per platform.

驗證： Client MCP list shows swarmvault

Hybrid search returns nothing

Vault not compiled yet, or embeddings not built for offline mode. Run swarmvault compile.

驗證： swarmvault status

替代方案

swarmvault 對比其他方案

替代方案	何時用它替代	權衡
documentation-server	You want quick drag-and-drop RAG without wiki compilation	No structured graph or contradiction detection
Obsidian + Smart Connections	You live in Obsidian and want in-editor AI	Less structured compile pipeline
NotebookLM	You're OK with Google-hosted, easy UI	Data leaves your machine; no graph export

swarmvault