AIコーディングエージェントはコードをどこまで理解できるか

Claude Code や Codex CLI のような AI コーディングエージェントを日常的に使うチームが増えています。しかし、エージェントに「この関数のエラーハンドリングの設計を説明せよ」と聞いたとき、返ってくる回答はどこまで正確でしょうか。grep でファイルを逐次読むだけでは、パッケージ境界をまたぐ依存関係や設計意図まで辿り着けません。

2026年6月〜7月にかけて、この課題に対処する「コードインデックス系 MCP サーバー」が GitHub Trending で同時に急上昇しています。codebase-memory-mcp（2026年7月時点 Star 26.4k）、codegraph（同 57.6k）、cognee（同 27.0k）— いずれもコードベースを事前にインデックス化し、エージェントのコード理解を底上げすることを狙っています。

しかし、ツールを入れるだけで本当にコード理解は改善するのか。本記事では、Express.js のソースコードから75項目の正解チェックリスト（Ground Truth）を手動で作成し、3ツールの「コード理解力」を定量評価しました。先に結論を言うと、デフォルト設定では正解率9〜28%だったものが、インデックス範囲やクエリ戦略の最適化で最大96%に跳ね上がります。ツール選びより設定とクエリ戦略が結果を左右する — 18セッション分のデータで検証しています。
計測方法の詳細は後述しますが、まず3ツールの結果を示します。

結果サマリー

ベースラインの grep（ファイル逐次読み）は75項目中62項目に到達できず、Recall 9.0% でした。3つの MCP サーバーの結果は以下の通りです。

ツール	Recall（デフォルト）	Recall（最適化後）	最適化の内容
codebase-memory-mcp	17.3%	84.7%	依存パッケージをインデックスに追加
codegraph	28.3%	96.0%	node/callers コマンドを併用
cognee	34.7%	65.7%	LLM を Sonnet 5 に変更 + インデックス範囲拡大

codegraph はコマンドの使い分けだけで 96.0% に到達し、codebase-memory-mcp はインデックス範囲の設定で 84.7% に到達しました。一方 cognee は LLM モデルの変更とインデックス拡大の両方が必要で 65.7% にとどまります。各ツールの設計思想、計測方法、インデックス速度やトークン削減などの詳細指標は以下のセクションで解説します。

コードインデックス系MCPサーバーの3つのアプローチ

設計思想が異なる3つのアプローチが存在します。

高速静的解析型: codebase-memory-mcp（MIT）— C言語のシングルバイナリ。tree-sitter による AST 解析と Hybrid LSP セマンティック型解決を組み合わせ、コードベースをナレッジグラフに変換します。LLM 不要、完全ローカル動作。158 言語のパースに対応し、9 つの言語で完全な Hybrid LSP セマンティック解決を実現します。

ライブ同期型: codegraph（MIT）— TypeScript 実装のナレッジグラフサーバー。OS ネイティブのファイル監視（2秒デバウンス）でコード変更をリアルタイム反映します。20+ 言語対応、17 Web フレームワークのルート認識。コード処理は完全ローカル（匿名テレメトリはデフォルト有効、codegraph telemetry off で無効化可）。

LLM 強化型: cognee（Apache-2.0）— Python ベースの AI メモリプラットフォーム。LLM がコードを「理解」してエンティティとリレーションを抽出し、ベクトル検索 + グラフ推論で検索します。コードだけでなく多様なデータ形式（ドキュメント等）も統合可能。LLM 必須（Ollama 等のローカル LLM にも対応）。

項目	codebase-memory-mcp	codegraph	cognee
解析手法	tree-sitter + Hybrid LSP	tree-sitter + FTS5	LLM エンティティ抽出
LLM 依存	なし	なし※1	必須（ローカル LLM 可）
ライブ同期	あり（バックグラウンド）	あり（OSネイティブ監視・2秒デバウンス）	なし
コード外データ	限定的（IaC/ADR 等）	限定的（コード周辺形式）	可（文書等の汎用データ）

※1 codegraph 自体は LLM API を呼びませんが、explore コマンドの自然言語クエリ解釈は MCP クライアント側の LLM に依存します。ツール単体としてはローカル完結です。

補足: cognee は AI メモリプラットフォームであり、コード専用ツールとは設計レイヤーが異なります。この違いが性能にどう影響するかも含めて、以下のベンチマークで検証します。

実測: 3ツールを同一リポで比較

ベンチマーク設計

