sonde

Sonde

AI コーディングエージェント向けのローカルコードコンテキストエンジンです。Sonde は TypeScript、 Python、または Swift のリポジトリを SQLite 内のシンボルレベルのグラフにインデックスし、 3 つの MCP ツール、find_symbols、query_graph、get_impact_radius を公開します。これにより、 エージェントは検索を繰り返さず、1 回の呼び出しで これを呼び出しているのは誰か、これを変更すると何が壊れるか、どのテストが関連するか に答えられます。

ベンチマークが実際に示すこと

誠実な主張は、「grep では見つけられないものが見つかる」ではありません。優れたエージェント型検索ループでも同じ構造的な証拠を見つけられます。実際の 19,409 行のリポジトリで測定したところ、すべてのタスクで再現率は 1.000 でした。

主張は、予算内で、わずかなコストで同じ答えを得られることです：

実際の本番用 TypeScript での結果	Sonde	エージェント型検索
構造的タスクでの再現率	1.00	1.00
ツール呼び出し回数	1.0	8.0
コンテキストトークン数	1,262	3,621
レイテンシ	263 ms	38,602 ms
トークン予算を超過した実行回数	6 回中 0 回	6 回中 3 回

Sonde は、ベースラインとすべての構造的タスクで同じ答えを返しながら、コンテキストを約 3 分の 1、呼び出し回数を 8 分の 1、実時間を約 147 分の 1 に抑えます。また、パッカーが設計上、指定されたトークン予算に合わせて切り詰めるため、呼び出し元のトークン予算を超えることはありません。これが提供するトレードオフです。

不得意なこと。 共通の語彙がない振る舞いに関するクエリ、たとえば 「再試行のバックオフはどこで決まるのか？」 のスコアは 0.00 です。ローカルのセマンティック検索も実装して測定しましたが、この問題は解決しませんでした（設計ドキュメントの §2.2 を参照）。そのため、この機能は主張していません。質問の大半がこのようなものであれば、現時点ではエージェント型検索ループのほうが適しています。

数値は再現可能です：npm run bench:fixture && npm run bench:large。 結果の詳細は BENCHMARK-LARGE.md と BENCHMARK.md をご覧ください。

インストールと実行

npm install -g @cheppulabs/sonde
cd your-project
sonde init

sonde init はリポジトリにインデックスを作成し、このプロジェクトの .mcp.json に sonde を MCP サーバーとして登録します。書き込みの前に確認を求めます（プロンプトを省略するには sonde init --yes を指定します）。安全にマージできない .mcp.json は変更しません。init が書き込む内容と異なる既存の sonde エントリは上書きせず、そのまま残して報告します。

Python リポジトリでは sonde init --resolve を使用してください。デフォルトの tree-sitter ティアは、構造的クエリに関するプロジェクトの配置ゲートを通過しませんでした。

すべての手順を確認したい場合は、同等の操作を手動で行えます：

sonde index .
# then add to .mcp.json:
# { "mcpServers": { "sonde": { "command": "sonde", "args": ["mcp", "serve", "."] } } }

アカウントやホステッドサービスは不要です。

アーキテクチャのドキュメント

sonde doc は、リポジトリのモジュール、それらの依存関係、および各モジュールが公開する内容を記述した ARCHITECTURE.md を、グラフから生成して書き出します。そのため、誰かの記憶ではなく、コードが実際に何をしているかを示します。

sonde doc            # write ARCHITECTURE.md
sonde doc --stdout   # print it instead
sonde doc --check    # fail if it is out of date (for CI)
sonde doc --module src/store   # symbol-level detail, never committed

これはコミットして再生成することを想定しており、手作業で編集するものではありません。変更がなければ再生成後もバイト単位で同一になるため、差分が無駄に増えることはありません。2つのブランチで同時に再生成した場合は、手作業でマージするのではなく、再度 sonde doc を実行して競合を解決してください。Sonde が生成していない ARCHITECTURE.md の上書きは拒否されます。

