trovex

trovex

trovex：コーディングエージェント向けの唯一の正規ドキュメントで、トークンを約60％削減します。

コーディングエージェント（Claude Code、Cursor、Windsurf、Zed、あらゆるMCPクライアント）は、どの .md が最新なのかを確認するため、セッションのたびにリポジトリを読み直し、推測に基づいて回答します。そのコストは、セッションごと、エージェントごと、チームメイトごとに発生します。

trovexはリポジトリ内のMarkdownをインデックス化し、1つのMCPツールを提供します。エージェントが質問すると、trovexは回答となる最新のドキュメントを、鮮度マーカー（正規／古い／重複）付きの path:line ポインターとして返し、ファイル全体ではなく回答に該当するセクションだけを提供します。エージェントは学んだ内容を共通の窓口から書き戻すこともできるため、エージェントもチームメイトも、改めて導き出すのではなく、同じ信頼できる情報源を参照できます。

ドキュメント検索時のトークンを約60％削減します。これは自社リポジトリでタスク成功率を同等にして測定した値です（リポジトリによって異なります）。ローカルで動作し、ベクトルはSQLiteに、埋め込みはONNXで処理します。クラウドもAPIキーも不要です。

インストールするもの

READMEで判断され、ディレクトリの一覧では判断されないため、30秒で確認できる安心材料をご紹介します。

• 自社製のオープンソースです。 開発元のtsukumoが本番環境で構築・運用しています。AGPL-3.0-or-laterです。
• ローカル優先で、何もマシンの外に送信されません。 ベクトルはSQLiteに、埋め込みはONNXで処理します。クラウドもAPIキーも不要で、クエリへの回答にネットワーク接続は必要ありません。
• 書き込み範囲は限定され、シェルは実行しません。 6つのMCPツールがあります。読み取り専用が3つ（trovex、trovex_read、trovex_search）、trovex自身のドキュメントストアだけを変更するものが3つ（trovex_write、trovex_tag、trovex_delete）です。シェルの実行も、ソースファイルへの書き込みもありません。
• 約60％の削減は再現可能です。 自社リポジトリでタスク成功率を同等にして測定しました（中央値69％、リポジトリ別で約41～81％、n=26、LLMによる評価）。trovex search を実行すると、ご自身のリポジトリでの削減量が表示されます。測定方法の詳細はこちらをご覧ください。

クイックスタート

trovexはPyPIで公開ベータ版を提供しています。クローンは不要です。uv tool install を実行すると、trovex がPATHに追加されます。

uv tool install trovex   # one-time, no clone
trovex setup             # wire into Claude Code (skill + hooks + MCP); idempotent

trovex index /path/to/your/repo        # index your markdown (~1 min)
trovex search "how do we roll back a deploy?"   # ask, prints the tokens it saved
trovex serve                           # wire into your agent: MCP at /mcp, dashboard at /savings

uv をまだお使いでない場合は、次の1行でインストールできます。curl -LsSf https://astral.sh/uv/install.sh | sh（または brew install uv）。

まず search を実行すると、trovexの効果をすぐに確認できます。正規ドキュメントを1つ返し、上位候補をいくつか読む場合と比べて、何トークン節約できたかを表示します。MCP経由でエージェントにtrovexを接続すると、同じ数値が節約ダッシュボード（http://localhost:8765/savings）に蓄積されます。

まだ何もインストールしたくない場合は、uvx trovex search "..." を実行すると、使い捨ての環境で単一コマンドを実行できます。インストールは不要です。

エージェントに接続する

trovexはMCPサーバーです。trovex serve の実行後、クライアントを http://localhost:8765/mcp に接続してください。クライアントごとの設定（Claude Code、Cursor、Windsurf、Cline、Zed、Roo）はこちらをご覧ください。

Claude Codeならコマンド1つ。 trovex setup を実行すると、Claude CodeのスキルとActive-Memoryのフックをインストールし、MCPサーバーを一度に登録します（冪等で、安全に再実行できます）。

