rag-rat

rag-rat

リポジトリが自身について把握していること。 rag-rat は、コーディングエージェント向けのローカルなリポジトリインテリジェンスインデックス兼 MCP サーバーです。ソースファイルは読み取り専用のまま保持し、自身の SQLite データベースにのみ書き込みを行い、すべての結果に根拠を添えて回答します。対象となるのは、現在のソース、コードグラフ、git/GitHub の履歴、そしてセッションやエージェントをまたいで保持される、ソースに紐付いた永続的なリポジトリメモリです。

ライブ版 VS Code Lens デモをご覧ください。インストールは不要です。 コードの横にクローンの分類、リポジトリメモリ、イシューや意思決定のコンテキストを表示します。Ctrl+Alt+R を押すとクローンのオーバーレイが表示されます。

どのコーディングハーネスにも、すでに grep とファイル読み取り機能は備わっています。rag-rat は、それらにはない層、つまりソースに紐付いた 理由 を加えます。エージェントがこれから変更しようとしているコードを、その呼び出し元、呼び出し先、テスト、git/GitHub の履歴、過去の意思決定、不変条件、リスク、重複コードのシグナルと結び付けます。そして、すべての結果に信頼度と網羅率をラベル付けするため、エージェントは結果を鵜呑みにせず、自ら判断できます。

sequenceDiagram
    participant Repo as Repository
    participant Engine as rag-rat engine
    participant Agent as Coding agent

    Repo->>Engine: Source · git/GitHub · repo memories
    Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile
    Agent->>Engine: where / why / who-calls / impact?
    Engine-->>Agent: source + call paths + papertrail + memories (with provenance)
    Agent->>Engine: record a finding
    Engine->>Repo: persist a source-anchored repo memory

理由

• 推測ではなく、根拠を示します。 すべての結果に信頼度ラベル、網羅率に関する警告、生の証拠が付くため、不完全なインデックスや曖昧なエッジも、そのとおりに把握できます。
• リポジトリメモリ。 型付きの、ソースに紐付いたメモ（Invariant、Decision、Risk など）で、リファクタリング後も保持され、今後のクエリで自動的に提示されます。これは grep では得られないシグナルです。アシスタントのメモリ ではありません。このリポジトリに関する、バージョン管理されたローカルな事実であり、ソースに紐付いているため、将来のあらゆるエージェントが証拠とともに取得できます。
• 本格的なコードグラフ。 Rust、TypeScript/TSX、Kotlin、C/C++、Python、Swift、Go に対応する tree-sitter の呼び出し元、呼び出し先、インポート情報を提供します。設定済みのツールチェーンでは、オプションのコンパイラー品質の SCIP オラクルを利用でき、エッジの信頼度を Compiler に引き上げ、重要なシンボルを順位付けします。
• 証拠としての履歴。 Git の履歴、必要に応じて実行するチャンク単位の blame、キャッシュされた GitHub のイシュー／PR／レビューの根拠を、すべてクエリできます。
• イシューの要約。 クローズされたすべてのイシューとマージ済み PR を、修正差分とあわせて型付きの意思決定レコードに要約します。根本原因、採用されたアプローチ（却下された代替案も含む）、結果をスレッドと照合して検証し、関連シンボルに紐付いた補足コンテキストとして提示します。
• 既存の grep に組み込めます。 grep 拡張フックにより、直前に検索した内容に関連するメモリとシンボルを挿入します。
• コードを書きながらクローンを検出します。 Write/Edit/MultiEdit の PreToolUse フックが、作成中の関数のフィンガープリントを作成し、リポジトリ内に完全一致または類似するコードがある場合に警告するため、エージェントは再実装ではなく既存コードを再利用できます。読み取り専用で、インデックスの準備ができていない場合は何もせず、書き込みを妨げることはありません。

クイックスタート

Claude Code、Codex、opencode では、プラグインをインストールしてください。MCP サーバーを登録し、フックを追加して、初回実行時にバージョンが一致する rag-rat バイナリを取得します。MCP サーバーの起動時には、これが ~/.local/bin/rag-rat として公開されます。詳しくはCLI の実行をご覧ください（Claude Code と Codex のバンドルにはスキルも追加されます。opencode では npx @rag-rat/skills で追加してください）。

