⚡ マルチリポジトリコード検索エンジン

複数のソースコードリポジトリを同時に照会・ナビゲートするために設計された本番グレードのコード検索・取得システムで、OpenSpec 仕様駆動開発フレームワークを用いて設計・計画されています。ランク付けされた結果（リポジトリ、ファイル、行、シンボル、グラフのメタデータ付き）は、外部クラウドLLMクライアントとの統合境界となり、クライアントは自身の環境で生成を実行します。

🌟 主な機能

1. マルチリポジトリ取り込みとインクリメンタル同期:

   • ローカルコードベースディレクトリとリモートGitリポジトリを管理します。

   • .gitignore ルールを尊重し、バイナリやロックファイルを自動的に除外します。

   • SHA-256ハッシュ追跡とGitコミット検出により、瞬時のインクリメンタル更新を実現します。

2. AST対応セマンティックコードチャンキング:

   • Python、TypeScript/JavaScript、Go、Rust、Java、C/C++、HTML/CSS、SQL、Markdown に対応した言語認識型構造解析。

   • 関数、メソッド、クラス、インターフェースの境界を保持します。

   • スコープヘッダー（// [Context] Repository | File | Scope | Imports | Doc）を注入します。

3. ハイブリッド密ベクトル＋語彙索引:

   • 密ベクトル検索: コサイン類似度によるセマンティックサブワード特徴ベクトル＋外部埋め込み（Gemini、OpenAI、Voyage AI、Ollama）のサポート。ローカルOllama埋め込みはデフォルトで qwen3-embedding:0.6b を使用し、オンデマンドでロードされ、アイドル時に解放されます。

   • スパースBM25検索: camelCase と snake_case のトークンを分割し、シンボルをブーストするコード向けトークナイザー。

   • 相互ランク融合（RRF）: 密ベクトルとスパースのランキングを正確な識別子ブーストで統合します。

4. シンボルグラフとクロスリポジトリ依存関係リンケージ:

   • SQLite にシンボル定義、呼び出し元、呼び出し先、インポートを抽出します。

   • 異なるリポジトリ間で フロントエンドクライアントのAPI呼び出し（例: apiClient.post('/api/v1/auth/login')）を バックエンドAPIルートハンドラ に自動的にマッピングします。

5. インターフェース:

   • モダンWeb UI: 主要なクエリ体験としてのハイブリッド検索、リポジトリマネージャー、クロスリポジトリAPIコントラクトマップ、コードインスペクタードロワー。

   • Model Context Protocol (MCP) サーバー: AIコーディングアシスタント（Antigravity、Cursor、Claude Code、Windsurf）に stdio ツール（search_codebases、get_symbol_definition、get_call_hierarchy、list_repositories）を公開します。

   • CLI: インデックス作成と検索のための高速ターミナルコマンド。

   • REST API: POST /api/v1/search は、外部クラウドLLMコンシューマー向けにランク付けされたコードチャンクを返します。

Related MCP server: CodeGraph

📂 OpenSpec仕様駆動計画

すべての仕様、アーキテクチャ契約、タスク分解は openspec/ の下で管理されています:

openspec/
├── config.json                     # OpenSpec project configuration
├── specs/                          # Living System Specifications (Source of Truth)
│   ├── repository-management.md    # Repo ingestion & git tracking
│   ├── ast-code-chunking.md        # AST semantic parsing & context injection
│   ├── hybrid-indexing.md          # Dense vector + BM25 lexical index
│   ├── symbol-graph-retrieval.md   # Call graph & cross-repo API linkage
│   ├── context-fusion-reranking.md # RRF fusion & citation packaging
│   ├── rag-generation.md           # LLM prompting & grounded citations
│   ├── mcp-server.md               # Model Context Protocol tools
│   └── api-and-web-ui.md           # REST & Web UI specifications
└── changes/
    └── 01-foundation-and-core-rag/ # Phase 1 Change Proposal
        ├── proposal.md             # Goals, scope, and motivation
        ├── design.md               # Technical architecture & contracts
        └── tasks.md                # Implementation checklist (Completed)

🚀 クイックスタート

1. リポジトリの登録とインデックス作成

# Add a local repository
python3 main.py add auth-service ./fixtures/repo_auth_service

# Add another repository
python3 main.py add web-client ./fixtures/repo_web_client

# List all indexed repositories
python3 main.py list

2. リポジトリグループと依存関係の管理

# Create a repository group
python3 main.py group create platform --repos auth-service shared-schemas

# Declare a dependency edge: web-client depends on auth-service
python3 main.py relation add web-client auth-service

# Inspect relations for a repository
python3 main.py relation show web-client

# Search with group scoping and upstream dependency expansion
python3 main.py search "jwt token" --group platform --expand upstream --expand-depth 1

3. リポジトリ横断検索（CLI）

# Hybrid search across all codebases
python3 main.py search "login user authenticate"

# Search scoped to a group with upstream dependency expansion
python3 main.py search "How does authentication flow between web-client and auth-service?" --group platform --expand upstream

4. インタラクティブWeb UIの起動

python3 main.py serve --host 127.0.0.1 --port 8000