trovex setup

スキルとフックを読み込ませるため、実行後にClaude Codeを再起動してください。MCPサーバーだけを手動で接続する場合は、trovex setup --no-skill --no-hooks を実行するか、次のように設定してください。

claude mcp add --transport http trovex http://localhost:8765/mcp

Cursorの場合は、（trovex serve の実行後に）ワンクリックで接続できます。 Cursorにtrovexを追加

仕組み

trovex は、リポジトリ内の Markdown を検索可能な単一の正規ストアに変換し、質問に答える現在有効なドキュメントを 1 つだけ各エージェントに提供します。順位付けが必要な候補を大量に返すことはありません。

flowchart LR
  A["Your repo<br/>.md files"] -->|trovex index| B["Chunk + parse"]
  B --> C["Embed locally<br/>ONNX · bge-small"]
  C --> D[("sqlite-vec<br/>vector store")]
  Q["Agent question"] -->|MCP| E["Route + rerank"]
  D --> E
  E --> F["One canonical doc<br/>path:line + freshness"]
  F --> G["Agent answers from<br/>the current doc"]

この仕組みを支える考え方は 4 つあります。

• 完全さではなく、正規性。 質問ごとに、それに答えるドキュメントは 1 つであるべきです。trovex は各ドキュメントを canonical／stale／duplicate と分類するため、今も正しいドキュメントを優先できます。古いドキュメントも現在のドキュメントと同じようにクエリに類似するため、類似度だけでは両者を見分けられません。
• 振り分けてから、該当セクションを提供。 クエリは、該当するドキュメント 1 つを示す path:line ポインターと、回答となるセクションだけを返します。ファイル全体でも、エージェント自身が読んで順位付けするトップ k 件の候補でもありません。この隔たりを埋めることで、トークンを節約できます。
• デフォルトでローカル。 インデックス作成、埋め込み（ONNX、bge-small-en-v1.5）、ベクトル検索（sqlite-vec）はすべてお使いのマシンで実行されます。クラウドも API キーも不要で、クエリへの回答にネットワーク呼び出しはありません。
• 共有の書き戻し経路。 エージェントは学習した内容を一度だけ（trovex_write）trovex 独自のストアに保存し、他のすべてのエージェントやチームメイトは、同じ内容を再導出する代わりに読み戻します（trovex_read）。

すべてのエージェントが同じ信頼できる情報源を参照し続ける、読み取りと書き込みのループ：

sequenceDiagram
  participant A as Agent
  participant T as trovex (MCP)
  participant S as Store (sqlite-vec)
  A->>T: trovex("how do we roll back a deploy?")
  T->>S: route + rerank candidates
  S-->>T: one canonical doc
  T-->>A: path:line + section + freshness
  A->>T: trovex_write("rollback runbook: …")
  T->>S: upsert (dedupes near-copies)
  Note over S: the next agent reads it back via trovex_read

ご自身のリポジトリで実証する

約 60％という数値は、鵜呑みにするものではなく、実行して確かめられる主張です。コマンドは 2 つです。

trovex bench /path/to/your/repo          # token-accounting model, instant, no LLM, no key
trovex bench /path/to/your/repo --eval   # full answer+judge A/B at equal task-success (needs OPENAI_API_KEY)

bench は最良のケースではなく、分布（中央値とばらつき）を報告します。つまり、振り分けられた正規ドキュメントを 1 つ読むコストと、支援なしのエージェントが読むトップ k 件の候補のコストを比較します。--eval ではさらに、両方の方式で回答し、LLM が判定します。両方が正しく回答した場合に限り、節約として計上されます。詳しい方法と実測値は trovex.dev/measure をご覧ください。

md-guard フック経由ですでに trovex を実行していますか？ trovex measure は、フックのベースラインログを使って、実際の .md のトークン消費量を導入前後で比較します。