# Claude Code
claude plugin marketplace add cq27-dev/rag-rat
claude plugin install rag-rat@rag-rat

# Codex
codex plugin marketplace add cq27-dev/rag-rat
codex plugin add rag-rat@rag-rat

# opencode (add -g for a global install)
opencode plugin @rag-rat/plugin-opencode

インストール後、プラグインを承認してツールとフックを実行できるようにしてください（opencode は承認手順なしでプラグインを読み込むため、操作は不要です）。

• Claude Code では、rag-rat の MCP ツールを初めて実行するときに毎回確認が表示されます。「はい、今後は確認しない」を選ぶか、~/.claude/settings.json で "permissions": { "allow": ["mcp__plugin_rag-rat_rag-rat__*"] } を指定して事前に許可してください（プラグインのツール名は mcp__plugin_rag-rat_rag-rat__<tool> です。claude mcp add で手動追加したサーバーの場合は、代わりに mcp__rag-rat__* を使用します）。

• Codex では、リポジトリ内で最初に開始した codex セッションに 「フックの確認が必要です」 というプロンプトが表示されます（プラグインには、サンドボックス外で実行される grep 拡張、クローンチェック、セッションダイジェストのフックが含まれています）。「すべて信頼して続行」 を選んで有効にしてください。codex review などの無人コマンドでは、ツールごとの承認プロンプトで処理が止まらないよう、~/.codex/config.toml でプラグインの MCP ツールも許可してください。

  [plugins."rag-rat@rag-rat".mcp_servers.rag-rat]
  default_tools_approval_mode = "approve"
  

これにより、インストール済みの rag-rat プラグインが公開する、現在および将来のすべての MCP ツールが信頼されます。プラグインのソースとインストール元を信頼できる場合にのみ有効にしてから、Codex を再起動してください。

次に、リポジトリを開いて、次のように依頼します。

このリポジトリに rag-rat をセットアップしてください。

init-rag-rat スキルはリポジトリをスキャンし、素材の選択肢について説明し、rag-rat.toml をプレビューします。確認後にのみ書き込みとインデックス作成を行い、インデックスを最新に保つ git フックのセットアップも提案します。未設定のリポジトリでは、MCP サーバーは休止状態で起動します。セットアップが完了したら、新しいインデックスに対して完全に有効な状態で再起動するよう再接続してください。Claude Code では /mcp を実行して rag-rat に再接続します。Codex と opencode では、新しいセッションを開始してください。

その後、実際に使ってみましょう。rag-rat が想定する一連の流れはお試しをご覧ください。

npm install -g @rag-rat/bin
# or run it without installing:
npx @rag-rat/bin --help

cargo install rag-rat
# or from a checkout:
cargo install --path crates/rag-rat-cli --bin rag-rat

cargo install rag-rat --no-default-features --features model2vec

cd /path/to/your/repo
rag-rat init

npx @rag-rat/skills

claude mcp add --scope project rag-rat -- rag-rat mcp
codex  mcp add rag-rat -- rag-rat mcp

{
  "mcpServers": {
    "rag-rat": { "command": "rag-rat", "args": ["mcp"] }
  }
}

{ "permissions": { "allow": ["mcp__rag-rat__*"] } }

試してみる

リポジトリのインデックス作成が完了すると、コードグラフ、シンボル、Git 履歴、セマンティック検索、クローン検出が使えるようになり、最初のクエリから回答できます。リポジトリメモリは空の状態から始まり、エージェントが memory_create で調査結果を記録するにつれて蓄積され、その後の回答に自動的に反映されます。 （トラッカーの Issue／PR の根拠には rag-rat papertrail sync が必要です。）

MCP クライアントに次のように尋ねてください。