Express.js v5.2.1（141 JS ファイル, ~21,000 LOC）を対象に、5つのタスクを grep（ベースライン）、codebase-memory-mcp、codegraph、cognee の4手法で実行し、各ツール呼び出しの出力バイト数・応答時間を記録しました。本記事の数値はすべて Express.js（+ 補足検証として Hono）での計測結果です。プロジェクトの規模・構造・言語によって結果は大きく変わりえます — 実際、2ページ目の Hono 検証では codebase-memory-mcp のトークン削減効果が Express.js の -27% に対し -1.6% とほぼゼロでした。自チームのリポジトリで再現検証することを推奨します。

#	タスク	差が出るポイント
1	app.use() の全呼び出し箇所を列挙せよ	動的登録を拾えるか
2	res.render() の呼び出し先を末端まで追え	ファイル境界を超えた追跡
3	HTTP リクエスト→レスポンスの経路を示せ	10ホップ超の追跡限界
4	エラーが throw されてからレスポンスになるまでの設計を説明せよ	パッケージ境界（node_modules）の壁
5	ミドルウェアの実行順序と next() の挙動を説明せよ	概念理解 vs コード検索

タスク1〜3は構造探索（特定シンボルの追跡）、4〜5は設計理解（パッケージをまたぐ概念の把握）を問います。タスク4・5は筆者が Express.js のソースコードを手動で精読し、75項目の正解チェックリスト（Ground Truth）を作成して精度評価に使用しました（全項目一覧は3ページ目の付録に掲載）。

精度評価は2段階で実施しています。初回は各ツールの主要コマンド（codebase-memory-mcp: search_graph、codegraph: explore、cognee: search）のみで計測。その後、codebase-memory-mcp では index_repository で依存パッケージを追加、codegraph では node/callers コマンドを併用、cognee では LLM を Haiku 4.5 から Sonnet 5 に変更しインデックス対象を router/finalhandler を含む10ファイルに拡大して再計測しました。設定やクエリ戦略の最適化がスコアにどう影響するかを示すためです。

各ツールにはタスクごとに2〜3回のクエリを発行し、全クエリの出力バイト数を合算しました。出力バイト数の合計が小さいほど、エージェントのコンテキスト窓を節約できます。バイト数とトークン数は厳密に比例しませんが、同一言語の相対比較では十分な近似指標です。

計測の限界: 本ベンチマークは「各ツールに同数のクエリを発行した場合の出力量」を比較しています。実際のエージェントセッションでは、grep/read の場合「grep → ファイル読み込み → 別の grep → さらに別のファイル → ...」と多段の探索が発生し、MCP サーバーはこの探索回数そのものを削減することが本来の価値です。したがって、単発クエリの出力バイト数と、エージェントセッション全体の累積トークン消費は異なる指標です。本ベンチマークは前者（ツール出力の情報密度）を測定しており、後者は「セッション全体のトークン消費」セクションで計測しています。

インデックス性能

コードインデックスサーバーは検索の前にコードベースのインデックスが必要です。この初期コストはツールの設計思想を如実に反映します。

ツール	インデックス時間	ピークメモリ	グラフ規模	ストレージ
grep	なし（即座）	—	—	—
codebase-memory-mcp	~1秒	~32 MB	1,619 ノード / 3,102 エッジ	~3.8 MB（インメモリ）
codegraph	1.8秒	~351 MB	1,083 ノード / 3,617 エッジ	3.8 MB（SQLite）
cognee	432秒（7分超）	2,879 MB	~1,300 ノード / ~2,500 エッジ※2	107 MB

※2 cognee のグラフ規模はクエリ時のログ出力（ID-filtered retrieval）に基づく概算値で、クエリごとに投影範囲が異なります。

codebase-memory-mcp と codegraph は tree-sitter による静的解析のため1〜2秒で完了します。一方 cognee は全ファイルを LLM に送信してエンティティを抽出する設計のため、同じ141ファイルに7分以上かかり、メモリ使用量も約3GB、ストレージも 107 MB に達しました（本ベンチマークでは Bedrock Haiku 4.5 を使用。LLM API コストは推定 $0.3〜0.5）。

コード変更後の再インデックスについて: codebase-memory-mcp と codegraph はファイル変更を自動検知して差分更新するため、日常開発で手動の再インデックスは不要です。cognee はファイル単位の MD5 ハッシュ比較で変更を検知し、変更ファイルのみパイプラインを再実行します（ソースコード: get_file_content_hash.py）。ただし、旧バージョンのグラフノードは自動では削除されないため、明示的な forget() API 呼び出しが必要です。また codebase-memory-mcp や codegraph のようなファイル監視による自動検知は備えていないため、変更後は手動での再処理が必要です。

結果: タスク別出力バイト数

