SwarmVault：给 AI 装上持久记忆，让知识真正属于你

一场关于 AI 记忆的实验

想象一下：你用 Claude Code 花了三小时搞定了一个复杂的身份认证模块，梳理清楚了整个 OAuth2 的流程、踩过的坑、以及最终的解决方案。一周后，你接手另一个项目，需要类似的 JWT Refresh Token 处理逻辑。你打开 Claude Code，发现它一脸茫然——上一个项目的上下文早已消散，那个帮你解决了头疼问题的小帮手，现在像个失忆症患者。

这不是 Claude Code 的 bug，这是所有 AI 编程工具的本质局限：上下文窗口是临时的，一旦会话结束，所有积累都归零。

SwarmVault 想要解决的，就是这个问题。它给 AI Agent 装上一个可以持久化的"外接大脑"，让 AI 在跨会话、跨项目中积累知识——就像人类会反复查阅笔记、参考过往经验一样，AI 也应该拥有自己的"个人知识库"。

这个想法的源头，是 Andrej Karpathy 在 2024 年分享的一个实验性方案：用三层结构（Raw Sources → Wiki → Schema）让 LLM 管理个人知识。SwarmVault 则是这个思路的生产级实现，从一条命令即可上手的 quickstart，到完整的知识图谱、RAG 检索、Agent Memory 和 MCP 集成，全部覆盖。

图1：SwarmVault 交互式图谱工作空间，节点代表实体，边代表关系，可视化呈现文档间的知识关联。

---

二、项目起源与背景

SwarmVault 由 swarmclawai 团队开发和维护，2026 年 4 月 6 日发布首个 commit，定位为面向 AI Agent 的本地优先 LLM Wiki。项目名称由 "Swarm"（蜂群，象征知识的汇聚）和 "Vault"（保险库，象征知识的保管）组合而成。

短短两个多月（截至 2026 年 6 月），项目已积累 578 stars 和 72 forks，最新版本 3.20.0，活跃度高，开发节奏紧凑。维护者在 GitHub 上持续更新，issues 极少（仅 1 个 open），说明项目质量稳定。

SwarmVault 的核心理念继承自 Vannevar Bush 在 1945 年提出的 Memex 概念——一个由文档和关联路径组成的个人化知识库。Bush 当年受限于技术，无法实现自动化维护；而 80 年后，LLM 填补了这个空白，使得大规模知识积累和自动关联成为可能。

---

三、核心功能：三层架构 + 全工具链

3.1 三层架构

SwarmVault 采用清晰的三层架构设计，每层职责明确：

第一层：原始来源（Raw Sources）

raw/ 目录存放所有导入资料的不可变副本——书籍、论文、代码、转录稿、图片、数据集。SwarmVault 从不修改这些原始文件，确保知识的原始性和可追溯性。

第二层：Wiki（wiki/）

LLM 对 Raw Sources 进行摘要、提取、归纳，生成 Markdown 格式的 wiki 页面。包括源摘要（source summaries）、实体页（entity pages）、概念页（concept pages）、交叉引用和概念间的关联路径。Wiki 是持续积累的持久化工件，不会随着会话结束而消失。

第三层：Schema（swarmvault.schema.md）

一个用户和 AI 共同维护的 Markdown 文件，定义了知识库的组织方式、遵循的领域约定，以及什么内容最重要。这个文件是整个 vault 的"宪法"，AI 和人类共同演进它。

3.2 完整工具链

SwarmVault 不只是一个"笔记工具"，而是一套完整的知识工程流水线：

命令	功能
swarmvault quickstart	一条命令完成初始化、导入、编译、生成图谱
swarmvault ingest	从文件、目录、GitHub 仓库、URL、PDF 导入资料
swarmvault compile	触发 LLM 对所有来源进行摘要和知识提取
swarmvault query	用自然语言查询知识库，底层是混合搜索（SQLite FTS + embeddings）
swarmvault graph serve	启动本地图谱查看器 Web UI
swarmvault next	告诉你下一步应该做什么（init/ingest/compile/query/review/refresh）
swarmvault doctor	健康检查，发现 vault 中的问题
swarmvault candidate list	列出待审核的新生成概念

支持 30+ 输入格式，涵盖 PDF、Markdown、代码文件、网页 URL、甚至音视频转录稿。处理大型仓库时，compile --max-tokens 会自动裁剪输出以适配有限上下文窗口。

3.3 知识图谱

SwarmVault 使用 Graphology（一个纯 JavaScript 的图数据库）构建本地图谱。不同于简单的关键词搜索，图谱支持：

• 路径查询（graph path）：找到两个实体之间的关联路径
• 调用者分析（graph callers）：某个函数/概念被哪些其他内容引用
• 图谱解释（graph explain）：某个节点在整个图谱中的上下文
• Neo4j 导出：如果你已经有 Neo4j 环境，可以将本地图谱导出为 Cypher 格式

图谱的每条边都带有置信度标签（extracted / inferred / ambiguous），矛盾检测会自动标记冲突声明。