• 「編集しようとしている関数に対して impact_surface を実行して。呼び出し元、呼び出し先、テスト、最近のコミットも含めて。」
• 「設定の再読み込みはどこで処理されていますか？」— ソースとドキュメントを対象にしたハイブリッドな semantic_search。
• 「このリポジトリで最も重要なシンボルは何ですか？」— important_symbols。
• 「このヘルパーは、すでにコードベースにあるものと重複していますか？」— find_clones（書き込み時のフックも、コードの記述中に警告します）。
• 「parse_config の不変条件を記録して。スケジューラーの開始後は、再読み込み時にメモリを確保してはいけません。」— memory_create が最初のリポジトリメモリを書き込み、以後は impact_surface／symbol_lookup の結果に自動的に含まれます。

または、CLI から実行します。

rag-rat query "where is config reload handled?"
rag-rat important-symbols --limit 20
rag-rat brief --mode spine
rag-rat clusters --limit 10
rag-rat tools impact-surface --symbol parse_config

エージェントのループ

重要なのはツールのカタログではありません。エージェントが編集の前後に回すループです。呼び出し元、テスト、根拠、既存の実装を確認しながらコードを変更できるため、推測に頼らずに済みます。

1. シンボルを編集する前に、impact_surface を実行します。 1 回の呼び出しで、現在のソースアンカー、呼び出し元と呼び出し先、関連するテスト、Git／GitHub の根拠、そのシンボル／パス／呼び出し経路に関連付けられたリポジトリメモリ、および信頼度とカバレッジに関する警告が返されます。
2. 影響範囲を確認してから編集します。 以前のエージェントが記録した不変条件、3 ホップ先の呼び出し元、動作を固定するテストなど、変更後に初めて見つかるのではなく、変更前にすべて表示されます。
3. クローン検出フックが書き込み時に重複を検出します。 新しい関数が既存のコードを再実装している場合、Write/Edit フックが再利用できる既存のシンボルとともに通知します。
4. 学んだことを記録します。 編集を通じて長期的に役立つ不変条件、決定、落とし穴が明らかになった場合、memory_create がソースアンカー付きのリポジトリメモリとして保存します。これにより、次のエージェント（または次のセッション）は再調査せず、1 回の呼び出しで情報を得られます。

impact_surface の回答例（TOON — デフォルトの出力形式。ここでは一部を省略）：すべてのフィールドが証拠であり、説明文ではありません。

query:
  ref: "crates/config/src/config.rs::parse_config"
  resolution: syntactic
direct_semantic_callers[12]:
  - from_symbol: "crates/runtime/src/boot.rs::start"
    edge_kind: calls_name
    confidence: syntactic
    callsite:
      path: "crates/runtime/src/boot.rs"
      line: 88
    importance:
      label: local structural load
      score: 6.8
      bucket: high
tests_touching_symbol_path[4]:
  - path: "crates/config/src/config_tests.rs"
    reason: test_mentions_symbol_or_path
recent_commits_touching_symbol_path[1]:
  - evidence[1]: "a1b2c3d touched crates/config/src/config.rs: fix reload race during startup (#141)"
repo_memories:
  direct[2]:
    - kind: Invariant
      title: "Config reload must not allocate after the scheduler starts"
      confidence: high
      anchor_status: current
      binding_kind: symbol
    - kind: Decision
      title: "TOML over JSON5 for the config surface (#88)"
      anchor_status: current
      binding_kind: path
completeness_and_caveats:
  exact_graph_callers: 12
  memory_status:
    active: 2
    stale: 0
  caveats[1]: "Graph evidence is tree-sitter/syntactic, not compiler-grade name resolution."

また、エージェントがロジックを重複して実装する前に表示される、書き込み時のクローン警告です。フックの出力をそのまま示しています。

▶ rag-rat clone check — code you're writing duplicates existing functions:
  • `normalize_path_for_lookup` (line 42) is ~91% similar to crates/index/src/paths.rs::canonicalize_lookup_path
Prefer reusing the existing function(s) over duplicating — impact_surface / symbol_lookup to inspect them.

ツール

rag-rat のツールカタログは、MCP とネイティブ CLI コマンドの両方から利用できます。カタログ全体と JSON スキーマについては、docs/mcp-tools.md に記載されています。 すべてのツールを確認するには rag-rat tools --help を、正規のスキーマから引数を確認するには rag-rat tools <name> --help を実行してください。既存の厳選されたコマンドである query、brief、memory、dream は変更されません。特によく使うツールは次のとおりです。

