vouch

Git-native, review-gated knowledge base for LLM agents. MCP server + JSONL tool server + CLI.

Agents should not start every session with amnesia — but they shouldn't get to write whatever they want either.

vouch gives LLM agents durable memory with an explicit review gate: sessions capture themselves, agents propose writes, and nothing becomes durable knowledge until you approve it. Approved artifacts are plain files under .vouch/ — YAML claims, markdown pages — so the KB lives in your repo, is reviewed like code, diffs cleanly, and travels with git clone.

The destination is the one Andrej Karpathy's llm-wiki idea file sketches: stop using LLMs as search engines that rediscover your documents on every question — use them as tireless knowledge engineers that compile, cross-reference, and maintain a living wiki, while humans curate and think. vouch is that idea with the write path made trustworthy. vouch compile has an LLM draft the topic pages, but every page cites approved claims, every [claim: …] citation is machine-verified before the draft is filed, and the drafts pass through the same review gate as every other write. The LLM compiles; the human approves; the wiki compounds.

"I can do this with one prompt"

Often true — and worth being honest about. If you want your agent to remember things, a paragraph in CLAUDE.md, a memory file, or your host's built-in auto-memory gets you most of the way, costs nothing, and needs no install. Reach for that first. Recall is not a hard problem.

What is hard is trust in the write path, and that's a different problem than memory. Single-writer memory needs no trust model: you're the only author, and a bad line costs you a shrug. The moment writes come from more than one author — several agents, a teammate, a future you who forgot the context — the question stops being "what did we say?" and becomes "who decided this was true, on what evidence, and can I audit it later?" A prompt cannot answer that, no matter how good the prompt is.

That's the whole of vouch:

The same argument as a picture — at one writer the two are the same thing; the gap opens at the second writer and only widens:

So the honest pitch: vouch is not a better place to put memory — it's a review gate in front of one, and a wiki on the other side of it. If you're solo and happy, one prompt is genuinely fine; vouch's session capture runs passively alongside whatever your host already remembers, rather than replacing it. But once a fleet of agents writes to shared knowledge — or a team does — that pile of notes needs an editor, and an editor is not something you can prompt your way to. The case in full: docs/review-gate.md.

Install

For the full UI experience (recommended first time):

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

Pre-seeded KB + full webapp console, zero setup. Pass -e ANTHROPIC_API_KEY=sk-ant-... to enable LLM features.

For the full UI without Docker — Python only, no clone, no 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 serves the same React console as the Docker demo, straight from the installed package.

For CLI + Claude Code integration (most common ongoing workflow):

# 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

The one-liner is POSIX sh and never needs sudo — inspect install.sh first if you'd like.

For MCP server or CLI-only use:

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

For local development — CLI and webapp, both running from source:

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 needs node — it starts vouch serve --transport http and the Vite dev server as a pair, installing the console's node deps automatically on first run. To instead serve the console the way a release wheel does (no dev server), run make webapp-build once, then vouch console. See CONTRIBUTING.md for the full dev workflow.

Reproduce the loop on your project

After exploring the demo above, set up vouch in your own project:

1. Set up the KB and wire Claude Code (one command, one-time, per repo):

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

install-mcp initialises the KB when no .vouch/ is discoverable (pass --no-init to skip; vouch init still exists for KB-only setup), then writes .mcp.json (the kb.* MCP tools), the /vouch-* slash commands, and five hooks — SessionStart recall, UserPromptSubmit per-prompt recall, PostToolUse capture, Stop answer capture, SessionEnd rollup. It also registers vouch as a local-scope MCP server in ~/.claude.json (the ⚑ line in the output). Reload your editor window (VS Code: Developer: Reload Window) so it loads.

Why the extra registration? A committed .mcp.json is a project-scope server, and Claude Code only loads one after a per-user approval — which the VS Code extension never prompts for, so .mcp.json alone leaves the kb_* tools invisible in the extension (they sit at "pending approval", while the hooks quietly work — easy to misread as "connected"). The local-scope entry install-mcp writes is trusted on sight, so a fresh install just connects. Verify with claude mcp list (vouch … ✔ Connected). Pass --no-approve to skip it and approve .mcp.json yourself.

What you'll see. Every prompt is checked against the KB first. When vouch knows something relevant, the answer opens with "From vouch memory:", grounded in the cited items; when it doesn't, it opens with "Nothing in vouch on this." — recall is visible on every turn, never silent. (A fresh KB knows almost nothing yet: work a session or two so capture fills it, then ask about the project again.)