開発者向けメモ：主張を検証する評価ハーネス

上記の bench --eval は、クエリごとに「trovex が引き続き正しい回答を得られるか」を、2 つの方式で比較します。trovex eval-harness（src/trovex/eval_harness.py）は、この考え方をリリース判定向けにしたものです。バージョン管理された cases.jsonl セット、検索品質（hit@k/MRR/recall@k、無料）、重み付きルーブリックスコア（正確性35/自律性25/実用性20/安全性10/簡潔さ10、ブラインド評価 — 判定者には、どの設定が回答を生成したかがわかりません）、$ の予算上限、そして再開可能性を備えています。

make eval                                                          # retrieval-only, no key, CI-safe
uv run trovex eval-harness . --gate --budget-usd 1.0 --resume run.jsonl   # full rubric pass, needs OPENAI_API_KEY

--retrieval-only（make eval が実行するもの）は LLM を一切呼び出さず、benchmarks/token-savings/eval-baseline.json に対する hit@1 のみで判定します。完全なルーブリック評価にはキーが必要なため、手動または CI シークレットによる実行となり、make test には含まれません。付属の cases.jsonl（47 件）と eval-baseline.json のしきい値は benchmarks/token-savings/ でバージョン管理されています。ベースラインは、実際に一度実行し、その数値を意図的に記入するまではプレースホルダーです（実行によってファイルが自動上書きされることはありません）。

MCP ツール

• trovex(q)：質問を適切なディスク上の .md にルーティングし、優先順位付けするためのファイルの山ではなく、鮮度マーカー付きの path:line ポインターを返します。
• trovex_write(content, kind?, doc_id?, tags?, section?) / trovex_read(query | doc_id, section?)： trovex の内部に保存されるドキュメントです。エージェントが記録（インシデント、決定事項、「実際にうまくいったこと」）を一度保存すると、ほかのすべてのエージェントや別の開発者は、内容を再導出する代わりに、記録を内容として読み返せます（必要に応じて特定のセクションのみ）。trovex_write に section= を渡すと、ドキュメント全体を置き換えるのではなく、指定した見出しのセクションだけをその場で更新できます。
• trovex_search(query, k?, tags?)：タグフィルターを使ってストア全体からパッセージ単位で検索します。正規のドキュメントを1つ返すのではなく、一致度の高いチャンクを取得したい場合に使用します。
• trovex_tag(...) / trovex_delete(...)：保存したドキュメントにタグを付けるか、ソフト削除します。削除は復元可能なアーカイブであり、完全な消去ではありません。どちらも trovex ストアだけに作用し、ファイルには触れません。

人間は、レンダリングされたリーダーで trovex が所有するドキュメントを /doc/{id} から読めます。エージェントによる .md の書き込みをディスクではなく trovex_write 経由にするには、PreToolUse フック deploy/hooks/trovex-md-guard.sh をインストールし、.trovexignore で例外を設定します。

比較

• CLAUDE.md / AGENTS.md との比較：古くなり、質問を適切なドキュメントにルーティングできない静的ファイル1つに対し、正規の状態に保たれ、クエリごとに提供される複数のドキュメントです。詳細。
• repomix / files-to-prompt との比較：リポジトリ全体をコンテキストに詰め込むのではなく、答えを1つ取得します。詳細。
• ベクトル DB / 単純な RAG との比較：鮮度のシグナルがない候補チャンクのランキング結果の山に対し、明示的なマーカー付きの最新ドキュメント1つです。詳細。

約60％という数値の根拠については、 ベンチマークの方法論で詳しく説明しています。

技術スタック

• Python 3.11 + uv
• FastAPI（MCP HTTP + サーバー側でレンダリングする HTML UI）
• fastembed（ローカル埋め込み。内部では ONNX を使用）
• sqlite-vec（SQLite 内のベクトル検索）
• Jinja2 + HTMX（ビルド手順不要の UI）