• impact_surface — 上記のループで使うコーディング前の調査です。呼び出し元、呼び出し先、テスト、Git 履歴、GitHub の経緯、シンボルに関係するリポジトリメモリーを、1 回の呼び出しで確認できます。メモリーは、コンパクトでざっと確認しやすいヘッダーがデフォルトです。本文とバインディング全体を取得するには full_memories: true を渡してください。
• semantic_search — ソースとドキュメントを対象とした、BM25 とベクトル検索を組み合わせたハイブリッド検索です。現在のソースに照らして検証されます。各検索結果には retrieval_mode が表示され、explain=true でスコアの内訳を確認できます。
• symbol_lookup — シンボルの完全一致／あいまい検索です。cfg／オーバーロードのバリエーションは、1 つの論理シンボルとしてまとめられます。
• find_callers / trace_callees — 呼び出しグラフを逆方向／順方向にたどります（シグナルの弱い std／マクロのノイズは、デフォルトで除外されます）。
• important_symbols — （SCIP 対応の）PageRank による、重要なシンボルです。デフォルトでは現在の差分を起点とします。詳しくは docs/oracle.md を参照してください。
• find_clones — 完全一致および類似する重複関数を、リファクタリングの ROI 順に表示します（候補グラフはバックグラウンドで事前計算されるため、大規模なリポジトリにも対応します）。
• memory_create — ソースに紐付いたリポジトリメモリーを記録します。dream は、それらを適切な状態に保つための保守作業リストを提示します（以下を参照）。

これらに加えて、リポジトリの概要把握（repo_brief、repo_clusters）、履歴と根拠（シンボル、パス、チャンク、コミットを対象とする history_for、コミット、Issue、レビューの議論を対象とする history_search）、メモリーの検索（memory_search、memory_for_*）、インデックスの健全性確認（index_status）もあります。保守と診断のツールである dream、heal_index、memory_doctor、グラフとコンパイラーの監査、メモリーのタスクグラフは、オプトインの admin および graph ツールセット（[mcp] toolsets）に含まれているため、必要になるまで各エージェントのツール一覧には表示されません。すべてのツールは docs/mcp-tools.md に記載されています。

リポジトリメモリー

リポジトリメモリーは、ローカルにある第一級の証拠です。チャットメモリーでも、クラウド上のパーソナライズでもありません。 このリポジトリに関する、バージョン管理されたローカルの事実であり、ソースに紐付いています。各メモリーには型（Invariant、Decision、RejectedAlternative、Risk、BugPattern、PerformanceNote、…）があり、ソースに紐付いています。論理シンボル、具体的なシンボル、チャンク、パスと範囲、グラフのエッジ、呼び出し経路、コミット、または GitHub の参照先に結び付けられます。rag-rat は各アンカーを current、relocated、stale、gone、unverified のいずれかとして追跡し、memory_* ツールを通じて、また read_chunk、symbol_lookup、find_callers、trace_callees、impact_surface 内に関連するメモリーを表示します。苦労して得たコンテキストを、失われることなく 1 回の呼び出しで次のエージェントに伝える手段です。

メモリーは単なるフラットなリストではなく、型付きグラフでもあります。memory_edge_add / memory_edges を使い、関係（depends_on、relates_to、supersedes、derived_from、tracks）でメモリー同士をつなげることができます。タスク DAG、意思決定同士をつなぐマインドマップ、あるいは GitHub Issue を tracks するタスクを作成できます。ツール一覧の全容は docs/mcp-tools.md を参照してください。

自己メンテナンスするメモリ

メモリは劣化します。コードが記述内容から変わり、不変条件が置き換えられ、重要な関数がメモリなしで追加されることもあります。dream は、メモリの層を正確に保つためのメンテナンスループです。メモリ自体に関する検出結果から、優先順位付きの作業リストを再計算します。各項目には、確認用の安定した ID が付与されます。

