/ 目录 / 演练场 / swarmvault
● 社区 swarmclawai ⚡ 即开即用

swarmvault

作者 swarmclawai · swarmclawai/swarmvault

将原始研究资料(PDF、文字记录、代码、音频)转化为本地 markdown wiki 和知识图谱,你的 AI 可以永久查询使用。

SwarmVault 把混合输入(30+ 种格式)编译成 Obsidian 兼容的 wiki,配有类型化知识图谱和混合搜索。为 Claude Code、Codex、OpenCode 等提供 MCP server。每条边都用 extracted/inferred/ambiguous 标记以追踪来源。本地优先设计,内置离线启发式提供商(无需 API 密钥)。

为什么要用

核心特性

实时演示

实际使用效果

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

将数月的研究积累编译成可查询的 wiki

👤 长期从事深度工作的研究者和分析师 ⏱ ~60 min intermediate

何时使用: 你研究某个话题已经好几周,却发现笔记散落各处。

前置条件
  • swarmvault CLI — npm install -g @swarmvaultai/cli
  • 一个 vault — swarmvault init --obsidian --profile personal-research
步骤
  1. 导入原始资料
    把所有东西放到 raw/ 目录:PDF、保存的文章、会议记录、代码片段。✓ 已复制
    → raw/ 文件夹已填充
  2. 编译 wiki
    swarmvault compile — 生成包含类型化页面和链接前置信息的 wiki/。✓ 已复制
    → Wiki 页面已创建
  3. 通过 MCP 查询
    通过 MCP:我的笔记中关于「后量子 TLS 时间表」的当前共识是什么?包括矛盾的地方。✓ 已复制
    → 带有图遍历引用和标记矛盾的答案

结果: 一个不断增长、可查询的研究基础,每次添加都变得更聪明。

注意事项
  • 输入质量差会导致图谱质量差 — 整理 raw/ 目录,删除无用数据而不是全量导入
  • 过度依赖图谱作为「真理」来源 — 标记为 'inferred' 或 'ambiguous' 的边是假设,不是事实——要尊重这些标签
搭配使用: documentation-server

将会议记录转化为结构化的团队知识

👤 进行大量会议录音的团队 ⏱ ~45 min intermediate

何时使用: 你有很多 Fathom/Otter 的会议记录堆积,想要跨文件查询。

步骤
  1. 将记录放到 raw/ 目录
    把上个季度所有的 Otter 记录复制到 raw/meetings/。✓ 已复制
    → 文件已就位
  2. 编译
    swarmvault compile。确认实体(人员、项目)已被提取。✓ 已复制
    → 实体计数报告
  3. 查询
    在所有第一季度会议中,我们关于定价调整决定了什么?引用每个来源。✓ 已复制
    → 包含来源记录引用的综合答案

结果: 即使人员离职也能保留的机构记忆。

构建支持跨书籍推理的读书会 wiki

👤 认真的读者 ⏱ ~90 min intermediate

何时使用: 你希望 AI 跨书籍推理,而不仅仅是一次一本。

步骤
  1. 导入
    把 5 本书的 PDF 和笔记放到 raw/ 目录,然后编译。✓ 已复制
    → 包含每本书一页 + 概念页的 wiki
  2. 跨书推理
    哪些概念出现在 3+ 本书中?识别作者之间的矛盾。✓ 已复制
    → 标记了矛盾的概念图

结果: 一个不断积累的阅读实践。

组合

与其他 MCP 搭配,撬动十倍杠杆

SwarmVault 用于结构化 wiki,documentation-server 用于快速导入搜索

把新论文导入两者——比较检索质量和结构。✓ 已复制
swarmvault + logseq

将 vault 页面导出到 Logseq 图

将 wiki/ Markdown 导出到我的 Logseq pages/ 目录,保留前置信息。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
vault_search query: str, top_k?: int 主要检索 free (local)
vault_get_page slug: str 完整页面读取 free
vault_graph_neighbors slug, depth? 探索概念图 free
vault_contradictions topic?: str 质量检查 free
vault_compile (none) 添加新原始文件后 CPU + optional embedding calls
vault_graph_report scope?: str 话题概览 free

成本与限制

运行它的成本

API 配额
使用启发式提供商时为零,否则受你的 LLM 提供商的限制
每次调用 Token 数
编译可以通过嵌入流传输大型源内容,搜索查询通常 500-2000 token
费用
免费;可选的 LLM 提供商收费标准为正常的 LLM 费用
提示
第一轮编译使用启发式提供商;只有在质量重要时才升级到 LLM 支持的编译。

安全

权限、密钥、影响范围

凭据存储: 可选的 LLM 提供商密钥存储在 env/config 中
数据出站: 默认无数据外流(启发式);仅选择加入的提供商调用

故障排查

常见错误与修复

编译特定 PDF 时失败

某些 PDF 是扫描/仅图像格式。在放到 raw/ 前用 ocrmypdf 预处理。

验证: pdftotext file.pdf - | head
Agent 安装后 MCP 连接失败

重新运行 swarmvault install --agent <name> 并重启 agent;配置路径因平台而异。

验证: Client MCP list shows swarmvault
混合搜索返回空结果

Vault 还未编译,或离线模式下未构建嵌入。运行 swarmvault compile

验证: swarmvault status

替代方案

swarmvault 对比其他方案

替代方案何时用它替代权衡
documentation-server你想要快速拖放 RAG,无需 wiki 编译没有结构化图或矛盾检测
Obsidian + Smart Connections你在 Obsidian 中工作,想要编辑器内 AI编译管道结构化程度较低
NotebookLM你可以接受 Google 托管的、易用的界面数据离开你的机器;无图导出

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills