本地优先的 AI 知识库与图谱构建工具SwarmVault

技能介绍

SwarmVault 是一个开源的本地优先（local-first）知识库与知识图谱构建工具，由 swarmclawai 开发，基于 Andrej Karpathy 的 LLM Wiki 模式，把文档、代码、转录文本、笔记和 URL 转换为持久的 Markdown Wiki，以及一个可检查、可查询、可交给 Agent 的本地图谱。它同时定位为「面向 AI Agent 的 RAG 知识库」。

用作者的话说：如果你喜欢 Karpathy 的 LLM Wiki gist，SwarmVault 就是它的生产级版本。它遵循 Vannevar Bush 1945 年 Memex 的传统——把「源与源之间的连接」视为与源本身同等重要；Bush 当年无法解决的是谁来维护，这里由 LLM 负责。

一条命令即可开始，首次运行不需要任何 API 密钥——内置的 heuristic 提供程序在本地离线运行。它把个人知识管理、研究深挖、书籍伴侣、代码文档、商业智能等场景统一到磁盘上的一个 Vault 中。

适用场景

• 研究深度分析 — 从论文和文章中构建不断演进的论点，并跨来源进行矛盾检测。
• 个人知识库 — 将日记、健康笔记、播客编译为带有仪表盘的个人 Memex。
• 书籍阅读 — 按章节创建粉丝维基，包含角色和主题页面，随着阅读不断累积。
• 代码仓库分析 — 摄取仓库，生成模块页面、图谱报告和基准测试。
• 研究感知式捕获 — 从 arXiv、DOI 和 URL 添加规范化元数据。
• 混合语料处理 — 跨混合输入类型进行编译、审查和保存输出。

核心能力

三层架构

SwarmVault 使用三层架构，遵循 Andrej Karpathy 描述的模式：

1. 原始源（raw/）——精心收集的源文档集合：书籍、文章、论文、转录文本、代码、图像、数据集。这些是不可变的，SwarmVault 从中读取但从不修改。
2. Wiki（wiki/）——LLM 生成和人工编写的 Markdown：源摘要、实体页面、概念页面、交叉引用、仪表盘和输出。Wiki 是持久且不断累积的产物。
3. Schema（swarmvault.schema.md）——定义 Wiki 的结构、遵循的约定以及领域中的重要内容，你和 LLM 会随时间共同演化它。

从 Gist 到生产级

对社区常见担忧的回应

• 「幻觉不会累积吗？」 每条边都被标记为 extracted、inferred 或 ambiguous；矛盾检测会标记冲突声明；compile --approve 将所有更改暂存到可审查的审批包；新概念首先进入 wiki/candidates/；lint --conflicts 按需审计矛盾。
• 「能扩展到 100 页以上吗？」 能。混合搜索把 SQLite 全文搜索与语义嵌入结合，查询无需把每一页都放进上下文；compile --max-tokens 修剪输出以适应有界窗口；图谱导航（graph query、graph path、graph explain、graph callers）让你遍历而非搜索。
• 「只适合个人使用吗？」 基于 Git 的工作流（--commit）、监视模式与 Git 钩子、定时自动化以及 MCP 服务器使其适用于团队。
• 「需要 API 密钥吗？」 不需要，内置 heuristic 提供程序完全离线；如需更精确的抽取，可搭配免费本地 LLM（通过 Ollama）。

其他能力要点

• 带有溯源的知识图谱 — 每条边都追溯到特定来源与声明；节点带有新鲜度、置信度和社区成员信息。
• 矛盾检测与语义自动标签 — 自动检测跨来源的冲突声明并在图谱报告中呈现，抽取出的领域标签出现在页面前置元数据、图谱节点和搜索中。
• 保存优先的查询 — 答案默认写入 wiki/outputs/，支持 markdown、report、slides、chart 和 image 输出格式。
• Agent 上下文包与任务台账 — swarmvault context build 写出带引用、受 token 限制的交接文档；swarmvault task start|update|finish|resume 把任务目标、决策、图谱证据和结果记录为 git 友好的 JSON 与 Markdown。
• 仓库诊断 — swarmvault doctor [--repair] 检查图谱制品、检索、审查队列、监视状态、迁移、托管源、源/页面计数与任务状态。
• 图谱工具链 — 图谱差异（swarmvault diff）、影响范围（graph blast）、循环检测（graph cycles）、过期检查（graph status / check-update）、统计与校验（graph stats / graph validate --strict）、HTML 树（graph tree）、图谱合并（graph merge）、社区重算（graph cluster）与多种导出（report / callflow / neo4j / obsidian / GraphML / Cypher / SVG）。
• 检索与重排序 — 本地检索把 SQLite FTS 分片与清单存在 state/retrieval/；可合并全文命中与语义页面匹配，tasks.embeddingProvider 指定嵌入后端，retrieval.rerank: true 让 queryProvider 对候选集重排序。
• MCP 服务器 — swarmvault mcp 通过 stdio 把仓库暴露给任何兼容的 Agent 客户端，包含图谱统计、图谱新鲜度、图谱刷新、社区查找、上下文包、任务台账、仓库诊断和检索健康等工具。
• 内置浏览器剪藏器 — graph serve 暴露本地 /api/bookmarklet 页面与 /api/clip 端点，可从工作台或书签小工具捕获当前浏览器 URL、标题、选中文本、Markdown、HTML 摘录和标签。
• 自动化与托管源 — 监视模式、git 钩子、定时计划、收件箱导入让仓库保持最新；swarmvault source add|list|reload|review|guide|session|delete 把重复文件、目录、公共 GitHub 仓库和文档中心变成命名的同步源。

