ローカルホスト型のコード検索サーバーであるSverkloは、AIエージェントが検索結果に基づいて動作する前に、ファイルの発見からシンボルグラフによる推論に至るまで、クエリのあらゆるステップを開発者が検証できるようにします。

既存のコーディングエージェントが苦戦する理由

ほとんどのコード生成ツールは、リポジトリを巨大なテキストの塊として扱います。それらはスニペットを埋め込み、類似性検索を実行し、最もスコアの高い断片を返します。その断片が古かったり、範囲外であったり、あるいは単なるファイル名であったりする場合、エージェントはそのソースを特定することができません。失敗のパターンは「言葉が足りない」ことではなく、その事実が「どこから来たのか」、そして「それがまだ適用可能か」を人間に伝えるための「コンテキスト層」が欠如していることなのです。

Sverkloの4層検証モデル

Sverkloは、従来の検索に構造解析を組み合わせた「エンジニアリング上の仮説」サーバーとして位置付けられています。

  • ファイルの発見 (File Discovery) – インデックスは .gitignore やその他の無視ファイル（ignore files）を読み取ります。結果を信頼する前に、どのパスが実際にスキャンされたかをインデックスに対してクエリして確認できます。
  • コード構造 (Code Structure) – シンボルは、定義、インポート、および呼び出し関係を記録するグラフ内に存在します。ルックアップを行うと、単なるファイルパスではなくシンボルオブジェクトが返されるため、正しいAPIサーフェスが参照されていることを確認できます。
  • コンテキストの提供 (Context Delivery) – トークン予算を設定すると、Sverkloは回答に寄与したスニペットのマップを返します。このマップには found_by フィールドが含まれており、マッチングがBM25キーワードマッチングによるものか、ONNX生成の埋め込みによるものか、あるいはPageRankでランク付けされたシンボルグラフによるものかを示します。
  • メモリ台帳 (Memory Ledger) – サーバーは各決定をログに記録します。ファイルが変更されると、台帳は対応するメモリのエントリを「古い（stale）」としてフラグを立て、キャッシュされた回答がまだ有効かどうかを示します。

検索スタックの仕組み

Sverkloは埋め込み（embeddings）だけに依存しているわけではありません。正確な用語一致のために古典的なBM25キーワードエンジンを実行し、それらのヒットをONNXベースのベクトル埋め込みで拡張して意味的な類似性を高め、さらにシンボルグラフに対してPageRankアルゴリズムを適用して影響力の大きい定義を提示します。各ヒットを生成した手法を公開することで、開発者は不一致（例えば、BM25ではヒットしたが埋め込みモデルでは無関係と判断されたものなど）を特定し、どのシグナルを信頼するかを選択できます。

実用的なユースケース

  • 未知のコードベースの探索 – 手動でgrepすることなく、関数名からそのすべての呼び出し元へジャンプできます。
  • 依存関係グラフのマッピング – 複数のパッケージにまたがるインポートの連鎖を可視化できます。
  • リファクタリングの影響予測 – 特定のファイルが変更された場合に、どのシンボルが壊れるかを確認できます。
  • 意味的な質問への回答 – 「このヘルパーは何をするものか？」と尋ねると、簡潔で出典の明らかな抜粋が得られます。

注意すべき落とし穴

  • 最新性 (Freshness) – 再インデックスが完了しても、インデックスのタイムスタンプが古いままの場合があります。最新の実行が現在のものだと決めつけず、常に index-status エンドポイントに対してクエリを実行してください。
  • プロジェクトの登録 – プロジェクトの登録を解除する際は、絶対ファイルシステムパスではなく、Sverkloから提供された内部プロジェクト名を使用してください。そうしないと、操作はエラーを出さずに失敗します。
  • ツールの命名に関する癖 – MCPホストは、プロジェクト名を二重に付与して sverklo_sverklo_impact のような識別子を生成することがあります。ツールを呼び出す前に名前を再確認してください。

次に試すべきこと

  1. 使い捨てのリポジトリをクローンし、ローカルでSverkloを立ち上げる。
  2. 単純なシンボルルックアップを実行し、found_by フィールドを検証する。
  3. ソースファイルを修正してルックアップを再実行し、メモリ台帳が古いエントリにどのようにフラグを立てるかを確認する。
  4. 古いインデックスを自動的に検知するために、index-status チェックをビルドスクリプトに組み込む。

まとめ

Sverkloは、コード検索エンジンを「監査可能な証拠の連鎖」へと変貌させます。ファイルの網羅性、シンボルの正確性、検索手法、そしてメモリの鮮度を開発者に検証させることで、AIによる提案が本番環境に到達する前に、それが信頼できるかどうかを判断できるようにします。