Socraticode

SocratiCode

「善はただ一つ、知識であり、悪はただ一つ、無知である。」 — Socrates

AI はコードを読みます。SocratiCode はコードを理解します。

オープンソースのコードベースコンテキストエンジン：あらゆる AI に、コードベース全体（およびインフラストラクチャ）の知識を即座に自動で提供します。大規模でも、設定不要、完全にプライベート、完全無料です。

Altaire Limited のご厚意によりスポンサー提供されています

🛡️ コードベースのコンテキストとともに MCP ガバナンスも必要ですか？ 姉妹プロジェクトのJanuScopeをご覧ください。ローカルファーストの MCP ポリシープロキシで、ツールのブロック、SQL 変更ゲート、PII のマスキング、監査、レート制限を備えています。

SocratiCode が役に立ったら、ぜひ ⭐ このリポジトリにスターを付けてください。ほかの人が見つけやすくなります。また、開発チームや開発者仲間にもぜひ共有してください！

💬 ご質問や、気軽に話したい方は、Discordにご参加ください。 ☁️ SocratiCode Cloud（プライベートベータ） — オープンソース版と同じエンジンを基盤とする、ホスト型の共有チームインデックスです。SSO、監査ログ、ブランチ対応のインデックス作成、VPC／エアギャップ環境へのデプロイオプションも備えています。オープンソースのコアは今後も無料です。早期アクセスをリクエスト →

ひとつのことを、優れた品質で：セットアップ不要、余計な機能なし、完全自動化の深いコードベースインテリジェンス。 SocratiCode は、AI アシスタントにコードベースの深い意味理解を提供します。**ハイブリッド検索、プロジェクト横断検索、多言語対応のコード依存関係グラフ、シンボルレベルの影響分析とフロー、視覚的なナビゲーションのためのインタラクティブな HTML グラフエクスプローラー、検索可能なコンテキストアーティファクト（データベーススキーマ、API 仕様、インフラ設定、アーキテクチャドキュメント）**を利用できます。設定は不要です。ローカル stdio サーバーに対応する MCP ホストに追加するか、対応するプラグインまたは拡張機能を使ってください。すべてを自動で管理します。

本番環境ですぐに使える品質で、エンタープライズレベルの大規模リポジトリ（約 4,000 万行以上）で実証済みです。バッチ処理による自動の再開可能なインデックス作成で、進捗をチェックポイントに保存します。一時停止、クラッシュ、再起動、中断が発生しても、作業が失われることはありません。ファイルウォッチャーが、ファイルの変更ごと、およびセッションをまたいで、インデックスを自動的に最新の状態に保ちます。マルチブランチ、マルチリポジトリ、マルチエージェントに対応しており、複数の AI エージェントが同じコードベースで同時に作業できます。自動調整される単一のインデックスを設定不要で共有できます。

デフォルトでプライベートかつローカル — Docker がすべてを処理するため、API キーは不要で、データがマシンの外部に出ることもありません。埋め込み（OpenAI、Google Gemini）や Qdrant に対応したクラウド利用も可能で、必要に応じて豊富な設定オプションも利用できます。

コードインテリジェンスはあなたのもの。AI やホストに依存しません — コードベースの理解はコードとともにあり、特定のアシスタント、IDE、モデルにロックされません。また、SocratiCode は負荷の高い処理（影響範囲、呼び出しフロー、依存関係のたどり）を事前に計算するため、より小規模なモデルでも、通常なら最上位の推論能力が必要となるアーキテクチャ上の複雑なタスクに対応でき、トークンコストをさらに節約できます。

Qdrant ベースの MCP／Claude プラグイン／スキルとして初めて、自動管理される設定不要のローカル Docker デプロイと、AST 対応のコード分割、ハイブリッドなセマンティック検索＋BM25（RRF による統合）のコード検索、循環依存の可視化に対応した多言語依存関係グラフ、シンボルレベルの影響分析（18 言語にわたる影響範囲と呼び出しフローの追跡）、検索可能なインフラ／API／データベースアーティファクトを、ひとつの目的に特化した、設定不要で使いやすいコードインテリジェンスエンジンに組み合わせています。

VS Code でのベンチマーク（245 万行）： SocratiCode は grep ベースの探索と比べ、コンテキストを 61％ 削減、ツール呼び出しを 84％ 削減し、37 倍高速です。Claude Opus 4.6 を使って実際にテストしました。ベンチマークの詳細 →

目次

• クイックスタート
• クイックガイド
• プラグインとホスト連携
• SocratiCode を選ぶ理由
• 機能
• 前提条件
• ワークフローの例
• エージェントへの指示
• 設定
• 言語サポート
• 除外ルール
• コンテキストアーティファクト
• 環境変数
• Docker リソース
• テスト
• grep だけでは不十分な理由
• よくある質問
• コミュニティ
• SocratiCode Cloud
• ライセンス

---

クイックスタート

必要条件： PATH に npx が通った Node.js 18.17 以降。また、デフォルトのローカル Qdrant および Ollama スタックを使用するには、Docker が起動している必要があります。

ホストごとの推奨セットアップ手順と、短い実践シナリオについては、クイックガイドをご覧ください。この README では、その他のインストール方法と設定全体を説明しています。

Claude Code、VS Code、Cursor 向けのクイックインストールガイド：

JSON の mcpServers オブジェクトを使用するMCP ホストでは、次の完全な設定を使用できます。

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

設定スキーマはホストごとに異なります。Continue、VS Code、Zed、OpenCode、Gemini CLI、Cline 用の専用例は、プラグインとホスト連携をご覧ください。

SocratiCode を最新の状態に保つ

SocratiCode には、互いに独立した 2 つの更新方法があります。MCP エンジンは npm で公開されている socraticode パッケージです。以下の npm を使用する設定ではすべて npx -y --prefer-online socraticode@latest を使用し、MCP サーバーの起動時に npm で現在の latest リリースを確認します。実行中のサーバーは自分自身を置き換えられません。また、新しいバージョンをダウンロードできるのは npm レジストリに接続できる場合に限られるため、リリース後にサーバーを再起動するか、再接続してください。

ネイティブのプラグインや拡張機能には、スキル、指示、マニフェスト、UI ファイルも含まれています。以下の手順に従ってホスト側でそれらを更新し、新しいプラグインファイルが読み込まれるよう、新しいセッションを開始してください。MCP を直接インストールした場合はエンジンのみが含まれ、SocratiCode のプラグインスキルはインストールされません。

連携	プラグイン、スキル、連携ファイルの更新
Claude Code プラグイン	マーケットプレイスの自動更新を有効にするか、claude plugin marketplace update socraticode を実行した後、claude plugin update --scope user socraticode@socraticode を実行します
OpenAI Codex プラグイン	codex plugin marketplace upgrade socraticode を実行し、続けて codex plugin add socraticode@socraticode を実行して、新しいタスクを開始します
VS Code Agent Plugin	日次チェックのために extensions.autoUpdate を有効にしたままにするか、Extensions: Check for Extension Updates を実行してから、新しいチャットを開始します
VS Code エディター拡張機能	拡張機能ビューまたは Extensions: Check for Extension Updates で更新してから、ウィンドウを再読み込みします
Cursor ローカルプラグイン	Cursor セクションのコマンドを使って最新の GitHub リリースタグに更新し、Cursor を再読み込みします
Gemini CLI の直接 MCP	サーバーに再接続し、現在の npm リリースを取得するため、Gemini を再起動します
MCP の直接利用のみ	別個のプラグインファイルはインストールされません。現在の npm リリースを取得するため、MCP サーバーを再起動するか、再接続します
@latest は npm の公開済み latest ディストリビューションタグを指し、Git ブランチは指しません。--prefer-online は、キャッシュがまだ有効な場合でも、npm にパッケージのメタデータを更新するか確認させます。同じレジストリが一時的に利用できない場合、npm はすでにキャッシュに保存されているデータを使用できますが、初回のインストールにはレジストリへのアクセスが必要です。npm の exec キャッシュに関するドキュメントとnpm のディストリビューションタグに関するドキュメントをご覧ください。

ホストを再起動してください。デフォルトのローカル設定では、初回使用時に必要な Docker イメージが取得され、管理対象の Qdrant が起動します。OLLAMA_MODE=auto は、検出したネイティブの Ollama インスタンスを再利用するか、管理対象の Ollama を起動し、ローカルの埋め込みモデルがまだ利用できない場合はダウンロードします。クラウドおよび外部の埋め込みプロバイダーでは、ローカルモデルはダウンロードされません。初期セットアップには通常、接続状況によって約5分かかります。以降の起動は数秒です。

プロジェクトでの初回利用時： AI に 「このコードベースをインデックス化して」 と尋ねてください。インデックス化はバックグラウンドで実行されます。進捗を確認するには、「コードベースのインデックス状況は？」 と尋ねてください。コードベースの規模や、GPU アクセラレーション対応の Ollama とクラウド埋め込みのどちらを使用するかによって、初回のインデックス化には数秒から数分かかります（Macbook Pro M4 では、+3 million lines of code の初回インデックス化は10分未満で完了します）。完了後は再実行する必要はなく、検索、依存関係グラフの探索、コンテキストアーティファクトのクエリが可能になります。

2回目以降： ツール（検索、グラフなど）を使うだけです。デフォルトでは、サーバーの起動時に MCP プロセスの作業ディレクトリにあるインデックス済みプロジェクトが再開されます。インデックスが完了している場合は、監視機能が開始され、差分更新が実行されます。中断されたインデックス化は、最後のチェックポイントから再開されます。SOCRATICODE_AUTO_RESUME_PROJECTS と SOCRATICODE_AUTO_RESUME=all を指定すると、追加のプロジェクトを選択できます。起動時に処理されなかったインデックス化済みプロジェクトは、最初の検索、状況確認、またはグラフ操作の際にフォールバックとして監視が開始されます。codebase_watch { action: "start" } を使って、監視を明示的に開始または再開することもできます。

意図的にインデックスのスナップショットを維持したい場合： チェックアウトを使用するすべての MCP プロセスで SOCRATICODE_WATCHER=off と SOCRATICODE_AUTO_RESUME=off を設定し、更新したいときだけ codebase_update を実行してください。既存のインデックスは、再構築しなくても引き続き使用できます。明示的な codebase_watch { action: "start" } を引き続き利用できるようにするには、代わりに SOCRATICODE_WATCHER=manual を使用してください。インデックス化の動作とホストごとの環境変数の渡し方をご覧ください。

Git の遷移時に更新したい場合： SOCRATICODE_WATCHER=git を設定してください。アクティブなインデックス化済みチェックアウトは、ネイティブのファイル監視機能を使わずに、チェックアウト済みの ref または HEAD の変更時に更新されます。Git トリガーによる更新をご覧ください。

大規模なコードベースを扱う macOS／Windows の場合：Docker コンテナでは GPU を使用できません。中規模から大規模のリポジトリでは、Ollama をネイティブにインストールすると（自動検出されるため、設定変更は不要です）、Metal／CUDA によるアクセラレーションを利用できます。または、ローカルにインストールせずに高速化するには、OpenAI embeddingsを使用してください。詳細はこちら。

推奨：最良の結果を得るには、エージェントの指示を AI アシスタントのシステムプロンプト、またはプロジェクトの指示ファイル（CLAUDE.md、AGENTS.md など）に追加してください。重要な原則である読む前に検索することで、AI は SocratiCode のツールを効果的に活用し、不要なファイルの読み込みを避けられます。

Claude Code ユーザーの場合：SocratiCode プラグインをインストールすると、エージェントの指示がスキルとして自動的に含まれるため、CLAUDE.mdに追加する必要はありません。また、プラグインには MCP サーバーも同梱されているため、別途claude mcp addを実行する必要はありません。

上級者向け：クラウド埋め込み（OpenAI／Google）、外部 Qdrant、リモート Ollama、ネイティブ Ollama、および多数のチューニングオプションを利用できます。以下の設定をご覧ください。

プラグインとホスト連携

SocratiCode は、ネイティブエージェントプラグイン、VS Code エディター拡張機能、または直接設定するローカル stdio MCP サーバーとしてインストールできます。これらは別々の連携方式であり、設定と更新の手順もそれぞれ異なります。

SocratiCode エンジンの実行には、PATH上にあるnpxと Node.js 18.17 以降が必要です。一部のホストでは、より新しいバージョンの Node.js が必要です。デフォルトのローカルスタックを使用する場合は、Docker も起動している必要があります。Qdrant が外部にあり、埋め込みに検出済みのネイティブ Ollama インスタンス、クラウドプロバイダー、または外部プロバイダーのいずれかを使用する場合、Docker は不要です。

ホスト	推奨される連携方式	適用範囲
Claude Code	ネイティブプラグイン	ユーザー
OpenAI Codex	ネイティブプラグイン	ユーザー
VS Code	エージェントプラグインまたはエディター拡張機能	現在の VS Code プロファイル
Cursor	ローカル Cursor プラグインまたは直接 MCP	ユーザーまたはプロジェクト
Gemini CLI	直接 MCP	ユーザー
Continue	直接 MCP	プロジェクトまたはユーザー設定
Cline	直接 MCP	プロジェクトまたはユーザー設定
Zed	直接 MCP	ユーザーまたはプロジェクトの設定
OpenCode	直接 MCP	プロジェクトまたはユーザー設定

Claude Code プラグイン（Claude Code ユーザーに推奨）

ネイティブプラグインには、MCP サーバー、ワークフロースキル、エージェントの指示が同梱されています。現在のユーザー向けにインストールします。

claude plugin marketplace add giancarloerra/socraticode
claude plugin install --scope user socraticode@socraticode
claude plugin list

インストール後、新しい Claude Code セッションを開始してください。既存のセッションでは、新たにインストールしたプラグインは読み込まれません。自動更新を有効にするには、/pluginを開き、Marketplacesを選択してsocraticodeを選び、自動更新を有効にしてください。手動で更新するには、次のコマンドを実行します。

claude plugin marketplace update socraticode
claude plugin update --scope user socraticode@socraticode

更新後、/reload-pluginsを実行するか、新しいセッションを開始してください。以前 SocratiCode を単独の MCP サーバーとして追加していた場合は、重複を避けるためにclaude mcp remove socraticodeで削除してください。プラグインにはサーバーが含まれています。

カスタムプロバイダーまたは外部 Qdrant を使用する場合は、継承する環境変数を Claude Code のユーザー設定に記述し、セッションを再起動してください。

{
  "env": {
    "EMBEDDING_PROVIDER": "openai",
    "OPENAI_API_KEY": "<your key>"
  }
}

ユーザー単位のこのファイルは非公開にするか、プロセスの環境変数を通じてシークレットを指定してください。シークレット値を決してコミットしないでください。

エンジンバージョンの固定

デフォルトでは、プラグインは npx -y --prefer-online socraticode@latest を起動し、サーバーの起動ごとに npm で最新リリースを確認します。起動のたびに個別に解決されるため、同じホスト上でも異なるタイミングで起動した2つのサーバーが、異なるリリースを実行する場合があります。

SOCRATICODE_SPEC はパッケージ指定を置き換えます。設定されていない場合は socraticode@latest に解決され、ランチャーは変更されないため、既存のインストールで再設定は不要です。プラグインのサーバーが環境変数を継承する場所、つまり Claude Code のユーザー設定で設定してください。

{
  "env": {
    "SOCRATICODE_SPEC": "[email protected]"
  }
}

デフォルトに戻すにはエントリーを削除してください。空文字列は値であり、未設定とは異なるため、パッケージ指定として npm に渡されます。

これにより、そのホスト上のすべてのサーバーが同じビルドを解決します。メタデータの取得には引き続き npm に接続するため、起動が完全にオフラインになるわけではありませんが、固定したバージョンは初回の解決後に npx キャッシュに保存され、新しいリリースごとに再ダウンロードされることはありません。エンジンを固定すると自動更新されなくなるため、リリースを取り込む場合は値を意図的に更新してください。

これは Claude Code プラグインにのみ適用されます。Codex と Cursor は、ランチャーが変更されていない共有の .mcp.json を読み込みます。VS Code 拡張機能では、同等の socraticode.command および socraticode.args 設定を利用できます。

Claude Code プラグインのドキュメントを参照してください。

Claude Code の MCP のみのインストール

同梱スキルを含めずにユーザー単位でインストールする場合：

claude mcp add --scope user socraticode -- npx -y --prefer-online socraticode@latest
claude mcp list

新しいセッションを開始するか、/mcp を実行して 再接続 を選択してください。明示的な @latest コマンドは、サーバーの起動ごとに公開済みの最新エンジンを確認します。--scope user を省略すると、claude mcp add はデフォルトでプロジェクト単位のスコープになります。Claude Code MCP のドキュメントを参照してください。

OpenAI Codex プラグイン

Codex プラグインには、SocratiCode の MCP サーバー、スキル、指示が同梱されています。Git マーケットプレイスを追加し、現在のユーザー向けにプラグインをインストールします。

codex plugin marketplace add giancarloerra/socraticode --ref main
codex plugin add socraticode@socraticode
codex plugin list --available --json

インストール後、新しい Codex タスクまたは CLI セッションを開始してください。既存のタスクを再度開いても、新しくインストールしたスキルや MCP ツールは読み込まれません。次のコマンドで更新と確認を行います。

codex plugin marketplace upgrade socraticode
codex plugin add socraticode@socraticode
codex plugin list --available --json

Codex Desktop で SocratiCode の起動に No such file or directory エラーが発生する場合、Codex が npx を見つけられていない可能性があります。command -v npx を実行してください。一部のデスクトップ起動では /usr/bin:/bin:/usr/sbin:/sbin のみが使用されます。npx が別の場所にインストールされている場合は、以下のカスタム Codex 設定でそのディレクトリを PATH に追加してから、Codex を再起動してください。

Codex には公開プラグインディレクトリがありますが、SocratiCode は現在そこに公開されていません。プラグインは ChatGPT デスクトップの Codex 環境と Codex CLI でサポートされています。Codex IDE 拡張機能がサポートするのは、共有 MCP 設定であり、プラグインの検出ではありません。OpenAI プラグインのドキュメントを参照してください。

Codex では現在、プラグインに同梱された MCP サーバーの有効化とツールポリシーを設定できますが、同梱定義に対するユーザー単位の環境変数オーバーライドは、ドキュメント化されていません。カスタム SocratiCode 変数を使いながらプラグインのスキルを維持するには、同梱サーバーのみを無効にし、~/.codex/config.toml にトップレベルのサーバーを1つ追加します。

[plugins."socraticode@socraticode".mcp_servers.socraticode]
enabled = false

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

[mcp_servers.socraticode.env]
QDRANT_MODE = "external"
QDRANT_URL = "https://xyz.qdrant.io"

Codex を再起動し、プラグインのスキルが引き続き利用できることを確認してから、/mcp または codex mcp list を使って、SocratiCode サーバーがちょうど1つだけ有効になっていることを確認してください。同梱 MCP サーバーのポリシーとCodex 設定リファレンスを参照してください。

OpenAI Codex の MCP のみのインストール

codex mcp add は、ユーザー設定を ~/.codex/config.toml に書き込みます。

codex mcp add socraticode -- npx -y --prefer-online socraticode@latest
codex mcp list

インストール後、新しいタスクまたは CLI セッションを開始してください。同等の TOML は次のとおりです。

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

インラインの env = { ... } と、ネストされた [mcp_servers.socraticode.env] テーブルのどちらも有効です。通常は CLI の --env KEY=value オプションのほうが明確です。OpenAI Codex MCP のドキュメントを参照してください。

