Hive Vault

hive-vault

AI コーディングアシスタントはセッション間で何も覚えていません。Hive がそれを解決します。

Hive は、AI アシスタントを Obsidian の保管庫に接続する MCP サーバーです。最初にすべてを読み込むのではなく、必要なものだけを必要に応じて検索します。

指標	Hive なし	Hive あり
セッションごとに読み込むコンテキスト	約800行（静的）	約50行（必要に応じて）
コンテキストのトークンコスト	毎セッション100%	5回のプロジェクトコンテキスト検索で0.6%（実際の保管庫、493Kトークン）
セッション間で保持される知識	0%	100%（保管庫内）

測定値はトークンコストの行のみです（実際の493Kトークンの保管庫で5回のプロジェクトコンテキスト検索を実施。方法と数値はベンチマークを参照）。行数と保持率の行は、2つの構成の動作を説明したものであり、測定値ではありません。

クイックスタート

Hive は保管庫がなくても動作します。VAULT_PATH が設定されるまでは、保管庫関連ツールはわかりやすいエラーを返すため、先にインストールして後から設定できます。

# Minimal — uses default vault path ~/Projects/knowledge
claude mcp add -s user hive -- uvx --upgrade hive-vault

# With a custom vault path
claude mcp add -s user hive -e VAULT_PATH=$HOME/path/to/vault -- uvx --upgrade hive-vault

# Gemini CLI
gemini mcp add -s user -e VAULT_PATH=$HOME/path/to/vault hive-vault uvx -- --upgrade hive-vault

デフォルトの保管庫パス：~/Projects/knowledge。上記のように VAULT_PATH（または HIVE_VAULT_PATH）で変更できます。

Codex CLI、GitHub Copilot、Cursor、Windsurf、その他のクライアントについては、はじめにを参照してください。

次に、アシスタントに「vault_list を使って保管庫を確認して」と尋ねてください。

要件

Hive は依存関係に応じて段階的に機能を拡張し、推奨またはオプションの依存関係がなくても基本機能は損なわれません。

• 必須

  • Python 3.12+（3.13でも動作します）。
  • Markdown ファイルのディレクトリ。00_meta / 10_projects / 50_work / 80_agents を使用する保管庫の構成は任意です。これらがなくても保管庫ツールは動作しますが、スコープの振り分けはフラットになります。

• 推奨

  • 保管庫内で初期化された git。ない場合も vault_write / vault_patch はディスクに書き込みますが、書き込みごとのコミットは省略され（vault_commit は作業ツリーを未追跡として報告します）。
  • 保管庫を手動で作成するための Obsidian デスクトップアプリ。
  • 自動コミット間隔を 5〜10分 に設定した obsidian-git プラグイン。vault_write(commit=False) / vault_patch(commit=False) と組み合わせると、git の処理を同期ツールの実行経路から切り離せます。詳しくは、以下の 推奨設定 を参照してください。

• オプション

  • HIVE_WORKER_BASE_URL、HIVE_WORKER_API_KEY、HIVE_WORKER_MODEL で設定する、delegate_task / capture_lesson のワーカーとしての任意の OpenAI 互換 /v1 エンドポイント。
  • 保管庫の履歴をディスク障害後も保持するための バックアップ用 git リモート（例：非公開の GitHub リポジトリ）。

推奨設定

ADR-006（コミットポリシー）に従い、書き込みの多いワークフローでは次の組み合わせを推奨します。

1. Vault に obsidian-git プラグインをインストールして有効にします。
2. 自動コミット間隔を5分または10分に設定します。
3. すべての一括操作で vault_write(..., commit=False) と vault_patch(..., commit=False) を呼び出します。
4. 必要に応じて、セッションの最後に vault_commit(message="...") を呼び出し、obsidian-git の実行間隔を待たずにチェックポイントを作成します。