ブラウザで http://localhost:8000 を開いてください。

5. MCP（Model Context Protocol）経由でAI IDEに接続

このMCPサーバーエントリをAI IDE設定（Antigravity / Cursor / Claude Code）に追加してください:

{
  "mcpServers": {
    "multi-repo-code-rag": {
      "command": "python3",
      "args": ["/Users/nick-work-pc/.gemini/antigravity/scratch/multi-repo-code-rag/main.py", "mcp"]
    }
  }
}

🧠 埋め込みモデルランタイム

エンジンは データディレクトリごとに単一インスタンス として動作し、ローカル埋め込みモデルを 動作中のみ 常駐させます。

• デフォルトモデル: qwen3-embedding:0.6b（ollama pull qwen3-embedding:0.6b で一度インストール）。--embedding-model または $OLLAMA_EMBEDDING_MODEL で上書きできます。

• オンデマンド常駐: モデルは起動時には決してロードされません。インデックス実行または検索の最初の埋め込み時にロードされ、最後の実行中操作が完了しアイドル猶予期間が経過すると解放されます。重複するリクエストは1回のロードを共有し、1回の解放を生成します。

• 常駐ポリシー（--keep-alive または $EMBEDDING_KEEP_ALIVE による）:

  値	動作
  (未設定)	30秒間非アクティブ後に解放（デフォルト）
  0	最後の操作の直後に解放
  45s, 5m	そのアイドル猶予期間の後に解放
  always	プロセスの存続期間中モデルを常駐させる

• 単一インスタンス: 起動時に <data-dir>/.rag-instance.lock に対して排他ロックを取得します。2番目のインスタンスは所有pidとともに即座に失敗します。--allow-multi-instance を渡すと、これを警告に格下げできます。

• 手動での確認 / 解放: GET /api/v1/models/status は常駐状態、アクティブな操作、ポリシー、インデックスの来歴を報告します。POST /api/v1/models/unload（または python3 main.py unload）はモデルを解放し、操作の実行中は 409 busy を返します。

モデル変更時の自動再インデックス

密ベクトルインデックスは、そのベクトルを生成したプロバイダー、モデル、ベクトル次元を記録します（<data-dir>/index_meta.json）。設定された埋め込みモデルが変更されると — 例えば qwen3-embedding:4b（2560次元）からデフォルトの qwen3-embedding:0.6b（1024次元）へのアップグレードなど — 影響を受けるリポジトリは、検索結果が提供される前に 自動的に再埋め込み されます:

• チャンクテキスト、シンボルグラフ、BM25語彙インデックスは保持されます（再解析ではなく埋め込みのみのパス）。

• 進捗は通常のインデックス進捗出力を通じて報告されます。

• 来歴はリポジトリごとに書き込まれるため、中断された再構築は未処理のリポジトリから再開されます。

• 再構築中に到着した検索は、別のモデルのベクトルに対してスコアリングされる代わりに 503 reindexing を受け取ります。

以前の動作へのロールバック: OLLAMA_EMBEDDING_MODEL=qwen3-embedding:4b EMBEDDING_KEEP_ALIVE=always は以前のモデルと常駐ポリシーを復元します。来歴チェックにより、コード変更なしで4bベクトル空間に再構築されます。

🏷️ リポジトリグループと依存関係アーキテクチャ

トポロジーとドメインルール

• 名前付きリポジトリグループ: リポジトリのフラットなコレクション（例: core、platform、billing）。グループを削除しても、基盤となるリポジトリが削除されることはありません。

• 有向依存DAG: 明示的な依存エッジ A -> depends on -> B。エッジを追加すると書き込み時サイクル検出が実行され（サイクル時には DependencyCycleError が発生）。

• スコープ解決: 明示的なリポジトリIDとグループメンバーをプライマリセットに結合し、upstream（依存先）、downstream（依存元）、または both の方向に expand_depth までグラフに沿って展開します。

• ホップ減衰ランキング: 展開されたリポジトリから取得されたチャンクには、スコア乗数ペナルティ (0.85 ** hops) が適用され、プライマリリポジトリが最初にランク付けされるようにします。

• 来歴メタデータ: 展開されたリポジトリ由来の結果にはメタデータ（repo_relation='expanded'、relation_direction、relation_hops）が付与され、UIで視覚的にバッジ表示されます。

REST APIエンドポイント

MCPツール

• manage_repository_relations: アクション create_group、delete_group、add_to_group、remove_from_group、add_dependency、remove_dependency。

• get_repository_relations: 単一リポジトリまたはリレーショングラフ全体のリレーションを返します。

• search_codebases: オプションの groups、expand、expand_depth 引数で拡張されています。

🧪 テストの実行

python3 -m unittest discover -s tests -p "test_*.py" -v

すべてのユニットテストおよび統合テストスイートが合格し、ASTチャンキング、シンボル抽出、クロスリポジトリAPI検出、リポジトリ関係DAGとサイクル検出、スコープ解決とホップ減衰検索、REST APIハンドラー、MCPプロトコル、エンドツーエンドのハイブリッド検索取得を検証しています。