3.4 混合搜索

RAG 知识库的核心是检索质量。SwarmVault 采用混合搜索策略：

• SQLite 全文索引（FTS5）：快速的关键词匹配
• 语义 Embeddings：理解语义相似性
• Rerank 阶段：结合两种结果进行排序优化

这套方案比纯向量检索更稳定，且完全本地运行，不依赖任何外部 API。

---

四、Agent Memory：从临时上下文到持久积累

这是 SwarmVault 最有想象力的功能方向。

4.1 Claude Code / Codex / OpenCode Hook

SwarmVault 为 Claude Code、Codex、OpenCode 和 Copilot 提供了 hook 脚本。安装后，AI 在工作过程中产生的关键信息会自动同步到 SwarmVault vault：

• 遇到的新概念和新术语
• 解决的 bug 和对应的解决方案
• 关键的设计决策和理由
• 对代码库结构的理解

下次启动新的会话时，AI 可以从 vault 中检索相关记忆，将过去的积累无缝接续。这解决了 AI Agent"每个会话都从零开始"的核心痛点。

4.2 MCP Server

SwarmVault 内置了 MCP（Model Context Protocol）Server，使用 @modelcontextprotocol/sdk 实现，通过 stdio 传输协议与 AI 客户端通信。这意味着任何支持 MCP 协议的 AI 工具（Claude Desktop、Cline 等）都可以将 SwarmVault 作为外部知识源接入。

MCP Server 暴露了以下核心工具：

• buildContextPack：将编译产物打包为 context pack，供 AI 直接使用
• listContextPacks：列出已有的 context packs
• readContextPack：读取指定 context pack 内容
• doctorVault：检查 vault 健康状态

4.3 Context Packs

Context Pack 是 SwarmVault 独创的概念——将编译后的 wiki 产物（摘要、实体关系、检索配置）打包成 AI 可以直接消费的上下文单元。类似于"为特定任务预先生成的知识卡片"，AI 在开始工作前加载 context pack，就获得了该领域的背景知识，无需每次都从原始资料重新检索。

4.4 Chat Sessions

swarmvault chat 命令可以在 vault 上启动一个对话会话，所有对话记录持久化保存到 state/chat-sessions/。对话内容同时生成对应的 wiki 输出，沉淀为可查阅的知识。

---

五、技术架构与代码质量

5.1 Monorepo 结构

SwarmVault 采用 pnpm workspace monorepo 架构，4 个核心 packages：

packages/
├── cli/          入口 CLI，封装所有命令（Commander.js）
├── engine/       核心引擎，所有业务逻辑
├── viewer/       Next.js Web UI，图谱可视化
└── obsidian-plugin/  Obsidian 插件，vault 与 Obsidian 互通

Engine 模块（核心） 包含约 50+ 个 TypeScript 源文件，覆盖：

模块	文件数	核心功能
图谱	14+	graph-* 系列：enrichment、export、merge、query、report-html、share 等
检索	4	embeddings、retrieval、search、tokenize
来源	7	ingest、sources、source-classification、source-registry、source-sessions
LLM	6	providers（anthropic/gemini/heuristic/openai-compatible/local-whisper）
Agent	4	agents、auto-commit、context-packs、memory
质量	5	doctor、deep-lint、consolidate、confidence、findings

5.2 Provider 架构

LLM Provider 设计采用适配器模式，每种 provider 继承 ProviderAdapter 基类：

// providers/registry.ts
import { AnthropicProviderAdapter } from "./anthropic.js";
import { GeminiProviderAdapter } from "./gemini.js";
import { HeuristicProviderAdapter } from "./heuristic.js";
import { LocalWhisperProviderAdapter } from "./local-whisper.js";
import { OpenAiCompatibleAdapter } from "./openai-compatible.js";

内置 Provider 包括：

• Heuristic（默认）：完全离线运行的启发式提取，无需 API key。适合快速上手和小规模场景。
• Anthropic（Claude）：通过 Anthropic API 调用 Claude 系列模型，提取质量最高。
• Gemini：Google Gemini 支持。
• OpenAI Compatible：任何兼容 OpenAI API 格式的本地或远程模型（如 Ollama）。
• Local Whisper：本地音频转录。

5.3 关键技术选型

• Graphology：纯 JS 图数据库，不依赖外部服务，数据存储在 state/graph.json
• Tree-sitter：代码感知提取，解析代码 AST 而非仅靠文本匹配
• Zod：全项目使用 Zod 进行运行时类型验证，从配置文件到 API 响应都有 schema 校验
• Biome：Fast linter + formatter，替代 ESLint + Prettier，更快更一致
• gray-matter：解析 Markdown frontmatter，提取 YAML 元数据
• YAML：配置文件和 hook 脚本的序列化格式

5.4 代码质量

项目对代码质量有较高追求：

