Vouch

vouch

基于 Git、需经审核的 LLM Agent 知识库。MCP 服务 + JSONL 工具服务 + 命令行。

Agent 不该每次会话开始时都失忆——但也不该任意写入内容。

vouch 为 LLM Agent 提供持久记忆，并设置明确的审核关卡：会话会自动记录内容，Agent 可以提议写入，但只有经过你批准，内容才会成为持久知识。获批的内容是 .vouch/ 下的纯文件——YAML 声明、Markdown 页面——因此知识库存放在你的代码仓库中，像代码一样接受审核，差异清晰，并随 git clone 一同迁移。

它的目标正是 Andrej Karpathy 的 llm-wiki 构想文件所描绘的愿景：不要再把 LLM 当作搜索引擎，让它们每次遇到问题时都重新发现你的文档；而要把它们当作不知疲倦的知识工程师，编纂、交叉引用并维护一部不断更新的 Wiki，由人类负责整理和思考。vouch 实现了这一构想，并让写入流程值得信赖。vouch compile 会让 LLM 起草主题页面，但每个页面都引用获批的声明，每条 [claim: …] 引用都会在草稿提交前经过机器验证，而且草稿也要经过与其他所有写入相同的审核关卡。LLM 负责编纂；人类负责批准；Wiki 持续积累。

“我用一个提示词就能搞定”

这通常没错，也值得坦诚承认。如果你想让 Agent 记住一些内容，在 CLAUDE.md 里写一段文字、使用记忆文件，或使用宿主内置的自动记忆功能，就能解决大部分问题，而且不花钱，也无需安装。先试试这些方法。记忆并不是难题。

难的是写入路径的可信度，这和记忆是不同的问题。单写入者的记忆不需要信任模型：只有你一个作者，写错一行也不过是耸耸肩。可一旦写入者不止一个——多个 Agent、队友，或忘了上下文的未来的你——问题就不再是“我们说了什么？”，而变成“是谁根据什么证据认定这是真的？我之后能审计吗？”无论提示词写得多好，提示词都回答不了这个问题。

这就是 vouch 的全部意义：

	一个提示词 / 记忆文件	vouch
谁能写入	Agent 决定保存什么	Agent 提出；由人工审批——其他内容一概不会写入
为什么相信一条内容	凭感觉	每项声明都引用经过内容哈希处理的来源；未引用会导致验证错误
内容出错时	修改并祈祷	替代 / 反驳 / 归档，旧版本仍保留在历史记录中
谁做了修改	文件修改时间	仅追加的审计日志：谁提出、谁审批、引用了什么，以及何时操作
写入者数量 n ≥ 2 时	静默地以最后一次写入为准	一个审核关口、一段经过审查的历史记录，可通过 git clone 共享
你读取的内容	越积越多的笔记	附有经验证引文的编译主题页面——是维基，而非日志

把同一论点画成图：只有一个写入者时，两者是一回事；从第二个写入者开始，差距便会出现并不断扩大：

因此，坦诚地说：**vouch 并不是一个更好的记忆存放处——它是在记忆前设置的审核关口，也是关口另一侧的维基。**如果你独自使用并且满意，一个提示词确实完全够用；vouch 的会话捕获功能会在后台运行，与宿主已有的记忆并行，而不是取而代之。但一旦多个 Agent 集体写入共享知识，或团队成员共同写入，积累的笔记就需要一位编辑，而编辑不是靠提示词就能得到的。完整论述请见：docs/review-gate.md。

安装

体验完整 UI（首次使用推荐）：

docker run --rm -p 127.0.0.1:5173:5173 -v vouch-demo-data:/data ghcr.io/plind-junior/vouch-demo
# then open http://localhost:5173

预置知识库 + 完整 Web 应用控制台，无需配置。传入 -e ANTHROPIC_API_KEY=sk-ant-... 即可启用大模型功能。

不使用 Docker 体验完整 UI——仅需 Python，无需克隆仓库，也无需 Node：