输入类型（30+ 格式）

PDF、Word（.docx/.docm/.dotx/.dotm）、RTF、OpenDocument（.odt/.odp/.ods）、EPUB、CSV/TSV、Excel（.xlsx/.xlsm/.xlsb/.xls/.xltx/.xltm）、PowerPoint（含宏与模板变体）、Jupyter 笔记本、BibTeX、Org-mode、AsciiDoc、字幕（.srt/.vtt）、Slack 导出、邮件（.eml/.mbox）、日历（.ics）、音频（.mp3/.wav/.m4a/.aac/.ogg/.webm）、视频（.mp4/.mov/.m4v/.mkv/.avi）、HTML 与 URL、YouTube 字幕、图片（.png/.jpg/.webp/.heic/.avif 等）、arXiv/DOI/X 研究资料、纯文本文档、配置与数据文件（.json/.toml/.yaml/.xml/.ini/.env 等）、开发者清单（package.json、Cargo.toml、Dockerfile、Makefile 等）、约 40 种编程语言源码（Java/Go/Rust/Python/TypeScript/SQL/Svelte/Vue 等），以及浏览器剪辑与托管源。

隐私与数据流

SwarmVault 默认在本地处理数据：代码文件在您的机器上通过 TypeScript 编译器 API、tree-sitter 或 SQL 解析器解析，源代码内容永远不会发送到外部 API；文档和文本仅发送到您配置的提供商做语义抽取（使用 heuristic 时全部在本地完成）；仅当配置了视觉能力提供商时图像才会发送；图谱构建、社区检测与报告生成全部在本地完成。

效果预览

首次编译后，磁盘上你会得到：

• raw/ — 摄取材料的不可变副本
• wiki/ — 生成的 Markdown 页面、保存的输出、图谱报告、上下文包和任务笔记
• state/graph.json — 机器可读的知识图谱
• state/retrieval/ — 本地搜索索引
• wiki/graph/share-card.md、wiki/graph/share-card.svg 和 wiki/graph/share-kit/ — 可复制和可视化的首次运行摘要

Vault 目录结构：

my-vault/
├── swarmvault.schema.md       用户可编辑的 Vault 指令
├── raw/                       不可变的源文件和本地化资源
├── wiki/                      编译后的 Wiki：源、概念、实体、代码、输出、图谱
├── state/                     graph.json、retrieval/、embeddings、sessions、approvals
├── .obsidian/                 可选的 Obsidian 工作区配置
└── agent/                     生成的面向 Agent 的辅助文件

知识仪表板位于 wiki/dashboards/，提供最近来源、阅读日志、时间线、源会话、源指南、研究地图、矛盾和未解决问题。

每次编译还会写入 wiki/graph/share-card.md、wiki/graph/share-card.svg 和 wiki/graph/share-kit/；swarmvault graph share --post 打印简洁文本，--svg [path] 写入 1200x630 视觉卡片，--bundle [dir] 写入 Markdown、帖子文本、SVG、HTML 预览和 JSON 元数据，便于发布、链接或截图。

工作方式

1. 您提供输入文件（代码、文档、图像、URL 或数据）。
2. SwarmVault 在本地处理它们，或将非代码内容发送到您配置的提供商进行语义分析。
3. 它构建图谱、检测社区并生成报告。
4. 您可以查询、检查、监视更改，或使用 MCP 集成。

quickstart 是 swarmvault scan 的初学者友好别名：在当前目录初始化一个 Vault，摄取本地文件、目录或公共 GitHub 仓库，编译 Wiki 和图谱，写入分享产物，并打开本地图谱查看器。swarmvault next 是只读的，会告诉你是否需要初始化、摄取、编译、查询、审查或刷新。