タスク	grep	codebase-memory	codegraph	cognee
1: シンボル参照	32,210	39,498	2,532	3,026
2: 依存チェーン	604	9,613	16,493	2,730
3: アーキテクチャ	2,226	9,363	11,630	3,579
4: エラーハンドリング	1,012	10,406	13,589	5,905
5: ミドルウェア設計	434	30,187	14,196	5,761
合計	36,486	99,067	58,440	21,001

上記は「同じクエリ数を発行した場合の出力量」です。では、エージェントに自由に探索させたらどうなるか — 次のセクションで計測しました。

セッション全体のトークン消費（実測）

同じタスク（Express.js のエラーハンドリングフローの解明）を Claude Code（Sonnet 4.6）に解かせ、ツール構成だけを変えて各3回実行しました（計9セッション）。エージェントは自律的にツールを選択し、満足するまで探索を続けます。cognee はクエリあたり約4〜18秒のレイテンシがありエージェントの探索ループに組み込むと実用的でないため、セッション計測の対象外としました。

注意: 各条件 N=3 のため統計的な信頼区間は出せません。baseline の入力トークンは 216K〜345K（60%の振れ幅）であり、以下の数値は傾向を示す参考値です。また、エージェントには MCP ツールの使い方に関するガイダンスを一切与えていません（--strict-mcp-config でツールを追加しただけ）。実運用では CLAUDE.md 等にツール活用のヒントを書くため、結果が改善する可能性があります。

条件	中央値入力トークン	baseline比	平均ターン数
baseline（grep + Read）	319,438	—	14.0
+ codebase-memory-mcp	232,566	-27%	12.3
+ codegraph	212,512	-33%	11.3

MCP サーバーを使うとエージェントの探索ターン数が減り（14回 → 11〜12回）、累積入力トークンは 27〜33% 削減されました。構造化されたクエリ結果が grep → ファイル読み込み → 別の grep...という多段探索を短縮しています。

補足: この27〜33%はセッション全体の累積入力トークン（エージェントの会話履歴・ツール呼び出し結果すべてを含む）の削減率です。公式論文や他の検証記事では「MCP クエリ単体の出力トークン」で90%以上の削減を報告していますが、測定対象が異なります。セッション全体では会話履歴の再送が大部分を占めるため、ツール出力の削減がそのまま全体の削減率にはなりません。

実質的な価値は「速度」にあります。ターン数 19% 削減（14回 → 11回）は API ラウンドトリップの削減を意味し、タスク完了までの待ち時間が短くなります。回答の詳細度も向上しました（MCP 条件の回答は平均14,000文字 vs baseline 11,500文字）。

とはいえ、ツール出力の量と質の違いも明確に表れています。

codebase-memory-mcp はタスク5の 30,187 bytes のうち、search_graph(name_pattern="use") 1回だけで 29,791 bytes を占めました。パターンが広いと大量のノードを返すため、クエリの絞り込みがコンテキスト効率を大きく左右します。codegraph は explore コマンドが関連ファイルのソースコードを丸ごと返すため、タスク2〜5で10〜16KB の出力です。

grep はタスク2〜5で最小出力ですが、タスク1ではテストファイルを含む565件の app.use 呼び出しを全行返し、32KB に膨れました。grep の出力サイズはパターンの広さに直結します。

cognee は全タスク合計で最小（21KB）ですが、LLM が合成した要約のためファイルパスや行番号を含みません。エージェントが実際にコードを修正するには、ファイル特定のための追加クエリが必要になるため、実質的なコンテキスト消費はこの数値より大きくなります。

クエリ速度

ツール	平均レスポンス時間	特徴
grep	~32ms	ファイルシステム直接スキャン
codebase-memory-mcp	~34ms※5	インメモリ SQLite、grep と同等
codegraph	~490ms	SQLite FTS5 + tree-sitter
cognee	~8,652ms	ベクトル検索 + グラフ投影 + LLM 回答生成

codebase-memory-mcp は grep と同等の速度です。これはナレッジグラフがインメモリの SQLite に保持されているためで、初期化済みセッション内では search_graph や trace_path が1ms未満で返ります（※5 上表の ~34ms は MCP プロトコルのオーバーヘッド（JSON-RPC シリアライズ、stdio パイプ）を含む全体の応答時間です。公式論文の「<1ms」はインプロセスのグラフクエリ時間のみを指します）。

cognee のクエリ時間が約8.6秒と突出するのは、ベクトル検索でグラフを投影した後、LLM で回答を合成するためです。つまり インデックス時（7分）とクエリ時（8.6秒/回）の両方で LLM API コストが発生 します。

出力の質: 何が返ってくるか

同じ「エラーハンドリングの仕組みを調べる」タスク（Task 4）に対する各ツールの出力を比較します。