VS Code Agent Plugin

このプラグインには、MCP サーバー、スキル、VS Code のネイティブエージェント向けのエージェント指示が含まれています。SocratiCode エディター拡張機能とは別のものです。

1. インストールする前に、現在の VS Code プロファイルにこの設定全体を追加します。

   {
     "chat.plugins.enabled": true
   }
   

2. コマンドパレットから Chat: Install Plugin From Source を実行し、https://github.com/giancarloerra/socraticode を入力します。

3. 新しい Chat セッションを開始します。

4. Agent Plugins - Installed で SocratiCode を確認し、MCP: List Servers を実行してサーバーが起動していることを確認します。

インストール済みのエージェントプラグインを更新するには Extensions: Check for Extension Updates を実行し、新しい Chat セッションを開始します。VS Code Agent Plugins を参照してください。

VS Code では、プラグインに同梱された MCP 定義に対するユーザー単位の環境変数オーバーレイは文書化されていません。プラグインのスキルを維持したままカスタム変数を適用するには、MCP: List Servers を実行して、同梱された SocratiCode サーバーを無効にし、MCP: Open User Configuration から次のユーザースコープの直接サーバーを追加します。

{
  "servers": {
    "socraticode-configured": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

新しい Chat を開始し、MCP: List Servers を使って socraticode-configured のみが有効であることを確認します。別のローカルファイルから変数を読み込む場合は、env の代わりに envFile を使います。サーバーの有効化状態は、共有プラグイン定義とは別に保存されます。VS Code MCP server management と env / envFile reference を参照してください。

VS Code editor extension

別途公開されているエディター拡張機能では、SocratiCode サイドバー、ステータス項目、コマンド、ウォークスルー、インタラクティブなグラフの Web ビューが追加されます。現在の VS Code プロファイルで、Visual Studio Marketplace から SocratiCode をインストールします。

Microsoft VS Code 1.99 以降、および VS Code MCP プロバイダー API を実装する互換エディターでは、この拡張機能によって SocratiCode がエディターのネイティブ MCP レジストリに登録されます。Cline や Continue などの独立したクライアントは設定されません。

VS Code の AI 機能を有効にし、GitHub Copilot にサインインしてネイティブの Agent Chat を使用します。VS Code 1.122 以降では、ツール呼び出しに対応した BYOK モデルも、GitHub にサインインせずに使用できます。インストール後、ウィンドウを再読み込みして新しい Chat セッションを開始します。MCP: List Servers を実行して SocratiCode が起動していることを確認し、SocratiCode サイドバーを開いてエディター UI を確認します。更新するには、拡張機能ビューまたは Extensions: Check for Extension Updates を使用します。

Open VSX package は VS Code 派生エディターにインストールできますが、ネイティブ MCP 登録には、そのエディターが vscode.lm.registerMcpServerDefinitionProvider を実装している必要があります。VS Code MCP extension API を参照してください。

VS Code direct MCP installation

上にある Stable または Insiders バッジを使用し、VS Code でユーザースコープまたはワークスペーススコープを選択してから、新しい Chat セッションを開始します。プロジェクトスコープの .vscode/mcp.json では、次のオブジェクト全体を使用します。

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

MCP: List Servers で確認します。リリース後は、そのコマンドからサーバーを再起動し、新しい Chat セッションを開始します。

Cursor

このリポジトリには、MCP サーバー、スキル、指示を含む Cursor 形式のプラグインが含まれています。SocratiCode は現在 Cursor Marketplace で公開されていないため、Cursor がドキュメント化しているユーザースコープのローカルプラグインディレクトリを使用してください。リポジトリをクローンし、最新の SocratiCode リリースに示されている安定版をチェックアウトします。

mkdir -p ~/.cursor/plugins/local
git clone https://github.com/giancarloerra/socraticode.git ~/.cursor/plugins/local/socraticode
git -C ~/.cursor/plugins/local/socraticode checkout <latest-release-tag>

<latest-release-tag> は、そのページに表示されているリリースタグ（例: vX.Y.Z）に置き換えてください。Cursor を再起動するか、Developer: Reload Window を実行し、Customize でプラグインを確認します。それ以降の公開リリースに更新するには、次のようにします。

git -C ~/.cursor/plugins/local/socraticode fetch --tags
git -C ~/.cursor/plugins/local/socraticode checkout <latest-release-tag>

更新後は Cursor をリロードしてください。これらのコマンドは、main 上の未リリースのコミットではなく、意図的にリリースタグを追跡しています。Cursor プラグインを参照してください。

MCP を直接構成する場合は、上記の Cursor バッジを使用し、Cursor で目的のユーザースコープまたはプロジェクトスコープを選択します。新しい Agent チャットを開始し、Customize → MCPs で socraticode を確認します。インストールリンクはすでに最新リリースのエンジンコマンドを使用しています。Cursor MCP インストールリンクを参照してください。

現在のローカルプラグインは、ユーザーが構成可能な変数を宣言していません。そのスキルを維持したままカスタム変数を適用するには、Customize を開き、プラグインが提供する SocratiCode MCP サーバーを無効化し、ユーザーまたはプロジェクトの mcp.json に直接サーバーを 1 つ追加します。

{
  "mcpServers": {
    "socraticode-configured": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

Cursor をリロードし、Customize で socraticode-configured のみが有効になっていることを確認します。Cursor プラグイン変数および MCP サーバー管理を参照してください。

Open VSX 上の SocratiCode パッケージは VS Code 形式のエディタ拡張機能であり、Cursor プラグインではありません。その拡張機能をインストールしても、Cursor が VS Code のネイティブ MCP プロバイダー API を実装していることにはなりません。MCP の可用性が必要な場合は、ローカルプラグインまたは直接 MCP のパスを使用してください。

Gemini CLI

ユーザースコープの MCP サーバーを追加し、確認してから、実行中の Gemini CLI セッションを再起動します。

gemini mcp add --scope user socraticode npx -y --prefer-online socraticode@latest
gemini mcp list

高度な構成を行うには、ユーザースコープ（~/.gemini/settings.json）でサーバーを編集するか、ワークスペーススコープ（.gemini/settings.json）で定義し、env で指定された変数を明示的に転送します。

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "QDRANT_MODE": "external",
        "QDRANT_URL": "${QDRANT_URL}",
        "QDRANT_API_KEY": "${QDRANT_API_KEY}"
      }
    }
  }
}

シークレット値はコミットせず、プロセスの環境変数に保持してください。Gemini を再起動し、gemini mcp list を実行して構成されたサーバーを確認します。Gemini MCP 構成を参照してください。

Continue

Continue は YAML の mcpServers リストを使用します。プロジェクトスコープの場合は、.continue/mcpServers/socraticode.yaml を作成します。

name: SocratiCode MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: SocratiCode
    type: stdio
    command: npx
    args:
      - "-y"
      - "--prefer-online"
      - socraticode@latest

Continue は保存された構成を自動的に更新します。新しい Continue Agent セッションを開き、SocratiCode のツールが一覧表示されていることを確認します。ユーザースコープの場合は、同じ mcpServers リストを ~/.continue/config.yaml に追加します。Continue は、.continue/mcpServers/ に配置された完全な JSON MCP ファイルをインポートすることもできます。Continue MCP 構成および Continue YAML リファレンスを参照してください。

Cline

プロジェクトスコープの場合は、この完全なオブジェクトを .cline/mcp.json として保存します。ユーザースコープの場合は、Cline の MCP 設定インターフェースを通じて、同じサーバーを ~/.cline/data/settings/cline_mcp_settings.json に追加します。

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

新しい Cline タスクを開始し、MCP Servers ビューに socraticode とそのツールが表示されることを確認します。リリース後はサーバーを再接続してください。Cline MCP ドキュメントを参照してください。

Zed

設定 → AI → MCP サーバー → サーバーを追加 → ローカルサーバーを追加を開きます。UI はユーザースコープの設定を書き込みます。ここで、またはプロジェクトスコープの .zed/settings.json で、この完全なサーバー定義を使用してください。

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

SocratiCode の横のインジケーターが緑色で、ツールチップにサーバーはアクティブですと表示されることを確認してから、新しいエージェントの会話を開始します。リリース後は、MCP サーバーページからサーバーを再起動してください。

Zed は個人用の指示に ~/.config/zed/AGENTS.md を使用します。プロジェクトの指示には、最初に一致したサポート対象ファイルを使用します。これは AGENTS.md、CLAUDE.md、GEMINI.md、またはその他のサポート対象の互換ファイルの場合があります。Zed Rules は Skills と Instructions に置き換えられました。Zed MCP サーバー と Zed Instructions を参照してください。

OpenCode

プロジェクトスコープにはプロジェクトルートの opencode.json または opencode.jsonc を使用します。ユーザースコープには ~/.config/opencode/opencode.json または opencode.jsonc を使用します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socraticode": {
      "type": "local",
      "command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
      "enabled": true
    }
  }
}

OpenCode を再起動し、opencode mcp list でサーバーを確認します。リリース後は、npm が現在のエンジンを確認できるように OpenCode を再起動してください。これは OpenCode 1.x のスキーマです。

OpenCode V2 ではサーバー名が mcp.servers の下にネストされ、enabled の代わりに disabled を使用しますが、ローカルサーバーの定義はそれ以外は同等です。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "socraticode": {
        "type": "local",
        "command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
        "disabled": false,
        "environment": {}
      }
    }
  }
}

OpenCode 1.x MCP サーバー、OpenCode V2 MCP サーバー、OpenCode の設定 を参照してください。

その他のローカル stdio MCP ホスト

クイックスタート にある完全な JSON オブジェクトは、ドキュメントで mcpServers オブジェクトが指定されているホストにのみ適用されます。そのホストがドキュメント化しているユーザースコープまたはプロジェクトスコープでこれを追加し、MCP サーバーを再起動するか新しいセッションを開始して、ホストの MCP サーバーとツールの一覧で SocratiCode を確認してください。この例では、サーバーの起動時に常に最新の公開エンジンを確認します。リモート HTTP MCP サーバーのみをサポートするホストは、SocratiCode を直接起動できません。

SocratiCode の理由

SocratiCode を開発したのは、さまざまな言語にまたがる既存の大規模で複雑なコードベースで日常的に作業しており、それらを素早く理解して対応する必要があるからです。既存のソリューションは、範囲が狭すぎるか、本番利用にはテストが不十分か、不要な複雑さで肥大化していました。私は、深いコードベースインテリジェンスをうまく実現する単一の焦点を絞ったツールを求めました。ゼロセットアップ、無駄がなく、完全に自動で、邪魔にならないものです。

組み込みコード検索と SocratiCode の比較

機能	Claude Code	Cursor	VS Code Copilot	+ SocratiCode
テキスト／grep 検索	✅	✅	✅	✅
セマンティック検索	—	✅	✅¹	✅
ハイブリッド検索（融合）	—	—	—	✅
コード依存関係グラフ	—	—	✅²	✅
シンボルレベルの影響／波及範囲	—	—	—	✅
呼び出しフローの追跡（エントリーポイント → 呼び出し先）	—	—	—	✅
インタラクティブなビジュアルグラフエクスプローラー	—	—	—	✅
循環依存の検出	—	—	—	✅
コード以外のナレッジ（スキーマ、API 仕様）	—	—	—	✅
プロジェクト横断検索	—	—	—	✅
ブランチ対応のインデックス作成	—	—	—	✅
複数エージェントで共有できるインデックス	—	—	—	✅
ツールに依存しない（AI を切り替えても使い続けられる）	—	—	—	✅
完全ローカル／プライベート	✅	—³	—⁴	✅
中断後に再開できるインデックス作成	—	—	—	✅
ファイルのライブ監視	—	✅	—	✅

_{¹ VS Code Copilot：GitHub／Azure DevOps 経由のリモートインデックス。ローカルの「External Ingest」は段階的に提供中です。² LSP ベースの「Find References」／「Go to Definition」（「Usages」ツール）であり、完全な依存関係グラフではありません。³ Cursor：埋め込みは Cursor のサーバーで処理されます（転送中および保存時に暗号化）。⁴ VS Code Copilot：GitHub／Azure DevOps でホストされるリモートインデックス。出典：Cursor のドキュメント、Claude Code のドキュメント、VS Code Copilot のドキュメント。}

🔌 コンテキストはアシスタントではなく、コードベースとともにあります。 組み込みインデックス（Cursor、Copilot のもの）は、それぞれのツールに結び付いているため、アシスタントを切り替えると最初からやり直しになります。SocratiCode は独立しているため、一度インデックスを作成すれば、Claude Code、Cursor、Copilot、Windsurf、独自のプライベートモデル、またはそれらすべてに同時に接続できます。どのツールも、コードを同じように理解できます。

VS Code の 245 万行のコードベースでは、SocratiCode は grep ベースの AI エージェントよりも、アーキテクチャに関する質問に対して データ量を 61% 削減し、ステップ数を 84% 削減し、37 倍高速に回答します。ベンチマークの詳細 →

機能

• ハイブリッドコード検索 — HNSW インデックス作成、並行読み書き、ペイロードフィルタリングを備えた、用途に特化したベクトルデータベースである Qdrant を基盤としています。各チャンクには密ベクトルと BM25 疎ベクトルの両方が保存されます。Query API は単一のラウンドトリップで両方のサブクエリを実行し、Reciprocal Rank Fusion（RRF）で結果を統合します。セマンティック検索は、コード内に「authentication middleware」という正確な単語がなくても、概念的なクエリに対応します。BM25 は識別子やキーワードの完全一致検索に対応します。調整は不要で、すべてのクエリで両方の利点を活用できます。
• 設定可能な Qdrant — 組み込みの Docker Qdrant（デフォルト、設定不要）を使用するか、独自のインスタンス（セルフホスト、リモートサーバー、Qdrant Cloud）に接続します。環境変数 QDRANT_MODE、QDRANT_URL、QDRANT_API_KEY で設定します。
• 設定可能な Ollama — 組み込みの Docker Ollama（デフォルト、設定不要）を使用するか、独自の Ollama インスタンス（ネイティブインストール -GPU アクセス-、リモートサーバーなど）を指定します。環境変数 OLLAMA_MODE、OLLAMA_URL、EMBEDDING_MODEL、EMBEDDING_DIMENSIONS で設定します。
• 複数のプロバイダーによる埋め込み — 1 つの環境変数で、ローカル Ollama（プライベート、GPU アクセス）、Docker Ollama（設定不要）、OpenAI（text-embedding-3-small、最速）、Google Gemini（gemini-embedding-001、無料枠あり）、LM Studio（ローカルの OpenAI 互換サーバー）、LiteLLM（100 以上のプロバイダーを前段で仲介するプロキシゲートウェイ）を切り替えられます。プロバイダー固有の設定ファイルは不要です。
• プライバシーとセキュリティ — すべてがマシン上で動作し、コードがネットワークの外に出ることはありません。デフォルトの Docker セットアップには Ollama（埋め込み）と Qdrant（ベクトルストレージ）が含まれ、外部 API 呼び出しはありません。API コストもトークン制限もありません。エアギャップ環境やオンプレミス環境に適しています。オプションとしてクラウドプロバイダー（OpenAI、Google Gemini、Qdrant Cloud）も利用できますが、必須ではありません。
• AST 対応のチャンク分割 — ファイルを任意の行数で分割するのではなく、AST 解析（ast-grep）を使用して関数やクラスの境界で分割します。これにより、検索結果の品質が向上します。サポートされていない言語では、行ベースのチャンク分割にフォールバックします。
• 多言語対応のコード依存関係グラフ — ast-grep を使用し、19 以上の言語で import／require／use／include 文を静的解析します。dependency-cruiser などの外部ツールは不要です。循環依存を検出し、Mermaid のビジュアル図を生成します。
• 幅広い言語サポート — 標準であらゆるサポート対象ファイル形式に対応します。完全サポートされている言語には文法が同梱されています。GDScript では、互換性がある場合はオプションのネイティブパーサーを使用し、それ以外の場合は構文対応のフォールバックを使用します。標準以外の拡張子は、EXTRA_EXTENSIONS を設定してください。AI が読み取れるファイルであれば、SocratiCode でインデックスを作成できます。
• 増分インデックス作成 — 初回の完全なインデックス作成後は、変更されたファイルのみを再処理します。コンテンツハッシュは Qdrant に永続化されるため、サーバーを再起動しても状態が保持されます。
• バッチ処理と再開可能なインデックス作成 — ファイルは 50 個ずつバッチ処理され、各バッチの後に進捗が Qdrant にチェックポイントとして保存されます。プロセスがクラッシュまたは中断した場合、次回の実行で中断箇所から自動的に再開します。ハッシュを比較して、すでにインデックス済みのファイルはスキップされます。これによりピーク時のメモリ使用量を抑え、非常に大規模なコードベースでも信頼性の高いインデックス作成が可能になります。
• ファイルのライブ監視 — オプションでファイルの変更を監視し、インデックスをリアルタイムで更新できます（デバウンス 2 秒）。監視機能はコードグラフのキャッシュも無効化します。
• 並列処理 — ファイルを 50 個ずつのバッチで並列にスキャンしてチャンク分割し、I/O を高速化します。一方、埋め込み生成とアップサートは個別にバッチ処理し、スループットを最適化します。
• 複数プロジェクト対応 — 複数のプロジェクトを同時にインデックス化できます。各プロジェクトには、プロジェクトパスの追跡機能を備えた独立したコレクションが作成されます。
• プロジェクト横断検索 — 1 つのクエリで、関連する複数のプロジェクトを横断して検索できます。.socraticode.json または SOCRATICODE_LINKED_PROJECTS 環境変数でプロジェクトをリンクし、codebase_search に includeLinked: true を設定します。結果にはプロジェクトラベルが付与され、サイズが大きく異なるプロジェクト間でも比較可能なコサイン類似度で順位付けされます（いずれかの結果でコサイン類似度を利用できない場合は、順位融合にフォールバックします）。
• ブランチ対応のインデックス作成 — SOCRATICODE_BRANCH_AWARE=true を設定すると、Git ブランチごとに個別のインデックスを保持できます。各ブランチには専用の Qdrant コレクションが作成されるため、ブランチを切り替えると適切なインデックスにも即座に切り替わります。CI/CD パイプラインや PR レビューワークフローに最適です。パスから導出されるプロジェクト ID が必要です。明示的な ID（SOCRATICODE_PROJECT_ID、または .socraticode.json の projectId）は安定した ID として扱われ、サフィックスは付加されないため、これらのプロジェクトにはブランチ対応モードは適用されません。
• 除外ルールの尊重 — すべての .gitignore ファイル（ルートおよびネストされたもの）と、追加の除外設定用のオプションの .socraticodeignore を尊重します。妥当な組み込みデフォルト設定も含まれています。RESPECT_GITIGNORE=false で .gitignore の処理を無効にできます。INCLUDE_DOT_FILES=true を指定すると、ドットディレクトリ（例：.agent）を含めることができます。
• カスタムファイル拡張子 — 標準以外の拡張子（例：.tpl、.blade）を持つプロジェクトは、EXTRA_EXTENSIONS 環境変数または extraExtensions ツールパラメーターを使用して含めることができます。これらのファイルはプレーンテキストとしてインデックス化され、コードグラフではリーフノードとして表示されます（AST チャンク分割やシンボルはありません）。カスタム拡張子を正式な言語として扱う場合（完全な AST チャンク分割、シンボル、呼び出しグラフを含む）は、EXTENSION_LANGUAGE_MAP でマッピングします（例：.inc:php）。
• 設定可能なインフラストラクチャ — すべてのポート、ホスト、API キーを環境変数で設定できます。エンタープライズ環境向けに Qdrant API キーをサポートしています。
• エンタープライズ対応のシンプルさ — エージェント間の調整設定、メモリ制限用の環境変数、コーディネーター／コンダクターの容量調整項目、バックプレッシャーの設定はありません。SocratiCode は、複雑なプロセス内オーケストレーションではなく、本番環境で実績のあるインフラストラクチャ（Qdrant、実績のある埋め込み API）を活用して拡張します。
• 自動セットアップと設定不要 — Claude プラグイン／スキルをインストールするか、AI ホストの設定に MCP サーバーを追加するだけです。初回使用時にサーバーが Docker を自動で確認し、イメージを取得して Qdrant と Ollama のコンテナーを起動し、埋め込みモデルをダウンロードします。設定ファイル、YAML、環境変数、必須のネイティブコンパイルは不要です。オプションの GDScript パーサーは、互換性のあるネイティブビルドがない場合に安全にフォールバックします。Docker が動作する環境であれば、どこでも使えます。
• セッションの再開 — デフォルトでは、サーバーの起動時に MCP プロセスの作業ディレクトリに対応するインデックス済みプロジェクトを再開します。完全なインデックスには監視機能と増分キャッチアップ更新が適用され、中断されたインデックスは最後のチェックポイントから再開されます。明示的なプロジェクトリストと SOCRATICODE_AUTO_RESUME=all を使用すると、他のインデックス済みプロジェクトにも適用できます。
• 監視機能の自動開始 — デフォルトの SOCRATICODE_WATCHER=auto モードでは、起動時の再開時と codebase_index または codebase_update の実行後にファイル監視機能が開始されます。起動時に選択されなかった、インデックス作成が完了済みのプロジェクトでは、最初の検索、ステータス確認、またはグラフ操作時に監視機能がフォールバックで開始されます。manual では codebase_watch { action: "start" } による明示的な開始のみが許可され、off では監視機能の開始が完全に無効になります。
• 手動インデックススナップショット — SOCRATICODE_WATCHER=off と SOCRATICODE_AUTO_RESUME=off を設定すると、暗黙的なコードインデックス更新、埋め込み、グラフ作成が行われなくなります。既存のコードインデックスとグラフは引き続き読み取り可能です。codebase_index、codebase_update、または codebase_graph_build を明示的に実行して更新してください。
• Git をトリガーとする更新：SOCRATICODE_WATCHER=git を設定すると、アクティブなインデックス済みチェックアウトを 10 秒ごと、および検索、ステータス確認、グラフ要求の際に確認します。チェックアウトされた ref または HEAD が変更されると、既存の増分更新処理とグラフの調整が実行されます。明示的に監視を開始した場合も含め、ネイティブのファイル監視は無効のままです。
• コードグラフの自動構築 — コード依存関係グラフはインデックス作成後に自動で構築され、監視対象ファイルの変更時に再構築されます。グラフ構築の入力に影響しない更新（README、フィクスチャ、マイグレーションなど）では再構築せず、既存のグラフを再利用します。各構築では読み取った入力が記録され、そのすべてに変更がない場合に限り再構築がスキップされます。グラフに関連するファイルが追加された場合（構築時に確認した場所にファイルが現れた場合。ただし、除外ルールで除外されるファイルは除く）は再構築されます。また、設定に変更があった場合や、そのような記録がないグラフも再構築されます。強制的に再構築する場合を除き、codebase_graph_build を手動で呼び出す必要はありません。
• 複数エージェントの連携 — 複数の AI エージェント（それぞれが独自の MCP インスタンスを実行）が同じコードベースで同時に作業し、1 つのインデックスを共有できます。1 つのエージェントがインデックスを作成し、すべてのエージェントが同じデータを検索します。プロジェクトごとに実行される監視機能は 1 つだけで、すべてのエージェントがリアルタイム更新を利用できます。プロセス間のファイルロックにより、インデックス作成と監視が自動的に調整されます。一方のエージェントがテストを作成し、もう一方がコードを修正するワークフローや、計画エージェントと実装エージェントが並行して作業する場合に最適です。
• プロセス間の安全性 — ファイルベースのロック（proper-lockfile）により、複数の MCP インスタンスが同じプロジェクトのインデックス作成や監視を同時に行うことを防ぎます。クラッシュしたプロセスの古いロックは自動的に回収されます。別の MCP プロセスがすでにプロジェクトを監視している場合、codebase_status は誤って「inactive」と表示せず、「active (watched by another process)」と報告します。
• 並行処理ガード — インデックス作成とグラフ構築の重複実行を防ぎます。インデックス作成中に codebase_index を呼び出すと、2 つ目の処理を開始する代わりに現在の進捗が返されます。
• 安全な停止 — 長時間実行されるインデックス作成処理は、codebase_stop で安全に停止できます。現在のバッチを完了してチェックポイントを保存し、進捗をすべて保持します。codebase_index を再実行すると、中断箇所から再開します。
• 明示的な回収 — codebase_prune はストアに保存されている内容を一覧表示し、明示的な確認と適用を行った場合に限り、1 回につき 1 つの ID を削除します。保存済み ID の回収を参照してください。
• 安全なシャットダウン — サーバーのシャットダウン時には、実行中のインデックス作成処理に最大 60 秒の完了時間が与えられ、すべてのファイル監視が正常に停止し、すべてが正常に終了します。
• 構造化ログ — すべての操作は、可観測性のために構造化されたコンテキスト情報とともに記録されます。ログレベルは SOCRATICODE_LOG_LEVEL で設定できます。
• グレースフルデグラデーション — 監視中にインフラストラクチャが停止した場合、監視機能はクラッシュせず、バックオフして再試行します。