• カバレッジの不足 — important_symbols と同じ PageRank で評価された重要なシンボルのうち、メモリがないものです。これらを次のエージェントが編集しても、手がかりが得られません。
• 古くなった参照 — 指定されたパスやアンカーが解決できなくなったメモリです。

dream は呼び出されるたびに、決定論的な検出を実行します。オプトインの モデルパス を 2 つ利用すると、さらに詳細な確認を行えます。作業が保留中の場合に限り、一時的なリモート GPU（[llm.dream.remote]）で小規模なモデルを実行します。rag-rat dream --verify は、現在のソースの実態に照らして各メモリの判定を再計算します（メモリに記載された内容からコードが変わっているかどうか）。また、--compact は冗長なメモリを簡潔な要約に書き換えます。これらのパスで保持された検出結果は、dream に反映されます。

何も自動的には削除されません。人間、または MCP 経由の高性能なエージェントが、dream_review で作業リストを処理します。実際の不足は accept、不要な項目は dismiss、以前の判定は reset できます。判定は次回以降の実行にも保持されるため、解決済みの検出結果が再び表示されることはありません。CLI の rag-rat dream／rag-rat dream <id> --accept|--dismiss|--reset と同じ機能です。

コンパイラー品質の解決とランキング

グラフはデフォルトではヒューリスティックに基づきます。オプトインの SCIP オラクル（rag-rat oracle run）を使用すると、実際の言語ツールに基づいてエッジを Compiler ティアに引き上げ、tree-sitter が見逃した呼び出しを検出し、外部エッジにフラグを付け、important_symbols に本物の巨大モジュールを表示できます。C/C++ では、scip-clang オラクルが宣言と定義を区別し、マクロが多いコードや複数のターゲットを持つコードで呼び出し／型エッジの精度を高めます。これにより、ファームウェア、カーネル、ドライバー、SDK で使えるグラフとノイズの多いグラフの違いが生まれます。[oracle] の auto_run を有効にすると、MCP サーバーが自動で最新の状態を保ちます（実行頻度を制限し、ファイル監視との競合も防ぎます）。詳細は docs/oracle.md を参照してください。

最新状態の維持

rag-rat mcp はバックグラウンドでファイルを監視するため（デフォルトで有効。無効にするには [watch] enabled = false または RAG_RAT_NO_WATCH=1 を指定）、コミットしなくてもグラフ／シンボルのクエリに未コミットの編集が反映されます。インデックス済みの行は Git のコンテキストを考慮します。クリーンなファイルは commit_sha で、変更済み／未追跡のファイルはワークツリーのオーバーレイに保存されます。そのため、1 つのデータベースでブランチ切り替え後も行を再利用しつつ、ローカルの編集を反映できます。オプションの Git フック（rag-rat hooks install）を使うと、チェックアウト／マージ／書き換え／コミットのたびにインデックスを最新の状態に保てます。read_chunk と検索は、結果を返す前に現在のソースに対してヒットを検証し、古くなったエントリを修復します。

ファイルロックにより、ワークツリーごとのファイル監視は 1 つ、同時に書き込めるプロセスは 1 つに制限されます（NFS／WSL2 の /mnt マウントでは信頼性が低くなります）。

Editor Lens HTTP API

アクティブな rag-rat mcp プロセスは、各ワークツリーにつき、認証済みの Lens HTTP サーバーを 1 つ選出します。ループバック URL とベアラートークンを .rag-rat/sockets/lens.json に公開します。Unix では、認証情報ファイルは所有者のみが読み取り可能です。この組み込みサーバーを無効にするには RAG_RAT_NO_LENS=1 を設定するか、許可するブラウザーオリジンをカンマ区切りで正確に指定して RAG_RAT_LENS_ORIGINS を設定してください。

HTTP API に独自のライフサイクルが必要な場合は、rag-rat serve を実行します。ループバックでのサーバー起動時にはトークンが生成され、クライアントは検出ファイルからそれを読み取ります。ループバック以外にバインドするには、明示的なトークン環境変数と、信頼できるブラウザーオリジンを少なくとも 1 つ指定する必要があります。