• Biome CI check：每次 check 命令运行 lint + typecheck + 多个脚本检查（readme parity、release sync、published manifests 等）
• Playwright 集成：端到端测试覆盖 SMC 测试套件
• 多语言 README：英文/简体中文/日文三语文档
• pre-commit hooks：通过 lefthook 配置 git hooks

---

六、部署方式

6.1 三种部署路径

路径一：桌面应用（最简单）

下载 macOS/Windows/Linux 桌面应用，自带 Node.js 运行时，无需安装任何依赖。适合非技术用户。发布在独立的 swarmvault-desktop 仓库。

路径二：npm 全局安装（开发者首选）

npm install -g @swarmvaultai/cli
swarmvault quickstart ./your-repo

要求 Node.js >= 24，5 分钟内完成安装和使用。Graph viewer 内置在 CLI 中，graph serve 直接启动本地 Web UI。

路径三：Docker 容器化部署（MCP Server）

docker build -t swarmvault-mcp .
docker run --rm -i swarmvault-mcp

Dockerfile 使用 Node 24 Alpine 多阶段构建，将 MCP Server 通过 stdio 暴露，适用于 CI/CD 集成或 serverless 场景。

6.2 无 API Key 起步

首次使用完全不需要 API key。内置的 Heuristic Provider 基于规则和模板进行文档提取，不调用任何外部 LLM API，完全离线运行。适合快速试用或隐私敏感场景。

如果需要更高质量的提取，可以后续配置云端 provider（Claude/Gemini 等）。

6.3 硬件需求

资源	需求
CPU	任意，现代多核更佳
内存	>= 512MB，大仓库建议 >= 2GB
磁盘	取决于 vault 规模，100MB base + 来源文件存储
GPU	不需要（Heuristic Provider），如使用云端 LLM 则依赖网络

---

七、争议与局限

7.1 幻觉风险

SwarmVault 直面了 LLM Wiki 模式的核心争议：LLM 提取的知识可能包含幻觉，越积累越多。

项目对此有几层应对：

1. 置信度标签：每条边标记 extracted / inferred / ambiguous，用户可据此判断可信度
2. 矛盾检测：lint --conflicts 自动扫描冲突声明
3. 审批队列：新概念先进入 wiki/candidates/，需要人类审核后才能提升
4. Review 命令：swarmvault candidate list + swarmvault review 提供人工审核入口

7.2 Node.js 24 的要求

这是一个前沿工具，对运行时版本的要求相当激进——Node.js >= 24（截至 2026 年 6 月仍处于即将发布的阶段）。这意味着：

• 大多数 Linux 发行版的默认 Node.js 版本不满足要求
• 需要使用 nvm 或 fnm 管理多版本
• 桌面应用版本可能是更务实的入门选择

7.3 存储空间

Vault 本地存储所有原始文件的副本，大型项目的 raw/ 目录可能占用数 GB 空间。这是"本地优先"设计的必要代价，但通过 .gitignore 排除 vault artifacts 可以避免污染主项目。

---

八、行业意义与未来趋势

SwarmVault 代表了一个正在浮现的 AI 工具链方向：从"单次会话利用 AI"到"跨会话积累 AI 知识"。

传统 RAG 系统是"搜索引擎模式"——用户提问，系统从文档库中检索相关内容。而 SwarmVault 更像"第二大脑模式"——AI Agent 在工作过程中主动记录、提炼、关联知识，形成可被未来 AI 和人类共同查阅的持久化知识资产。

这个方向的价值在于：

1. 知识主权：数据存在本地磁盘，不依赖任何第三方 API，避免知识被锁定在特定平台
2. 记忆连续性：AI Agent 不再是"每次都从零开始"，而是真正拥有积累的概念
3. 知识图谱标准化：SwarmVault 的 hyperedge graph 模型、context pack 格式和 MCP 协议接入，都在推动 Agent Memory 的开放标准
4. Obsidian 的竞争者：Obsidian 是人类用户的知识管理工具；SwarmVault 则同时服务于人类和 AI Agent，开辟了一个全新的品类

从增长曲线看，578 stars / 2.5 个月的节奏在开源知识管理工具中属于早期爆发型。随着 AI Agent 在编程、写作、研究等场景的普及，像 SwarmVault 这样专注于 Agent Memory 的基础设施工具，需求空间可能持续扩大。

---

九、快速体验

# 最快路径（无需 API key）
npm install -g @swarmvaultai/cli
swarmvault quickstart https://github.com/owner/repo

# 体验 demo vault
swarmvault demo

# 查看下一步建议
swarmvault next

# 自然语言查询
swarmvault query "这个项目的核心架构是什么？"

# 启动图谱查看器
swarmvault graph serve

# MCP Server 模式（供 AI Agent 使用）
docker build -t swarmvault-mcp . && docker run --rm -i swarmvault-mcp

适合人群：使用 Claude Code / Codex / OpenCode 进行开发的工程师，需要长期维护项目文档的研究者，以及对个人知识管理系统（Obsidian 用户）感兴趣且希望 AI 也参与其中的用户。