pipx install 'vouch-kb[web]'                  # the browser console ships inside the wheel
vouch serve --transport http --port 8731 &    # a backend for the current .vouch/
vouch console                                 # console at http://localhost:5173 — connect it to :8731

vouch console 会直接从已安装的软件包提供与 Docker 演示相同的 React 控制台。

CLI + Claude Code 集成（最常用的日常工作流）：

# one-liner (Linux + macOS) — picks a Python, ensures pipx, installs vouch-kb
curl -fsSL https://raw.githubusercontent.com/vouchdev/vouch/main/install.sh | sh

# …or directly via pipx (vouch-kb on PyPI; the command stays `vouch`)
pipx install vouch-kb

这条一行式命令使用 POSIX sh，无需 sudo——如果你愿意，可先检查 install.sh。

仅使用 MCP 服务或 CLI：

docker run -i --rm -v "$PWD:/data" ghcr.io/vouchdev/vouch:latest          # stdio MCP server
docker run --rm -v "$PWD:/data" ghcr.io/vouchdev/vouch:latest status      # any CLI command

本地开发——CLI 和 Web 应用均从源码运行：

git clone https://github.com/vouchdev/vouch
cd vouch
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev,web]'    # dev,web is what CI installs — make check needs both
vouch --version                # the CLI now runs straight from src/ — edits apply without reinstalling

make console                   # webapp in dev mode: vouch backend on :8731 + live-reload
                               # console at http://localhost:5173 — Ctrl-C stops both

make check                     # the CI gate: lint + type + test

make console 需要 Node——它会同时启动 vouch serve --transport http 和 Vite 开发服务器，并在首次运行时自动安装控制台的 Node 依赖项。若要像发布版 wheel 一样提供控制台服务（不使用开发服务器），请先运行一次 make webapp-build，然后运行 vouch console。完整开发工作流请见 CONTRIBUTING.md。

在你的项目中复现这一工作流

探索完上面的演示后，在你自己的项目中设置 vouch：

1. 设置知识库并接入 Claude Code（每个仓库只需运行一次命令）：

cd /path/to/your/project
vouch install-mcp claude-code       # creates .vouch/ (if missing) + wires Claude Code

install-mcp 会在找不到 .vouch/ 时初始化知识库（传入 --no-init 可跳过；仅设置知识库时仍可使用 vouch init），然后写入 .mcp.json（包含 kb.* MCP 工具）、/vouch-* 斜杠命令，以及负责权重处理的钩子——SessionStart 回忆、UserPromptSubmit 每次提示词回忆、SessionEnd 汇总。每个工具对应的 PostToolUse 观察和 Stop 回答为可选项（capture.realtime；默认关闭）。它还会将 vouch 注册为 ~/.claude.json 中的本地作用域 MCP 服务（输出中的 ⚑ 行）。重新加载编辑器窗口（VS Code：Developer: Reload Window），使其加载。

为什么还要额外注册？ 已提交的 .mcp.json 是一个项目作用域服务，而 Claude Code 只会在获得每位用户的批准后加载它——但 VS Code 扩展从不提示批准，因此仅靠 .mcp.json 会导致扩展中看不到 kb_* 工具（它们会停留在“待批准”状态，而钩子则悄悄运行——很容易误以为“已连接”）。install-mcp 写入的本地作用域条目会自动受信任，因此全新安装后即可连接。运行 claude mcp list 验证（vouch … ✔ Connected）。传入 --no-approve 可跳过此步骤，并自行批准 .mcp.json。

你会看到什么。 每条提示词都会先与知识库核对。vouch 找到相关信息时，回答会以 “来自 vouch 记忆：” 开头，并以引用条目为依据；找不到时，则会以 “vouch 中没有相关内容。” 开头——每一轮回忆都会显示出来，不会悄无声息。（全新的知识库几乎一无所知：先工作一两次会话，让采集流程填充知识库，然后再询问项目相关内容。）