LENS_TOKEN="$(openssl rand -hex 32)" rag-rat serve \
  --bind 0.0.0.0 --token-env LENS_TOKEN --allow-origin https://lens.example.com

プリフライト以外のすべてのリクエストで Authorization: Bearer <token> を使用します。許可するオリジンは完全一致で照合され、ワイルドカード CORS は一切出力されません。組み込みリスナーはプレーン HTTP のため、信頼できないネットワークにループバック以外のサーバーを公開する前に、信頼できるリバースプロキシまたはトンネルで TLS を終端してください。

デフォルトでは、すべてのリポジトリのインデックスとメモリーは、マシンごとに統合データベース 1 つ（$XDG_DATA_HOME/rag-rat/rag-rat.sqlite。RAG_RAT_DATA_DIR で上書き可能）に保存されます。そのため、チェックアウトを削除したり git clean -fdx を実行したりしても、自分が作成したメモリーが失われることはありません。リポジトリごとに独自のファイルを使用するには、明示的な [index] database を設定してください（非推奨）。既存の .rag-rat/index.sqlite をグローバルストアにインポートするには、rag-rat consolidate を実行してください。詳細は docs/config/database.md を参照してください。

出力形式

CLI と MCP の結果は、デフォルトで TOON（Token-Oriented Object Notation）です。これはトークン効率の高いエンコーディングで、均一な行を密度の高い [N]{cols}: テーブルとして出力します（該当するペイロードではコンパクトな JSON より約 30% 小さく、実際にはそれより大きくなることはありません）。出力を JSON パーサーで読み取る必要がある場合は、--json（CLI、位置はどちらでも可）を渡すか、rag-rat mcp --json（MCP）を起動してください。

埋め込みバックエンド

デフォルトのローカル埋め込みモデル（FastEmbed）はセットアップ不要ですが、大規模なリポジトリや、より高性能なモデルでは処理を外部に委ねる価値があります。rag-rat は OpenAI 互換の /v1/embeddings API に対応しているため、[llm.embedding.remote] ブロックを使って、Ollama、vLLM、michaelfeil/infinity から埋め込みを取得できます。クライアントは 1 つで、監査と保護を行う場所も 1 か所にまとまります。モードは 2 つあります。

• すでに稼働しているサーバーに接続します（endpoint を設定）。
• 一時利用 — 同梱のクックブックでバックフィル専用の GPU ワーカー（Modal / RunPod）を用意し、完了後に破棄します（cookbook を設定）。バックエンドと GPU クラスは設定で選択します。

初期化フローでは、コンテキスト長が短いモデルでは長いコードチャンクが切り捨てられる場合に警告し、長いコンテキストに対応したコード埋め込みモデルを案内します。また rag-rat は、選択したバックエンドに合わせてクライアントの並列度を自動調整するため、スイープでスループットの限界点を見つけられます。セットアップとすべての設定項目については、docs/config.md を参照してください。

検索品質

検索品質は推測ではなく、測定できます。rag-rat にはコミット再生評価ハーネス（rag-rat eval --replay）が付属しています。直近の各コミットをケースとして扱い、コミットメッセージをクエリに、変更されたファイルを正解セットとして、検索がそれらをどれだけ正確に見つけられるかをスコア化します。recall@3（正しいチャンクが最初の 3 回の読み取りに含まれたか）、recall@10、MRR@10 をレポートします。また、CI では main の傾向を Bencher で追跡するため、リグレッションをリリース前に検出できます。

埋め込みモデルの比較、チャンク分割の変更、int8 ベクトルストレージ（ディスク使用量の削減）の有効化、リモートバックエンドの調整を行う際に活用してください。変更によって再現率が低下していないことを、期待するだけでなく実証できます。（rag-rat eval には --features eval を指定したビルドが必要です。リリース済みバイナリには含まれていません。）

ベンチマーク

代表的なワークロードは、Linux カーネル全体（v7.0、C/H ファイル約 63k 個、グラフエッジ 9.14M 個）のインデックス作成です。 実行時間、スループット、ピーク RSS、ディスク上のサイズ、未解決エッジの分類など、すべての数値は docs/benchmarks.md に記載されています。パフォーマンスはプッシュごとに追跡され、PR ごとにゲートされます。最新の 履歴は bencher.dev/perf/rag-rat/plots で確認できます（設定方法： docs/bencher.md）。