意図的に行わないことが3つあります。

• 証拠のない依存関係は描画しません。 シンボル名を共有しているだけのモジュールの組み合わせは除外され、別途カウントされます。このリポジトリでは、2つのアダプターが symbols.ts、parser.ts、references.ts というファイル名を共有しているため、互いにインポートしていないモジュール間に、ヒューリスティックな「参照」が62件も作られていました。図では2番目に太い矢印になるほどの数です。
• 図が完全であるかのようには見せません。 図には最も重い依存関係と、省略した依存関係の数が示されます。下の表にはさらに詳しい情報があり、残りは --module で確認できます。すべての依存関係を含む図は読みにくくなり、かえって何も伝わらなくなるためです。
• 最新でないのに最新であるとは主張しません。 ヘッダーには説明対象のコミットが記載され、ファイルにその後の変更がある場合は警告が表示されます。

保証すること

• 古いソースのバイト列は返しません。 ソースを含むレスポンスを返すときは、必ずインデックス化されたバイト範囲を読み直してハッシュを再計算します（仕様 §8.1、保証 A）。
• 構造上のずれを常に報告します。 検証できない完全性を主張することはありません（仕様 §8.1、保証 B）。sonde status には、ツールのレスポンスエンベロープに含まれるものと同じずれとティア分布が表示されます。
• すべてのエッジには、検出方法を示すティアラベルが付与されます。 COMPILER（--resolve のもとで同梱の型チェッカーが正確に解決。TypeScript には TypeScript コンパイラー、Python には pyright を使用）、LEXICAL（インポートバインディングまたは字句スコープを通じて解決）、HEURISTIC（メンバーアクセスなど、型推論を必要とする関係）、EXTERNAL（インデックス化されたリポジトリの外部にあるターゲット）、または UNRESOLVED（理由を伴う、実際に配置できない参照）。
• エッジを捏造することはありません。 未解決の参照は EXTERNAL または UNRESOLVED になります。推測したターゲットを割り当てたり、参照を黙って破棄したりすることはありません。

精度

Sonde は、固定されたフィクスチャを使い、セットアップ不要の tree-sitter 経路を TypeScript コンパイラーと比較して測定し、好ましくない数値も含めて結果を公開します（仕様 §12）。COMPILER エッジはそのコンパイラーを直接使用するため、同じ基準と比較しても独立した精度テストにはなりません。

Sonde のエッジ精度と TypeScript コンパイラーとの比較

生成日時：2026-08-23T18:16:41.557Z TypeScript：5.9.3（同梱版。リポジトリの TypeScript は読み込まれません）

この数値の対象範囲。 オラクルが測定するのは tree-sitter の解決経路です。これはセットアップ不要のデフォルト経路であり、精度が問題となる唯一のティアです。COMPILER ティアのエッジは TypeScript コンパイラー自体から得られるため、同じコンパイラーを基準に採点しても意味がありません。これらは仕組み上正確であり、この数値から除外されています。これらの値を生成するには、sonde index --resolve を実行してください。

オラクルの対象はリポジトリ内のターゲットに絞られており、node_modules と .d.ts 宣言は除外されます。型のみの参照、JSX 組み込み要素、export =、デコレーター、宣言のマージは、既知の想定内の差異です（仕様 §10）。ティアの各行では、そのティア単独の結果をオラクル全体と比較し、各ティアが独立してどのように寄与するかを示します。ALL は合算結果です。

ここで精度が 1.000 を下回ることが想定される理由

これらの差異は構造上生じるものです。そのため、精度の数値を「Sonde がどれくらいの頻度で誤るか」と捉えると、エラー率を過大評価することになります。

