giancarloerra/SocratiCode

SocratiCode – コードベース認識AIエンジン

概要 – SocratiCodeは、あらゆるLLM（Claude、OpenAI、Geminiなど）が、クエリのたびにすべてのファイルを読み込むことなく、リポジトリの完全なセマンティクスを理解できるようにするオープンソースのコードベース・コンテキストエンジンです。ローカルインデックス（埋め込み + AST認識チャンク、依存関係グラフ、シンボルレベルのインパクトデータ）を構築し、Claude Code、OpenAI Codex、VS Code、Cursor、Gemini CLIなどのホストで使用されるMCP (Multi-Chat-Protocol) インターフェースを通じて提供します。

重要性 – 大規模なコードベース（数千万行）をLLMに読み込ませるには、トークンコスト、レイテンシ、ハルシネーションといったコストがかかります。SocratiCodeは、重い処理を一度だけ事前計算し、アシスタントが正確なシンボル、コールフロー、関連アーティファクト（DBスキーマ、API仕様、インフラ構成）を数ミリ秒で取得できるようにします。これにより、コンテキストサイズ、トークン使用量、ツール呼び出しが削減され、より小型で安価なモデルでもアーキテクチャレベルの推論が可能になります。

---

主な機能（READMEより）

• ハイブリッド検索 – セマンティック（埋め込み）とBM25（キーワード）検索を相互ランク融合（Reciprocal Rank Fusion）で組み合わせます。
• 多言語依存関係グラフ – 18言語を解析し、シンボルレベルのコールフロー/影響範囲グラフを構築し、インタラクティブなHTMLエクスプローラーで可視化します。
• インパクト分析 – 変更によってどの関数、クラス、ファイルが影響を受けるかを追跡します。
• コンテキストアーティファクト – DBスキーマ、OpenAPI仕様、Terraform/クラウド構成、アーキテクチャドキュメントなどをインデックス化し、検索可能にします。
• ゼロ構成スタート – npx socraticode@latest でDockerスタック（QdrantベクトルDB + ローカル埋め込み用Ollama）を自動的に起動します。
• 自動増分インデックス – ファイルウォッチャーが変更のたびにインデックスを更新し、クラッシュ時も再開可能なチェックポイントを備えています。
• マルチリポジトリ / マルチブランチ / マルチエージェント – 単一のインデックスを複数のAIエージェントで同時に共有できます。
• デフォルトでプライベート – すべてローカルで実行されます。クラウド埋め込み（OpenAI、Google Gemini）や外部のQdrantインスタンスを選択しない限り、APIキーは不要です。
• クラウド対応 – SocratiCode Cloud（プライベートベータ）は、SSO、監査ログ、ブランチ認識インデックス、VPC/エアギャップ環境へのデプロイを追加しつつ、コアエンジンは無料で提供します。
• 広範なホスト統合 – Claude Code、OpenAI Codex、VS Code（エージェントプラグインおよびエディタ拡張）、Cursor、Gemini CLI、Continue、Cline、Zed、OpenCode、および直接MCPモード用のネイティブプラグイン。
• ベンチマーク性能 – 245万行のVS Codeプロジェクトにおいて、grepベースのワークフロー（Claude Opus 4.6）と比較して、コンテキストを61%削減、ツール呼び出しを84%削減し、37倍高速化しました。

---

はじめに（クイックスタート）

1. 前提条件 – Node ≥ 18.17、PATH上のnpx、Dockerの実行（デフォルトのQdrant + Ollamaスタック用）。
2. インストール – 最も簡単な方法はMCPホスト経由です：

   {
     "mcpServers": {
       "socraticode": {
         "command": "npx",
         "args": ["-y", "--prefer-online", "socraticode@latest"]
       }
     }
   }
   

   または、Claude Code、VS Code、Cursor用の一括インストールバッジを使用してください（READMEに同じ npx コマンドをトリガーするバッジリンクがあります）。