vault_health は、Vault 内で obsidian-git を検出すると ## external_committer ブロックを報告します。commit=False の耐久性に関する契約は明確です。ファイルはどちらの場合もディスクに保存され、延期されるのは コミット のみです。次のフラッシュより前にクラッシュした場合、失われるのはコミットであり、コンテンツではありません。

ツール呼び出しが処理中にキャンセルされた場合（ワーカーの遅延、クライアントのタイムアウトなど）、キャンセル確認が通信経路に届く前に、サーバーがすでにディスクを変更している可能性があります。vault_health は ## ghost_responses カウンターを表示し、イベントごとに mcp.ghost_response.suppressed_after_cancel_ack WARNING を出力します。ErrorData の確認応答はロールバックを意味しないため、再試行するのではなく、vault_query で状態を確認してください（ADR-007）。

デーモンモード（任意）

デフォルトの uvx hive-vault は、セッションごとに新しいサーバーを実行します。一方、デーモンモードでは、Vault を管理する長時間稼働の hive serve を1つ実行し、各 stdio 専用セッションは hive client を介して接続します。アダプターは Hive サーバーや FastMCP をインポートせずに起動し、JSON-RPC をデーモンの固定ループバックエンドポイントに中継します。デーモンまたは認証情報を利用できない場合は、競合するインプロセスの管理者を起動せず、明示的に失敗します。

デフォルトのエンドポイントは、ユーザーごとに決定的に割り当てられる 49152..65535 のポートです。そのため、通常のデーモン再起動でクライアント設定が無効になることはありません。導出されたポートが別のローカルサービスと競合する場合は、デーモンとすべてのクライアントの環境で HIVE_DAEMON_PORT を指定して上書きしてください。hive serve --port で変更されるのはデーモンのバインドポートのみです。hive client や hive delegate の設定は変更されません。Hive は別のポートへ暗黙に移行せず、フェイルクローズします。所有者専用のベアラートークンは、通常の再起動後もデーモンの状態ディレクトリに保持されます。daemon.port は診断用の移行メタデータであり、クライアントの検出状態ではありません。ADR-022を参照してください。

セキュリティ上の制限： #456が解決されるまでは、信頼できないマルチユーザーホストにデーモンモードをデプロイしないでください。エンドポイントは、Hive のクライアントがピン留めするユーザーごとの証明書を使って TLS を提供するため、固定ポートでなりすます相手がいても、ベアラーを送信する前にハンドシェイクに失敗します。この制限は、ユーザー間の確認を含む Linux と Windows の証拠が記録されるまで継続します。

uv tool install --upgrade hive-vault   # >= 1.32.0
hive service install                   # supervise hive serve (systemd --user / Task Scheduler)
hive service status                    # exit 0 only if the listener proves the daemon's certificate

MCP ホストから hive client を実行します。デーモンの証明書を検証できるホストは、https://127.0.0.1:<derived-or-overridden-port>/mcp に直接接続できます（Node ベースのホストの場合は、状態ディレクトリ内の daemon.crt を指す NODE_EXTRA_CA_CERTS を設定します）。検証を無効にしないでください。また、http:// は使用できなくなったことに注意してください。トークンをログやシェル履歴に出力したり、コピーしたりしないでください。

新しいリリースをインストールするには、プラットフォーム固有のコマンドを使用します。

# Linux / macOS
uv tool upgrade hive-vault

# Windows (the version is optional; omitted selects the latest PyPI release)
hive self-upgrade [version]

Windows では、self-upgrade は実行中のファイルの隣にリリースをビルドし、管理対象のランタイムをアトミックに切り替えることで、使用中のファイルとの競合を回避します。最初の管理対象アップグレード後は、新しいターミナルを開いて PATH の変更を反映してください。監視下で実行されている場合、デーモンはインストール済みの新しいバージョンを検出して 75 で終了し、スーパーバイザーが再起動して新しいコードを実行します。デーモンモードガイドと有効化手順書を参照してください。

ツール

