vouch-kb 1.0.0

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

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 is a knowledge base for LLM agents with an explicit review gate: agents propose writes; humans approve them with vouch approve. Approved artifacts are plain files on disk — YAML for claims, markdown for pages — so the KB lives in your repo, is reviewed in PRs, diffs cleanly, and can be exported as a portable bundle.

Still alpha — surface is small on purpose; expect breaking changes pre-1.0.

Featured for Gittensor (SN74). vouch ships a one-command starter pack for Gittensor — Bittensor subnet 74. vouch init --template gittensor seeds a cited, already-approved decision-memory of SN74's scoring model: merged-PR rewards, PAT verification, sybil-resistance, the repo allow-list, the issue multiplier, and the emission split. It's the durable why behind each rule — reviewed, cited, and committed alongside your code. → docs/gittensor.md

Why this exists

Three opinionated choices distinguish vouch from the neighbours:

1. The KB is a folder in your repo. Git is your audit log, your backup, and your sync mechanism. PRs are your review UI.
2. Writes require approval. Agents file proposals; a human (or trusted approving agent) explicitly accepts them. proposed/ is gitignored, so rejected drafts never pollute history.
3. Claims must cite sources. A claim without at least one Source / Evidence id is a validation error, not a warning. Sources are content-hashed; the same evidence registered twice de-duplicates.

When to use vouch

Worth it when:

• You run or contribute to a Gittensor (SN74) repo. Scoring weights, the repo allow-list, anti-sybil thresholds, and emission splits get debated across PRs, Discord, and validator changes — then settle into nobody's notes. vouch init --template gittensor gives you a cited, reviewed record of why each rule exists and what it superseded. See docs/gittensor.md.
• Multiple agents share a repo (Claude Code + Cursor + a CI bot). Per-agent attribution in the audit log makes "which agent claimed what" answerable.
• Sessions keep re-explaining the same context. Curated, cited claims let new sessions start from your team's agreed answer instead of re-grepping.
• You want decision records without the ADR ceremony. vouch crystallize promotes a session's durable parts into proposals; one approve and they're permanent.
• You'd review agent-stated facts the way you review agent-written code. Vouch is a PR queue for claimed knowledge.
• Compliance / audit trails matter. Required citations + append-only audit log give you "who decided X, citing what, when" for free.

Skip it if:

• Solo hobby project where context fits in your head.
• Short-lived branches with no compounding context.
• Your team won't actually review proposals — without the gate, vouch is a worse note app.

Install

# 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

# …or from the cloned repo, in a venv
pip install -e '.[dev]'

The one-liner is POSIX sh, never needs sudo, and detects an existing Claude Code install to point you at the next step (vouch install-mcp claude-code). Inspect it first if you'd like — it's install.sh at the repo root.

Quick start

# 1. set up a KB at your project root
vouch init

# 2. as agent, register evidence + propose claims (via MCP/JSONL server)
vouch serve                      # MCP over stdio  (Claude Code, Cursor, Codex)
vouch serve --transport jsonl    # newline-delimited JSON over stdin/stdout

# 3. as human, review and decide
vouch status                     # one-line summary
vouch pending                    # list pending proposals
vouch show <id>                  # full details
vouch approve <id>               # → durable artifact
vouch reject <id> --reason "..."
vouch expire --apply                  # optional: clear stale pending proposals

# 4. commit
git add .vouch/ && git commit -m "kb: approve auth-uses-jwt"

30-second tour

vouch init now creates a starter config plus one cited example claim, so you can try the loop before wiring an agent:

mkdir vouch-demo && cd vouch-demo
vouch init
vouch status
vouch search agent
vouch cite vouch-starter-reviewed-knowledge

The starter claim is already durable and cites the starter source. Replace it with your project's first real source and claim when you are ready.

The full captured walkthrough lives at docs/example-session.md; re-render the GIF from docs/demo.tape with vhs docs/demo.tape.

