Vouch

vouch

LLM エージェント向けの、Git ネイティブでレビュー承認を必須とするナレッジベースです。MCP サーバー＋JSONL ツールサーバー＋CLI。

エージェントがセッションのたびに記憶喪失から始めるべきではありません。しかし、好き勝手に何を書いてもよいわけでもありません。

vouch は、明示的なレビューゲートを設けて、LLM エージェントに永続的なメモリを提供します。セッションの内容は記録され、エージェントは書き込みを提案しますが、承認されるまでは何も永続的な知識になりません。承認済みの成果物は .vouch/ 以下に YAML の主張や Markdown ページといったプレーンなファイルとして保存されます。そのため、ナレッジベースはリポジトリ内に存在し、コードと同様にレビューでき、差分も明瞭で、git clone で一緒に取得できます。

目指すのは、Andrej Karpathy の llm-wiki アイデアファイルが描くものです。質問のたびにドキュメントを再発見する検索エンジンとして LLM を使うのではなく、知識を編纂し、相互参照し、進化し続ける Wiki を維持する疲れ知らずの知識エンジニアとして活用し、人間は知識を整理して考えるのです。vouch は、書き込み経路の信頼性を確保したそのアイデアです。vouch compile では LLM がトピックページの草案を作成しますが、すべてのページは承認済みの主張を引用し、すべての [claim: …] 引用は草案の提出前に機械的に検証され、草案はほかのあらゆる書き込みと同じレビューゲートを通ります。LLM が編纂し、人間が承認し、Wiki は知識を蓄積していきます。

「これは 1 つのプロンプトでできます」

多くの場合、そのとおりです。そして、正直に伝える価値があります。エージェントに情報を記憶させたいなら、CLAUDE.md に段落を書いたり、メモリファイルを使ったり、ホスト組み込みの自動メモリ機能を使ったりすれば、大部分は実現でき、費用もかからず、インストールも不要です。まずはそちらを使ってください。想起は難しい問題ではありません。

難しいのは書き込み経路への信頼であり、記憶とは別の問題です。書き手が 1 人の記憶には、信頼モデルは必要ありません。作者はあなた 1 人で、まずい記述があっても肩をすくめる程度で済みます。書き込み元が複数の作者、たとえば複数のエージェント、チームメイト、あるいは文脈を忘れた未来の自分になると、問いは「何を話したか？」ではなく、「誰が、どの証拠に基づいてこれが真実だと判断したのか、後から監査できるのか？」に変わります。プロンプトがどれほど優れていても、この問いには答えられません。

これが vouch のすべてです。

	1 つのプロンプト／メモリファイル	vouch
書き込める人	エージェントが保存すると決めたもの	エージェントは提案し、人間が承認します。それ以外は何も反映されません
記述を信じる理由	なんとなく	すべての主張にコンテンツハッシュ付きの出典が記載されます。出典のない記述は検証エラーになります
誤りがあった場合	編集して、うまくいくことを願います	古いバージョンを履歴に残したまま、置き換え／矛盾の記録／アーカイブを行います
変更した人	ファイルの更新日時	追記専用の監査ログに、誰が、いつ、何を引用して提案し、承認したかを記録します
書き手が n ≥ 2 人の場合	最後の書き込みが黙って優先されます	1 つのゲート、1 つのレビュー済み履歴を git clone で共有します
読むもの	増え続けるメモの山	検証済みの引用を含む、トピックごとにまとめられたページ。ログではなく、ウィキです

同じ説明を図で示すと、書き手が 1 人なら両者は同じもので、2 人目から差が生まれ、その差は広がる一方です。

つまり、正直な説明はこうです。vouch は記憶を保存するためのより良い場所ではなく、記憶の前に置くレビューゲートであり、その先にあるウィキです。 1 人で使っていて満足しているなら、1 つのプロンプトで本当に十分です。vouch のセッション記録は、ホストがすでに記憶している内容を置き換えるのではなく、それと並行して受動的に動作します。しかし、エージェントの集団やチームが共有ナレッジに書き込むようになると、メモの山には編集者が必要です。そして、プロンプトだけで編集者を用意することはできません。詳しい説明はこちらです：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

KB が事前に用意されており、完全な Web アプリコンソールをすぐに利用できます。セットアップは不要です。LLM 機能を有効にするには、-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. KB をセットアップし、Claude Code と連携する（リポジトリごとに一度、コマンド 1 つで実行します）：

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

install-mcp は .vouch/ が見つからない場合に KB を初期化し（スキップするには --no-init を指定します。KB のみをセットアップする場合は、引き続き 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）。スキップして .mcp.json を自分で承認するには --no-approve を指定します。

表示される内容。 すべてのプロンプトは、まず KB と照合されます。関連する情報が vouch にある場合、引用された項目を根拠に、回答は 「From vouch memory:」 で始まります。ない場合は 「Nothing in vouch on this.」 で始まります。想起は毎回のターンで確認でき、決して無言ではありません。（初期状態の KB にはほとんど何もありません。記録が蓄積されるよう、1、2 セッション作業してから、もう一度プロジェクトについて質問してください。）