对于支持钩子的 Agent，安装的钩子会引导「图谱优先读取」，强制执行是可选的。默认以建议模式（context）运行：每个会话的第一次广泛 Grep/Glob/Bash 搜索会收到一次引导提示，指向纯文本图谱命令，且不会拒绝任何操作；传递 --graph-first 可选择强制执行模式，第一次广泛搜索会被拒绝一次并重定向到图谱命令，重复相同搜索随后会被允许。在 Edit/Write 工具之后，钩子会在后台启动 swarmvault graph update --file 刷新，让图谱跟踪你的编辑。

你需要提供

• 输入文件（代码、文档、图像、URL 或数据）。
• （可选）如果您想使用外部 LLM 分析，则需要提供提供商 API 密钥和配置。
• （可选）CLI 选项，如 --hook、--graph-first、--mcp、--scope。
• 运行环境：SwarmVault 需要 Node >=24。全局 CLI 已包含图谱查看器工作流和 MCP 服务器流，最终用户无需单独安装 @swarmvaultai/viewer。

你会获得

• 编译后的知识库，包含图谱和报告。
• 仪表盘、粉丝维基、Memex 风格的个人知识库。
• 代码仓库的模块页面、图谱报告、基准测试。
• 来自研究来源的规范化元数据。
• 混合语料的编译输出。
• 可发布的分享套件（share-card.md / share-card.svg / share-kit/）与多种格式的外部图谱导出（HTML、SVG、GraphML、Cypher、JSON、Obsidian 笔记包或画布、Neo4j 推送）。

使用示例

30 秒尝试：

swarmvault quickstart ./your-repo

没有现成的仓库？

swarmvault demo

首次编译后，最有用的后续命令是：

swarmvault next
swarmvault query "What are the key concepts?"
swarmvault graph serve
swarmvault doctor
swarmvault candidate list

从空文件夹开始的快速路径：

mkdir my-vault
cd my-vault
swarmvault quickstart ../your-repo
swarmvault next

分步执行主循环：

swarmvault init --obsidian --profile personal-research
swarmvault ingest ./src --repo-root .
swarmvault ingest ./meeting.srt --guide
swarmvault add https://arxiv.org/abs/2401.12345
swarmvault compile
swarmvault next
swarmvault query "What is the auth flow?"
swarmvault graph serve

注册定期源：

swarmvault source add ./exports/customer-call.srt --guide
swarmvault source add https://github.com/karpathy/micrograd
swarmvault source add https://example.com/docs/getting-started
swarmvault source list
swarmvault source session file-customer-call-srt-12345678
swarmvault source reload --all

设置编码 Agent 让它了解 Vault：

swarmvault install --agent claude --hook --mcp  # Claude Code + 图谱优先钩子 + MCP 服务器
swarmvault install --agent codex --hook     # Codex + 图谱优先钩子
swarmvault install --agent cursor           # Cursor
swarmvault install --agent copilot --hook   # GitHub Copilot CLI + 钩子
swarmvault install --agent gemini --hook    # Gemini CLI + 钩子
swarmvault install --agent trae             # Trae
swarmvault install --agent claw             # Claw / OpenClaw 技能目标
swarmvault install --agent droid            # Droid / Factory 规则目标
swarmvault install --agent kiro             # Kiro IDE + 始终开启的引导
swarmvault install --agent kilo --hook       # Kilo 项目规则 + 插件
swarmvault install --agent hermes           # Hermes 用户范围技能
swarmvault install --agent antigravity      # Google Antigravity 规则 + /swarmvault 工作流
swarmvault install --agent vscode           # VS Code Copilot Chat 聊天模式
swarmvault install status --agent kilo --hook

可选：通过 Ollama + Gemma 使用本地 LLM（无需 API 密钥）：

{
  "providers": {
    "llm": {
      "type": "ollama",
      "model": "gemma4",
      "baseUrl": "http://localhost:11434/v1"
    }
  },
  "tasks": {
    "compileProvider": "llm",
    "queryProvider": "llm",
    "lintProvider": "llm"
  }
}

语音优先捕获（本地 Whisper，离线转录）：

swarmvault provider setup --local-whisper --apply

该命令会验证二进制文件，将 base.en ggml 模型（约 147 MB）下载到 ~/.swarmvault/models/ 并在配置中注册提供程序。local-whisper 提供程序类型在 1.1.0 版本的 STABILITY.md 中被记录为实验性。

构建有界的 Agent 上下文与记录任务历史：

swarmvault context build "Implement the auth refactor" --target ./src --budget 8000
swarmvault task start "Implement the auth refactor" --target ./src --agent codex
swarmvault chat "How should the next agent use this vault?"