SwarmVault

核心定位#

SwarmVault 解决 AI Agent 在长周期、多源研究任务中缺乏持久化、可追溯知识基底的问题。灵感来源于 Andrej Karpathy 的 LLM Wiki gist 与 Vannevar Bush 的 Memex（1945）。

三层架构（Karpathy 模式）#

• raw/ — 不可变原始资料，支持 30+ 格式（代码、PDF、音视频、SRT、URL、数据集、邮件导出、日历等）
• wiki/ — LLM 生成 + 人工编写的持久化 Markdown Wiki
• swarmvault.schema.md — 可协同演化的 vault 结构与领域约定

知识图谱#

带类型节点（sources / concepts / entities / code modules）与溯源标记边（extracted / inferred / ambiguous），内置交互式 graph viewer（大型图谱自动切换 overview 模式），支持 Neo4j 导出。图谱以 JSON 格式本地存储于 state/graph.json。

混合搜索#

SQLite 全文检索（FTS）+ 语义向量嵌入 + 可选 rerank。无 embedding provider 时优雅降级为 SQLite FTS + heuristic。

审批与矛盾检测#

• 跨源冲突自动标记，lint --conflicts 按需审计
• compile --approve 将变更暂存为可审查的 approval bundle，新概念先进入 wiki/candidates/

Agent 集成#

• MCP Server：兼容 Claude Code、Codex、OpenCode、OpenClaw
• Context Packs：token 边界内带引用的 agent 交接文档（context build）
• Task Ledger：task start/update/finish/resume 持久化本地任务历史

代码感知#

基于 tree-sitter AST 解析，scan ./your-repo 一键扫描代码库生成知识图谱和可搜索 wiki。

协作与分享#

• Git-backed 工作流（Watch 模式 + Lefthook Git Hooks）
• Share Kit：可发布的 share-card.md、share-card.svg、自包含 HTML 预览及 share-kit/ 包
• 可选 Obsidian 集成（--obsidian 初始化，图谱可导出至 Obsidian vault）

运行模式#

• 完全离线：内置 heuristic provider，零 API key
• 本地 LLM 加速：推荐 Ollama + Gemma 4 + nomic-embed-text
• 云端 API：支持 OpenAI、Anthropic、Gemini、OpenRouter、Groq、Together、xAI、Cerebras 及任意 OpenAI-compatible 端点
• 桌面应用：macOS / Windows / Linux，内置运行时，无需单独安装 Node.js

运维工具#

Vault Doctor 提供图健康检查、检索状态、审查队列、迁移、managed sources、任务状态，含优先级排序和自动修复（doctor --repair）。

架构概览#

pnpm monorepo，包含 @swarmvaultai/cli（命令行入口）、@swarmvaultai/engine（核心编译引擎）、@swarmvaultai/viewer（图谱可视化前端）。构建工具链为 pnpm + TypeScript + Biome，测试采用 Node.js built-in test runner + Playwright（E2E）。数据存储层为本地文件系统（Markdown + JSON）+ SQLite。

编译流程#

raw/ 原始资料 → LLM/heuristic 提取 → wiki/candidates/ 待审 → 审批队列 → wiki/ 持久化产物 + state/graph.json 图谱更新 + SQLite 索引更新

快速开始#

npm install -g @swarmvaultai/cli  # 要求 Node >= 24
swarmvault demo                    # 内置示例 vault，无需 API key
swarmvault scan ./your-repo        # 扫描代码库

待确认事项#

• 官方网站 https://www.swarmvault.ai 在 manifest.json 中被引用为 authorUrl，但未实际抓取验证其内容
• Obsidian 插件市场发布状态待确认（manifest.json 存在，minAppVersion 1.5.0）
• NPM 包 @swarmvaultai/cli 发布信息未实际验证
• 桌面应用具体下载地址未验证
• MCP Server 暴露的具体 tools/resources 未详细说明