想要一次安装，让每个项目都能使用？ vouch install-mcp claude-code --global 会在整台机器上一次性配置 vouch：在 ~/.claude/ 中安装用户级钩子和命令，并在 ~/.claude.json 中注册用户作用域 MCP 服务。之后，每个文件夹中的每次 Claude 会话都会将内容采集并回忆到该文件夹自己的 .vouch/ 中——数据按项目隔离。在每个想使用 vouch 的项目中运行一次 vouch init；默认情况下，没有知识库的文件夹不会在任何地方采集内容——其会话会以一行提示“运行 vouch init 以在此启用持久记忆”开场，kb_* 工具也会显示相同提示。与现有的项目级安装共存是安全的：重复钩子会合并，采集流程会按事件 ID 去重。

可选的个人兜底知识库。 全局安装会询问一个问题（或传入 --personal-fallback；之后也可运行 vouch hub init-personal --fallback）：选择启用后，没有项目知识库的文件夹会将内容采集到 ~/.local/share/vouch/personal 中的个人知识库，而不是不存到任何地方——每个采集到的来源都会标记其所属文件夹，会话横幅也会明确说明知识的去向。它是所有没有知识库的文件夹共用的一个存储库：在其中任何一个文件夹中进行回忆，都会读取整个个人知识库，因此在其中一个文件夹工作时采集的知识可能会出现在另一个文件夹中（注入的区块会说明这一点）。拥有自己 .vouch/ 的项目不会受到影响。此类文件夹之后成为真正的项目时，vouch init + vouch adopt 会将其采集内容移入新项目知识库，并经过该知识库自己的审核关卡：来源会逐字节复制，每条声明都会重新提交，且会重新验证其字节偏移回执；项目的审核配置决定内容能否持久保存——迁移绝不会绕过审核。此功能必须明确选择启用；否则一切保持不变。

2. 将 compile 指向一个大模型——这是唯一需要模型的步骤。在 .vouch/config.yaml 中：

compile:
  llm_cmd: "claude -p --model sonnet"

3. 工作一个会话——它会自行采集内容。 像平常一样使用 Claude Code。每次工具调用都会被收集到一个由 git 忽略的暂存缓冲区中，会话结束时，缓冲区会汇总——这是机械处理，不需要大模型——生成一页待审核的会话摘要。它绝不会自动批准；下次会话会这样向你问候：

🔔 1 auto-captured session summary(ies) awaiting review — run `vouch review`.

4. 在审核关卡中批准。

vouch review                    # walk pending proposals one at a time

经回执验证的声明默认会跳过队列（入门配置中为 review.auto_approve_on_receipt: true）：每个会话捕获的回答都会成为可供回忆的记忆，无需经过审核。进入 vouch review 的内容，是机械检查无法验证的所有内容——会话摘要页面、实体、关系，以及无法引用来源的声明。在 .vouch/config.yaml 中将该标志设为 false，即可让每次写入都必须经过审核。

想要使用浏览器界面进行审核和提议？ 视频展示的是 vouch webapp——聊天、审核队列、声明和统计信息。你有以下选择：

• 无需设置：上面的 Docker 演示
• 使用 pip，无需克隆：运行 pipx install 'vouch-kb[web]'，然后运行 vouch console（仅需 Python，无需 Docker 或 node）——打开 http://localhost:5173
• 本地开发：克隆仓库，然后运行 make console
• 更轻量的内置队列：运行 vouch review-ui（也包含在 [web] 扩展中）
• 仅使用 CLI：vouch pending、vouch show <id>、vouch approve <id>、vouch reject <id> --reason "…"

若要让其中任一方式连接到现有知识库，请在项目中启动后端——vouch serve --transport http --port 8731——然后将控制台连接到 :8731（对于 Docker 演示，传入 -e VOUCH_TARGET=http://host.docker.internal:8731）。

5. 编译 Wiki。

vouch compile                   # LLM drafts cited topic pages from approved claims
vouch review                    # drafts land in the same gate — approve the keepers

