SwarmVault
本地优先的 LLM Wiki：把文档、代码、转录与笔记编译成可检索的知识图谱与 RAG 知识库，为 Claude Code、Codex 等 Agent 提供持久记忆，无需 API 密钥即可离线运行。
权限控制良好：默认 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 与维护者治理文件，长期维护承诺缺乏书面依据。
这个 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. 知识图谱、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 有哪些优点和局限？
- 默认完全离线：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？
需要 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 与同类方案有什么区别？
README 明确将自己定位为 Karpathy LLM Wiki gist 的生产级实现，并直接与 Obsidian 对比：相比 Obsidian 手动维护笔记，SwarmVault 自动编译 wiki、构建类型化知识图谱、检测矛盾，并通过 graph export --obsidian 输出保留 Dataview 仪表盘和 Breadcrumbs/Juggl 类型化链接的 Obsidian 兼容包，可作为其替代或补充。
常见问题
必须付费或配置 API 密钥吗？
我的代码和数据会被上传吗？
它和 Obsidian 互斥吗？
--obsidian 生成工作区配置，graph export --obsidian 可导出带类型化链接和 Dataview 仪表盘的完整 Obsidian 包，wiki 本身就是普通 markdown。新概念会被 LLM 直接写进 wiki 吗？
compile --approve 将变更分阶段进入可审查的审批包，矛盾由 lint --conflicts 审计，任何变更都不静默发生。