セキュリティ

MCP サーバーが公開するのは読み取り専用のソースツールです。シェルコマンドを実行したり、ソースファイルに書き込んだりすることはありません。 書き込み先は、設定された SQLite インデックスのみです。インデックス作成、マイグレーション、メンテナンス、 整合処理、リポジトリメモリ操作、自動的な古いインデックスの修復時に書き込みます。GitHub との同期は明示的に行い、 gh api を使用します。通常のクエリツールが読み取るのはローカルキャッシュのみです。

ローカル埋め込みとリモート埋め込み

デフォルトのローカル埋め込み機能では、マシンの外にデータが送信されることはありません。インデックス作成もクエリもすべてローカルで行われます。 [llm.embedding.remote] バックエンドを設定すると、次の 2 つの場面でテキストがマシンの外に送信されます。 インデックス作成時に選択されたチャンクテキストと、各セマンティック検索のクエリテキストです（検索では、クエリを埋め込み、インデックス済みのベクトルと比較します）。 CONNECT バックエンドでは、設定された endpoint を使って両方を埋め込みます。エフェメラルバックエンドでは、ローカルの query_endpoint を使ってクエリを埋め込みます。

重要なのは、エンドポイントが何であるかです。

• 自前のサーバー（セルフホスト型の Ollama／vLLM／infinity）— テキストは、ご自身が管理するインフラ内に留まります。
• エフェメラルな Modal／RunPod ワーカー（クックブックの手順）は、入力データを使って学習するデータサービスではなく、ご自身のオープンソース埋め込みモデルを実行するエフェメラルなコンピューティングプロバイダーです。どちらも SOC 2 Type II に準拠し、通信中と保存時のデータを暗号化し、テナントを分離します。また、バックフィル後にはインスタンスとストレージを破棄します。クラウド VM と同じように、プロプライエタリなコードを扱ううえで妥当なデータ処理者との関係です。
• 管理していないサードパーティの埋め込み APIについては、利用規約（データの保持、入力データを使った学習）を実際に確認してください。

バックエンドを問わず、インデックス対象からシークレット、生成ファイル、ベンダーツリーを除外し、チャンク化や埋め込みの対象にならないようにしてください。また、クエリテキストにシークレットを含めないでください。詳しくは docs/config.md を参照してください。

プラットフォームのサポート

rag-rat は Linux、macOS、Windows でビルドおよびテストされています。Linux ではすべての PR と main へのすべての プッシュでテストが行われ、macOS と Windows ではリリース時にテストが行われるため、cargo install rag-rat は 3 つすべてのプラットフォームでビルドされ、リンクされます。Android（aarch64、bionic）もリリース対象です。ビルド済みバイナリが 各リリースに添付され、@rag-rat/bin に公開されるため、Termux で npx @rag-rat/bin を使用できます。詳しくは クイックスタートを参照してください。 SQLite はバンドルされています（rusqlite を介してソースからコンパイルされます）。そのため、システムライブラリは不要ですが、 各プラットフォームで C ツールチェーンが必要です。Linux には同梱されています。macOS では Xcode Command Line Tools（xcode-select --install）をインストールしてください。Windows では C++ ワークロード（MSVC）を含む Visual Studio Build Tools をインストールしてください。 Rust 1.98 以降が必要です。ワークスペースでは依存関係の安定版ベースラインとしてこのバージョンを採用しています（バンドルされた SQLite のビルド自体は cfg_select! のため、少なくとも Rust 1.95 が必要です）。

メンテナンスを便利にする機能の一部は、設計上 Unix または Linux のみを対象としており、それ以外の環境では問題なく機能が縮退します。インデックス、クエリ、MCP の機能には影響しません。

