[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_130":131},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","vouchdev","moduleId","vouch","@vouchdev/vouch","displayName","Vouch","tagline","Git-native, review-gated knowledge base for LLM agents. Cited retrieval, audited writes.","iconKey","https://avatars.githubusercontent.com/u/285916225?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783485077000,"updatedAt",1788168065000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.vouchdev%2Fvouch","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",91,"upstreamUpdatedAt",1787457212000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/vouchdev/vouch","githubRepoFullName","vouchdev/vouch","releaseId","ext-vouchdev-vouch","version","1.2.2","descriptionMarkdown","# vouch\n\n[![MCP Toplist](https://mcptoplist.com/badge/io.github.vouchdev%2Fvouch.svg)](https://mcptoplist.com/server/io.github.vouchdev%2Fvouch)\n\n**Git-native, review-gated knowledge base for LLM agents. MCP server + JSONL tool server + CLI.**\n\n\n\n\n

\n $\"CI\"$ \n $\"PyPI\"$ \n $\"MCP$ \n $\"Python$ \n $\"MIT$ \n $\"Gittensor$ \n

\n\n> Agents should not start every session with amnesia — but they shouldn't get to write whatever they want either.\n\n`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`.\n\nThe destination is the one [Andrej Karpathy's llm-wiki idea file](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 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.\n\n## \"I can do this with one prompt\"\n\nOften 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.\n\nWhat 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.\n\nThat's the whole of vouch:\n\n| | one prompt / memory file | vouch |\n|---|---|---|\n| **Who can write** | whatever the agent decides to save | agents *propose*; a human approves — nothing else lands |\n| **Why believe a line** | vibes | every claim cites a content-hashed source; uncited is a validation error |\n| **When it's wrong** | edit and hope | supersede / contradict / archive, with the old version still in history |\n| **Who changed it** | file mtime | append-only audit log: who proposed, who approved, citing what, when |\n| **At n ≥ 2 writers** | last write wins, silently | one gate, one reviewed history, shared by `git clone` |\n| **What you read** | a growing pile of notes | compiled topic pages with verified citations — a wiki, not a log |\n\nThe same argument as a picture — at one writer the two are the same thing; the gap opens at the second writer and only widens:\n\n

\n\nSo 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](https://github.com/vouchdev/vouch/blob/test/docs/review-gate.md).\n\n## Install\n\n**For the full UI experience** (recommended first time):\n\n```bash\ndocker run --rm -p 127.0.0.1:5173:5173 -v vouch-demo-data:/data ghcr.io/plind-junior/vouch-demo\n# then open http://localhost:5173\n```\n\nPre-seeded KB + full webapp console, zero setup. Pass `-e ANTHROPIC_API_KEY=sk-ant-...` to enable LLM features.\n\n**For the full UI without Docker** — Python only, no clone, no node:\n\n```bash\npipx install 'vouch-kb[web]' # the browser console ships inside the wheel\nvouch serve --transport http --port 8731 & # a backend for the current .vouch/\nvouch console # console at http://localhost:5173 — connect it to :8731\n```\n\n`vouch console` serves the same React console as the Docker demo, straight from the installed package.\n\n**For CLI + Claude Code integration** (most common ongoing workflow):\n\n```bash\n# one-liner (Linux + macOS) — picks a Python, ensures pipx, installs vouch-kb\ncurl -fsSL https://raw.githubusercontent.com/vouchdev/vouch/main/install.sh | sh\n\n# …or directly via pipx (vouch-kb on PyPI; the command stays `vouch`)\npipx install vouch-kb\n```\n\nThe one-liner is POSIX `sh` and never needs `sudo` — inspect [`install.sh`](https://github.com/vouchdev/vouch/blob/test/install.sh) first if you'd like.\n\n**For MCP server or CLI-only use**:\n\n```bash\ndocker run -i --rm -v \"$PWD:/data\" ghcr.io/vouchdev/vouch:latest # stdio MCP server\ndocker run --rm -v \"$PWD:/data\" ghcr.io/vouchdev/vouch:latest status # any CLI command\n```\n\n**For local development** — CLI and webapp, both running from source:\n\n```bash\ngit clone https://github.com/vouchdev/vouch\ncd vouch\npython3 -m venv .venv && source .venv/bin/activate\npip install -e '.[dev,web]' # dev,web is what CI installs — make check needs both\nvouch --version # the CLI now runs straight from src/ — edits apply without reinstalling\n\nmake console # webapp in dev mode: vouch backend on :8731 + live-reload\n # console at http://localhost:5173 — Ctrl-C stops both\n\nmake check # the CI gate: lint + type + test\n```\n\n`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](https://github.com/vouchdev/vouch/blob/test/CONTRIBUTING.md) for the full dev workflow.\n\n## Reproduce the loop on your project\n\nAfter exploring the demo above, set up vouch in your own project:\n\n**1. Set up the KB and wire Claude Code** (one command, one-time, per repo):\n\n```bash\ncd /path/to/your/project\nvouch install-mcp claude-code # creates .vouch/ (if missing) + wires Claude Code\n```\n\n`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 the weight-bearing hooks — `SessionStart` recall, `UserPromptSubmit` per-prompt recall, `SessionEnd` rollup. Per-tool `PostToolUse` observe / `Stop` answer are opt-in (`capture.realtime`; default off). 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.\n\n> **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.\n\n> **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.)\n\n> **Prefer one install for every project?** `vouch install-mcp claude-code --global` wires vouch once, machine-wide: user-level hooks and commands in `~/.claude/` plus a user-scope MCP server in `~/.claude.json`. Every Claude session in every folder then captures + recalls into *that folder's own* `.vouch/` — data stays per project. Run `vouch init` once in each project you want vouch in; by default a folder without a KB never captures anywhere — its session opens with a one-line \"run `vouch init` to enable durable memory here\" note and the `kb_*` tools say the same. Safe next to existing per-project installs: duplicate hooks collapse and capture dedups by event id.\n\n> **Optionally, a personal catch-all KB.** The global install asks one question (or pass `--personal-fallback`; later: `vouch hub init-personal --fallback`): opt in, and folders *without* a project KB capture into a personal KB at `~/.local/share/vouch/personal` instead of nowhere — each captured source stamped with the folder it came from, and the session banner saying exactly where the knowledge is going. It is **one store shared by every KB-less folder**: recall in any of them reads the whole personal KB, so knowledge captured while working in one such folder can surface in another (the injected block says so). Projects with their own `.vouch/` are never affected. When such a folder later becomes a real project, `vouch init` + **`vouch adopt`** moves its captures into the new project KB *through that KB's own review gate*: sources copy byte-identically, every claim is re-proposed and its byte-offset receipt re-verified, and the project's review config decides durability — adoption never bypasses review. Strictly opt-in; without it, nothing changes.\n\n**2. Point `compile` at an LLM** — the only step that needs a model. In `.vouch/config.yaml`:\n\n```yaml\ncompile:\n llm_cmd: \"claude -p --model sonnet\"\n```\n\n**3. Work a session — it captures itself.** Use Claude Code normally. Each tool call is harvested into a gitignored scratch buffer, and at session end the buffer rolls up — mechanically, no LLM — into **one pending session-summary page**. Never auto-approved: the next session greets you with\n\n```text\n🔔 1 auto-captured session summary(ies) awaiting review — run `vouch review`.\n```\n\n**4. Approve at the gate.**\n\n```bash\nvouch review # walk pending proposals one at a time\n```\n\nReceipt-verified claims skip the queue by default (`review.auto_approve_on_receipt: true` in the starter config): each session's captured answers become recallable memory with no review pass. What lands in `vouch review` is everything the mechanical check can't vouch for — session-summary pages, entities, relations, and claims that can't quote their source. Set the flag to `false` in `.vouch/config.yaml` to put every write behind the gate.\n\n**Want a browser UI for reviewing and proposing?** The video shows the **vouch webapp** — chat, review queue, claims, and stats. Your options:\n\n- **No setup**: the Docker demo above\n- **pip, no clone**: `pipx install 'vouch-kb[web]'` then `vouch console` (Python only, no Docker, no node) — open http://localhost:5173\n- **Local development**: clone the repo, run `make console`\n- **Lighter built-in queue**: `vouch review-ui` (also in the `[web]` extra)\n- **CLI-only**: `vouch pending`, `vouch show `, `vouch approve `, `vouch reject --reason \"…\"`\n\nTo point any of them at an existing KB, start a backend in your project — `vouch serve --transport http --port 8731` — then connect the console to `:8731` (for the Docker demo, pass `-e VOUCH_TARGET=http://host.docker.internal:8731`).\n\n**5. Compile the wiki.**\n\n```bash\nvouch compile # LLM drafts cited topic pages from approved claims\nvouch review # drafts land in the same gate — approve the keepers\n```\n\nEvery `[claim: …]` marker and `[[wikilink]]` in a draft is verified mechanically against the store; drafts whose citations don't hold are dropped before they reach you. See [docs/compile.md](https://github.com/vouchdev/vouch/blob/test/docs/compile.md).\n\n**6. Start the next session — it already knows.** The `SessionStart` hook runs `vouch recall`, injecting every approved claim and page title into the first turn, so the session starts from your reviewed knowledge instead of re-discovering it.\n\nDetection is Claude Code's hook contract: whatever a `SessionStart` hook prints becomes context in the session's opening turn. `vouch recall` prints the digest the video closes on — claims with their full text, pages by id and title:\n\n```text\n\n# approved KB knowledge for this repo — 2 claim(s), 1 page(s). reviewed,\n# cited, durable. use kb_read_page / kb_search for detail; kb_propose_*\n# (human-approved) to add more.\n\n## claims\n- [auth-uses-jwt] Auth uses JWT tokens — decision from the design note.\n- [vouch-starter-reviewed-knowledge] Vouch stores reviewed, cited knowledge\n in the repository so future agent sessions can retrieve agreed project\n context.\n\n## pages\n- [edit-in-obsidian] Edit in Obsidian\n\n```\n\nOnly approved artifacts are ever emitted — archived, superseded, and still-pending items are excluded — and the digest is size-guarded (`recall.max_chars`) with an explicit truncation notice.\n\nHow the approved pages actually get used from there: recall carries the *titles*, and the session pulls full content on demand through the `kb.*` MCP tools — `kb_search` matches page bodies, `kb_read_page` returns a page's markdown plus the claims it cites, and `kb_context` bundles the most relevant claims and pages for a stated task. To pull a topic in explicitly, use the `/vouch-recall ` slash command, or just ask Claude to check the KB. One thing to know: pages still sitting in `vouch review` are invisible to all of this — the gate applies to retrieval too, so a compiled page only starts informing sessions once you approve it.\n\n**7. Commit the knowledge with the code.**\n\n```bash\ngit add .vouch/ && git commit -m \"kb: approve session summary\"\n```\n\nPending drafts (`proposed/`) and the derived search index (`state.db`) are gitignored — what lands in history is exactly what passed review.\n\n## The rules underneath\n\n* **Writes require approval.** Agents file *proposals* via the `kb.*` MCP tools (or `vouch serve --transport jsonl`); approval is the only path to a durable artifact, and the approver must differ from the proposer unless you opt out.\n* **Claims must cite sources.** A claim without evidence is a validation error, not a warning. Sources are content-hashed; the same evidence registered twice de-duplicates.\n* **History is append-only.** Every mutation lands in a committed audit log — who proposed, who approved, citing what, when.\n\n## Going further\n\n* [docs/example-session.md](https://github.com/vouchdev/vouch/blob/test/docs/example-session.md) — the full capture→approve→recall walkthrough with real output\n* [docs/getting-started.md](https://github.com/vouchdev/vouch/blob/test/docs/getting-started.md) — the agent-side flow\n* [SPEC.md](https://github.com/vouchdev/vouch/blob/test/SPEC.md) — the protocol contract (object model, JSONL envelopes, trust metadata)\n* `vouch --help` / `vouch capabilities` — the full CLI and machine-readable method surface\n* `vouch install-mcp ` also wires cursor, codex, zed, windsurf, openclaw and friends ([adapters/](https://github.com/vouchdev/vouch/blob/test/adapters/))\n* [vouch webapp](https://github.com/vouchdev/webApp) — the chat-first browser console from the video; [vouch-desktop](https://github.com/vouchdev/vouch-desktop) wraps the same loop as a desktop app\n* [CONTRIBUTING.md](https://github.com/vouchdev/vouch/blob/test/CONTRIBUTING.md) — development setup and the test gate\n* [docs/mining-on-vouch.md](https://github.com/vouchdev/vouch/blob/test/docs/mining-on-vouch.md) — get paid to improve the retrieval engine: submit ranking code, scored by a reproducible benchmark; the best verified strategy ships as the default\n\n## Incubated by Gittensor\n\nVouch was incubated and supported by [Gittensor](https://gittensor.io), a protocol that rewards open-source contributions. The knowledge-base-as-code pattern and review-gated persistence model emerged directly from conversations about trusted AI agents and long-term memory in collaborative development workflows.\n\n## License\n\nMIT.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","agent-skills","ai","ai-brain","assistant","audit-log","claude-code","claude-momory","git-native","karpathy-llm-wiki","knowledge-base","knowledge-graph","llm-agents","note-taking","open-source","personal","topics",[94,95,96,97,98,99,100,101,102,103,104,105,126,106,107,108,127,128,129,21],"license","MIT","language","Python","registryName","io.github.vouchdev/vouch","homepage","https://vouchai.dev","packages",[121],{"_122":123,"_124":125,"_71":72},"registryType","pypi","identifier","vouch-kb","mcp","personal-knowledge-management","review-gate","vibe-coding","ENV",{"_132":133,"_134":135,"_136":137},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]