前提条件

依存関係	目的	インストール
Docker	Qdrant（ベクトル DB）と、デフォルトでは Ollama（埋め込み）を実行します	docker.com
PATH に npx が含まれる Node.js 18.17 以降	MCP サーバーを実行します	nodejs.org

デフォルトの managed モードでサーバーを使用する場合、Docker が起動している必要があります。

Qdrant コンテナは自動的に管理されます。QDRANT_MODE=external を設定し、QDRANT_URL をリモートまたはクラウドの Qdrant インスタンスに指定した場合は、Ollama（埋め込み）にのみ Docker が必要です。

デフォルトの auto モードでは、Ollama コンテナ（埋め込み）も自動的に管理されます。SocratiCode はまず Ollama がネイティブで起動しているか確認し、起動していればそれを使用します。そうでなければ、Docker コンテナを管理します。Docker イメージや埋め込みモデルの初回ダウンロードには、インターネット速度によって数分かかる場合があります。これは初回起動時のみ必要です。

macOS／Windows での埋め込み処理のパフォーマンス

macOS と Windows の Docker コンテナからは GPU にアクセスできません（Metal や CUDA のパススルーはできません）。小規模なプロジェクトでは問題ありませんが、中規模から大規模なコードベースでは、CPU のみのコンテナは明らかに低速です。

最高のパフォーマンスを得るには、Ollama をネイティブにインストールしてください。ollama.com/download からインストーラーをダウンロードして実行します。Ollama が起動すると、SocratiCode は自動的に検出して使用するため、追加の設定は不要です（埋め込みモデルがまだない場合、初回ダウンロードに数分かかることがあります）。これにより、macOS では Metal GPU アクセラレーション、Windows／Linux では CUDA を利用できます。

ローカルにインストールせずに速度を優先する場合は、クラウドベースの選択肢として、以下の OpenAI Embeddings と Google Generative AI Embeddings をご覧ください。OpenAI はローカルのセットアップが不要で、非常に高速です。Google の無料枠は利用できますが、レート制限があります。設定の詳細については、環境変数をご覧ください。

ワークフローの例

すべてのツールで projectPath のデフォルト値は現在の作業ディレクトリです。そのため、アクティブなプロジェクトのパスを指定する必要はありません。

User: "Index this project"
→ codebase_index {}
  ⚡ Indexing started in the background — call codebase_status to check progress
→ codebase_status {}
  ⚠ Full index in progress — Phase: generating embeddings (batch 1/1)
  Progress: 247/1847 chunks embedded (13%) — Elapsed: 12s
→ codebase_status {}
  ✓ Indexing complete: 342 files, 1,847 chunks (took 115.2s)
  File watcher: active (auto-updating on changes)

User: "Search for how authentication is handled"
→ codebase_search { query: "authentication handling" }
  Runs dense semantic search + BM25 keyword search in parallel, fuses results with RRF
  Returns top 10 results ranked by combined relevance

User: "What files depend on the auth middleware?"
→ codebase_graph_query { filePath: "src/middleware/auth.ts" }
  Returns imports and dependents
  (graph was auto-built after indexing — no manual build needed)

User: "Show me the dependency graph"
→ codebase_graph_visualize {}
  Returns a Mermaid diagram colour-coded by language

User: "Are there any circular dependencies?"
→ codebase_graph_circular {}
  Found 2 cycles: src/a.ts → src/b.ts → src/a.ts

User: "What breaks if I rename validateUser?"
→ codebase_impact { target: "validateUser" }
  Blast radius for symbol: validateUser
  Hop 1 (3 files): src/auth/login.ts, src/api/users.ts, tests/auth.test.ts
  Hop 2 (5 files): ...

User: "What does the server entry point actually do?"
→ codebase_flow {}
  Detected 4 entry point(s):
    main (cmd/server.go:10) — well-known-name:main
    healthz (src/api/routes.ts:42) — framework:get
    ...
→ codebase_flow { entrypoint: "main" }
  └── main (cmd/server.go:10)
      ├── loadConfig (cmd/server.go:15)
      └── startServer (src/server.ts:8)
          └── ...

User: "Who calls bcryptCompare and what does it call?"
→ codebase_symbol { name: "bcryptCompare" }
  Symbol: bcryptCompare (function)
  Defined: src/auth/hash.ts:42–58
  Callers (3): ← src/auth/login.ts:12, ← src/auth/reset.ts:30 ...
  Callees (1): → compare [unique, 1 candidate]

エージェント向けの指示

Claude Code プラグインのユーザー向け：これらの指示は、SocratiCode プラグインのスキルとして自動的に含まれます。CLAUDE.md にコピーする必要はありません。以下のセクションは、Claude Code 以外のホスト（VS Code、Cursor、Claude Desktop など）向けです。

最良の結果を得るには、次のような指示を AI アシスタントのプロジェクトレベルの指示ファイルに追加してください。基本原則は、読む前に検索することです。インデックスを使えば、ミリ秒単位でコードベースの全体像を把握できます。ファイルを直接読むのはコストが高く、コンテキストを消費します。

これらの指示を配置する場所（IDE ごと）：

IDE／ツール	指示ファイル
Claude Code	プロジェクトのルートにある CLAUDE.md（自動的に読み込まれます）。プラグインのユーザーには、スキルを通じて自動的に提供されます。
Cursor	プロジェクトのルートにある AGENTS.md、または専用のルールファイル .cursor/rules/socraticode.mdc
VS Code Copilot	.github/copilot-instructions.md、または VS Code のユーザープロンプトフォルダーにあるカスタム指示ファイル
Zed	プロジェクトのルートにある AGENTS.md、または個人用の指示ファイル ~/.config/zed/AGENTS.md。Zed は、対応するプロジェクト指示ファイルのうち最初に見つかったものを使用します。
Windsurf	プロジェクトのルートにある .windsurfrules
Claude Desktop／Cline	システムプロンプトの設定に直接追加します

重要な理由：MCP サーバーをインストールするだけでも、エージェントは SocratiCode のツールを利用できるようになりますが、ツールをいつ使うかはエージェントが判断します。これらの指示をプロジェクトに追加すると、エージェントはファイルを直接読むよりも一貫して SocratiCode の検索を優先し、依存関係を考慮するタスクではグラフを活用し、「読む前に検索する」ワークフローに従うようになります。

## Codebase Search (SocratiCode)

This project is indexed with SocratiCode. Always use its MCP tools to explore the codebase
before reading any files directly.

### Workflow

1. **Start most explorations with `codebase_search`.**
   Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.
   - Use broad, conceptual queries for orientation: "how is authentication handled",
     "database connection setup", "error handling patterns".
   - Use precise queries for symbol lookups: exact function names, constants, type names.
   - Prefer search results to infer which files to read — do not speculatively open files.
   - **When to use grep instead**: If you already know the exact identifier, error string,
     or regex pattern, grep/ripgrep is faster and more precise — no semantic gap to bridge.
     Use `codebase_search` when you're exploring, asking conceptual questions, or don't
     know which files to look in.

2. **Follow the graph before following imports.**
   Use `codebase_graph_query` to see what a file imports and what depends on it before
   diving into its contents. This prevents unnecessary reading of transitive dependencies.
   - **Before modifying or deleting a file**, check its dependents with `codebase_graph_query`
     to understand the blast radius.
   - **When planning a refactor**, use the graph to identify all affected files before
     making changes.

3. **Use Impact Analysis BEFORE refactoring, renaming, or deleting code.**
   The symbol-level call graph (`codebase_impact`, `codebase_flow`, `codebase_symbol`,
   `codebase_symbols`) goes one step deeper than the file graph: it knows which
   functions and methods call which.
   - `codebase_impact` answers "what breaks if I change X?" (blast radius — every file
     that transitively calls into the target).
   - `codebase_flow` answers "what does this code do?" by tracing forward from an entry
     point. Call with no `entrypoint` to discover candidate entry points (auto-detected
     via orphans, conventional names like `main()`, framework routes, tests).
   - `codebase_symbol` gives a 360° view of one function: definition, callers, callees.
   - `codebase_symbols` lists symbols in a file or searches by name.
   - Always prefer these over reading multiple files when the question is about
     dependencies between functions, not concepts.

4. **Read files only after narrowing down via search.**
   Once search results clearly point to 1–3 files, read only the relevant sections.
   Never read a file just to find out if it's relevant — search first.

5. **Use `codebase_graph_circular` when debugging unexpected behaviour.**
   Circular dependencies cause subtle runtime issues; check for them proactively.
   Also run `codebase_graph_circular` when you notice import-related errors or unexpected
   initialisation order.

6. **Check `codebase_status` if search returns no results.**
   The project may not be indexed yet. Run `codebase_index` if needed, then wait for
   `codebase_status` to confirm completion before searching.

7. **Leverage context artifacts for non-code knowledge.**
   Projects can define a `.socraticodecontextartifacts.json` config to expose database
   schemas, API specs, infrastructure configs, architecture docs, and other project
   knowledge that lives outside source code. These artifacts are auto-indexed alongside
   code during `codebase_index` and `codebase_update`.
   - Run `codebase_context` early to see what artifacts are available.
   - Use `codebase_context_search` to find specific schemas, endpoints, or configs
     before asking about database structure or API contracts.
   - If `codebase_status` shows artifacts are stale, run `codebase_context_index` to
     refresh them.

### When to use each tool

| Goal | Tool |
|------|------|
| Understand what a codebase does / where a feature lives | `codebase_search` (broad query) |
| Find a specific function, constant, or type | `codebase_search` (exact name) or grep if you know already the exact string |
| Find exact error messages, log strings, or regex patterns | grep / ripgrep |
| See what a file imports or what depends on it | `codebase_graph_query` |
| Check blast radius before modifying or deleting a file | `codebase_impact` (symbol-level) or `codebase_graph_query` (file-level) |
| **What breaks if I change function X?** | `codebase_impact target=X` |
| **What does this entry point actually do?** | `codebase_flow entrypoint=X` |
| **List entry points in this codebase** | `codebase_flow` (no args) |
| **Who calls this function and what does it call?** | `codebase_symbol name=X` |
| **What functions/classes exist in this file?** | `codebase_symbols file=path` |
| **Search for symbols by name across the project** | `codebase_symbols query=X` |
| Spot architectural problems | `codebase_graph_circular`, `codebase_graph_stats` |
| Visualise module structure | `codebase_graph_visualize` |
| Verify index is up to date | `codebase_status` |
| Discover what project knowledge (schemas, specs, configs) is available | `codebase_context` |
| Find database tables, API endpoints, infra configs | `codebase_context_search` |

セマンティック検索を最初に使う理由：codebase_search を 1 回呼び出すだけで、コードベース全体から順位付けされ、重複が除去されたスニペットがミリ秒単位で返されます。これにより、トークンの消費をほぼ抑えながら全体像を把握できます。見当をつけてファイルを開くよりも、はるかに低コストです。関連するファイルがわかったら、対象を絞って読むことで、より速く、より正確に作業できます。ただし、正確な文字列やパターンがわかっている場合は、grep が適切なツールです。クエリに合ったものを使ってください。

**インデックス作成中は接続を維持してください。**インデックス作成はバックグラウンドで実行され、MCP サーバーはツール呼び出しに応答していない間も動作し続けます。ただし、アイドル状態の MCP 接続を一定時間後に切断する MCP ホストもあり、その場合はバックグラウンド処理が中断される可能性があります。codebase_index の開始後、完了するまでおよそ 60 秒ごとに codebase_status を呼び出すよう AI に指示してください。これにより、ホストとの接続を維持し、リアルタイムで進捗を確認できます。

設定

インストール

プラグインとホスト連携に記載されている、ホスト固有の手順に従ってください。インストール範囲、有効化、確認、更新のほか、各ホストで実際に使用される設定スキーマについて説明しています。

ソースからインストールする（コントリビューター向け）

git clone https://github.com/giancarloerra/socraticode.git
cd socraticode
npm install
npm run build

MCP ホストがサポートするユーザーまたはプロジェクトのスコープに、node /absolute/path/to/socraticode/dist/index.js を登録してから、サーバーを再起動するか、新しいセッションを開始してください。ホストの MCP サーバー一覧で SocratiCode を確認します。更新するには、クローン内で git pull --ff-only、npm install、npm run build を実行し、MCP サーバーを再起動して、もう一度確認してください。

MCP ホストの設定バリエーション

以下の例では、SocratiCode の設定を示すために、一般的な JSON の mcpServers 形式を使用しています。プラグインとホスト連携に記載されているホスト固有のスキーマを使って、同じコマンドと環境変数の値を適用してください。Continue、Gemini CLI、VS Code、Zed、OpenCode では、設定パスやラッパーがそれぞれ異なります。

デフォルト（設定不要、ソースから実行）

npx を使う場合は、以下の node コマンドとソースパスを "command": "npx" および "args": ["-y", "--prefer-online", "socraticode@latest"] に置き換えてください。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"]
    }
  }
}

ヒント：デフォルトの OLLAMA_MODE=auto は起動時にネイティブの Ollama（ポート 11434）を検出し、利用可能であればそれを使用します。利用できない場合は、管理対象の Docker コンテナにフォールバックします。設定を自己文書化するには、明示的な値を指定した "env" ブロックを追加してください。すべてのオプションについては、環境変数を参照してください。

外部 Ollama（ネイティブインストール）

Ollama をネイティブにインストールしている場合は、OLLAMA_MODE=external を設定し、インスタンスを指定してください。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "OLLAMA_MODE": "external",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

埋め込みモデルは初回使用時に自動的に取得されます。事前にダウンロードするには、ollama pull nomic-embed-text を実行してください。

リモート Ollama サーバー

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "OLLAMA_MODE": "external",
        "OLLAMA_URL": "http://gpu-server.local:11434"
      }
    }
  }
}

OpenAI の埋め込み

ローカルの Ollama ではなく、OpenAI のクラウド埋め込み API を使用します。API キーが必要です。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