1. 曖昧なメンバー呼び出しでは、候補がすべて出力されます。 x.foo() に対して可視の foo 宣言が 2 つある場合、Sonde は信頼度で重み付けした HEURISTIC エッジを両方出力します。コンパイラーと一致するのは最大でも 1 つであるため、もう一方は構造上、偽陽性として数えられます。代わりに単一の対象を推測する方法もありますが、不変条件 1 により禁止されています。解決済みに見える誤ったエッジを出すより、ヒューリスティックであることを正直に示すエッジを 2 つ出すほうが適切です。そのため、フィクスチャに曖昧な呼び出しが含まれる場合、精度は 1.000 を下回ります。
2. コンストラクター呼び出しは Sonde 独自のものです。 Sonde は new Foo() に対して CALLS を出力しますが、オラクルはこれをモデル化しません。そのため、グラウンドトゥルースに含まれない呼び出しはそれぞれ偽陽性となります。
3. メンバーレベルの IMPLEMENTS は Sonde 独自のものです。 クラスがインターフェースを実装すると宣言している場合、Sonde は RegExpRouter.add から Router.add への IMPLEMENTS エッジを導出します。tsc は型レベルでのみ継承句を報告するため、メンバーレベルのエッジはすべて、これをモデル化しないグラウンドトゥルースに対する偽陽性として数えられます。インターフェースのメソッドに対する影響分析を可能にする機能であるため、精度への影響は取り除かずに開示しています。

件数は絶対値であり、大規模なコーパスに対する割合ではありません。各数値に対する 1 つのエッジの影響が分かるよう、フィクスチャのエッジ総数を以下に示します。

tests/fixtures/repos/small

フィクスチャ設定の SHA-256：e02e2d5003f96d1ad22519f04e10d687fe689cf9298e7fcbc588eab525dce1ad

オラクルのエッジ数：9 · Sonde のエッジ数：7 · オラクルのエッジが 1 つ増えると再現率は 11.1% 変動します

エッジの種類	ティア	精度	再現率	TP	FP	FN
CALLS	ALL	0.500	1.000	2	2	0
CALLS	LEXICAL	0.500	0.500	1	1	1
CALLS	HEURISTIC	0.500	0.500	1	1	1
IMPLEMENTS	ALL	0.500	1.000	1	1	0
IMPLEMENTS	LEXICAL	0.500	1.000	1	1	0
IMPLEMENTS	HEURISTIC	1.000	0.000	0	0	1
INHERITS	ALL	1.000	1.000	1	0	0
INHERITS	LEXICAL	1.000	1.000	1	0	0
INHERITS	HEURISTIC	1.000	0.000	0	0	1
REFERENCES	ALL	0.571	0.800	4	3	1
REFERENCES	LEXICAL	0.800	0.800	4	1	1
REFERENCES	HEURISTIC	0.000	0.000	0	2	5

全体： 精度 0.571、再現率 0.889

npm run bench:oracle で再生成できます。

CLI

sonde init [path] [--resolve] [--yes]      # index and register project MCP config
sonde index [path] [--resolve]             # full index; optional compiler pass
sonde update [path] [--resolve]            # update; optional compiler pass
sonde status [path]                        # freshness and tier distribution
sonde search <query> [path]                # find_symbols
sonde query <pattern> <symbol> [path]      # query_graph
sonde impact [path] --symbol <name>        # get_impact_radius by symbol
sonde impact [path] --from-git-diff        # impact from working-tree diff
sonde doctor [path]                        # parser/database/tsc health
sonde clean [path]                         # remove the cached index
sonde mcp serve [path]                     # MCP server over stdio

impact は、繰り返し指定できる --symbol オプションと --token-budget <n> にも対応しています。init、index、update、status、search、query、 impact、doctor、clean の各コマンドは --json を受け付けます。

既知の制限事項