codebase-memory-mcp — 構造化 JSON。関数名、ファイルパス、依存グラフのメトリクス（in_degree、complexity 等）を返します。index_repository で node_modules/router と node_modules/finalhandler を追加インデックスすることで、Express v5 が外部パッケージに分離した router 内部のロジックにも到達できます。

search_graph(name_pattern="logerror") の出力例:

{"name":"logerror", "file_path":"lib/application.js",
 "in_degree":1, "out_degree":2, "signature":"(err)"}

codegraph — ソースコード全文（行番号付き）と blast radius 分析。explore コマンドは関連ファイルのコードを丸ごと返すため情報量が最も豊富です。ただし1回の explore で10〜15KB のソースコードを返すため、コンテキスト消費が大きくなります。

cognee — LLM が合成した自然言語の要約。概念レベルの説明（「error-handling middleware は arity 4 の関数」等）は正確ですが、具体的なファイルパス・行番号・コードスニペットは一切含まれません。エージェントが修正対象のファイルを特定するには、追加のツール呼び出しが必要です。

「エラーハンドリングの仕組みを説明せよ」に対する出力例:

Express error handling operates through error-handling middleware
with a distinctive signature of arity 4: (err, req, res, next).

grep — 行マッチ（ファイル名:行番号:一致行）。パターンが正確なら最小ノイズですが、「error handling の設計思想」のようなセマンティックな問いには答えられません。

観点	codebase-memory	codegraph	cognee	grep
ファイルパス	○	○	×	○
行番号	×	○	×	○
コードスニペット	×	○（全文）	×	○（一致行）
依存グラフ	○（メトリクス）	○（blast radius）	×	×
セマンティック理解	×	△（explore）	○	×
パッケージ横断	○（要追加設定）	○	○	○

Recall: 正解チェックリストに対する精度

タスク4・5の Ground Truth チェックリスト（タスク4: 33項目、タスク5: 42項目、計75項目）に対し、各ツールの出力を5段階で評価しました。

評価基準: ◎ 正確＋コード根拠あり（1.0点）、○ 概念的に正確（0.75点）、△ 部分的カバー（0.5点）、× 不到達（0点）、- 構造的に返却不可能（0点扱い。全ツール共通で75項目を分母に算出）

ツール	◎	○	△	×	-	加重スコア	全75項目比
grep	1	5	4	62	3	6.75	9.0%
codebase-memory-mcp（初回）	4	8	6	57	0	13.00	17.3%
codebase-memory-mcp（設定後）	52	10	8	5	0	63.50	84.7%
codegraph（explore のみ）	5	13	13	44	0	21.25	28.3%
codegraph（node/callers 併用）	68	4	2	1	0	72.00	96.0%
cognee（Haiku 4.5 / lib 6ファイル）	0	22	19	34	0	26.00	34.7%
cognee（Sonnet 5 / 10ファイル）	0	61	7	7	0	49.25	65.7%

最大の差別化要因は設定とクエリ戦略。各ツールのデフォルト設定・単一コマンドで計測した初回スコアと、設定やクエリを最適化した後のスコアでは劇的な差が出ました。

• codebase-memory-mcp: デフォルト（lib/ 6ファイルのみ）では 17.3%。index_repository で node_modules/router/ と node_modules/finalhandler/ を追加 → 84.7%
• codegraph: explore（広く浅く関連ファイルを返す）のみでは 28.3%。node（単一シンボルのソース＋callers/callees）を併用 → 96.0%
• cognee: Haiku 4.5 + lib 6ファイルでは 34.7%。Sonnet 5 に変更し router/finalhandler を含む10ファイルに拡大 → 65.7%

grep は lib/router/ を検索して空振り（×62件の主因）。cognee は LLM による概念理解で最大 65.7% を達成していますが、コード根拠（◎）は0件です。カテゴリ別の内訳は2ページ目「カテゴリ別加重スコア」、全75項目の個別評価は3ページ目の付録に掲載しています。

注意: recall の種類が異なります。cognee の ○61件は「概念的カバレッジ」（「arity 4 のエラーハンドラが存在する」と正しく説明）。codebase-memory-mcp と codegraph の ◎ は「実装カバレッジ」（該当コードを行番号付きで返却）。エージェントがコードを修正するには後者が必要です。

recall の数値だけでツールの優劣は決まりません。同じツールでもクエリ戦略で 28.3% にも 96.0% にもなり、同じ cognee でも LLM の選択とインデックス範囲で 34.7% にも 65.7% にもなります。重要なのはツール選定ではなく、そのツールが提供するコマンド群・設定・LLM 選択をどう最適化するかです。