デフォルト値：EMBEDDING_MODEL=text-embedding-3-small、EMBEDDING_DIMENSIONS=1536。品質を高めるには、text-embedding-3-large と EMBEDDING_DIMENSIONS=3072 を使用してください。

Google Generative AI の埋め込み

Google の Gemini 埋め込み API を使用します。API キーが必要です。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "google",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}

デフォルト値：EMBEDDING_MODEL=gemini-embedding-001、EMBEDDING_DIMENSIONS=3072。

LM Studio（ローカル、OpenAI 互換）

LM Studio には、http://localhost:1234/v1 で OpenAI 互換の API を公開するローカルサーバーが付属しています。LM Studio で埋め込みモデルを ホストしたい場合（たとえば、チャットモデルと埋め込みモデルの両方を LM Studio に 集約する場合や、GGUF モデルを管理するための Mac／Windows 向けデスクトップ UI が 必要な場合）は、このプロバイダーを使用してください。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "lmstudio",
        "EMBEDDING_MODEL": "nomic-embed-text-v1.5",
        "EMBEDDING_DIMENSIONS": "768"
      }
    }
  }
}

デフォルト値はありません — EMBEDDING_MODEL と EMBEDDING_DIMENSIONS は必須です。 LM Studio には すぐに使える埋め込みモデルが付属していないため、ローカルサーバータブで自分で読み込む必要があります。SocratiCode は、 どちらか一方でも設定されていない場合、即座にエラーで終了します。

オプション：デフォルト以外のポートを使う場合は LMSTUDIO_URL（デフォルトは http://localhost:1234/v1）を指定します。 LM Studio で API キー認証を有効にしている場合は LMSTUDIO_API_KEY を指定します。 /v1/models エンドポイントがない OpenAI 互換サーバーでは LMSTUDIO_ALLOW_MISSING_MODEL_LISTING=true を指定します（以下を参照）。

このプロバイダーは、OpenAI の埋め込み API に対応する他のサーバーでも使用できます。 HuggingFace Text Embeddings Inference （TEI）のような単一モデルのサーバーでは、モデルが起動時に固定され、/v1/models が 404 を返します。そのため、準備状態の確認で /v1/embeddings をプローブするフォールバックを有効にするには、LMSTUDIO_ALLOW_MISSING_MODEL_LISTING=true が必要です。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "lmstudio",
        "LMSTUDIO_URL": "http://localhost:8080/v1",
        "EMBEDDING_MODEL": "BAAI/bge-m3",
        "EMBEDDING_DIMENSIONS": "1024",
        "LMSTUDIO_ALLOW_MISSING_MODEL_LISTING": "true"
      }
    }
  }
}

EMBEDDING_MODEL はサーバーの起動時に指定した値（TEI の --model-id）です。 EMBEDDING_DIMENSIONS はそのモデルの出力幅に合わせる必要があります。プローブで 値を検証し、一致しない場合は即座にエラーで終了します。/v1/models がない場合、 それ以外に照合できるものがないためです。

LiteLLM（プロキシゲートウェイ、100 以上のプロバイダー）

LiteLLM プロキシサーバーは、OpenAI 互換の /v1/embeddings エンドポイントを公開し、100 以上の基盤プロバイダー（OpenAI、Anthropic、 Cohere、Voyage、HuggingFace、Bedrock、Vertex AI、Ollama など）にリクエストを振り分けます。 このプロバイダーは、一元化されたキー管理（MCP の各設定に N 個のプロバイダーキーを分散させる代わりに、開発者ごとに仮想キーを 1 つ使用）、埋め込みバックエンド間のフォールバック／負荷分散、またはバックエンドを切り替えても維持できるプロバイダーに依存しないインデックスが必要な場合に使用してください。

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["/absolute/path/to/socraticode/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "litellm",
        "LITELLM_API_KEY": "sk-...",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSIONS": "1536"
      }
    }
  }
}

LITELLM_API_KEY、EMBEDDING_MODEL、EMBEDDING_DIMENSIONS はすべて必須です。 LiteLLM プロキシは常に認証を行います（マスターキーまたは /key/generate で生成した仮想キー）。エイリアス名と基盤となる次元数は config.yaml で指定します。SocratiCode は、いずれかが不足している場合、ただちにエラーで終了します。

任意の設定：LITELLM_URL（デフォルトは http://localhost:4000/v1）— /v1 サフィックスを含める必要があります。LITELLM_SEND_DIMENSIONS=true を設定すると、OpenAI の dimensions パラメーターをプロキシ経由で転送します（text-embedding-3-* や voyage-3 など、Matryoshka に対応したバックエンドでのみ安全です。Matryoshka 非対応のバックエンドではリクエストが拒否されます）。

これは LiteLLM の プロキシサーバー 用クライアントであり、LiteLLM Python ライブラリ用ではありません。また、provider/model 形式の文字列を独自にルーティングすることはありません。 EMBEDDING_MODEL をそのまま LITELLM_URL に送信し、その名前がプロキシの /v1/models に存在する必要があります。OpenRouter などのバックエンドを利用するには、プロキシの config.yaml の model_list に登録してください（model_name を EMBEDDING_MODEL に設定する値に、litellm_params.model を openrouter/qwen/qwen3-embedding-8b などに設定します）。ルーティングはプロキシが行い、SocratiCode はエイリアスを送信するだけです。LITELLM_URL に LiteLLM 以外のエンドポイントを直接指定できるのは、そのエンドポイントが OpenAI 互換であり、/v1/models に EMBEDDING_MODEL が掲載され、自身のネイティブモデル ID（LiteLLM の provider/ プレフィックスなし）でそのモデルを受け付ける場合に限られます。

Git Worktrees（ディレクトリ間でインデックスを共有）

git worktrees を使用する場合、または同じリポジトリが複数のディレクトリに存在するワークフローでは、通常、それぞれのパスに個別の Qdrant インデックスが作成されます。つまり、実質的に同じコードベースに対して、埋め込みとストレージが重複します。

SOCRATICODE_PROJECT_ID を設定すると、同じプロジェクトのすべてのディレクトリで単一のインデックスを共有できます。

git worktree の検出機能がある MCP ホスト（例：Claude Code）

一部の MCP ホスト（Claude Code など）は、git worktree のリンクをたどってプロジェクトのルートを解決します。worktree はメインリポジトリの .git ディレクトリを参照するため、ホストはすべての worktree を同じプロジェクト設定に自動的にマッピングします。つまり、メインのチェックアウトで MCP サーバーを一度だけ設定すれば、すべての worktree が自動的にその設定を引き継ぎます。

Claude Code の場合は、メインのチェックアウトからローカルスコープでサーバーを追加します。

cd /path/to/main-checkout
claude mcp add -e SOCRATICODE_PROJECT_ID=my-project --scope local socraticode -- npx -y --prefer-online socraticode@latest

このリポジトリから作成されたすべての worktree は、共有プロジェクト ID を使って socraticode に自動的に接続します。worktree ごとの設定は不要です。

注： これは git worktree でのみ機能します。同じリポジトリを個別に git clone した場合、.git ディレクトリはそれぞれ独立しているため、設定は共有されません。

その他の MCP ホスト（プロジェクトごとの .mcp.json）

git worktree のパスを解決しない MCP ホストでは、各 worktree のルート（およびメインのチェックアウト）に .mcp.json を追加します。

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

追跡対象にしたくない場合は、.mcp.json を .gitignore に追加してください。

仕組み

この設定では、/repo/main、/repo/worktree-feat-a、/repo/worktree-fix-b で実行されているエージェントが、同じ codebase_my-project、codegraph_my-project、context_my-project の Qdrant コレクションを共有します。

実際の動作：

• セマンティックインデックスには、最後にファイル変更を検知したワークツリーの内容が反映されます。ただし、ブランチ間の違いは通常、少数のファイルに限られるため、すべてのワークツリーでインデックスの精度は 99% 以上です
• AI エージェントは自身のワークツリーから実際のファイル内容を読み取ります。共有インデックスは、検索とナビゲーションにのみ使用されます
• 変更を main にマージすると、ファイルウォッチャーが変更されたファイルのインデックスを再作成し、インデックスが収束します

チーム共有インデックス（projectId をコミット）

前述の環境変数による方法はマシンごとに適用されます。チームメイト全員（および CI ランナー）が自動的に同じ識別子を使用できるようにするには、プロジェクトルートの .socraticode.json に projectId をコミットします。

{
  "projectId": "my-project"
}

これにより、リポジトリをどこにチェックアウトしても、またどのユーザーアカウントが所有していても、同じ codebase_my-project、codegraph_my-project、context_my-project の Qdrant コレクションが参照されます。Qdrant インスタンスを共有するチームには、この設定をおすすめします。インデックスは一度作成すれば、OS ユーザーやファイルシステムの構成がまったく異なるノート PC 間でも、チーム全員が利用できます。

値には [a-zA-Z0-9_-]+ を指定する必要があります。前後の空白は削除され、値が指定されていない場合や空の場合は、パスのハッシュを使ったデフォルト値にフォールバックします。SOCRATICODE_PROJECT_ID 環境変数が設定されている場合は、このファイルの値より優先されます。リポジトリを変更せずに、マシンごとに一時的な値を指定する際に便利です。

プロジェクト間検索（リンクされたプロジェクト）

関連する複数のリポジトリやパッケージにまたがって作業する場合、それらを単一のクエリでまとめて検索できます。

設定

プロジェクトルートに .socraticode.json ファイルを作成します。

{
  "linkedProjects": [
    "../shared-lib",
    "/absolute/path/to/other-project"
  ]
}

または、SOCRATICODE_LINKED_PROJECTS 環境変数を設定します（パスをカンマ区切りで指定）。

SOCRATICODE_LINKED_PROJECTS="../shared-lib,/absolute/path/to/other-project"

両方の設定元がマージされ、重複は除去されます。相対パスはプロジェクトルートを基準に解決されます。存在しないパスは通知なしでスキップされます。

使用方法

codebase_search に includeLinked: true を渡します。

includeLinked: true を指定して「authentication middleware」を検索します

結果は、各ヒットが自身のプロジェクト内でどの位置にあるかではなく、クエリとのコサイン類似度に基づいて順位付けされます。順位が意味を持つのは、その順位が付けられたリスト内だけです。そのため、順位を使うと、小さなプロジェクトの最上位ヒットが大きなプロジェクトのはるかに強いヒットより上位になる可能性があり、プロジェクト間のスコアはすべて 1/61 ≈ 0.016 以下に制限されます。これは SEARCH_MIN_SCORE のデフォルト値 0.10 を下回るため、結果がすべて破棄されていました。コサイン類似度は、同じクエリベクトルに対する絶対的な指標なので、プロジェクト間で比較でき、しきい値が想定するのと同じスケールになります。単一プロジェクトの検索には影響せず、引き続き Qdrant のサーバー側 RRF を使用します。

すべてのヒットについてコサイン類似度を計算できない場合は、異なる2つの指標を混在させるのではなく、そのクエリ全体で以前の順位融合にフォールバックします。次の3つのケースで検出され、それぞれコレクション名とともにログに記録されます。有効な密ベクトルを持たないチャンクが返された場合、ベクトルの大きさがゼロの場合、ベクトルの次元数がクエリのものと異なる場合です。最後のケースには限界がある点に注意してください。異なる次元数のモデルで埋め込みされたコレクションは検出できますが、同じ次元数を出力する別のモデルは区別できず、そのままスコアが計算されます。そのため、リンクされたプロジェクトでは1つの埋め込みモデルを使用してください。

フォールバックでは、1件のヒットが寄与するスコアは最大 1/(60+0+1) ≈ 0.0164 です。ただし、複数のチャンクとして一致するファイルはチャンクごとに寄与が累積されるため（1/61 + 1/62 ≈ 0.0325）、最終スコアはこの上限を超えることがあります。いずれの場合もデフォルト値の 0.10 を大きく下回るため、このケースに該当したクエリでは minScore を下げてください。

結果には、各結果がどのプロジェクトに由来するかを示す [project-name] ラベルが付きます。重複排除は単一プロジェクト内で行われます。異なる2つのプロジェクトに同じ相対パスがある場合、それぞれ別の結果として保持されます。これは実際に異なるファイルであり、自身の src/util.ts とリンクされたプロジェクトの src/util.ts は相互に置き換えられないためです。1つのプロジェクト内では、パスの出現箇所のうち優先度が高いものが採用されます。

注記： リンクされた各プロジェクトは、検索する前に個別にインデックス化（codebase_index）する必要があります。

Python のインポートルート

インポートルートがプロジェクトルート、src/、lib/、または pyproject.toml で宣言されたルートではない Python プロジェクトは、実行時のパスエントリーをプロジェクトルートの .socraticode.json に記述できます。たとえば、Apache Airflow は dags/ を sys.path に追加するため、DAG リポジトリでは次のように宣言できます。

{
  "pythonRoots": ["dags"]
}

エントリーには、プロジェクトルートからの相対パスで指定した、既存のディレクトリを記述する必要があります。エントリーは前後の空白が削除され、正規化され、宣言された順序を保ったまま重複が排除されます。絶対パス、プロジェクトルート外のパス（シンボリックリンクによる逸脱を含む）、存在しないパス、ファイル、および文字列以外の値は無視されます。pythonRoots が存在しない、空である、または使用可能なエントリーがない場合、Python の解決動作はこれまでとまったく同じです。

解決時には、既存の検索対象が引き続き最初に試されます。プロジェクトルート、プロジェクトルートの src/ と lib/、およびインポート元ファイルのディレクトリです。 その後、設定されたルートが宣言順に試され、続いて該当する pyproject.toml マニフェストから導出されたルートが試されます。これにより、既存プロジェクトの動作を変えることなく、明示的に指定された実行時のレイアウトをマニフェストから導出された代替ルートより優先できます。

有効なルートの追加、削除、順序変更、または変更を行うと、次回の増分更新時にコードグラフが再構築されます。コード／ベクトルインデックスは再構築も無効化もされず、手動での再インデックスは不要です。

ブランチ対応インデックス

デフォルトでは、プロジェクトのすべてのブランチで同じインデックスを共有します。ブランチを切り替えると、変更されたファイルはウォッチャーによって再インデックスされ、インデックスは現在のブランチの状態を反映します。

CI/CD パイプラインやブランチ間のコード比較など、ブランチごとに独立した永続インデックスが必要なワークフローでは、ブランチ対応モードを有効にします。

SOCRATICODE_BRANCH_AWARE=true

これを有効にすると、コレクション名にブランチ名が含まれます（例：codebase_abc123__main、codebase_abc123__feat_my-feature）。各ブランチは、それぞれ独立したインデックス、コードグラフ、コンテキストアーティファクトを保持します。

使用可能なブランチ名も必要です。 ブランチ名はコレクション名に使えるようサニタイズされるため、区切り文字だけで構成されたブランチ（例：___）は空のサフィックスになり、ブランチごとのコレクションは作成されません。その場合は、ブランチ固有の SOCRATICODE_PROJECT_ID を設定してください。

パスから導出されるプロジェクト ID にのみ適用されます。 プロジェクトで SOCRATICODE_PROJECT_ID または .socraticode.json 内の projectId によって ID を固定している場合、その ID は安定した識別子として扱われ、ブランチサフィックスは付加されません。そのため、すべてのブランチで引き続き同じインデックスを共有します。これは意図した動作です。明示的な ID にサフィックスを付けると、既存のインストールで使われているコレクション名が変わり、インデックスが見つからないように見えてしまうためです。この理由でブランチ対応モードが無視された場合、SocratiCode はプロジェクトごとに 1 回、警告をログに記録します。ブランチごとのコレクションを使用するには、明示的な ID を削除してパスから導出される ID にサフィックスを付加できるようにするか、ブランチ固有の SOCRATICODE_PROJECT_ID を意図的に設定してください。

使用する場面：

• 各ブランチ／PR を個別にインデックスする CI/CD パイプライン
• ブランチ間の検索結果の比較
• フィーチャーブランチの変更の影響を受けない、クリーンな main インデックスの維持

使用しない場面：

• ブランチを頻繁に切り替えるローカル開発（デフォルトの共有インデックスのほうが効率的です）
• SOCRATICODE_PROJECT_ID で追跡されるプロジェクト（明示的な ID はブランチ検出を回避します）

仕組み： projectIdFromPath() は git rev-parse --abbrev-ref HEAD を使って現在の git ブランチを検出し、ハッシュベースのプロジェクト ID にサニタイズ済みのブランチサフィックス（例：feat/my-feature → feat_my-feature）を付加します。detached HEAD の状態では、ブランチサフィックスのない ID が使用されます。

保存済みの識別子を再利用する

ワークツリーの削除、クローンの削除、フォルダー名の変更が発生すると、インデックスはそのディレクトリより長く残ります。codebase_remove はパスでプロジェクトを指定するため、すでに存在しないディレクトリは指定できません。codebase_prune は、ストアにすでに記録されている情報を基に動作します。

レポート。 引数なしの codebase_prune は、変更を加えずにインベントリを表示します。保存済みの識別子ごとに、その名前を持つコレクション（コード、グラフ、シンボルグラフ、コンテキスト）とすべてのメタデータレコードを一覧表示し、記録されたパスを次のいずれかの状態として報告します。

パスの状態	意味
present-on-this-host	記録されたディレクトリが、このマシン上で解決できます。
absent-on-this-host	このマシンでの確認結果が ENOENT／ENOTDIR であることが確定しました。これは観測結果であり、放棄されたことの証明ではありません。共有 Qdrant では、インデックスを書き込んだホスト上でのみパスが存在します。
unknown/inaccessible	アクセス許可がない、マウントを利用できない、またはパスが記録されていません。削除する理由にはなりません。
同じ正規パスを記録した 2 つのアイデンティティ — パスハッシュによるアイデンティティと、同じチェックアウトに対して後から固定された projectId — は、参考情報としてのみ possible-superseded とマークされます。自身のパスについて記録が一致しないアイデンティティは手動検査対象としてマークされ、このツールでは削除できません。アイデンティティに帰属できないメタデータポイントは、そのポイント ID と理由とともに一覧表示され、同様にそのまま残されます。名前が 2 つのアイデンティティに当てはまるコレクションも同様です。すなわち、それ自体が codebase_、codegraph_、context_ で始まるか、_symgraph_meta/_file/_index で終わる固定済みの projectId は、別のアイデンティティも所有しうる名前を生成します。インベントリは、ストアが示す内容（メタデータポイントはファミリーコレクションを指名し、完全なシンボルグラフの三つ組はシンボルグラフを指名します）でそれらを確定し、残りは手動検査用に一覧表示します。そのような名前が属しうるすべてのアイデンティティもまた削除から保留されます。なぜなら、1 つを削除すると証拠が失われ、次の読み取りでそのコレクションがもう一方の手に渡ってしまうからです。

適用。 削除はレポートから正確な identity、その横に出力された confirmationToken、および acknowledgeNoRemoteWriters: true を取ります。トークンはそのアイデンティティのすべてのコレクションとすべてのメタデータレコードをフィンガープリントするため、レポート以降のあらゆる変更 — 新しいレコード、変更されたステータス、追加または消失したリソース — があると、適用は拒否され、最新のレポートを求めるます。このプロセス内でそのアイデンティティがインデックス作成、監視、グラフ構築、またはコンテキストインデックス作成中である間、このホスト上の別のプロセスがそのライターロック（index、watch、graph、context）のいずれかを保持している間、またはロックを検査できないときは常に、削除は拒否されます。最終検証から最後の削除までの間、ツールはアイデンティティ単位のバリア（prune ロックとすべてのライターロック）を保持します。すべてのライターは開始前にバリアを確認し、実行中は自身のロックを非再入的に取得します（このプロセスがすでに保持しているロックが採用されることはありません）。そのため、別のローカルプロセスでのグラフ構築やコンテキストインデックス作成は、インデクサーやウォッチャーと同様に排除されます。あるアイデンティティのグラフ構築が実行中に、別のプロセスが同じアイデンティティのグラフを構築しようとすると、並行して実行されるのではなく拒否されます。