草稿中的每个 [claim: …] 标记和 [[wikilink]] 都会根据存储内容进行机械验证；引用不成立的草稿会在送达你之前被丢弃。请参阅 docs/compile.md。

6. 开始下一个会话——它已经了解情况。 SessionStart 钩子会运行 vouch recall，将所有已批准的声明和页面标题注入首轮对话，让会话从你审核过的知识出发，而不是重新发现这些知识。

检测机制采用 Claude Code 的钩子约定：SessionStart 钩子输出的任何内容都会成为会话开场轮次的上下文。vouch recall 会输出视频结尾所展示的摘要——包含完整文本的声明，以及按 ID 和标题列出的页面：

<vouch-approved-knowledge>
# approved KB knowledge for this repo — 2 claim(s), 1 page(s). reviewed,
# cited, durable. use kb_read_page / kb_search for detail; kb_propose_*
# (human-approved) to add more.

## claims
- [auth-uses-jwt] Auth uses JWT tokens — decision from the design note.
- [vouch-starter-reviewed-knowledge] Vouch stores reviewed, cited knowledge
  in the repository so future agent sessions can retrieve agreed project
  context.

## pages
- [edit-in-obsidian] Edit in Obsidian
</vouch-approved-knowledge>

仅会输出已批准的内容——已归档、已被取代和仍待审核的项目都会被排除；摘要还会受到大小限制（recall.max_chars），并在截断时明确提示。

已批准页面之后的实际使用方式：回忆内容会包含标题，会话则会按需通过 kb.* MCP 工具获取完整内容——kb_search 会匹配页面正文，kb_read_page 会返回页面的 Markdown 内容及其引用的声明，kb_context 会根据指定任务汇总最相关的声明和页面。若要明确调取某个主题，请使用 /vouch-recall <topic> 斜杠命令，或者直接让 Claude 检查知识库。需要注意的是：仍在 vouch review 中的页面对上述所有功能都不可见——审核门槛同样适用于检索，因此只有在你批准编译后的页面后，它才会开始为会话提供信息。

7. 将知识与代码一同提交。

git add .vouch/ && git commit -m "kb: approve session summary"

待审核草稿（proposed/）和派生的搜索索引（state.db）会被 Git 忽略——历史记录中只会留下通过审核的内容。

其背后的规则

• 写入需要批准。 Agent 通过 kb.* MCP 工具（或 vouch serve --transport jsonl）提交提案；只有经过批准才能生成持久内容，且批准者必须与提案者不同，除非你选择退出此规则。
• 声明必须注明来源。 没有证据支持的声明属于验证错误，而不是警告。来源会进行内容哈希；重复注册相同证据时会自动去重。
• 历史只追加，不可改写。 每次变更都会写入已提交的审计日志——记录提案者、批准者、引用内容以及时间。

深入了解

• docs/example-session.md — 展示完整的捕获→审批→回忆流程，并提供实际输出
• docs/getting-started.md — Agent 端的工作流程
• SPEC.md — 协议规范（对象模型、JSONL 封装、信任元数据）
• vouch --help / vouch capabilities — 完整的 CLI 和机器可读的方法接口
• vouch install-mcp <host> 还会为 cursor、codex、zed、windsurf、openclaw 等工具配置连接（adapters/）
• vouch webapp — 视频中以聊天为先的浏览器控制台；vouch-desktop 将相同的工作流程封装为桌面应用
• CONTRIBUTING.md — 开发环境配置和测试门槛
• docs/mining-on-vouch.md — 通过改进检索引擎获得报酬：提交排序代码，并由可复现的基准进行评分；最佳的已验证策略将作为默认策略发布

由 Gittensor 孵化

Vouch 由 Gittensor 孵化并提供支持。Gittensor 是一个奖励开源贡献的协议。知识库即代码模式和经审核后才持久化的模型，直接源自关于可信 AI Agent 以及协作开发工作流中长期记忆的讨论。

许可证

MIT。