Gittensor (SN74)

vouch's first domain template targets Gittensor — Bittensor subnet 74, which rewards open-source contribution by rule. Its scoring model evolves across PRs, Discord, and validator changes, and the rationale usually lives in people's heads. vouch is the durable, cited memory for it:

cd your-gittensor-repo
vouch init --template gittensor   # seeds 1 source, 1 entity, 7 cited claims about SN74 scoring
vouch status                      #   durable: 7 claims · 1 source · 1 entity
vouch search "emission split"
git add .vouch && git commit -m "chore: add vouch decision-memory KB"

The seeded pack covers merged-PR rewards, PAT verification, scoring factors, sybil-resistance, the repo allow-list, the issue-solving multiplier, and the emission split — each a cited, approved, supersede-able claim. When a rule changes, vouch supersede the old claim with the new one so the history of what changed stays queryable.

vouch stores no live signals — it is not a validator or miner client and never reads on-chain scores. It is the institutional memory that sits beside the live layer (Gittensory). The seeded claims are starter-grade; vouch supersede them with the real spec or PR once you confirm the live rule.

Full adoption guide — install, seed, wire the MCP server, capture decisions as cited claims: docs/gittensor.md.

Object model

Source     immutable input material (file, URL, transcript, commit, …)
           content-addressed by sha256

Evidence   span pointer into a Source (line range, timestamp, quote)

Claim      atomic durable assertion
           type: fact | decision | preference | workflow | observation | question | warning
           status: working | actionable | stable | contested | superseded | archived | redacted
           confidence: 0.0–1.0
           cites: list of Source / Evidence ids

Entity     typed thing (person | project | repo | concept | decision | system | …)
Relation   typed edge (uses | depends_on | supersedes | contradicts | implements | …)

Page       maintained markdown — entity write-up, decision record, session summary

Session    work block opened by an agent; bundles its proposals
AuditEvent append-only log record for every mutation

File layout

After vouch init, your repo contains:

.vouch/
├── config.yaml                 # KB settings
├── .gitignore                  # ignores proposed/, state.db
├── audit.log.jsonl             # append-only audit (committed)
├── state.db                    # SQLite FTS5 index (derived; not committed)
├── claims/<id>.yaml            # reviewed claims (init seeds vouch-starter-*.yaml)
├── pages/<id>.md               # markdown pages with YAML frontmatter
├── sources/<sha>/{meta.yaml,content}
├── entities/<id>.yaml          # graph nodes
├── relations/<id>.yaml         # graph edges
├── evidence/<id>.yaml          # span pointers into sources
├── sessions/<id>.yaml          # agent session records
├── proposed/<id>.yaml          # pending (gitignored, local-only)
└── decided/<id>.yaml           # approved/rejected (committed for audit)

The files are the source of truth; state.db is a derivable cache (vouch index rebuilds it).

CLI surface

vouch init                                  # set up .vouch/ at PATH
vouch discover [--path P]                   # find the nearest .vouch/ root
vouch capabilities                          # emit the JSON capabilities descriptor
vouch status [--json]                       # KB counts + pending proposals
vouch stats [--days N] [--json]             # observability: queue, review rates, citations
vouch lint [--stale-days N]                 # user-actionable problems
vouch doctor                                # full sweep incl. source verification
vouch fsck                                  # deep consistency: indexes, lifecycle, decided
vouch migrate [--check] [--dry-run]         # upgrade .vouch/ format safely

vouch pending                               # list pending proposals
vouch review [--limit N] [--type KIND]      # guided proposal review queue
vouch show <proposal-id>
vouch approve <proposal-id> [--reason ...]
vouch reject <proposal-id> --reason "..."
vouch expire [--apply] [--days N] [--json]   # GC stale pending proposals

vouch propose-claim --text ... --source ... [--type ...] [--confidence X]
vouch propose-page --title ... [--body -] [--claim ID ...]
vouch propose-entity --name ... --type ...
vouch propose-relation --from ID --rel uses --to ID