共有ストアの制限。 ロックファイルはこのホスト上に存在します。同じ Qdrant を共有する別のマシンがアイドル状態であることを示すことはできません。これが acknowledgeNoRemoteWriters がオペレーターに代わって表明する内容であり、ツール内でそれを推測するものは何もありません。

結果。 すべてのリソースはそれぞれの結果とともに報告されます。バリアの所有権は各書き込みの前に確認されます。クリーンアップの途中でバリアロックの喪失が報告された場合、削除は次の書き込みで停止し、残りのリソースはスキップとして報告され、クリーンアップは不完全として報告されます。すでに消失しているリソースは削除済みとしてカウントされるため、部分的な失敗後に適用を繰り返しても安全であり、何も残っていない箇所では何も行いません。成功は、削除後に再読み取りしたインベントリがそのアイデンティティのリソースを 1 つも示さない場合にのみ報告されます。そうでなければ、残存物が一覧表示されます。アイデンティティをキーとするキャッシュ — グラフ、読み込み済みファイルハッシュ、シンボルグラフ — はこのプロセス内で破棄されます。既存のインデックスは、報告されるために移行や再インデックスを必要としません。

オプションのローカル自動クリーンアップ

自動クリーンアップはデフォルトで無効になっています。SOCRATICODE_AUTO_CLEANUP=local は、Qdrant が ホスト専用で、別のマシンと共有されていない場合に限り 設定してください。これにより、ローカルが所有者であることを明示的に宣言します。マネージドモードとループバックエンドポイントが必要です。共有ストア／外部ストアと明示的なプロジェクト ID は、codebase_prune を通じて引き続きオペレーターが管理します。

新たに対象となるインデックスには、ローカルインストール UUID と、元のリポジトリ、正確なブランチ参照、チェックアウト、Git 管理ディレクトリが記録されます。UUID はユーザーのホームディレクトリにある .socraticode/local-index-owner に保存され、再起動後も再利用されます。既存のレコードと、十分な証明情報がない孤立リソースは、自動クリーンアップの対象にならず、自動報告のみが行われます。移行や再インデックスは不要です。ローカル所有権ファイルを紛失しても、それらのレコードを引き継ぐ根拠にはなりません。クリーンアップが無効な状態で書き込まれたインデックスメタデータは、自動クリーンアップの所有権を得ません。

MCP サーバーは、自動再開とは独立して、起動時と毎分チェックを行います。プルーニングで使用されるインベントリフィンガープリント、書き込みバリア、リソースの削除と検証を再利用します。リンクされたワークツリーは、Git から登録が解除され、元の Git 管理ディレクトリが削除され、同じ検証済みのアクセス可能なファイルシステム上でソースディレクトリが存在しなくなった場合にのみ対象となります。ブランチを認識するインデックスは、その正確なローカル参照が削除され、登録済みのワークツリーがそのブランチを使用していない場合にのみ対象となります。マージ、スカッシュマージ、ブランチの切り替え、ワークツリーの移動、ディレクトリが見つからないことだけ、マウントを利用できないこと、権限エラー、ID が不明瞭なこと、書き込みが進行中であることは、削除の許可にはなりません。削除されるのはインデックスリソースとメタデータのみで、ソースディレクトリや Git ブランチは削除されません。削除、拒否、不完全なクリーンアップは、MCP のログ通知を通じて報告されます。コレクションの一部で取得に失敗した場合は、安全に後から再試行できるよう、所有権メタデータが保持されます。

利用可能なツール

接続すると、AI アシスタントで次のツールを利用できます。

インデックス作成

ツール	説明
codebase_index	コードベースのインデックス作成をバックグラウンドで開始します（進行状況を確認するには codebase_status をポーリングします）
codebase_stop	進行中のインデックス作成を正常に停止します（現在のバッチを完了してチェックポイントを保存します。codebase_index で再開します）
codebase_update	増分更新します。変更されたファイルのみを再インデックスします
codebase_remove	プロジェクトのインデックスを削除します（ウォッチャーを安全に停止し、進行中のインデックス作成／更新をキャンセルし、グラフ構築の完了を待ちます）
codebase_prune	保存されているすべてのプロジェクト ID とそのコレクションおよびメタデータを一覧表示します。削除できるのは、正確な ID、新しい確認トークン、共有ストアに関する確認を指定した場合のみです（保存済み ID の解放を参照）
codebase_watch	ファイル監視を開始／停止します。開始時に未反映の変更を取り込み、その後の変更を監視します

検索

ツール	説明
codebase_search	ハイブリッドのセマンティック検索＋キーワード検索（密ベクトル＋BM25、RRF で統合）を実行します。ファイルパス、言語フィルター、プロジェクト横断検索（includeLinked）をオプションで指定できます
codebase_status	インデックスの状態とチャンク数を確認します

コードグラフ

ツール	説明
codebase_graph_build	多言語対応の依存関係グラフを構築します（バックグラウンドで実行されます。codebase_graph_status で進捗を確認してください）
codebase_graph_query	特定のファイルのインポート元と依存先を検索します
codebase_graph_stats	グラフの統計情報（接続数の多いファイル、孤立ファイル、言語別の内訳）を取得します
codebase_graph_circular	循環依存を検出します
codebase_graph_visualize	依存関係グラフの Mermaid 図（mode=mermaid、デフォルト）またはインタラクティブな HTML エクスプローラー（mode=interactive）を生成します。インタラクティブモードでは、自己完結型のページ（同梱の Cytoscape.js と Dagre を使用し、オフラインで動作）を書き出して、デフォルトのブラウザーで開きます。ファイル表示とシンボル表示、影響範囲のオーバーレイ、ライブ検索、PNG 書き出しに対応しています。
codebase_graph_status	グラフの構築状況または永続化されたグラフのメタデータを確認します（解決済みの取得済みインポートが少ない場合に通知するため、ほぼ空のグラフを正常なものと誤認せずに済みます。また、グラフを構築したバージョンも表示するため、アップグレード前のバージョンが残したグラフをリゾルバーの不具合と誤認せずに済みます）
codebase_graph_remove	プロジェクトの永続化されたコードグラフを削除します（実行中のグラフ構築が完了するまで待機します）

影響分析（シンボルレベルの呼び出しグラフ）

2 つ目のグラフレイヤーでは、ファイルのインポートより一歩踏み込み、どの関数や メソッドがどれを呼び出すかを追跡します。コードのリファクタリング、名前変更、削除の前に、これらのツールを使用してください。

ツール	説明
codebase_impact	影響範囲を調べます。ファイル／関数 X を変更すると、どのファイルに影響が及ぶかを確認します（逆方向の呼び出しエッジをたどる BFS）。曖昧なシンボル名の候補を最初の N 件だけ表示するには limit を指定します。候補を省略した場合、回答には総数が示されます
codebase_flow	エントリーポイントから前方への実行フローをたどります。引数なしで呼び出すと、エントリーポイント（孤立ノード、main()、フレームワークのルート、テスト）を検出します。曖昧なエントリーポイント名の候補を最初の N 件だけ表示するには limit を指定します。候補を省略した場合、回答には総数が示されます
codebase_symbol	1 つのシンボルの 360°ビューを表示します。定義、呼び出し元、呼び出し先を確認できます。一意でない名前の定義を最初の N 件だけ解決するには limit を指定します。候補を省略した場合、回答には総数が示されます
codebase_symbols	ファイル内のシンボルを一覧表示するか、プロジェクト全体から名前で検索します

制約事項。 呼び出しグラフは静的解析に基づいており、型推論は行いません。動的ディスパッチ（getattr、obj[key](...)、リフレクション、eval）、展開されていないマクロ、フレームワーク固有の暗黙的な機能（Spring の @Autowired、Angular の DI、Rails の has_many、デコレーター駆動のルーティング）は認識されません。こうした仕組みを通じてのみメソッドに到達する呼び出し元は、codebase_impact に表示されません。「呼び出し元がゼロ」と表示された場合は、DI を多用するコードベースでは再確認の目安としてください。codebase_graph_status は品質指標として、未解決の割合（unresolvedEdgePct）を報告します。これは、プロジェクト内のシンボルに一致しなかった、取得済みのシンボルエッジ（呼び出し、インポート、再エクスポート、型または値の参照）の割合です。GDScript のエンジン呼び出しは対象外です。この割合には、ランタイムの組み込み機能や外部ライブラリ（setTimeout、JSON.stringify、SDK クライアントのメソッド）へのエッジも含まれます。これらはプロジェクト内のシンボルでは解決できないため、正常な TypeScript／JavaScript コードでも割合が高くなり、リゾルバーの失敗率を示すものではありません。全項目は DEVELOPER.md § 影響分析 を参照してください。

インタラクティブなグラフエクスプローラー

AI に 「このプロジェクトのインタラクティブなグラフを表示して」 と尋ねるか、codebase_graph_visualize を mode: "interactive" で呼び出すと、SocratiCode が自己完結型の HTML ページを生成し、既定のブラウザーで開きます。

• ファイルビュー — すべてのソースファイルをノードとして表示し、インポートをエッジで表します。言語ごとに色分けされ、循環依存は赤色で表示されます。
• シンボルビュー — 切り替えると、関数／クラス／メソッドを呼び出しエッジ付きのノードとして表示します（シンボルグラフが埋め込み上限内に収まる場合に利用できます。上限を超えるとファイルビューが維持され、シンボルレベルのクエリには codebase_impact を使うようバナーで案内します）。
• サイドバー — ノードをクリックすると、インポート／依存元／ファイル内のシンボル／行番号が表示され、影響範囲と呼び出しフローを確認するアクションボタンも表示されます。
• 任意のノードを右クリック → そのノードの逆向きの推移的閉包（ここが変更された場合に影響を受けるもの）を強調表示します。
• ライブ検索で一致するノードを絞り込み、中央に表示できます。レイアウト切り替え — Dagre／力学ベース／同心円／幅優先／グリッド／円形。PNG エクスポートで共有可能な画像を作成できます。
• オフライン対応 — Cytoscape.js と Dagre は SocratiCode パッケージ内に同梱されています。CDN やネットワーク接続は不要で、エアギャップ環境でも動作します。

出力は単一の HTML ファイルです（OS の一時ディレクトリにプロジェクトごとに 1 つ書き込まれます）。PR にコミットしたり、Slack で共有したりすることもできます。

管理

ツール	説明
codebase_health	Docker、Qdrant、埋め込みプロバイダーの状態を確認します
codebase_list_projects	インデックス済みのすべてのプロジェクトを、パスとメタデータとともに一覧表示します
codebase_about	SocratiCode に関する情報を表示します

コンテキストアーティファクト

ツール	説明
codebase_context	.socraticodecontextartifacts.json で定義されたすべてのコンテキストアーティファクトを、名前、説明、インデックス状況とともに一覧表示します
codebase_context_search	コンテキストアーティファクトを意味検索します（初回使用時に自動インデックス化し、古さを自動検出します）
codebase_context_index	.socraticodecontextartifacts.json のすべてのアーティファクトをインデックス化、または再インデックス化します
codebase_context_remove	プロジェクトのインデックス済みコンテキストアーティファクトをすべて削除します（インデックス作成中は実行できません）

言語サポート

SocratiCode は、次の 3 段階で言語をサポートします。

完全サポート（インデックス化＋コードグラフ＋AST チャンク化）

JavaScript、TypeScript、TSX、Python、Java、Kotlin、Scala、C、C++、C#、Go、Rust、Ruby、PHP、Swift、Dart、Elixir（HEEx/EEx を含む）、Bash/Shell、HTML、CSS/SCSS、Svelte、Vue

条件付き AST サポート

GDScript：.gd ファイルでは、AST チャンク化、シンボル抽出、呼び出し箇所の解決に、オプションのネイティブバイナリ（tree-sitter-gdscript）を使用します。ネイティブパーサーを利用できない場合は、構文を認識するフォールバック処理により、コメントや文字列からエッジを作成することなく、インポート抽出と行ベースのチャンク化を行います。class_name 宣言、extends／preload／load によるインポート、res:// パスが解決されます。相対パスの extends と preload はスクリプトのディレクトリを基準とし、相対パスの実行時 load は Godot プロジェクトルートを基準とします。ファイルごとの project.godot 検出により、ネストされた Godot プロジェクトと兄弟プロジェクトをサポートします。Godot のシーンとリソース（.tscn／.tres）は、行ベースのチャンク化でインデックス化されます。[ext_resource] 宣言は、任意の空白、属性の順序、エスケープされた引用符、uid="uid://..." と path="..." の両方の属性を処理するトークナイザーによって、依存関係エッジとして抽出されます。両方がある場合は UID が優先されます。TSCN ドキュメントに従い、res:// パスと .tscn／.tres ファイルからの相対パスの両方をサポートします。コードグラフでは、res:// パスは .gd、.tscn、.tres のターゲットに解決されます。 Svelte と Vue: <script> ブロックから抽出されたインポート（TypeScript として再パースされます）と、<style> ブロックからの CSS @import/@require（lang、scoped、module、global 属性の任意の組み合わせ）に対応します。tsconfig.json/jsconfig.json の compilerOptions.paths からのパスエイリアスが解決されます（extends チェーンを含む）。SCSS のパーシャル解決（_ プレフィックスの慣習）がサポートされています。

Python: 絶対インポートは、プロジェクトの pyproject.toml ファイルによって示されるインポートルートを通じて解決されます — ルートとネストされたものの両方であるため、uv ワークスペースではパッケージ間のエッジが得られます — これは src/ レイアウト（packages/<dist>/src/<module>/…、uv init --lib、hatchling、setuptools が生成するもの）と、各マニフェストに隣接するフラットレイアウトの両方をカバーし、PEP 420 名前空間パッケージと単一モジュール配布も含みます。マニフェストがファイルに適用されるのは、そのファイルの祖先パス上に存在する場合、または祖先マニフェストがそれを [tool.uv.workspace] メンバーとして宣言している場合のみであるため、独自のマニフェストを持つサンプルアプリ、ドキュメントプロジェクト、チェックインされた sdist が無関係なコードのインポートルートになることはありません。読み取られるのは [tool.uv.workspace] のみであるため、poetry、pdm、hatch のパス依存モノレポは祖先パスによるスコープ設定となり、パッケージ間のエッジは得られません。適用可能なルートは最も近いものから順に試されるため、パッケージは兄弟のモジュールより先に自身のモジュールを解決します。相対インポートおよびプロジェクトルートの src//lib/ と兄弟フラットの慣習は変更されていません — 兄弟フラットのフォールバックは依然としてこれらのルートより優先され、スクリプト自身のディレクトリを sys.path[0] に置く CPython と一致します。

PHP: use インポートは、プロジェクトの composer.json ファイルで宣言された PSR-4 プレフィックスを通じて解決されます — ルートとネストされたものの両方であるため、Composer モノレポのパスパッケージではパッケージ間のエッジが得られます。プレフィックスが一致しない場合は、プロジェクト自体で見つかった namespace およびクラス/インターフェース/トレイト/enum の宣言に対して解決されます。これは "autoload": {} を同梱し実行時に名前空間を登録するパッケージ（$loader->addNamespace(...)、WordPress プラグインの定番）に到達する方法です — spl_autoload_register の解釈は関与しません。カンマ区切りリスト（use A\B, A\C;）、グループ（use A\{B, C};、メンバーごとの function/const 修飾子を含む）、完全修飾名（use \A\B;）はすべて読み取られます。require/include は相対パス、ベアパス（まずソースディレクトリ、次にプロジェクトルート）、および __DIR__ . '<literal>' / dirname(__FILE__) . '<literal>'（Composer 以外での支配的なインクルードイディオム）を解決します。これらはインクルード式自体から読み取られるため、どの位置でも見つかります — return require __DIR__ . '/routes.php'; や $config = include 'config.php'; は該当しますが、コメント内で言及された include や文字列内で引用されたものは該当しません。実行時の値に結合されたインクルード（ABSPATH . '/x.php'、$base . '/x.php'）は、推測されるのではなく未解決のままになります。

Dart: シンボル（クラス、ミックスイン、enum、拡張、typedef、関数、ゲッター、セッター、演算子、名前付きおよびファクトリを含むコンストラクタ、抽象/本体なしメンバー）、呼び出しサイト（メソッド呼び出し、カスケード、コンストラクタ呼び出し）、main() エントリポイント検出、および AST チャンキングはすべて tree-sitter ベースです。インポート/エクスポート/パートのエッジは正規表現で抽出されます。プロジェクト内の package: インポート（Flutter の慣習）は、プロジェクトの pubspec.yaml ファイルを通じて解決されます — ルートとネストされたものの両方であるため、pub ワークスペース/melos モノレポではパッケージ間のエッジが得られます — pub の package:<name>/<rest> → <package_root>/lib/<rest> マッピングを介して行われます。dart: および未知のパッケージ名は外部のままです。同梱のグラマー（@ast-grep/lang-dart）は Dart 3 のクラス修飾子（sealed/base/interface/final/mixin class）および extension type より前のものであるため、これらを使用する宣言は（一度だけ警告がログに記録されて）スキップされます — 上流のグラマーが更新されるまで。一方、各ファイルの残りの部分は通常どおりインデックスされます。 Elixir: .ex および .exs ファイルは、チャンク分割に ast-grep グラマーを使用します。alias、import、require、use ディレクティブは、プロジェクト内の defmodule 宣言に解決されます。これらのディレクティブを伴わない完全修飾呼び出しは未解決のままです。defmodule、def、defp、および通常の呼び出しはシンボルと呼び出しエッジを生成します。チャンク分割はモジュール単位で行われ、大きなモジュールは関数単位のチャンクではなく行ウィンドウにフォールバックします。defprotocol、defimpl、defguard、defmacro、defdelegate 宣言はまだシンボルを登録しません。プロトコルと実装のスコープは表現されないため、その内部の関数はトップレベルのシンボルとして現れます。単独の .heex および .eex テンプレートは、AST チャンク分割、リモートコンポーネントの依存関係、埋め込み Elixir 式からの呼び出しのために専用の tree-sitter グラマーを使用します。マークアップとコメントが Elixir として解析されることはありません。.leex は EEx グラマーをベストエフォートで使用し、解析に失敗した場合は安全に行チャンクへフォールバックし、エッジを抽出しません。

正規表現 + インデックスによるコードグラフ

Lua (require/dofile/loadfile)、SASS、LESS、Stylus (CSS の @import/@require 抽出)

インデックスのみ (ハイブリッド検索、行ベースのチャンク分割)

JSON、YAML、TOML、XML、INI/CFG、Markdown/MDX、RST、SQL、R、Dockerfile、TXT、およびサポート対象の拡張子や特殊なファイル名 (Dockerfile、Makefile、Gemfile、Rakefile など) に一致する任意のファイル

63 のファイル拡張子 + 8 の特殊なファイル名をすぐに利用できます。