• 実行中の MCP サーバーのホットアップグレード（SIGUSR1 によるプロセス内再実行）は Unix のみです。Windows では rag-rat mcp を再起動して新しいバイナリを適用してください。
• フリートの自動アップグレード（新しいバイナリが配置されたとき、実行中のほかのサーバーにシグナルを送信）は /proc を走査するため Linux のみです。それ以外の環境では何もしません。
• grep 拡張フックは、Linux と macOS ではセッションごとの重複排除機能を備えた、起動済みの Unix ソケットリスナーを使用します。Windows では、呼び出しごとにインデックスへ直接読み取り専用クエリを実行します。動作は同じですが、呼び出しをまたいだ重複排除は行われません。

コマンド

CLI の実行

この README と docs/ のコマンドは、rag-rat <command> として記述されています。

プラグインを使用する場合、rag-rat は ~/.local/bin/rag-rat（Windows の場合： %USERPROFILE%\.local\bin\rag-rat.cmd）です。MCP サーバーは初回起動時に、このシムがプラグインのバージョンに合ったバイナリを指すようにし、プラグインの更新時にはシムの参照先も更新します。Claude Code のインストーラーと同様に、シェルプロファイルや PATH は変更しません。rag-rat が見つからない場合は、~/.local/bin が PATH に含まれていません。シェルプロファイルに export PATH="$HOME/.local/bin:$PATH" を追加するか、~/.local/bin/rag-rat doctor を実行してください。cli セクションに、お使いのシステムに適した修正方法が表示されます。このシムが作成したものでない rag-rat がそこにある場合、シムが置き換えることはありません。RAG_RAT_NO_PATH_SHIM=1 を設定すると、シムは無効になります。

プラグインを使用しない場合、CLI をインストールします：npm install -g @rag-rat/bin または cargo install rag-rat。

最後の手段として、どちらも使用できない場合は、MCP サーバーが実行しているバージョン（index_status ツールの version フィールド）を指定して npx 経由で実行します：

npx -y @rag-rat/bin@<version> <command>

バージョン指定はそのままにしてください。バージョンを指定せずに npx @rag-rat/bin を実行すると、最新リリースが起動します。最新リリースはインデックスを新しいスキーマに移行するため、古いプラグインのサーバーはそのインデックスを開けなくなります。Git フックはこの方法でバージョンを指定し、プラグインの更新にも自動で追従します。

rag-rat init                       # guided first-run setup
rag-rat index [--changed|--discover|--full]
rag-rat doctor
rag-rat query "semantic recall"    # add --json for JSON
rag-rat important-symbols --limit 20
rag-rat brief --mode spine|churn|god_modules|refactor_candidates
rag-rat clusters --limit 10
rag-rat oracle run | status        # compiler-grade resolution (docs/oracle.md)
rag-rat models list | install <model>
rag-rat reconcile --changed-first --max-seconds 60 --batch-size 64
rag-rat papertrail sync            # add --full to force a historical healing pass
rag-rat memory list | show <id> | doctor | rebind <id>    # inspect / re-anchor repo memories
rag-rat dream [--verify|--compact] [<id> --accept|--dismiss|--reset]   # memory-maintenance worklist
rag-rat consolidate                # import a legacy per-repo index into the global store
rag-rat hooks install              # git maintenance hooks
rag-rat gc                         # prune rows for dead git contexts
rag-rat eval [--json|--update-baseline]   # CI search-quality gate; requires a `--features eval` build (absent from the released binary)
rag-rat serve                      # authenticated editor Lens HTTP API
rag-rat tools <name>               # invoke any tool directly; see `tools --help`
rag-rat mcp                        # start the STDIO server

リリースとライセンス

リリースは release-plz によって自動化されています（3 つのクレートは同時にリリースされます。詳しくは docs/releasing.md を参照してください）。rag-rat は MIT ライセンスです。詳しくは LICENSE を参照してください。

先行研究

rag-rat のクローン検出設計は、スケーラブルなトークンバッグ候補生成における SourcererCC、正規化されたニアミスクローン検出の枠組みにおける NiCad、移動を考慮した AST 差分における GumTree、テンプレート抽出における反単一化／最小一般化に着想を得ています。計画中のフラグメントレベルのマイニングと、コピー＆ペーストのバグを推定するヒューリスティックは CP-Miner に着想を得ています。