• Node 22 以降が必要です。 better-sqlite3 が必要とするためです。古い Node にインストールすると EBADENGINE 警告が表示されますが、インストール自体は完了します。その後 sonde の実行に失敗する場合は、これが原因です。警告を無視せず、Node をアップグレードしてください。
• Python では --resolve が必要で、エッジはオラクルによる検証を受けていません。 --resolve を指定しない場合、Python のインデックス作成は tree-sitter の段階にとどまり、実際の 56 ファイルのプロジェクトでは 62.81％、pydantic では 57.39％が未解決という測定結果でした。これは、このプロジェクトが求める上限の 30％を大幅に超えているため、構造クエリには適していません。--resolve を指定すると、同梱された pyright によって COMPILER 段階が実行され、同じコーパスでの未解決率は 27.00％ と 17.42％ になります。このゲートで測定したのは 配置、つまり参照がターゲットを見つけられたかどうかであり、見つかったターゲットが正しかったかどうかではありません。TypeScript のエッジは ORACLE.md で tsc に照らして評価されていますが、Python には同等のオラクルがありません。より悪い方のコーパスでは余裕がわずかです。既知の上方バイアスを補正すると、わずか 0.28 ポイントです。詳しくは probes/python-placement/FINDINGS.md を参照してください。
• 対応言語は TypeScript、Python、Swift のみです。他の言語アダプターはありません。
• Swift の解決はヒューリスティックに基づいており、コンパイラーを利用していません。また、絞り込みルールの 1 つは未検証です。 参照は完全な型推論ではなく、ファイルの可視性と明示的なローカル型注釈によって絞り込まれます。実際の 376 ファイルの Swift アプリケーションでは、配置率 74.84％、未解決率 25.16％でした。測定の詳細は probes/swift-narrowing/FINDINGS.md を参照してください。3 つ目の絞り込みルールである SwiftPM のターゲット境界は、一度もテストされていません。検証用のコーパスは Xcode プロジェクトだったため、そのシグナルを得られる Package.swift の構成がありませんでした。厳選された Swift SDK のシンボルテーブルも、意図的に保守的な内容になっています。曖昧な名前のいくつかは推測せずに除外したため、正当な SDK 参照でも EXTERNAL ではなく UNRESOLVED と表示される場合があります。
• TypeScript のコンパイラー解決（--resolve）は、処理が大幅に遅く、一時メモリーの使用量も増えるため、オプトインです。19,409 行の Hono フィクスチャでは、デフォルトのインデックス作成に 3.58 秒かかりました。--resolve では 13.70 秒かかり、正確な配置／昇格が 10,329 件増え、callers_of Hono.route の結果はグラフ上で 0 件からコンパイラーの呼び出し元 8 件に変わりました。インデックス作成後、Program は破棄されます。インライン更新ではコンパイラーを使わず、影響を受ける証拠を明示的に格下げします。完全な sonde update --resolve を実行するまで、この状態が続きます。
• コンパイラー解決では、リポジトリ独自のコンパイラーではなく、同梱された TypeScript 5.9.3 を使用するため、バージョンのずれが生じる可能性があります。この点は doctor と応答エンベロープで開示されています。
• パースエラーのあるファイルでも、tree-sitter が復元できた内容はすべて反映されます。これは意図した動作です（設計仕様 §8 を参照）。エラーがあっても実際の宣言を復元できた場合、parse_state は partial になります。利用可能な内容が何も得られなかった場合に限り、failed になります。
• TESTS エッジが示すのは構造上の関連性のみです。テストカバレッジを証明するものではありません。
• tree-sitter による抽出経路では、型のみの参照、JSX の組み込み要素、export =／import =、デコレーター、宣言マージが既知の欠落項目です。
• 名前変更の推論には対応していません。 ファイル名を変更すると、パスから導出されるすべての安定キーが変わります。保存済みクエリやエージェントの過去のターンなど、古いキーを保持しているものは、名前変更を追跡せず、黙って解決できなくなります。
• 意味的／振る舞いに基づく検索は利用できません。構築して測定した結果、2 種類の埋め込みモデルと 4 種類のドキュメント構成のいずれも、想定していたタスクのクラスでは、字句／構造検索を上回りませんでした。数値については設計仕様 §2.2 を参照してください。find_symbols には組み込まれていません。

設計全体については docs/superpowers/specs/2026-08-16-sonde-design.md を参照してください。