埋め込み：デフォルトではローカル、自分のモデルも利用可能

trovex は標準で BAAI/bge-small-en-v1.5（ONNX、384次元）を使ってローカルで埋め込みを行います。 API キーは不要で、データがマシンの外に出ることもありません。任意の埋め込みモデルに切り替えられます。

• 別のローカルモデル： TROVEX_EMBED_MODEL=<fastembed model> を設定し、組み込みモデルではない場合は TROVEX_EMBED_DIM=<its dimension> も設定します。
• OpenAI 互換のエンドポイント（Ollama、LM Studio、vLLM などのローカルサーバーを含む）：TROVEX_EMBED_PROVIDER=openai、TROVEX_EMBED_MODEL=<model>、 TROVEX_OPENAI_BASE_URL=http://localhost:11434/v1、TROVEX_EMBED_DIM=<dim> を設定します。 localhost を指定すれば完全にローカルで利用できます。より高精度な検索のために OpenAI（text-embedding-3-large）を指定することもできますが、その場合は各チャンクが OpenAI の API に送信されます。

モデルを変更するとベクトルの次元が変わるため、切り替えには再インデックスが必要です。

パブリックベータ

trovex はパブリックベータ版です。インストールしてリポジトリで実行し、トークンを節約できたら、 GitHub でスターを付けていただけると、ほかの開発者にも見つけてもらいやすくなります。Issue と PR も歓迎します。

質問がある方や、エージェントを運用しているほかの方と情報交換したい方は、Discord のコミュニティにご参加ください： tsukumo.ch/discord。

セキュリティ

trovex はローカルファーストかつシングルテナントです。お使いのマシン上で動作し、ドキュメントをインデックス化して、エージェントに提供します。変更操作は X-TROVEX-Write-Token ヘッダーで制御され、デフォルトではフェイルクローズです。トークンが設定されていない場合、trovex は初回起動時にインスタンスごとのトークンを自動生成して <data_dir>/.write_token（chmod 600）に保存するため、ネットワークに公開されたインスタンスでも匿名での書き込みは受け付けません。マシン間でトークンを共有するには TROVEX_WRITE_TOKEN を設定してください。または、信頼できる localhost で意図的に書き込みを許可するには TROVEX_ALLOW_UNAUTH_WRITES=1 を設定してください。信頼モデル、セキュリティ強化の内容、脆弱性の報告方法については、SECURITY.md に記載されています。

ライセンス

trovex はGNU AGPL-3.0-or-laterのライセンスで提供されています（LICENSE を参照）。自由にセルフホストして改変できます。改変版をネットワークサービスとして運用する場合、AGPL により変更内容を共有する必要があります。

スイートの一部

trovex は、tsukumo が開発する、本番環境で AI コーディングエージェントを運用するための 4 つのオープンソース製品から成るスイートのコンテキストレイヤーです。

• trovex、コンテキスト：リポジトリを何度も読み直す代わりに、クエリごとにエージェントへ唯一の正規ドキュメントを提供します（検索あたりのトークン数を約 60% 削減。測定方法は trovex.dev/measure を参照）。
• wrai.th、オーケストレーション：エージェント群を実行し、連携させます。
• yoru、オブザーバビリティ：各エージェントが実際に行ったことのセッション記録を提供します。
• dokan、決定論的な実行：エージェントが確立した再現可能な作業を、モデルを介さずにクリーンなコンテナ内でスクリプトとして実行します。

チームでの導入をお考えですか？

trovex は無料でご利用いただけます。チームでコーディングエージェントを大規模に導入するにあたって、適切な導入の実践的なサポートをご希望の場合や、AGPL のコピーレフト義務なしで改変版の trovex を非公開で組み込み、ホスティングしたい場合は、コンサルティングをご利用ください。 trovex の開発チームである tsukumo までお問い合わせください。