SwarmVault
本地优先的 LLM Wiki：把文档、代码、转录与笔记编译成可检索的知识图谱与 RAG 知识库，为 Claude Code、Codex 等 Agent 提供持久记忆，无需 API 密钥即可离线运行。
- Star 数
- ★ 730
- 最近更新
- 3 个月前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 67/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 个人研究者想用期刊、播客转录和论文构建带仪表盘的私人 Memex（worked/personal-knowledge-base 示例即为此场景）
- 不适合
- 仍在使用 Node.js 24 以下运行时的环境
- 希望界面与文档以中文为主的用户
- 源码审查
- 67/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
SwarmVault 是一个开源的本地优先知识工具，将任意输入（PDF、代码仓库、字幕转录、网页 URL、邮件、音频等 30 多种格式）转化为持久化的 markdown wiki 加上机器可读的知识图谱。它实现了 Andrej Karpathy 提出的三层架构：不可变的 raw/ 原始资料层、LLM 与人工共写的 wiki/ 层、以及可随时间共同演化的 swarmvault.schema.md 模式层。通过 @swarmvaultai/cli 全局命令行运行，核心命令包括 quickstart、ingest、compile、query、graph serve 和 doctor，产物全部落盘在 raw/、wiki/ 和 state/ 目录中。内置 heuristic 提供者完全离线，也可接入 Ollama 本地模型或 OpenAI、Anthropic、Gemini 等云端模型。它同时是 MCP 服务器，并为 Claude Code、Codex、Cursor 等 40 多个编码 Agent 提供规则安装与 graph-first 钩子，可作为 Agent 的持久记忆存储。
SwarmVault 读取本地文件、目录、公共 GitHub 仓库、URL、arXiv/DOI 论文、YouTube 转录和音频视频，经本地解析器（tree-sitter、TypeScript 编译器 API、SQL 解析器等）与可选 LLM 提供者处理后，编译生成 wiki markdown 页面、state/graph.json 知识图谱、SQLite FTS + 语义嵌入的混合检索索引以及图报告与分享卡片。每条图谱边都标注 extracted/inferred/ambiguous，支持矛盾检测、审批队列（compile --approve）与候选页缓冲（wiki/candidates/）。swarmvault context build 为编码 Agent 产出带引用、按 token 预算裁剪的上下文包；swarmvault task start 记录 Agent 任务台账；swarmvault mcp 通过 stdio 暴露 graph stats、context-pack、task-ledger 等 MCP 工具；swarmvault install --agent claude --hook --mcp 注册会话钩子和 MCP 服务器；swarmvault graph export --neo4j 还可导出 Cypher 并推送到 Neo4j。
- 个人研究者想用期刊、播客转录和论文构建带仪表盘的私人 Memex（worked/personal-knowledge-base 示例即为此场景）
- Claude Code / Codex 用户希望 Agent 在回答代码问题前先查本地知识图谱，减少重复 grep 和 token 消耗
- 软件开发团队想为代码仓库生成模块页面、调用关系图和影响面分析（graph blast、graph callers）
- 写书或深度阅读者想要逐章生长的粉丝 Wiki，自动建立角色与主题页面的交叉引用
- 需要把会议录音、客户通话字幕离线转写并纳入知识库的顾问或分析师（whisper.cpp 本地 Whisper）
- Obsidian 用户想迁移到带自动编译和矛盾检测的图谱工作流，并保留 Obsidian 导出兼容性
如何安装或部署这个 Agent？
需要 Node.js >= 24。全局安装 CLI：npm install -g @swarmvaultai/cli，用 swarmvault --version 验证。也可从 swarmvault.ai/download 下载无需 Node.js 的桌面应用（macOS/Windows/Linux）。首个 vault 初始化：mkdir my-vault && cd my-vault && swarmvault quickstart ../your-repo。无需任何 API 密钥——内置 heuristic 提供者离线运行。可选增强：安装 Ollama 并 ollama pull gemma4 获得更精准的本地概念抽取，或 swarmvault provider setup --local-whisper --apply 启用本地音频转写（需 whisper.cpp）。
如何使用这个 Agent？
核心循环：swarmvault next（只读提示下一步）、swarmvault ingest ./src --repo-root . 摄取源、swarmvault compile 编译 wiki 与图谱、swarmvault query "What is the auth flow?"（回答默认写入 wiki/outputs/）、swarmvault graph serve 打开本地图谱查看器。托管持续源：swarmvault source add https://github.com/owner/repo 后用 source reload --all 刷新。Agent 集成：在项目根目录运行 swarmvault init && swarmvault ingest .，然后 swarmvault install --agent claude --hook --mcp --graph-first，再用 swarmvault hook install 挂 git 钩子；为 Agent 构建上下文包：swarmvault context build "Implement the auth refactor" --target ./src --budget 8000。健康检查：swarmvault doctor --repair。
这个 Agent 有哪些优点和局限？
- 默认完全离线：heuristic 提供者和本地解析器不需要 API 密钥或网络，代码内容从不发送到外部 API
- 每个图谱边都有 extracted/inferred/ambiguous 标签和矛盾检测，LLM 产物可审计而非静默污染
- MCP 服务器加 40+ 编码 Agent 的规则/钩子安装，可直接充当 Claude Code、Codex 等工具的持久记忆层
- 混合检索（SQLite FTS + 语义嵌入）和
--max-tokens预算裁剪，明确针对超过 100 页规模的可扩展性设计 - 审批队列、候选页缓冲和
swarmvault diff让编译变更可审查，图谱变更可对比
- CLI 依赖 Node.js >= 24，较新版本要求可能迫使部分环境升级运行时
- heuristic 模式的抽取质量有限，要获得精准的概念/实体/论断抽取需自行配置 Ollama 或云端 LLM 提供者
- local-whisper 音频转写在 1.1.0 中被官方标注为实验性（见 STABILITY.md），API 可能变动
- 功能面非常庞大（graph 子命令、source 会话、profiles、任务台账等），学习曲线明显，新用户需依赖 quickstart 和 next 引导
- 文档网站以英文为准，中/日文翻译可能与英文版存在措辞漂移
这个 Agent 与同类方案有什么区别？
README 明确将自己定位为 Karpathy LLM Wiki gist 的生产级实现，并直接与 Obsidian 对比：相比 Obsidian 手动维护笔记，SwarmVault 自动编译 wiki、构建类型化知识图谱、检测矛盾，并通过 graph export --obsidian 输出保留 Dataview 仪表盘和 Breadcrumbs/Juggl 类型化链接的 Obsidian 兼容包，可作为其替代或补充。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| SwarmVault 当前 | 67 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 730 | 3 个月前 | TypeScript | Codex · Claude Code |
| PipesHub 企业 AI 上下文平台 | 66 · 存在缺口 | 自托管服务免费 + 模型费 | ★ 3.8k | 今天 | Python | — |
| IWE 知识图谱与智能体记忆 | 73 · 存在缺口 | 命令行工具免费 | ★ 1.8k | 今天 | Rust | Codex · Claude Code · Claude.ai |
| Athena | 68 · 存在缺口 | IDE 插件免费 + 模型费 | ★ 619 | 今天 | Python | Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
权限控制良好：默认 advisory hook、agent rule files 默认不写入、API key 仅经 apiKeyEnv 引用、不动 raw/ 原始源。扣分：hook 会在 Edit/Write 后触发后台 graph update，install 会改写 .gitignore/tsconfig（有条件与豁免，但仍属宿主文件改写）；依赖清单未在可见文件中给出，无法静态核实供应链；回滚仅依赖 git --commit 与 doctor --repair，无独立回滚保证；敏感数据处理声称对 ingest 与语音文本做 secret 掩码，但仅是 README 断言，未见实现代码。
存在真实测试（notices、chat/export、chunking）且覆盖面具体；CI 用 frozen-lockfile、perf budget、打包 smoke，依赖可用性安排充分。扣分：测试仅覆盖外围行为，未覆盖核心图编译路径；失败信息主要靠 README 描述（stderr 进度、doctor），静态证据中等。
受众与场景描述非常充分（PKM、研究、代码文档、agent memory），提供 heuristic 离线默认与多 provider 渐进升级，Node>=24 与桌面版并陈。扣分：能力边界多处依赖外部二进制（whisper.cpp、ffmpeg、yt-dlp）且标注 experimental 的部分只在 STABILITY.md 提及、本次未见；触发精度（graph-first hook 拦截规则）描述细致但无法静态验证其实现。
信息架构出色（raw/wiki/schema/state 分层、目录树图示、多语言 README、安装/更新命令、FAQ 式'为什么'章节、MIT 与 LICENSE 文件齐全）。扣分：未见 CHANGELOG 与版本历史文件；维护责任与更新路径仅隐含在 npm 发布流程中，无 GOVERNANCE/CONTRIBUTING 证据；已知限制只零散标注（如 local-whisper experimental、R parser 诊断）。
产出可用性明确：wiki/outputs 保存式查询、context packs、task ledger、share kit 均为可留存工件；离线 heuristic provider 降低成本门槛。扣分：所有产出与省 token 收益均为文档声称，未见实测数据；CLI 命令面非常庞大（数十个命令），学习成本与维护面相应偏高，成本收益对普通用户不算显然。
图边带 extracted/inferred/ambiguous 标签、citation 与 chunk 级溯源在测试中得到部分印证（citation: source:long#chunk-1）；README 与 package. 的版本/命令相互一致。扣分：大量性能与功能对比表（vs Karpathy gist）为自评断言，未附可核查证据；fact 与推断的分离依赖 LLM 输出质量，静态无法确认强制力。
- 本次为静态审查，未执行任何命令；性能与省 token 声明均未经实测验证。
- install --agent 会写入项目配置并改写 .gitignore/tsconfig，请在纳入版本控制前审查 diff。
- 依赖清单未在提供文件中，安装前请自行审计 @swarmvaultai/cli 的 npm 依赖树。
- 语音转录模型（约147MB）会下载到 ~/.swarmvault/models/，请确认网络来源可信。
- 依赖外部二进制（whisper.cpp、ffmpeg、yt-dlp）的功能标记为 experimental，生产使用前请验证。
- 无 CHANGELOG 与维护者治理文件，长期维护承诺缺乏书面依据。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v3.20.0 SwarmVault 3.20.0
发布说明摘录
- Added declaration line ranges to code symbols: the TypeScript/JavaScript analyzer records startLine/endLine for functions, classes, and variables, the ranges travel through CodeSymbol onto graph symbol nodes, and graph callers scans only each caller's own declaration range so call sites are attributed to the correct caller even when several callers share a file. Symbols without ranges (other languages, older graphs) keep the previous per-file behavior. …在 GitHub 查看 ↗ -
v3.19.0 SwarmVault 3.19.0
发布说明摘录
- Added swarmvault graph callers <symbol> (CLI) and graph_callers (MCP): lists every caller of a symbol from graph call edges with exact file:line call-site evidence, scanning only the files the graph identifies as callers. Live token A/B testing showed caller/impact questions were the one category where agents still fell back to repo-wide grep; this closes that gap, and hook guidance now points who-calls/impact questions at it. …在 GitHub 查看 ↗ -
v3.18.0 SwarmVault 3.18.0
发布说明摘录
- Made graph-first search enforcement opt-in: installed agent hooks now default to advisory mode (context), and swarmvault install --agent <agent> --hook --graph-first [deny|context|off] persists the chosen mode as hooks.graphFirst in swarmvault.config.json (SWARMVAULT_GRAPH_FIRST still overrides per session). - Stopped the graph-first hooks from flagging search tools that filter piped output (e.g. some-command | grep …); only a search tool leading a pipeline counts as a broad file search. …在 GitHub 查看 ↗
常见问题
必须付费或配置 API 密钥吗？
我的代码和数据会被上传吗？
它和 Obsidian 互斥吗？
--obsidian 生成工作区配置，graph export --obsidian 可导出带类型化链接和 Dataview 仪表盘的完整 Obsidian 包，wiki 本身就是普通 markdown。新概念会被 LLM 直接写进 wiki 吗？
compile --approve 将变更分阶段进入可审查的审批包，矛盾由 lint --conflicts 审计，任何变更都不静默发生。