選定フレームワーク: どのチームにどのツールが合うか

以下の推奨は Express.js（パッケージ分散型）と Hono（単一パッケージ型）の2プロジェクトで、ドキュメント（CLAUDE.md 等）なしの条件で計測した結果に基づいています。プロジェクト構造やドキュメント整備状況によって効果は大きく変わるため、自チームのリポジトリで再現検証することを推奨します。

実測データに基づく比較サマリー

指標	codebase-memory	codegraph	cognee
Recall（加重スコア）※3	84.7%	96.0%	65.7%
トークン削減（Express.js）	-27%	-33%	—
トークン削減（Hono）	-1.6%	-20%	—
ターン数削減（Hono）	ほぼ変化なし	56%減（13→5.7回）	—
インデックス速度	~1秒	1.8秒	34秒
クエリ速度	~34ms	~490ms	~8,652ms
出力形式	構造化 JSON（99 KB）	ソースコード全文（58 KB）	LLM 要約（21 KB）
LLM 依存	なし	なし（explore はクライアント LLM）	必須
ライブ同期	○	○	×
完全ローカル	○	○	×
セットアップ	バイナリ1本	npm install	pip install + LLM 設定※4

codebase-memory-mcp の効果はプロジェクト構造に強く依存します。Express.js のように依存関係が node_modules に分散する構造では grep で追いにくいため大きな効果が出ましたが、Hono のように単一パッケージで完結する構造ではトークン削減がほぼゼロでした。codegraph はどちらの構造でも安定した効果を示しています。

※3 codegraph の 96.0% は node/callers 併用時（explore のみでは 28.3%）。codebase-memory-mcp の 84.7% は index_repository で依存パッケージを追加後（初回は 17.3%）。cognee の 65.7% は Sonnet 5 + 10ファイル（Haiku 4.5 + lib 6ファイルでは 34.7%）。cognee は概念カバレッジ（LLM 要約）のため◎は0件。修正タスクには実コードを返す前2者が有利です。
※4 cognee の pip install によるローカル利用は比較的容易ですが、Docker Compose でのセルフホスト（PostgreSQL + Redis + Ollama 構成）は2026年7月時点でセットアップに相当の手作業が必要との報告があります。本ベンチマークは pip install でのローカル利用で実施しました。

ケース別推奨

チームの状況	推奨	理由（実測データ）
回答精度を最重視	codegraph	Recall 96.0%（最高）。Hono でもターン数 56% 減と、プロジェクト構造を問わず安定した効果
大規模モノレポ + 速度最重視	codebase-memory-mcp	インデックス ~1秒、クエリ ~34ms で最速。ただし効果はプロジェクト構造に依存（Hono ではトークン削減 -1.6%）
コード + ドキュメントの統合記憶	cognee	出力 21 KB（最小）。Recall 65.7%（Sonnet 5 時）。ただしインデックス ~34秒 + クエリ毎に7〜17秒の LLM コスト追加。コード根拠（◎）は返さない
小〜中規模リポ + コスト問題なし	grep + Read	導入コストゼロ。単一パッケージ構成なら精度も十分

選定チェックリスト

• CLAUDE.md や ARCHITECTURE.md を整備済みか？ → Yes なら baseline の探索精度が高いため、どのツールも追加効果が縮小します。まず探索速度や回答品質に具体的な課題があるか確認してください（本ベンチマークはドキュメントなしで計測しています）
• プロジェクトの依存構造は？ → 依存が node_modules や外部パッケージに分散する構造（Express.js 型）なら codebase-memory-mcp / codegraph の効果大。単一パッケージで完結する構造（Hono 型）なら codebase-memory-mcp の効果はほぼゼロ、codegraph は有効
• コードが外部 API に送信されても問題ないか？ → No なら codebase-memory-mcp or codegraph（コード処理はローカル完結）。cognee はインデックス・クエリ時にコードを LLM API に送信します（ローカル LLM なら回避可能だが性能は大幅に低下）
• 大規模モノレポか？ → Yes なら codebase-memory-mcp を優先（21,000 LOC で ~1秒。論文は Linux カーネル2,800万行で3分と報告していますが、筆者は未検証です）
• エディタで編集しながらリアルタイムにクエリしたいか？ → Yes なら codegraph（OS ネイティブ監視、保存2秒後にグラフ更新）
• コード以外（ドキュメント・議事録）も記憶させたいか？ → Yes なら cognee
• チームで共有するか？ → 3ツールともインデックスは個人のローカルマシンに閉じるため、開発者ごとにインデックス構築が必要です。チーム共有が必須なら別のアプローチを検討してください