拡張子のないファイル (Unix スクリプト、ヘルスプローブ、source されるライブラリ) も、INDEX_EXTENSIONLESS が有効な場合 (デフォルト) はコンテンツベースの言語検出によってインデックスされます。この環境変数については以下を参照してください。

無視ルール

インデクサーは 3 層の無視ルールを組み合わせます。

1. 組み込みのデフォルト — node_modules、.git、dist、build、ロックファイル、IDE フォルダーなど。
2. .gitignore — プロジェクト内のすべての .gitignore ファイル (ルートおよびネストされたサブディレクトリ)。RESPECT_GITIGNORE=false を設定すると、.gitignore の処理を完全にスキップします。
3. .socraticodeignore — インデクサー固有の除外のためのオプションのファイルです。構文は .gitignore と同じです。

3 つの層はすべて、ディレクトリを指す コンテキストアーティファクトにも適用されますが、それらはプロジェクトルートではなく、アーティファクトディレクトリを基準に解決されます。プロジェクトルートの .gitignore や .socraticodeignore はコードインデックスを制御し、ディレクトリアーティファクトには及びません。ディレクトリアーティファクトに適用されるのは、組み込みのデフォルト、アーティファクトルートの .gitignore およびネストされた .gitignore ファイル、そしてアーティファクトルートのみの .socraticodeignore です。ネストされた .socraticodeignore ファイルは読み込まれません。ディレクトリアーティファクトから何かを除外するには、適用可能なそれらのファイルのいずれかにパターンを記述してください。