ツール	機能
vault_query	プロジェクトのコンテキスト、タスク、ロードマップ、教訓、またはパスで指定した任意のファイルを読み込みます
vault_search	メタデータフィルター、正規表現、ランキングされた検索結果、最近の変更、教訓の使用状況ランキング（rank_by）を使った全文検索
vault_list	glob フィルタリングでプロジェクトとファイルを参照します
vault_ask	ソースの引用を伴うセマンティックな質疑応答（任意）。埋め込みバックエンドが設定されるまで無効です（[semantic] extra）
vault_health	サーバーの識別情報（バージョン、Vault のパス、バックエンド）、健全性メトリクス、ドリフト検出、使用統計、オプトインのランタイムブロック
vault_write	Vault ファイルを作成、追記、置換します。commit=False を指定すると、まとめてコミットするため Git コミットを保留します
vault_patch	対象を絞った検索と置換を行います。commit=False を指定すると、まとめてコミットするため Git コミットを保留します
vault_commit	保留中の commit=False による書き込みを、1つの Git コミットにまとめます
vault_delete	ファイルを1つ削除します。Git 履歴から復元できるよう、同期的にコミットします
capture_lesson	教訓をその場で記録する、テキストから一括抽出する、キーワード（find=）で既存の教訓を検索する
session_briefing	タスク、教訓、Git ログ、健全性情報を1回の呼び出しで取得します
delegate_task	タスクをより低コストのモデルに割り当てるか、Vault ファイルを要約します
worker_status	予算、接続状況、利用可能なモデル

ガイド付きワークフロー用のリソースが5つ、プロンプトが4つあります。

教訓の強化

vault_query、vault_search、または capture_lesson(find=…) で教訓を読み込むたびに、カウンターが増加し、その教訓の信頼度は漸近的に1.0に近づきます。検証済みの教訓は、単発で記録された教訓よりも時間の経過とともに上位に表示されます。

# Surface the top-ranked lessons matching a keyword
capture_lesson(project="hive", find="multi-process")

# Search lessons ranked by usage signal (not BM25)
vault_search(query="timeout", rank_by="reinforcements")    # most-reinforced first
vault_search(query="timeout", rank_by="confidence")        # highest decayed confidence
vault_search(query="timeout", rank_by="hybrid")            # α=0.7 BM25 + 0.3 confidence

保存先：HIVE_LESSON_DB_PATH の SQLite サイドテーブル（デフォルトは ~/.local/share/hive/lesson_reinforcement.db）。WAL モードと busy_timeout により、複数プロセスから安全に利用できます。

アーキテクチャ

MCP Host (Claude Code, Gemini CLI, Codex CLI, Cursor, ...)
    └── hive-vault (MCP server, stdio)
            ├── Vault Tools (9) ── Obsidian vault (Markdown + YAML frontmatter)
            ├── Session Tools (1) ── Adaptive context assembly
            └── Worker Tools (3) ── one OpenAI-compatible endpoint, no internal fallback

ドキュメント

詳細なドキュメントは mlorentedev.github.io/hive にあります。

• はじめに — すべての MCP クライアントへのインストール方法
• 設定 — 19個すべての環境変数
• Vault の構成 — Vault の整理方法
• ユースケース — 実際のワークフロー
• アーキテクチャ — モジュールマップと設計上の決定事項
• トラブルシューティング — よくある問題と解決方法

プロジェクトに紐づくナレッジ（ドキュメントをコードとして管理）は docs/ にあります。

• docs/adr/ — アーキテクチャ決定記録
• docs/runbooks/ — 運用手順
• docs/troubleshooting/ — 既知の問題と根本原因の分析記録
• docs/lessons.md — 蓄積された注意点と事後分析

コントリビューション

セットアップと PR のワークフローについては、CONTRIBUTING.md をご覧ください。

git clone https://github.com/mlorentedev/hive.git && cd hive
make install   # create venv + install deps
make check     # lint + typecheck + test (478 tests, 90% coverage)

ライセンス

MIT