vouch source add PATH [--title ...] [--url ...]
vouch source verify [--fail-on-issue]

vouch supersede OLD_ID NEW_ID
vouch contradict CLAIM_A CLAIM_B
vouch archive CLAIM_ID
vouch confirm CLAIM_ID
vouch cite CLAIM_ID

vouch session start [--task ...] [--note ...]
vouch session end SESSION_ID
vouch crystallize SESSION_ID [--no-page]

vouch search QUERY [--limit N]
vouch context TASK [--max-chars N] [--min-items N] [--require-citations]
vouch index
vouch audit [--tail N] [--json]

vouch export --out path.tar.gz
vouch export-check path.tar.gz
vouch import-check path.tar.gz
vouch import-apply path.tar.gz [--on-conflict skip|overwrite|fail]
vouch sync-check PATH_OR_BUNDLE
vouch sync-apply PATH_OR_BUNDLE [--on-conflict fail|skip|propose]

vouch serve [--transport stdio|jsonl]

MCP tools / JSONL methods (same surface, two transports)

Read (unrestricted): kb.capabilities, kb.status, kb.search, kb.context, kb.read_{page,claim,entity,relation}, kb.list_{pages,claims,entities,relations,sources,pending}

Source intake (not gated — evidence is harmless and de-duplicates): kb.register_source, kb.register_source_from_path, kb.source_verify

Write (gated → produce proposals): kb.propose_{claim,page,entity,relation} (with dry_run:true for preview-only)

Decisions: kb.approve, kb.reject (host trust required)

Lifecycle (metadata about reviewed knowledge — direct mutation, audited): kb.supersede, kb.contradict, kb.archive, kb.confirm, kb.cite

Sessions: kb.session_start, kb.session_end, kb.crystallize

Maintenance: kb.index_rebuild, kb.lint, kb.doctor, kb.audit, kb.export, kb.export_check, kb.import_check, kb.import_apply

Wiring into Claude Code

In your project's .mcp.json:

{
  "mcpServers": {
    "vouch": {
      "command": "vouch",
      "args": ["serve"],
      "env": { "VOUCH_AGENT": "claude-code" }
    }
  }
}

VOUCH_AGENT is recorded as proposed_by and as the actor on every audit event, so multi-agent setups can attribute writes correctly.

Running vouch as an OpenClaw plugin

Vouch ships an OpenClaw plugin manifest at the repo root — openclaw.plugin.json. Drop the vouch repo into an OpenClaw deployment and the plugin loader picks it up automatically: the MCP server, the four slash commands (/vouch-recall, /vouch-status, /vouch-resolve-issue, /vouch-propose-from-pr), and the CLAUDE.md fenced snippet become available as one bundle.

The manifest declares vouch's trust boundary explicitly — remote callers' filesystem access is confined, every write tool routes through the review gate, every lifecycle op is audit-logged. The configSchema exposes only kb_path, agent, and transport — no API keys, no secrets; vouch is local-first.

# Inside an OpenClaw deployment that vendors plugin repos:
openclaw plugin add vouchdev/vouch
openclaw plugin enable vouch

The plugin's mcpServers.vouch block matches the same .mcp.json shape Claude Code uses — both platforms drive the same vouch serve process, so the kb.* surface is identical regardless of host.

JSONL request/response shape

The JSONL transport reads one envelope per line on stdin, writes one per line on stdout:

{"id":"r1","method":"kb.search","params":{"query":"jwt","limit":5}}
{"id":"r1","ok":true,"result":[{"kind":"claim","id":"auth-uses-jwt","snippet":"…","score":1.2,"backend":"fts5"}]}

Errors come back with ok:false and a structured error.code (method_not_found, missing_param, invalid_request, internal_error).

Every successful kb.* result that is object-shaped carries read-only trust metadata so clients can detect remote confinement:

{
  "id": "r1",
  "ok": true,
  "result": {
    "backend": "fts5",
    "hits": [],
    "_meta": {
      "vouch_trust": {
        "remote": false,
        "caller_kind": "jsonl",
        "auth_subject": null
      }
    }
  }
}

Transport	remote	caller_kind	auth_subject
JSONL stdio	false	jsonl	null
HTTP /rpc	true	jsonl_http	bearer fingerprint when authenticated
MCP stdio	false	mcp_stdio	null
HTTP /mcp	true	mcp_http	bearer fingerprint when authenticated
CLI --json	false	cli	null

The block is server-attached metadata — client mutations are ignored. Array-shaped read results (e.g. kb.list_claims) pass through unchanged; trust rides on dict-shaped responses only (#233).

Portable bundles

vouch export --out kb.tar.gz                     # tar.gz + manifest.json with per-file sha256
vouch export-check kb.tar.gz                     # verify every file against the manifest
vouch import-check kb.tar.gz                     # diff against destination — new / conflict / identical
vouch import-apply kb.tar.gz --on-conflict skip  # apply (default skip; never destructive without overwrite)

proposed/, state.db, and audit.log.jsonl are excluded from bundles — only committable artifacts travel.

Compared to neighbours

	mem0 / Letta	LLM-Wiki tools	vouch
Knowledge lives in	a service	filesystem	your repo
Review of writes	none	none	explicit approve
Evidence required	no	optional	enforced
Per-agent attribution	partial	none	yes (audit log)
Graph (entities + relations)	no	no	yes
FTS5 search	no	varies	yes
Portable bundle	no	no	yes
Transports	SDK / HTTP	none	MCP + JSONL

What ships today

Area	Current support
Knowledge base	.vouch/ folder, YAML claims/entities/relations/evidence/sessions, markdown pages with frontmatter, JSONL audit log, content-addressed sources
CLI	init, discover, capabilities, status, lint, doctor, fsck, pending, show, approve, reject, propose-{claim,page,entity,relation}, source add, source verify, supersede, contradict, archive, confirm, cite, session {start,end}, crystallize, search, context, index, audit, export, export-check, import-check, import-apply, serve
Tool servers	MCP over stdio + JSONL over stdin/stdout, same kb.* surface across both transports, capabilities + knowledge-capability descriptor
Schemas	13 JSON Schemas (Draft 2020-12) generated from pydantic in schemas/, plus hand-maintained bundle.manifest and jsonl-envelope schemas
Write safety	review-gated writes via proposed/, dry_run:true previews, host trust required for approve/reject, atomic exclusive-create storage, path-traversal blocked on source intake and bundle import
Retrieval	retrieval.backend in config.yaml selects the path: auto (default — embedding → FTS5 → substring), embedding, fts5, or substring. Semantic backends (all-mpnet-base-v2, MiniLM-L6, fastembed-BGE) ship behind install extras; auto degrades to FTS5 when they aren't installed. Context packs with citations + quality gate
Lifecycle	supersede, contradict, archive, confirm, cite — direct mutations, all audited
Portability	tar.gz bundles with per-file sha256 manifest.json, export-check, import-check, import-apply with skip/overwrite/fail conflict modes
Audit	append-only audit.log.jsonl, per-event actor (VOUCH_AGENT), object ids, dry-run flag, reversible flag
Adapters	Claude Code wiring documented via .mcp.json + VOUCH_AGENT env; per-runtime adapter templates not yet shipped
Validation	pytest suite (storage, FTS5, audit, source-verify, review-gate, bundle, JSONL), ruff + mypy gates, GitHub CI
Specification	dated snapshots under spec/, JSON Schemas in schemas/, generator script at scripts/gen_schemas.py

Status

Pre-1.0. What's not in this implementation: per-runtime adapter templates, benchmark fixtures, multi-agent sync, scopes beyond a single field on Claim/Source. If a hole matters to you, file an issue.

License

MIT.