ディレクトリアーティファクトは組み込みのデフォルトを完全に継承し、ビルド出力に関するものだけではありません。__pycache__、*.pyc、dist、build に加えて、そのリストにはアーティファクトディレクトリが正当に使用する可能性のある名前も含まれます: env、vendor、target、out、coverage、*.map、*.log。ディレクトリアーティファクトでこれらのいずれかが必要な場合は、アーティファクトルートの .socraticodeignore で ! パターンを使って再包含してください。名前自体を否定します (!env)。gitignore のセマンティクスでは、親ディレクトリが除外されているファイルを再包含することはできないため、!env/** だけでは何の効果もありません。target には追加の制約が 1 つあります。その内容は再包含できますが、ネストされた .gitignore ファイルを探索する際に target/ はスキップされるため、target/.gitignore のルールは読み込まれません。代わりにそれらのルールをアーティファクトルートの .gitignore または .socraticodeignore に記述してください。無視ルールによって、バイナリチェックによって、または読み取れなかったために除外されたファイルは、そのアーティファクトがインデックスされる際にそのログ行でカウントされます。node_modules、.git、ドットファイルは走査がそれらを認識する前に枝刈りされるため、どのカウントにも現れません。

コンテキストアーティファクト

ソースコード以外のプロジェクト知識（データベーススキーマ、API 仕様、インフラ設定、アーキテクチャドキュメントなど）を AI に認識させます。

セットアップ

プロジェクトのルートに .socraticodecontextartifacts.json ファイルを作成します（ひな形については .socraticodecontextartifacts.json.example を参照してください）。

{
  "artifacts": [
    {
      "name": "database-schema",
      "path": "./docs/schema.sql",
      "description": "Complete PostgreSQL schema — all tables, indexes, constraints, foreign keys. Use to understand what data the app stores and how tables relate."
    },
    {
      "name": "api-spec",
      "path": "./docs/openapi.yaml",
      "description": "OpenAPI 3.0 spec for the REST API. All endpoints, request/response schemas, auth requirements."
    },
    {
      "name": "k8s-manifests",
      "path": "./deploy/k8s/",
      "description": "Kubernetes deployment manifests. Shows how services are deployed, scaled, and networked."
    }
  ]
}

各アーティファクトには、次の項目があります。

• name — 一意の識別子（検索のフィルタリングに使用）
• path — ファイルまたはディレクトリへのパス（プロジェクトルートからの相対パス、または絶対パス）。ディレクトリは再帰的に読み込まれ、ドットファイルやドットディレクトリ（.pytest_cache/、.tox/）、アーティファクトディレクトリを基準に適用される除外ルールに一致するもの、先頭 8 KiB に NUL バイトがあることで検出されたバイナリファイルは除外されます。除外されたファイルは、ディレクトリごとの件数の概要とともにログに記録されます。単一ファイルを指すパスはそのまま読み込まれます。除外は適用されないため、指定されたバイナリファイルもインデックスされます。
• description — このアーティファクトが何であり、どのように使うかを AI に伝えます

仕組み

アーティファクトはチャンクに分割され、コードと同じハイブリッドな密ベクトル検索＋BM25 検索を使って Qdrant に埋め込まれます。初回の検索時にアーティファクトは自動でインデックスされます。以降の検索では、コンテンツのハッシュによって古さが自動検出され、変更されたファイルは透過的に再インデックスされます。

コンテンツハッシュの計算前に除外が適用されるため、アーティファクトディレクトリ内のビルド出力によって、そのアーティファクトが古いと判定されることはなくなります。以前のバージョンでインデックスされたディレクトリアーティファクトは、ハッシュの次回チェック時に、以前の走査で埋め込まれたファイルが現在は除外対象となっている場合、再インデックスされます。その際、チャンク数は減少することが予想されます。除外するものがないアーティファクトは同じハッシュになるため、そのまま維持されます。

使い方

1. 確認：codebase_context — 定義済みのアーティファクトと、それぞれのインデックス状況を一覧表示します
2. 検索：codebase_context_search — すべてのアーティファクトを対象にセマンティック検索します（または名前で絞り込みます）
3. 再インデックス：codebase_context_index — 強制的に再インデックスします（通常は不要です。自動インデックスで処理されます）
4. クリーンアップ：codebase_context_remove — インデックスされたアーティファクトをすべて削除します

重要な理由：実際のワークフロー例

アーティファクトがなければ、エージェントが参照できるのはソースコードだけです。アーティファクトがあれば全体像を把握でき、最初からプロジェクトに合ったコードを書けます。

データベーススキーマ — *「users に last_login タイムスタンプを追加して」*と依頼します。エージェントは codebase_context_search を実行して「users table」を検索し、スキーマでは snake_case のカラムを使っていて、すべてのテーブルにトリガー付きの updated_at があることを見つけます。エージェントが作成するマイグレーションは、推測ではなく既存の規約に沿ったものになります。

{
  "name": "database-schema",
  "path": "./docs/schema.sql",
  "description": "Complete PostgreSQL schema — all tables, columns, types, constraints, indexes, and triggers. Check this before writing migrations to match naming conventions and existing patterns."
}

API 仕様 — *「ユーザー設定用の GET エンドポイントを追加して」*と依頼します。エージェントは OpenAPI 仕様を検索し、すべてのエンドポイントで Bearer 認証を使い、{ data, meta } ラッパーを返し、cursor／limit でページネーションしていることを確認します。新しいエンドポイントも自動的に同じパターンに従います。

{
  "name": "api-spec",
  "path": "./docs/openapi.yaml",
  "description": "OpenAPI 3.0 spec for the REST API — all endpoints, request/response schemas, auth, pagination. Check this before adding or modifying endpoints to match existing conventions."
}

ドメイン用語集（DDD） — *「注文をキャンセルする方法を追加して」*と依頼します。エージェントはドメイン用語集を検索し、キャンセルは「cancelled」ではなく OrderVoided イベントとしてモデル化されていること、Confirmed ステータスの注文のみ取り消せること、Fulfillment 境界づけられたコンテキストに通知する必要があることを見つけます。実装では正しいドメイン用語を使い、適切な境界づけられたコンテキストと連携します。

{
  "artifacts": [
    {
      "name": "ubiquitous-language",
      "path": "./docs/ubiquitous-language.md",
      "description": "Domain glossary — bounded context terms, their definitions, and relationships. Always check this before naming entities, events, or commands to use the correct domain language."
    },
    {
      "name": "context-map",
      "path": "./docs/context-mapping.md",
      "description": "Bounded context map — context boundaries, relationships (shared kernel, customer-supplier, etc.), and integration patterns. Check before implementing cross-context communication."
    },
    {
      "name": "event-storming",
      "path": "./docs/event-storming/",
      "description": "Event storming output — domain events, commands, aggregates, policies, and read models. Check before adding new domain behaviour to see how it fits the existing event flows."
    }
  ]
}

description フィールドが重要な鍵です。 このフィールドは、アーティファクトが何であるかだけでなく、いつ参照すべきかも AI に伝えます。「X を行う前に確認する」と説明に記載しておくと、適切なタイミングでエージェントがアーティファクトを参照するようになります。

成果物の例

カテゴリ	例
データベース	SQL スキーマダンプ（pg_dump --schema-only）、Prisma スキーマ、Rails の schema.rb、Django モデルダンプ、マイグレーションファイル
API コントラクト	OpenAPI/Swagger 仕様、GraphQL スキーマ、Protobuf 定義、AsyncAPI 仕様（Kafka、RabbitMQ）
インフラストラクチャ	Terraform/Pulumi 設定、Kubernetes マニフェスト、Docker Compose ファイル、CI/CD パイプライン設定
アーキテクチャ	アーキテクチャ決定記録（ADR）、サービスのトポロジー文書、データフロー図、ドメイン用語集
運用	監視／アラートルール、RBAC／権限マトリクス、認証フローのドキュメント、フィーチャーフラグ設定
外部	サードパーティ API ドキュメント、コンプライアンス要件（SOC2、HIPAA、GDPR）、SLA の定義

ヒント：データベーススキーマは、主要なデータベースであればどれも、スキーマ全体を単一のファイルにエクスポートできます。pg_dump --schema-only（PostgreSQL）、mysqldump --no-data（MySQL）、sqlite3 db.sqlite .schema（SQLite）を使用します。ORM スキーマ（Prisma、Rails、Django）は、すでにリポジトリに含まれていることがよくあります。

環境変数

SocratiCode は、MCP サーバーの起動時に環境変数から設定を読み込みます。キー名とファイル形式は MCP ホストによって異なり、プラグインにバンドルされたサーバーが、直接登録されたサーバーで使用される設定を必ずしも引き継ぐとは限りません。変数を変更した後は、サーバーを再起動するか再接続し、新しいホストセッションを開始してください。変数が無視されているように見える場合は、まずホストのドキュメントに記載されたスキーマとインストール範囲を確認してください。

運用設定は新しいプロセスに適用されます。保存済みのベクトル、チャンク、パス、その他のインデックス表現を定義する設定には、有効なインデックスプロファイルが適用されます。値を変更すると、既存のコレクションに対して保留中として報告されます。既存のコレクションは引き続き使用可能で、自動的に再構築されたり、一部だけ書き換えられたりすることはありません。変更後の表現を意図的に適用する場合にのみ、コレクションを削除して新たにインデックスを作成してください。

ホストごとの環境変数の渡し方

ホスト	設定ファイル	環境変数の構文
Claude Code のネイティブプラグイン	~/.claude/settings.json	最上位の "env": { "KEY": "value" }
Claude Code の MCP のみ	ユーザーまたはプロジェクトの MCP 設定	claude mcp add --env KEY=value ...、または保存されたサーバー定義内の env オブジェクト
Claude Desktop、Windsurf、Cline	ホストの MCP JSON	サーバー定義内の "env": { "KEY": "value" }
OpenAI Codex のネイティブプラグイン	~/.codex/config.toml	同梱サーバーを無効にして、最上位に設定済みサーバーを追加します
OpenAI Codex の MCP のみ	~/.codex/config.toml	codex mcp add --env KEY=value、インライン TOML の env = { ... }、または [mcp_servers.NAME.env]
VS Code Agent Plugin	VS Code の MCP サーバー状態とユーザー MCP 設定	env または envFile を使用して、プラグインを残し、同梱サーバーを無効にして、直接サーバーを追加します
VS Code の直接 MCP	.vscode/mcp.json またはユーザー MCP 設定	servers エントリ内の "env": { "KEY": "value" }
VS Code エディター拡張機能	VS Code の設定	"socraticode.env": { "KEY": "value" }
Cursor のローカルプラグイン	Cursor の カスタマイズ と直接 MCP 設定	env を使用して、プラグインを残し、同梱サーバーを無効にして、直接サーバーを追加します
Cursor の直接 MCP	ユーザーまたはプロジェクトの mcp.json	サーバー定義内の "env": { "KEY": "value" }
Continue	YAML 設定	mcpServers リスト項目内の env: マップ
Zed	context_servers JSON	"env": { "KEY": "value" }
Gemini CLI の直接 MCP	~/.gemini/settings.json または .gemini/settings.json	サーバーに対する明示的な "env" エントリ
OpenCode 1.x / V2	opencode.json / opencode.jsonc (スキーマ)	"env" ではなく "environment": { "KEY": "value" }。V2 ではサーバーを mcp.servers の下にネストします

環境変数をいくつか設定する例：

MCP JSON ホスト（Claude Desktop、Windsurf、Cline、Cursor など）：

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

OpenCode — env ではなく environment である点に注意してください：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socraticode": {
      "type": "local",
      "command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
      "enabled": true,
      "environment": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

ネストされたテーブル形式を使った OpenAI Codex CLI：

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

[mcp_servers.socraticode.env]
QDRANT_MODE = "external"
QDRANT_URL = "https://xyz.qdrant.io"

同等の CLI 形式は codex mcp add socraticode --env QDRANT_MODE=external --env QDRANT_URL=https://xyz.qdrant.io -- npx -y --prefer-online socraticode@latest です。インラインの env = { ... } も有効な TOML です。

このセクションの以降では、各変数について説明します。ホストに合った構文を使って渡してください。

有効なインデックスプロファイル

コードとコンテキストのコレクションには、保存される表現を定義する設定が永続化されます。既存のコレクションは、インデックス作成、ウォッチャーによる更新、検索において、引き続きその有効なプロファイルを使用します。検索とステータス確認では、プロファイルが未設定のレガシーコレクションをメタデータに書き込まずに解決します。次回のインデックス作成または更新操作では、ベクトルを変更する前に、解決されたプロファイルが永続化されます。埋め込みプロバイダー、モデル、次元数、コンテキスト長、クエリまたはドキュメントのプレフィックス、パスの包含設定、チャンク上限、拡張子と言語のマップ、ファイルサイズ上限、または LiteLLM の次元数フラグに変更がある場合、codebase_status は保留中として報告し、コレクションを部分的に変更することはありません。codebase_remove でコレクションを削除してから、codebase_index を実行し、新しいインデックスで要求されたプロファイルを有効にしてください。レガシーコレクションは、新たに導入された設定にはリリース時のデフォルト値を使って引き続き利用できます。過去に利用できなかった値には legacy-unverified のマークが付けられます。

埋め込みプロバイダー

変数	デフォルト	説明
EMBEDDING_PROVIDER	ollama	埋め込みバックエンド：ollama（ローカル、デフォルト）、openai、google、lmstudio、または litellm
EMBEDDING_MODEL	(プロバイダーごと)	モデル名。デフォルト：nomic-embed-text（ollama）、text-embedding-3-small（openai）、gemini-embedding-001（google）。lmstudio と litellm では必須です（デフォルト値はありません）。
EMBEDDING_DIMENSIONS	(プロバイダーごと)	ベクトルの次元数。デフォルト：768（ollama）、1536（openai）、3072（google）。lmstudio と litellm では必須です（デフォルト値はなく、ロードされたモデルやプロキシのエイリアスによって異なります）。
EMBEDDING_CONTEXT_LENGTH	(自動検出)	モデルのコンテキストウィンドウのトークン数です。既知のモデル名では自動検出されます（基盤となるモデル名と一致する LiteLLM のエイリアスでも機能します）。カスタムの LM Studio モデルや任意の LiteLLM エイリアスでは、手動で設定してください。
EMBEDDING_QUERY_PREFIX	"search_query: "	埋め込みの前にクエリへ追加するタスクプレフィックスです。モデルに合わせて設定してください。multilingual-e5-* では "query: "、cl-nagoya/ruri-v3-* では "検索クエリ: "、プレフィックスを必要としない bge-m3 では空文字列を指定します。無効にするには "" を設定してください。この変数を省略することと、空の値を設定することは同じではありません。未設定の場合はデフォルト値が使われ、= の後に何も指定しない場合はプレフィックスが一切付与されません。
EMBEDDING_DOCUMENT_PREFIX	"search_document: "	埋め込みの前にドキュメントへ追加するタスクプレフィックスです。対応する値は、multilingual-e5-* では "passage: "、cl-nagoya/ruri-v3-* では "検索文書: "、bge-m3 では空文字列です。無効にするには "" を設定してください。未設定と空の値の違いは上記と同じです。EMBEDDING_QUERY_PREFIX と一緒に変更する必要があります。既存のコレクションでは実効プレフィックスが維持されます。値を変更して有効にするには、コレクションを削除して新たにインデックスを作成してください。
EMBEDDING_DOCUMENT_INCLUDE_PATH	true	チャンクとともに、EMBEDDING_DOCUMENT_PREFIX とコンテンツの間にファイルパスを埋め込むかどうかを指定します。大文字と小文字を区別せず、前後の空白を無視して true／1／yes および false／0／no を受け付けます。空のままにした場合は未設定と同じです。それ以外の値は、その値を示すエラーとともに拒否されます。パスのトークンはパス形式のクエリに役立ちますが、文章中心のコーパスではノイズになります。false に設定すると、ドキュメントプレフィックスとチャンクの内容のみを埋め込みます。両者の間には、プレフィックス末尾に含まれるもの以外の区切り文字は入りません。同じテキストが密ベクトル埋め込みおよび BM25 字句インデックスに使われるため、パス由来のトークンはキーワード検索でも一致しなくなります。また、コンテキストアーティファクトでは context:<name>:<path> 識別子もパスとともに除外されます。既存のコレクションでは実効パス設定が維持されます。値を変更して有効にするには、コレクションを削除して新たにインデックスを作成してください。

Ollama の設定（EMBEDDING_PROVIDER=ollama の場合）

変数	デフォルト	説明
OLLAMA_MODE	auto	auto = ポート 11434 でネイティブの Ollama が利用可能な場合はそれを使い、利用できない場合は Docker コンテナを管理します（推奨）。docker = 常に管理対象の Docker コンテナをポート 11435 で使用します。external = ユーザー管理の Ollama インスタンス（ネイティブ、リモートなど）を使用します。
OLLAMA_URL	http://localhost:11434（auto/external）／http://localhost:11435（docker）	Ollama API の完全なエンドポイント
OLLAMA_PORT	11435	Ollama コンテナのポート（Docker モード）。OLLAMA_URL が明示的に設定されている場合は無視されます。
OLLAMA_HOST	http://localhost:{OLLAMA_PORT}	Ollama のベース URL（OLLAMA_URL の代替）
OLLAMA_API_KEY	(なし)	認証が必要な Ollama プロキシ向けの任意の API キー

クラウドプロバイダーの API キー

変数	デフォルト	説明
OPENAI_API_KEY	(none)	EMBEDDING_PROVIDER=openai の場合に必須です。platform.openai.com から取得してください
GOOGLE_API_KEY	(none)	EMBEDDING_PROVIDER=google の場合に必須です。aistudio.google.com から取得してください

LM Studio の設定（EMBEDDING_PROVIDER=lmstudio の場合）

変数	デフォルト	説明
LMSTUDIO_URL	http://localhost:1234/v1	LM Studio の OpenAI 互換ローカルサーバーの完全なベース URL です。サーバーがデフォルト以外のポートまたはリモートマシンで動作している場合は上書きしてください（例：http://gpu-rig.local:5678/v1）。/v1 の接尾辞を含める必要があります。
LMSTUDIO_API_KEY	(none)	任意です。LM Studio のローカルサーバーではデフォルトで認証が不要です。LM Studio の UI で API キー認証を有効にした場合にのみ設定してください。
LMSTUDIO_ALLOW_MISSING_MODEL_LISTING	false	/v1/models エンドポイントがない OpenAI 互換サーバーを受け入れます。HuggingFace Text Embeddings Inference（TEI）などの単一モデルサーバーでは、モデルが起動時に固定され、一覧取得は 404 を返しますが、/v1/embeddings は通常どおり動作します。有効にすると（true / 1 / yes）、準備状態およびヘルスチェックでは、使い捨ての入力を 1 つ使って /v1/embeddings を確認する方法に切り替わり、確認結果のベクトル幅が EMBEDDING_DIMENSIONS と照合されます。一覧取得で 404 または 405 が返された場合にのみフォールバックします。接続拒否、401、または 5xx の場合は、引き続き LM Studio の診断情報が報告されます。false / 0 / no も受け付けます。それ以外の空でない値は、暗黙に false として扱わず、起動時に拒否されます。

LiteLLM の設定（EMBEDDING_PROVIDER=litellm の場合）

変数	デフォルト	説明
LITELLM_URL	http://localhost:4000/v1	LiteLLM プロキシの OpenAI 互換エンドポイントの完全なベース URL です。デフォルト以外のポートやリモートプロキシを使用する場合は上書きしてください（例：https://litellm.internal:4001/v1）。LiteLLM はこのプレフィックスの下に /v1/embeddings を公開するため、/v1 の接尾辞を含める必要があります。
LITELLM_API_KEY	(none)	必須です。 マスターキー（プロキシの config.yaml にある general_settings.master_key）または LiteLLM の /key/generate エンドポイントで発行された仮想キーです。LM Studio とは異なり、LiteLLM では常に認証が必要です。/v1/models 自体も認証で保護されています。
LITELLM_SEND_DIMENSIONS	false	オプトイン（true / 1 / yes）です。OpenAI 形式の dimensions パラメーターをプロキシ経由で転送します。Matryoshka 対応バックエンド（text-embedding-3-*、voyage-3）でのみ安全に使用できます。他のバックエンド（BGE、nomic-embed-text、Cohere v3）はリクエストを拒否します。エイリアスが Matryoshka モデルに解決されると確認できている場合を除き、設定しないでください。

Qdrant の設定

変数	デフォルト	説明
QDRANT_MODE	managed	managed = Docker で管理されるローカル Qdrant（デフォルト）。external = ユーザーが用意したリモートまたはクラウドの Qdrant（Docker による管理なし）。
QDRANT_URL	(none)	リモート／クラウドの Qdrant インスタンスの完全な URL（例：https://xyz.aws.cloud.qdrant.io:6333）。設定されている場合、QDRANT_HOST + QDRANT_PORT より優先されます。ポートは URL から自動的に判別されます。明示的なポートがある場合（例：:8443）はその値、ない場合は https:// なら 443、http:// なら 6333 になります。QDRANT_MODE=external の場合は必須です（または QDRANT_HOST を設定してください）。
QDRANT_PORT	16333	Qdrant REST API のポート（managed モード、または QDRANT_URL を指定しない external モード）
QDRANT_GRPC_PORT	16334	Qdrant gRPC のポート（managed モードのみ）
QDRANT_HOST	localhost	Qdrant のホスト名（HTTPS ではない外部インスタンスの場合、QDRANT_URL の代わりに指定）
QDRANT_API_KEY	(none)	Qdrant API キー（Qdrant Cloud およびその他の認証が必要なデプロイで必須）。設定する場合、キーが暗号化されずに HTTP で送信されないよう、URL は https://... にする必要があります。ローカル開発では、ループバック URL（localhost、127.0.0.1、[::1]）を http:// で使用できます。
QDRANT_COLLECTION_PREFIX	(empty)	SocratiCode が作成するすべての Qdrant コレクション名の先頭に付加する任意のプレフィックスです。1 つの Qdrant インスタンスを他のアプリケーション（Open-WebUI、カスタム RAG など）と共有する場合や、複数の SocratiCode インスタンスを 1 つの Qdrant に接続し、プロジェクト、環境、ユーザーごとのインデックスを分離する場合に便利です。デフォルトの空文字列では、以前のリリースからコレクション名は変更されず、完全な後方互換性が保たれます。設定する場合は [a-zA-Z0-9_-]+ に一致する必要があります。一致しないプレフィックスを指定すると、起動時にエラーが発生します。実行のたびにプレフィックスを変更すると、以前のコレクションが孤立します。移行が必要な場合は、先に codebase_remove を実行してください。

インデックス作成の動作

変数	デフォルト	説明
RESPECT_GITIGNORE	true	false に設定すると .gitignore の処理をスキップします。組み込みのデフォルトと .socraticodeignore は引き続き適用されます。
INCLUDE_DOT_FILES	false	true に設定すると、インデックス作成時にドットディレクトリ（例: .agent、.config）を含めます。デフォルトでは、. で始まるディレクトリとファイルは除外されます。重要なコードがドットディレクトリにあるプロジェクトで役立ちます。
EXTRA_EXTENSIONS	(なし)	スキャン対象とする追加のファイル拡張子をカンマ区切りで指定します（例: .tpl,.blade,.hbs）。インデックス作成とコードグラフの両方に適用されます。追加拡張子のファイルはプレーンテキストとしてインデックス化され、コードグラフではリーフノードとして表示されます。extraExtensions ツールパラメーターで操作ごとに渡すこともできます。
EXTENSION_LANGUAGE_MAP	(なし)	非標準の拡張子を実際の言語としてエンドツーエンドで扱う（セマンティック/AST チャンキング、シンボル、コールグラフ）ための、カンマ区切りの 拡張子:言語 オーバーライドです。例えば Drupal/PHP 向けに EXTENSION_LANGUAGE_MAP=.inc:php,.module:php と指定します。プレーンテキストとしてインデックス化する EXTRA_EXTENSIONS とは異なり、マッピングされた拡張子は完全な言語処理を受け、EXTRA_EXTENSIONS に列挙しなくても自動検出されます。ターゲットは SocratiCode が AST 文法を持つ言語（上記の Full Support リストに加え、AST グラフ対応言語）である必要があり、不明なターゲットは起動時の警告とともに無視されます。組み込みのマッピングもオーバーライドします（例: .h:cpp）。既存のコードコレクションは、新たにインデックス化されるまで有効なマップを保持します。
INDEX_EXTENSIONLESS	true	有効（デフォルト）の場合、拡張子のないファイルは、その内容がコードであると判別されたときにインデックス化されます — シバン（#!/bin/bash、#!/usr/bin/env python3 など）または保守的な内容スニッフ（シバンのない Python/シェル）。マッピングされていないインタープリター（perl、awk、make など）のシバンは、検索可能なプレーンテキストとしてインデックス化されます。バイナリ（先頭に NUL バイトを含むもの）および判別不能なテキスト（設定、ライセンス、データ）は決してインデックス化されません。実際のオンディスクパスは常に保持され、推定されるのは検出された言語/文法のみであるため、.txt と判別されたファイルはコードグラフには入りません。false または 0 に設定すると以前の動作（拡張子のないファイルは、その正確な名前が Dockerfile/Makefile のような特殊ファイルである場合にのみインデックス化）に戻ります。ライターの一貫性: 1 つのコレクションに書き込むすべてのプロセスがこのフラグについて一致している必要があります — 混在した構成では、実行ごとに拡張子のないチャンクが揺れ動きます。
MAX_FILE_SIZE_MB	5	最大ファイルサイズ（MB）。値は完全な有限数である必要があり、5MB のような不正な部分値は拒否されます。これより大きいファイルはインデックス作成時にスキップされます。インデックス化したい大きな生成ファイルやデータファイルがあるリポジトリでは増やしてください。既存のコードコレクションは、新たにインデックス化されるまで有効な制限を保持します。有効な制限を超えて大きくなったファイルは、古いチャンクが削除されます。
MAX_CHUNK_CHARS	2000	チャンクあたりの文字数上限。フォーマット 2 としてインデックス化されたコレクションでは、これを超えるチャンクは切り捨てではなく分割されます。チャンキングは行数（100 行）で区切るため、文字数で数えた上限をチャンクが超えることがあり、その場合は超過分が切り捨てられるのではなくさらなるチャンクになります。通常のチャンクは、利用可能であれば上限以前の最後の改行で終わります。圧縮またはバンドルされたコードでは、リリース済みのチャンカーによるスペース、タブ、セミコロン、カンマの境界も考慮され、可能な限り識別子の途中での分割を避けます。有効な境界がない場合、その部分は上限で終わります。サロゲートペアや CRLF を保つために境界が 1 UTF-16 コード単位分ずれることがあるため、1 の上限でも 2 コード単位の部分が生成される場合があります。空白のみを含む部分を除き、何も切り捨てられません。フォーマット 2 より前にインデックス化されたコレクションは切り捨てを続けます — 上限を超えた内容はチャンクが保存される前に切り捨てられるため、ベクトルにも、ペイロードにも、キーワード（BM25）テキストにも到達しません。そのようなインデックスは、保存された、場合によっては切り捨てられた範囲のまま動作し続けます。codebase_remove の後に codebase_index を実行するとフォーマット 2 が採用され、省略された内容が回復しますが、これは任意です。デフォルトが想定するよりもコンテキストが小さい埋め込みモデルに合わせるには、この上限を下げてください。モデルのコンテキスト長 × プロバイダーの文字あたりトークン数の推定値を超えて上げても、1 つの埋め込みに入る内容は増えません。プロバイダーが事前に切り捨てるため、余分な文字は保存されたペイロードとキーワード（BM25）テキストには到達しますが、ベクトルには反映されません。既存のコードコレクションとコンテキストコレクションは、新たにインデックス化されるまで有効な上限を保持します。
SEARCH_DEFAULT_LIMIT	10	codebase_search が返す結果のデフォルト件数（1〜50）。各結果は、ファイルパス、行範囲、内容を含むランク付けされたコードチャンクです。値を大きくするとカバレッジが広がりますが、出力が増えます。limit ツールパラメーターでクエリごとに上書きすることもできます。
SEARCH_MIN_SCORE	0.10	最小スコアしきい値（0〜1）。このスコアを下回る結果は除外されます。検索結果から関連性の低いノイズを取り除くのに役立ちます。0 に設定するとフィルタリングが無効になります（limit までのすべての結果を返します）。minScore ツールパラメーターでクエリごとに上書きすることもできます。limit と連携して動作します。結果はまずスコアでフィルタリングされ、次に limit で上限が適用されます。スコアは、単一プロジェクト検索では RRF（Reciprocal Rank Fusion）値であり、クロスプロジェクト検索（includeLinked: true）ではコサイン類似度です。いずれかのヒットでコサインが利用できない場合は RRF にフォールバックします — スケールが異なる理由と、それがこのしきい値にとって何を意味するかについては、以下のクロスプロジェクト検索を参照してください。
SOCRATICODE_PROJECT_ID	(なし)	自動生成されるプロジェクト ID をオーバーライドします。設定すると、すべてのパスが同じ Qdrant コレクションに解決され、複数のディレクトリ（例: 同じリポジトリの git ワークツリー）が単一のインデックスを共有できるようになります。[a-zA-Z0-9_-]+ に一致する必要があります。.socraticode.json の projectId フィールドより優先されます。
SOCRATICODE_BRANCH_AWARE	false	true の場合、現在の git ブランチ名をプロジェクト ID に付加し、ブランチごとに別々の Qdrant コレクションを作成します。SOCRATICODE_PROJECT_ID が設定されている場合、または .socraticode.json で projectId が設定されている場合は無視されます。
SOCRATICODE_LINKED_PROJECTS	(なし)	クロスプロジェクト検索に含める追加のプロジェクトパスをカンマ区切りで指定します。.socraticode.json のパスとマージされます。存在しないパスは黙ってスキップされます。
SOCRATICODE_WATCHER	auto	更新ポリシー（大文字小文字を区別しません）: auto はデフォルトのファイルウォッチャーを維持します。manual は明示的なウォッチャー開始のみを許可します。off はすべてのウォッチャー開始を拒否します。git はファイルウォッチャーの開始を拒否し、ref/HEAD の変更時にアクティブなインデックス済みチェックアウトを更新します。manual と off では、グラフクエリは不足しているグラフを作成しません。無効な値は起動時に失敗します。チェックアウトとインデックスを共有するすべての MCP プロセスで設定してください。再インデックスは不要です。
SOCRATICODE_AUTO_RESUME	(なし)	起動ポリシー: 未設定の場合は既存の現在のプロジェクトのキャッチアップ/リカバリ動作を維持します。all は保存されたパスを持つすべてのインデックス済みプロジェクトを順次再開します。off は Docker や Qdrant へのアクセスの前に、すべての起動時キャッチアップ更新と中断されたインデックスのリカバリをスキップします。off は SOCRATICODE_AUTO_RESUME_PROJECTS より優先されます。これは、後のツール使用によって引き起こされるウォッチャーの開始を無効にするものではありません。意図的なスナップショットにするには SOCRATICODE_WATCHER=off と組み合わせてください。
SOCRATICODE_AUTO_RESUME_PROJECTS	(なし)	サーバー起動時に自動再開するプロジェクトパスをカンマ区切りで指定します（順次実行）。例: /repos/api,/repos/web。未設定/all の動作より優先されますが、SOCRATICODE_AUTO_RESUME=off よりは優先されません。存在しないパス、またはインデックス化されていないパスは警告とともにスキップされます。
SOCRATICODE_AUTO_CLEANUP	(off)	ホスト専用の管理対象ループバック Qdrant を宣言し、廃止が証明されたローカル所有のワークツリー/ブランチ ID のクリーンアップをオプトインする場合にのみ local に設定します。未設定または off の場合、自動クリーンアップは実行されません。既存の非所有レコードはレポートのみのままです。自動再開とは独立しています。オプションの自動ローカルクリーンアップを参照してください。
SOCRATICODE_LOG_LEVEL	info	ログの冗長性: debug、info、warn、error
SOCRATICODE_LOG_FILE	(なし)	ログファイルへの絶対パス。設定すると、すべてのログエントリがこのファイルに追記されます（サーバー起動ごとにセッション区切りが書き込まれます）。MCP ホストがログ通知を表示しない場合のデバッグに役立ちます。

重要：既存のコレクションは、実行時の設定が変更されても、保存されている有効なプロバイダー、モデル、次元数を維持します。codebase_status は、要求された設定との差異を保留中として報告します。反映するには、codebase_remove でコレクションを削除してから、codebase_index で新しいインデックスを作成してください。既存のインデックスを引き続き使用する場合は不要ですが、設定を反映するには、この明示的な再構築が必要です。

Docker リソース

SocratiCode は Docker コンテナと永続ボリュームを管理します。

リソース	名前	目的	使用モード
コンテナ	socraticode-qdrant	Qdrant ベクトルデータベース（固定バージョン v1.17.0）	managed モードのみ
コンテナ	socraticode-ollama	Ollama 埋め込みサーバー	docker モードのみ
ボリューム	socraticode_qdrant_data	永続ベクトルストレージ	managed モードのみ
ボリューム	socraticode_ollama_data	永続モデルストレージ	docker モードのみ

QDRANT_MODE=external モードでは、Qdrant コンテナとボリュームは作成も起動もされません。SocratiCode は設定されたリモートエンドポイントに直接接続します。サーバー側の BM25 推論（ハイブリッド検索で使用）には、Qdrant v1.15.2 以降が必要です。管理対象のコンテナでは v1.17.0 を実行します。独自の Qdrant インスタンスを使用する場合は、この最小要件を満たしていることを確認してください。

すべてのコンテナでは、自動復旧のために --restart unless-stopped を使用します。

標準とは異なるポートを使用する理由：SocratiCode は、管理対象コンテナで意図的にデフォルト以外のポートを使用します。Qdrant のデフォルト（6333／6334）の代わりに 16333／16334、Ollama のデフォルト（11434）の代わりに 11435 を使用します。これにより、ローカルで実行中の Qdrant や Ollama との競合を避けられます。必要に応じて、すべてのポートを環境変数で変更できます。

テスト

SocratiCode には、ユニット、統合、エンドツーエンドの各レイヤーにわたる包括的なテストスイートがあります。

前提条件

• ユニットテスト：外部依存関係は不要です。
• 統合テストと E2E テスト：Qdrant および Ollama コンテナを実行する Docker が必要です。コンテナはテストインフラストラクチャによって自動的に管理されます。

テストの実行

# Run all tests
npm test

# Run only unit tests (no Docker needed)
npm run test:unit

# Run integration tests (requires Docker)
npm run test:integration

# Run end-to-end tests (requires Docker)
npm run test:e2e

# Watch mode (re-runs on file changes)
npm run test:watch

# With coverage report
npm run test:coverage

テストアーキテクチャ

レイヤー	Docker	説明
ユニット（tests/unit/）	いいえ	設定、定数、無視ルール、プロセス間ロック、ログ記録、グラフ分析、インポート抽出、パス解決、埋め込み設定、インデクサーユーティリティ、埋め込み、起動ライフサイクル、ウォッチャーのプロセス間認識
統合（tests/integration/）	はい	Docker／Ollama のセットアップ、Qdrant の CRUD、実際の埋め込み、インデクサー、ウォッチャー、コードグラフ、すべての MCP ツール
E2E（tests/e2e/）	はい	完全なライフサイクル：ヘルスチェック → インデックス作成 → 検索 → グラフ → 監視 → 削除

Docker が必要な統合テストと E2E テストは、Docker を利用できない場合、自動的にスキップされます。

grep だけでは不十分な理由

実際のリポジトリを対象とした最新の評価では、自然言語クエリ、大規模なコードベース、コーディングエージェントを考慮する場合、ハイブリッドな字句検索とセマンティックコード検索は、単純な grep より一貫して優れた結果を示しています。報告によると、BM25F ランキングにより大規模環境で検索品質が約 20% 向上し、AST を考慮した検索により RepoEval と SWE-bench で再現率とバグ修正性能が改善しています。また、grep とのハイブリッド方式（SocratiCode のデフォルト）は、エージェントによるコード検索タスクの 70% で grep を上回り、検索操作を半分以上削減しています。

実環境でのベンチマーク：Claude Opus 4.6 による VS Code（245 万行のコード）

VS Code のコードベース（5,300 以上のファイルにわたる約 245 万行の TypeScript／JavaScript、インデックス化されたチャンクは 55,437 個）を使って直接比較し、アーキテクチャに関する質問への回答時に Claude Opus 4.6 の AI エージェントが実際に処理する量を測定します。

方法： 各質問に対し、grep 方式では、現在の AI エージェントが使う現実的な複数ステップのワークフローに沿って、grep -rl で該当するファイルを検索し、主要なファイルを特定して、チャンク単位（1 回につき 200 行）で読み込み、十分なコンテキストが得られるまで繰り返します。SocratiCode 方式では、コードベース全体から関連性の高い上位 10 個のコードチャンクを返すセマンティック検索を 1 回実行します。

質問	Grep（バイト）	SocratiCode（バイト）	削減率	高速化率
VS Code はワークスペースの信頼制限をどのように実装していますか？	56,383	21,149	62.5%	49.7x
差分エディターはテキストの差分をどのように計算して表示していますか？	37,650	15,961	57.6%	40.2x
VS Code は拡張機能の有効化とライフサイクルをどのように管理していますか？	36,231	16,181	55.3%	34.4x
統合ターミナルはシェルをどのように起動し、管理していますか？	50,159	22,518	55.1%	31.1x
VS Code はコマンドパレットとクイックピックをどのように実装していますか？	70,087	20,676	70.5%	31.7x
合計	250,510	96,485	61.5%	37.2x

主な結果：

• ツール呼び出しが 84% 減少 — Grep では 5 つの質問に対して計 31 ステップ（質問ごとに 6～7 ステップ）が必要でした。SocratiCode では計 5 ステップ（質問ごとに 1 ステップ）でした。
• 処理データが 61.5% 減少 — AI エージェントが処理するコンテキストを約 150 KB 削減でき、どの LLM を使う場合でもトークンコストを直接抑えられます。
• 37 倍高速 — 245 万行を Grep でスキャンすると、質問ごとに 2～3.5 秒かかることがあります。セマンティック検索なら 60～90 ms ほどです。

注： このベンチマークでは、Grep 方式に有利な 保守的な 条件を想定しています。エージェントがどのファイルを読むべきか、すでに把握している前提です。実際には、AI エージェントは追加の探索的な grep 呼び出しを行い、行き止まりをたどったり、無関係なファイルを読んだり、絞り込みを何度も繰り返したりする必要があります。そのため、実際の削減効果はさらに大きくなる可能性があります。

ハイブリッド検索が有効な場合

自然言語による概念的なクエリ — *「データベースのコネクションプーリングはどこで処理していますか？」や「このライブラリでは指数バックオフをどのように実装していますか？」*のようなクエリは、関数名ではなく動作について尋ねるものです。リポジトリレベルのベンチマーク（RepoEval、SWE-bench）での評価では、AST を考慮したセマンティック検索により、固定の行ベースのチャンクと比べて再現率が最大 4.3 ポイント、下流のコード生成精度が約 2.7 ポイント向上することが示されています。実際のオープンソースリポジトリを使ったエージェント評価では、難易度の高い概念的な質問に対して、ハイブリッド検索は通常の grep に対して 70% の勝率を示しました。検索操作は 56% 減少し、複雑なクエリ 1 件あたりのトークン数も約 60,000 減少しています。

大規模なリポジトリやモノレポ — 数百万行のコードになると、全文スキャンは高コストになります。実運用の検索エンジンでは、従来の手法と比べて BM25F ランキングによって関連性が約 20% 向上することが報告されており、セマンティックな再ランキングの第一段階の検索器として採用されています。転置インデックスとベクトルインデックスを利用するハイブリッド検索は、全文スキャンを完全に回避するため、大規模環境でも高速かつ高精度です。業界の実務者も、grep と find は「数百万のファイルにはうまくスケールしない」と明言しており、最適化された埋め込みベースのインデックスはその規模でより高速になり得ると述べています。

ファイルや言語をまたぐ推論 — サービス間で最終的に内部ヘルパーを呼び出すすべてのコードパスを見つけたり、自然言語の仕様を Go と SQL の実装に対応付けたりするには、文字列の照合を超えた理解が必要です。評価では、tree-sitter による解析と依存関係のコンテキストを組み合わせたハイブリッドパイプラインは、名前から機能が明確に分からず、セマンティックな理解が必要な場合に grep より優れた結果を示しています。学習済みの検索器を使った AST ベースのチャンク化は、複数言語のベンチマークで検索精度を向上させます。また、複数ベクトルを用いるセマンティックモデルは、クエリが自然言語で記述され、対象が多様な言語にまたがるコード検索タスク（AppsRetrieval、CodeSearchNet、CosQA）において、BM25 単独と比べて大きな改善を示しています。

コードとコンテキスト成果物の混在 — *「レート制限はどこで設定されていますか？」*のような質問は、アプリケーションコードだけでなく、Nginx の設定ファイル、Terraform ファイル、YAML に該当する場合があります。構造化フィールドとフリーテキストが混在する技術文書群に対するハイブリッド検索は、公開されている評価で、純粋な字句検索や純粋なベクトル検索を一貫して上回っています。

grep が依然として有効な場合

同じ研究では、grep（または ripgrep）が十分に妥当であり、ときには最適となる場合も明らかにされています。

• 正確な識別子、エラー文字列、または正規表現パターンが分かっている場合。 埋めるべきセマンティックな隔たりがありません。
• リポジトリの規模が適度な場合 — 全文スキャンを低コストで高速に実行できます。
• 内容が限定され、特徴的な名前を持つ構造化コードである場合であり、散文やドキュメントではありません。

簡単なクエリや名前が直接指定されたクエリでは、grep はセマンティックな手法に匹敵するか、それを上回る場合があります。そのため、最適なアーキテクチャは grep を置き換えるのではなく、拡張します。SocratiCode のハイブリッド方式では、すべてのクエリに対して BM25 キーワード検索と高密度セマンティック検索の両方を実行し、RRF で結果を統合します。これにより、1 回の呼び出しで正確な一致による精度とセマンティックな理解による再現率を両立できます。

よくある質問

インデックス作成中にエラーが発生しました。最初からやり直さずに再開できますか？

はい。インデックス作成は、中断したところから自動的に再開されます。インデクサーはファイルのハッシュを、ファイルのバッチごとにチェックポイントとして保存します。AI に再度インデックス作成を依頼すると（例：「このプロジェクトをインデックス化して」）、既存のデータを検出し、すでに埋め込みに成功したファイルをすべてスキップして、エラー発生前にチェックポイントへ保存されていなかったファイルだけを再処理します。インデックス作成済みのチャンクが削除されたり、再度埋め込まれたりすることはありません。AI に再度インデックス作成を依頼するだけで、中断したところから続行できます。

大規模なコードベースのインデックス作成中に、MCP ホストが切断されます。どうすればよいですか？

インデックス作成は MCP サーバー上でバックグラウンド実行されます。ただし、一部の MCP ホスト（VS Code、 Claude Desktop など）は、一定時間操作がないとアイドル状態の接続を切断し、バックグラウンドプロセスを終了します。 接続を維持するには、インデックス作成を開始した後、完了するまでおよそ 60 秒ごとに AI にステータスを確認するよう依頼します （例：「インデックス作成のステータスを確認して」）。接続が切れてインデックス作成が中断された場合は、AI にもう一度 インデックスを作成するよう依頼してください。自動的に再開されます（上記を参照）。

インデックス作成が繰り返し失敗する、または正しく再開されません。どうすればよいですか？

インデックス作成が繰り返し失敗する、再開時にエラーが発生する、またはループ状態から抜け出せない場合は、最も簡単な解決策として 最初からやり直します。AI に 「このプロジェクトのインデックスを削除して」 と依頼してから、もう一度インデックスを作成するよう 依頼してください。これにより、そのプロジェクトに保存されているチャンクとメタデータがすべて消去され、クリーンな状態で インデックス作成が始まります。他のインデックス済みプロジェクトには影響しません。

コードベースが非常に大きいのですが、インデックス作成を一時停止して後から再開できますか？

はい。進行状況を失うことなく、いつでもインデックス作成を停止し、後から再開できます。

1. AI アシスタントに停止を依頼する — 「インデックス作成を停止して」 などと伝えると、次のバッチ境界で現在の処理がキャンセルされます。そこまでに完了したすべてのバッチはチェックポイントとして保存されます。
2. または、プロジェクト／エディターを閉じる — SocratiCode が切断を検出して適切に終了し、チェックポイントとして保存された進行状況をすべて保持します。
3. 好きなときに再開する — エディターで同じプロジェクトを開き、AI にインデックス作成の再開を依頼します（例：「インデックス作成を再開して」）。SocratiCode は未完了のインデックスを自動的に検出し、すでに埋め込み済みのファイルをすべてスキップして、中断したところから再開します。

この方法なら、低速なハードウェアでも非常に大規模なコードベースのインデックスを実用的に作成できます。数時間から数日にわたって複数のセッションに分けて作業でき、作業が繰り返されたり失われたりすることはありません。

プロジェクトを開き直しましたが、新規／変更したファイルが検索結果に表示されません。

デフォルトの SOCRATICODE_WATCHER=auto モードでは、サーバーの起動時に、MCP プロセスの作業ディレクトリに対応するインデックス済みプロジェクトの監視を再開します。ウォッチャーを起動し、SocratiCode の停止中に変更されたファイルをすべて反映してから、今後の変更を監視します。起動時に追加のプロジェクトを選択するには、SOCRATICODE_AUTO_RESUME_PROJECTS または SOCRATICODE_AUTO_RESUME=all を使用します。起動時に選択されなかった、インデックス作成が完了しているプロジェクトでは、最初の検索、ステータス確認、またはグラフ操作時に同じフォールバック処理でウォッチャーが起動します。

検索の前にすぐに変更を反映したい場合は、AI に 「このプロジェクトの監視を開始して」 または 「インデックスを更新して」 と依頼してください。どちらも同期的に増分更新を実行してから、監視を開始します。

完全なインデックス作成または増分更新が進行中の場合、プロジェクトがまだインデックス化されていない場合、または別の MCP プロセスが同じプロジェクトをすでに監視している場合、ウォッチャーは自動起動しません。また、manual モードまたは off モードでも自動起動しません。これらのモードでは、codebase_status と検索結果に、エージェントにウォッチャーの再起動を依頼する代わりに、インデックスがスナップショットとして表示されます。

スナップショットの状態を完全に維持するには、チェックアウトを使用するすべての MCP プロセスで SOCRATICODE_WATCHER=off と SOCRATICODE_AUTO_RESUME=off を設定します。既存のインデックスとグラフは、再インデックスせずに引き続き読み取れます。 コードのインデックスを更新するには codebase_update を実行し、グラフを明示的に作成または再構築するには codebase_graph_build を実行します。明示的に一時的な監視を行いたい場合は、代わりに SOCRATICODE_WATCHER=manual を使用します。

複数のインデックス済みリポジトリを使っていて、開いたリポジトリだけでなく、すべてのリポジトリについてサーバー起動時に監視と変更反映を再開したい場合は、インデックス作成の動作 の表にある SOCRATICODE_AUTO_RESUME と SOCRATICODE_AUTO_RESUME_PROJECTS 環境変数を参照してください。

Git トリガーによる更新

SOCRATICODE_WATCHER=git を設定すると、MCP サーバーの実行中に継続的なファイル監視の代わりに、固定の 10 秒間隔の Git 状態チェックが行われます。検索、ステータス、グラフのリクエストも、現在の ref と HEAD をチェックします。コミット、チェックアウト、fast-forward、リベース、および同一コミット内でのブランチ切り替えはインクリメンタル更新をトリガーしますが、チェックアウトされている ref と HEAD を変更しない通常のファイル保存やフェッチはトリガーになりません。

Git はトリガーであり、コンテンツのソースではありません。更新はコミットされていない編集を含むワーキングツリーをインデックス化します。それらの編集を次の Git の遷移の前に検索可能にする必要がある場合は、いつでも codebase_update を実行してください。このモードでは codebase_watch はネイティブのウォッチャーを起動できません。Git がサーバーの PATH 上で利用可能である必要があります。実行ファイルが存在しない場合や Git ディレクトリでない場合には、目に見える診断が出力され、ファイルウォッチャーへのフォールバックは行われません。明示的なインデックス作成は、Git 以外のプロジェクトでも引き続き利用できます。

監視されるのは、起動時に選択された、またはその後ツールによって使用された、すでにインデックス化済みのチェックアウトのみです。このモードを選択しても、プロジェクトの最初のインデックスが作成されたり、他のワークツリーが検出されたりすることはありません。既存の起動時のプロジェクト選択設定は引き続き適用されます。SOCRATICODE_AUTO_RESUME=off は起動時のキャッチアップを抑制します。その後の最初のツールリクエストは、既存のインデックスが最新であると主張することなく監視をアタッチし、明示的な更新またはその後の Git の遷移によって鮮度が確立されます。

既存の共有 ID およびブランチ対応 ID は維持されます。インデックス化済みのチェックアウトを監視した後、ブランチ対応 ID が有効な場合、インデックス化されていないブランチに切り替えるとそのブランチのインデックスが作成されることがあります。Detached HEAD は既存のパスベースの ID ルールに従います。明示的なプロジェクト ID は引き続き優先されます。

検索とグラフの結果は、保留中、失敗、または未検証の更新を報告します。更新中にロックのビジー、キャンセル、失敗、またはチェックアウトの変更が発生した場合、その更新は保留のままとされ再試行されます。安定した観測に対するインデックス作成とグラフの照合が成功した場合にのみ、同期済みとして報告されます。複数の MCP プロセスは、既存のプロセス間ライター ロックを使用します。フック、サービス、永続化された Git カーソル、マイグレーション、インデックスのリセットは不要です。すべてのプロセスを一貫して設定してください。別のプロセスにあるファイルウォッチャーは、ファイル保存時に共有インデックスを更新する可能性があります。同じホスト上の協調するプロセスは、既存のロックのために同じ OS 一時ディレクトリを使用する必要があります。これらのロックは異なるホスト上のライターを調整しません。共有チームインデックスには依然として指定ライターが必要です。

複数の AI エージェントが同じコードベースで同時に作業できますか？

はい — これは第一級でサポートされるワークフローです。複数のエージェント（それぞれが独自の MCP サーバーインスタンスを実行）が同じプロジェクトディレクトリを指している場合、それらは自動的に同じ Qdrant インデックスを共有します。最初にインデックス作成をトリガーしたエージェントがプロセス間ロックを取得してインデックスを構築し、同時にインデックスを作成しようとする他のエージェントは、重複した操作を開始する代わりに現在の進捗を受け取ります。すべてのエージェントは調整を必要とせずに同時に検索できます — Qdrant は並列読み取りをネイティブに処理します。

ファイルウォッチャーも自動的に連携します。プロジェクトごとに監視するプロセスは 1 つだけです。他のインスタンスはこれを検出し、ウォッチャーの起動をスキップします。監視しているプロセスがファイル変更を検知すると、共有インデックスを更新し、すべてのエージェントの次の検索で更新された結果が表示されます。

ウォッチャーまたはインデックス作成ロックを所有するエージェントがクラッシュした場合、そのロックは 2 分後に古いものとなり、別のエージェントの次の操作で自動的に再取得されます。手動での介入は不要です。

これにより、SocratiCode はマルチエージェントワークフローに最適です。あるエージェントがテストを書きながら別のエージェントがコードを修正する、プランニングエージェントと実装エージェントが並行して作業する、あるいは作業を重複させることなく深いコードベースの知識を共有する AI アシスタントの任意の組み合わせなどが可能です。

複数のプロジェクトを同時にインデックス化できますか？

はい。SocratiCode は、プロジェクトのパスごとに独立したコレクションを管理します。AI に *「インデックス化済みのプロジェクトをすべて一覧表示して」*と尋ねると、現在インデックス化されているものを確認できます。

埋め込みプロバイダーやモデルを変更するとどうなりますか？

各コレクションには、インデックスの作成時に使用されたプロバイダー、モデル、次元数、クエリの動作が記録されています。MCP 設定でこれらの設定を変更しても、既存のコレクションには反映されません。インデックス化と検索は保存されたプロファイルを使って続行され、codebase_status は要求された設定が保留中であることを報告します。新しい設定を有効にするには、AI に*「このプロジェクトのインデックスを削除して」*と頼んでから、再度インデックス化してください。他のコレクションは、それぞれのプロファイルを引き続き使用します。

プロジェクトのインデックスを削除するにはどうすればよいですか（例：埋め込みモデルの変更や、最初からインデックスを作り直す場合）？

1. 最初に停止 — インデックス化が進行中の場合は、*「このプロジェクトのインデックス化を停止して」*と伝えてください。インデックス化中に削除するとデータが破損するため、現在のバッチが完了するまで削除は拒否されます。
2. 削除 — *「このプロジェクトのインデックスを削除して」*と伝えてください。このプロジェクトのベクターコレクション、保存されたすべてのチャンクメタデータ、コードグラフ、コンテキストアーティファクトのメタデータが削除されます。他のプロジェクトには影響しません。
3. 再インデックス化 — 必要に応じて MCP 設定を新しいパラメーターに更新してから、*「このプロジェクトをインデックス化して」*と伝えて、最初から開始してください。

SocratiCode のロゴにある、ソクラテスの後ろのコードは何ですか？

ソクラテスの後ろに見えるコードは、アポロ11号誘導コンピューター（AGC）のコマンドモジュール（Comanche055）のオリジナルソースコードの一部です！

コミュニティ

• 💬 Discord — ユーザーやメンテナーと交流したり、「どうすればよいですか？」と質問したり、開発中のものを共有したりできます
• 🐛 GitHub Issues — バグ報告や確認済みの機能リクエスト（テンプレートを使用してください）
• 📣 リリース — リポジトリを Watch（GitHub の右上 → Custom → Releases）すると、新しいバージョンの通知を受け取れます

SocratiCode が役に立った場合、最もありがたいのは ⭐ リポジトリにスターを付けることです。ほかの人がこのプロジェクトを見つけるきっかけになります。

---

SocratiCode Cloud

SocratiCode のエンジン全体は、AGPL-3.0 の下で無料のオープンソースとして提供されており、今後もその方針は変わりません。SocratiCode Cloud は、同じエンジンを基盤とする任意利用のホスト版です。共有型のマネージドでコンプライアンスに対応したインフラを必要とするチーム向けに、現在プライベートベータとして提供しています。

OSS エンジンに加えて Cloud が提供するもの：

• チーム共有インデックス — すべての開発者が同じデータを検索でき、すべてのブランチへのプッシュごとに自動でインデックス化
• リポジトリ横断検索 — 組織が所有するすべてのリポジトリに、1 回の呼び出しでクエリを実行
• SSO / SAML、監査ログ、IP 許可リスト — 後から有料オプションとして追加するのではなく、標準で組み込み済み
• デプロイモデル — マネージドクラウド（EU/US）、独自の VPC（AWS/GCP/Azure）、または完全にエアギャップ化されたオンプレミス
• Web ダッシュボード — 検索、依存関係グラフ、アーティファクト、チームとリポジトリの管理
• ローカルインフラ不要 — チームが Docker、Qdrant、Ollama を管理する必要はありません

現在、少数のエンジニアリングチームの利用を順次開始しています。早期アクセスをリクエスト →

このリポジトリのオープンソースエンジンは、Cloud を支えるエンジンと同じものであり、今後も変わりません。誤解を招くような変更も、OSS コアの機能制限もありません。Cloud は、その周囲にチーム、デプロイ、コンプライアンスのレイヤーを追加するだけです。

---

ライセンス

SocratiCode はデュアルライセンスです：

• オープンソース — AGPL-3.0。無料で利用、変更、配布できます。 SocratiCode を変更してネットワークサービスとして提供する場合、変更内容を AGPL-3.0 の下で公開する必要があります。

• 商用 — AGPL の義務なしで SocratiCode を独自製品やサービスに使用する必要がある組織向けです。LICENSE-COMMERCIAL を参照するか、[email protected] までお問い合わせください。

Copyright (C) 2026 Giancarlo Erra - Altaire Limited.

サードパーティライセンス

SocratiCode には、それぞれ独自のライセンス（MIT、Apache 2.0、ISC、BSD 3-Clause）のもとで提供されるオープンソースの依存関係が含まれています。詳細はサードパーティライセンスをご覧ください。

コントリビューション

コントリビューションを歓迎します。プルリクエストを提出すると、コントリビューターライセンス契約に同意したものとみなされます。