すべてのプロジェクトに一度のインストールで対応したい場合は？ vouch install-mcp claude-code --global を実行すると、マシン全体に一度だけ vouch を設定します。ユーザーレベルのフックとコマンドを ~/.claude/ に、ユーザースコープの MCP サーバーを ~/.claude.json に設定します。以後、どのフォルダーの Claude セッションでも、そのフォルダー固有の .vouch/ に記録と想起を行います。データはプロジェクトごとに保持されます。vouch を使いたい各プロジェクトで vouch init を一度実行してください。デフォルトでは、KB のないフォルダーではどこにも記録されません。そのセッションでは「この場所で永続的なメモリを有効にするには vouch init を実行してください」という1行のメモが表示され、kb_* ツールも同じことを伝えます。既存のプロジェクトごとのインストールと併用しても安全です。重複したフックは統合され、記録はイベント ID によって重複排除されます。

個人用の一括受け皿 KB も任意で利用できます。 グローバルインストールでは1つ質問されます（または --personal-fallback を指定します。後から設定する場合は vouch hub init-personal --fallback）。オプトインすると、プロジェクト KB のないフォルダーで、どこにも記録しない代わりに ~/.local/share/vouch/personal の個人用 KB に記録します。記録された各ソースには元のフォルダーが付記され、セッションバナーには情報の保存先が明示されます。**これは KB のないすべてのフォルダーで共有される1つのストアです。**そのため、いずれかのフォルダーで想起すると個人用 KB 全体が読み込まれ、あるフォルダーでの作業中に記録した情報が別のフォルダーで表示されることがあります（挿入されるブロックにもその旨が記載されます）。独自の .vouch/ を持つプロジェクトには影響しません。そのようなフォルダーが後から実際のプロジェクトになった場合は、vouch init と vouch adopt を実行すると、その記録を新しいプロジェクト KB のレビューゲートを通じて移行できます。ソースはバイト単位で同一のままコピーされ、すべての主張は再提案され、バイトオフセットのレシートが再検証されます。また、永続性はプロジェクトのレビュープロファイルによって決まります。移行によってレビューを回避することはありません。厳密にオプトイン方式です。オプトインしなければ、何も変わりません。

2. compile の接続先として LLM を指定します — モデルが必要なのはこの手順だけです。.vouch/config.yaml で設定します。

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

3. セッションで作業します — 自動的に記録されます。 Claude Code を通常どおり使用してください。各ツール呼び出しは Git で無視されるスクラッチバッファに取り込まれ、セッション終了時にそのバッファが集約されます。LLM を使わず、機械的に、保留中のセッション要約ページ1件にまとめられます。自動承認はされません。次のセッションでは、次のように表示されます。

🔔 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 に設定します。

レビューや提案のためのブラウザー UI が必要ですか？ 動画に登場するのは、チャット、レビューキュー、主張、統計を備えた vouch webapp です。選択肢は次のとおりです。

• セットアップ不要：上記の Docker デモ
• クローン不要の pip：pipx install 'vouch-kb[web]' を実行してから vouch console を実行します（Python のみ。Docker と node は不要です）。http://localhost:5173 を開きます
• ローカル開発：リポジトリをクローンして、make console を実行します
• より軽量な組み込みキュー：vouch review-ui（[web] extra にも含まれています）
• CLI のみ：vouch pending、vouch show <id>、vouch approve <id>、vouch reject <id> --reason "…"

いずれかを既存の KB に接続するには、プロジェクト内でバックエンドを起動します（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 に KB を確認するよう頼みます。知っておくべきことが一つあります。vouch review に残っているページは、これらすべてから見えません。承認ゲートは検索にも適用されるため、コンパイル済みのページがセッションに反映されるのは、承認されてからです。

7. コードと一緒に知識をコミットします。

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

保留中の下書き（proposed/）と派生検索インデックス（state.db）は git の追跡対象から除外されています。履歴に残るのは、レビューに合格したものだけです。

その根底にあるルール

• 書き込みには承認が必要です。 エージェントは kb.* MCP ツール（または vouch serve --transport jsonl）を使って 提案 を提出します。永続的な成果物にする唯一の方法は承認です。オプトアウトしない限り、承認者は提案者とは別の人でなければなりません。
• 主張には出典の引用が必要です。 根拠のない主張は警告ではなく、検証エラーになります。出典はコンテンツハッシュで管理され、同じ証拠を二度登録すると重複が解消されます。
• 履歴は追記専用です。 すべての変更は、誰が提案し、誰が承認し、何を引用し、いつ行ったかを記録した監査ログにコミットされます。

さらに詳しく

• docs/example-session.md — 実際の出力を使った、記録→承認→想起の一連の手順
• docs/getting-started.md — エージェント側のフロー
• 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 によるインキュベーションと支援を受けました。ナレッジベースをコードとして扱うパターンと、レビューを経て永続化するモデルは、信頼できる AI エージェントと、協調的な開発ワークフローにおける長期記憶についての議論から生まれました。

ライセンス

MIT。