3. 最初のインデックス作成 – チャットでアシスタントに「Index this codebase」と尋ねてください。SocratiCodeがバックグラウンドで実行され、リポジトリを監視し、codebase_update / codebase_watch コマンドで進捗を報告します。
4. 使用方法 – インデックス作成後、以下が可能です：
   • codebase_search { query: "…" } – ハイブリッドなセマンティック + BM25検索。
   • codebase_graph { symbol: "MyClass.method" } – 依存関係グラフの表示。
   • codebase_impact { symbol: "…" } – 影響範囲分析の取得。
   • schema_search、api_spec_search などのアーティファクトのクエリ。
5. 最新状態の維持 – エンジンはMCPサーバー起動時に自動的に更新されます (npm @latest)。プラグイン/拡張機能は、ホストの通常の拡張機能更新メカニズムを通じて更新されます。

---

典型的なワークフローの例

User:  Index this codebase.
Assistant (via SocratiCode):  Indexing started… 45 % done.
User:  What function reads the `config.yaml` file?
Assistant:  (runs `codebase_search` → returns `loadConfig` in `src/config.ts`)
User:  Show me the call-flow from `loadConfig`.
Assistant:  (runs `codebase_graph` → displays interactive HTML graph)
User:  Which modules would be affected if I change `Database.connect`?
Assistant:  (runs `codebase_impact` → lists dependent services, tests, docs)

重い分析はすべてローカルで行われ、LLMには簡潔な結果のみが送信されます。

---

設定のハイライト

• 埋め込みプロバイダー – EMBEDDING_PROVIDER は ollama（デフォルト、ローカル）、openai、または google に設定可能です。環境変数で適切なAPIキーを設定してください。
• ウォッチャーモード – SOCRATICODE_WATCHER=off|manual|auto で自動ファイル監視更新を制御します。
• 再開動作 – SOCRATICODE_AUTO_RESUME_PROJECTS / SOCRATICODE_AUTO_RESUME で複数のリポジトリを事前ロードできます。
• バージョン固定 – SOCRATICODE_SPEC を特定のnpmバージョン（例: socraticode@1.14.0）に設定して、再起動時もエンジンを固定できます。
• Dockerリソース – READMEでは、大規模リポジトリ向けにQdrant/OllamaコンテナへCPU/RAMを割り当てる方法を説明しています。

---

対象ユーザー

• 開発者 – LLMアシスタント（Claude、ChatGPT、Geminiなど）に、ソースコードを外部サービスに公開することなく、モノレポ、マイクロサービスアーキテクチャ、またはInfrastructure-as-Codeについて推論させたい方。
• チーム – AIを活用した社内DevOpsツール、コードレビューボット、自動化されたインパクト分析パイプラインを構築している方。
• 企業 – セルフホスト可能でポリシー制御されたコードインテリジェンス層を必要とする方（MCPガバナンス、PIIの編集、レート制限などについては姉妹プロジェクト JanuScope を参照）。

---

ライセンスとコミュニティ

• ライセンス: AGPL-3.0（完全なソースコードが利用可能。商用利用にはAGPLへの準拠が必要）。
• コミュニティ: サポート用のDiscordサーバー、バグ/機能リクエスト用のGitHub Issues、およびSSOと監査ログを備えたマネージドホスティングを求めるチーム向けのプライベートベータ版SaaS (SocratiCode Cloud)。

---

結論

SocratiCodeは、リポジトリ全体のローカルで最新のインデックスを構築し、標準的なMCPインターフェースを通じて強力な検索、グラフ、インパクト分析ツールを公開することで、あらゆるLLMをコードを認識するアシスタントに変えます。ゼロ構成でプライバシーを最優先した企業規模のデプロイメント向けに設計されていますが、VS CodeやClaude Codeプラグインをワンクリックするだけで、個人の開発者でも簡単に利用できます。