AIにコードベースの「地図」を渡そう——codebase-memory-mcpで爆速コード探索
GitHubで爆伸び中のcodebase-memory-mcp。コードベースをナレッジグラフ化し、AIエージェントのトークン消費を99%削減するMCPサーバーの仕組みと使い方をチカちゃんが徹底解説。
GitHubで爆伸び中のcodebase-memory-mcp。コードベースをナレッジグラフ化し、AIエージェントのトークン消費を99%削減するMCPサーバーの仕組みと使い方をチカちゃんが徹底解説。
📑 目次
ふむふむ。きょうGitHubを眺めてて、チカちゃんの目が釘付けになったツールがあるんです。
DeusData/codebase-memory-mcp——この1週間で2,000スター以上を獲得して、いまGitHubのデイリートレンド1位に躍り出てるやつ。
なにがそんなに凄いのか？ 一言でいうと——
「AIにコードベースの地図を渡す」 ツールなんです。
いまのAIエージェント、コードベースをどう探索してる？
ちょっと想像してみてください。
あなたが初めて入った巨大図書館で、目隠しをされた状態で「この本とあの本の関係を調べて」と言われたら……本棚を手探りで1冊ずつ開いては閉じて、開いては閉じて。永遠に終わらない。
それが、いまのAIコーディングエージェントがやってることです。
Claude CodeでもCodexでもCursorでも、コードベースを理解しようとするとき、AIエージェントは基本的に——
grepでキーワード検索- ヒットしたファイルを
read - 出てきた関数名でまた
grep - またファイルを
read - ……（延々と続く）
これ、トークンの無駄遣いが半端ないんです。
論文（arXiv:2603.27277）によると、典型的なコード探索セッションでは数十回のツール呼び出しが発生し、数十万トークンを消費する。構造的な質問（「この関数を変えたら何が壊れる？」）に答えるだけで、です。
一方で、私たち人間の開発者はといえば——「この関数はあそこから呼ばれてて、依存先はこっちで……」と頭の中で構造ごと把握してますよね。
このギャップが、codebase-memory-mcpの出発点です。
codebase-memory-mcpは何をするのか？
codebase-memory-mcpは、コードベースを静的に解析して、ナレッジグラフ（知識グラフ）に変換します。
具体的には：
- Tree-Sitter というパーサーで、158言語のソースコードをAST（抽象構文木）に分解
- 関数定義、呼び出し関係、インポート、継承、HTTPルートなどをノードとエッジに変換
- SQLiteデータベースに永続化して、超高速な構造検索を可能に
で、これを MCP（Model Context Protocol）サーバー としてAIエージェントに提供する。
エージェントから見ると——「この関数を呼んでるのは誰？」「この変更の影響範囲は？」といった構造的な質問を、ミリ秒単位で答えられる14種類のツールが増えるわけです。
なるほどねえ。つまり「grepとreadで手探り」から「地図を見ながら的確に質問」に変わる。これだけで、トークン消費が最大99%削減されるというから驚きです。
どれくらい速いの？
公式ベンチマークがかなり攻めてます。
| 操作 | 時間 | 対象 |
|---|---|---|
| Linuxカーネル全文インデックス | 3分 | 2,800万行、75,000ファイル |
| Django全文インデックス | 約6秒 | 49,000ノード、196,000エッジ |
| 構造検索（Cypherクエリ） | 1ms未満 | リレーションシップの横断 |
| デッドコード検出 | 約150ms | グラフ全体スキャン |
| 呼び出し経路トレース | 10ms未満 | 深さ5のBFS探索 |
Linuxカーネルを3分でインデックスですよ。え、それビルドより速くない？ってなりませんか。
しかもこれ、全部ローカル完結。外部APIなし、データは外に出ない。シングルバイナリで依存ゼロ。macOSでもLinuxでもWindowsでも動く。
チカちゃん的には、この「全部入りバイナリ1個」という思想がすごく好みです。pip install 地獄とも docker compose up とも無縁。ダウンロードして実行するだけ。
セットアップ——3ステップで動く
ステップ1：インストール
macOS / Linux なら、これだけ。
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bashグラフ可視化UI付きが欲しければ：
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --uiWindows（PowerShell）なら：
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1このインストーラー、賢くて——インストール済みのAIエージェント（Claude Code、Codex CLI、Gemini CLI、Zed、OpenCode、Aider、KiloCode、VS Code、OpenClaw、Kiro、Antigravity——最大11種類！）を自動検出して、全部にMCPサーバー設定を書き込んでくれます。
ステップ2：エージェントを再起動
Claude Codeなら exit してから再度 claude。
ステップ3：インデックス！
エージェントに向かってこう言うだけ。
「このプロジェクトをインデックスして」
あとはエージェントが index_repository ツールを呼んで、数十秒〜数分で完了。プロジェクトの規模によるけど、Djangoレベルなら6秒です。
実践ワークフロー——「地図」の引き方
インデックスが済んだら、どんなことができるのか。基本の流れを紹介します。
① まずスキーマを把握する
「このプロジェクトのグラフ構造を教えて」エージェントが get_graph_schema を呼んで、ノード種別（Function、Class、File、Route…）とエッジ種別（CALLS、IMPORTS、INHERITS…）を返してくれます。まずはこれで「どんな地図か」を把握。
② 目的の関数を探す
「〇〇Handlerって名前の関数を探して」search_graph(label="Function", name_pattern=".*Handler.*") が走って、候補を一覧。grepと違って、「この関数はこのクラスのメソッドで、このファイルで定義されてる」といった構造情報付きで返ってきます。
③ 呼び出し関係をトレース
「関数Xの呼び出し経路を深さ3で追って」trace_call_path(function_name="X", direction="both", depth=3) で、誰がXを呼んで、Xが誰を呼んでいるかを一発取得。ファイルを何個も開く必要なし。
④ 影響範囲を調べる
「いまの変更で何が壊れる可能性がある？」detect_changes() が git diff を見て、変更されたシンボルとその影響範囲をリスク分類付き（CRITICAL / HIGH / MEDIUM / LOW）で返します。プッシュする前に壊れる箇所がわかる——これはデカい。
⑤ デッドコードを見つける
「呼ばれていない関数を探して」find_dead_code() が、呼び出し元ゼロの関数（ただしエントリポイントやルートハンドラーを除く）をリストアップ。リファクタリングのお供に。
⑥ アーキテクチャ全体を俯瞰
「このプロジェクトの全体像を見せて」get_architecture() が、言語構成、パッケージ構造、エントリポイント、ホットスポット（呼び出し頻度の高い関数）、検出されたレイヤー構造までを一気に返します。
上級者向け：Cypherクエリで自由自在に
SQL的にグラフを検索できるCypherクエリも使えます。対応しているのは読み取り専用のサブセットですが、かなり強力。
# CLIから直接クエリ
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function)-[:CALLS]->(g:Function) WHERE f.name CONTAINS \"Handler\" RETURN f.name, g.name LIMIT 10"}'エージェント越しでも query_graph ツールで同じクエリが投げられます。
論文が語る「質と効率のトレードオフ」
codebase-memory-mcpにはちゃんとarXiv論文（2603.27277）がついていて、31の実プロジェクトで評価しています。
気になる数字はこちら：
- 回答品質 83%（従来のファイル探索型エージェントは92%）
- 消費トークン数 1/10（10分の1！）
- ツール呼び出し回数 1/2.1
つまり、「ちょっとだけ精度は落ちるけど、そのぶんコストは10分の1」というトレードオフ。
でもこれ、チカちゃん的には「ちょっと待って」なんです。
92%と83%の差は、構造的な質問だけに絞った数字。一方で、グラフネイティブな質問（「最も呼ばれている関数は？」「このリポジトリのハブはどこ？」）では、codebase-memory-mcpのほうが31言語中19言語で従来手法を上回ったそうです。
つまり使いどころが大事。「呼び出し関係を追う」みたいな構造探索ではグラフが圧倒的。「この変数名は何の略？」みたいな意味理解が必要なときは従来探索も併用——という使い分けが現実的です。
注意しておきたいこと
正直ベースで、いくつか気になる点も。
① 初期インデックスに時間がかかる巨大プロジェクト
Linuxカーネルが3分なら大抵のプロジェクトは秒〜数十秒で済みますが、数万ファイルを超えるモノレポだと数分かかることも。初回だけのコストですが、CIに組み込むときは要注意。
② 動的なコードパターンは追えない
Tree-Sitterベースの静的解析なので、リフレクション、動的インポート、eval 系の呼び出しはグラフに乗りません。Pythonの getattr 呼び出しや、Rubyの send も同様。
③ MCPサーバーなので、対応エージェントが必要
スタンドアロンツールとしてもCLIモードで使えますが、本領を発揮するのはMCP対応のAIエージェントと組み合わせたとき。幸い、主要なコーディングエージェントはほぼカバーされてます（11種対応）。
④ グラフ可視化UIはオプション
--ui 付きでインストールすると localhost:9749 に3Dグラフ可視化UIが立ち上がります。派手で楽しいけど、実用上は無くても困らないです。お好みで。
⑤ 日本語のコードやコメントは？
Tree-Sitterは言語の文法を解析するので、日本語コメントがあっても関数定義や呼び出し関係の抽出には影響しません。とはいえ、関数名に日本語を使っているコードベースでは、検索パターンに注意が必要かも。
どんな人におすすめ？
- AIコーディングエージェントを日常的に使っている人 —— トークン節約の即効薬。Claude CodeやCodexのAPI代が目に見えて下がります
- 大規模コードベースを相手にする人 —— モノレポ、マイクロサービス群、レガシーコードの理解に。アーキテクチャ俯瞰が特に効く
- 「grepじゃ限界」と感じてる人 —— 構造的な探索（呼び出し関係、依存連鎖、影響範囲）がしたいなら、grepより断然こっち
- プライバシー重視の人 —— 全部ローカル完結。ソースコードが外部に送信される心配ゼロ
さいごに——地図を持ったエージェントの未来
codebase-memory-mcpを見てて思ったんですけど、これって「AIがコードを書く」から「AIがコードベースを理解する」へのシフトの象徴ですよね。
いままでは「プロンプトに貼った数ファイル」だけを見てコードを生成するのが普通だった。でも、コードベース全体を地図として持つエージェントなら——リファクタリングの影響を事前に評価したり、使われてないコードを検出したり、複数サービスにまたがるHTTP呼び出しの連鎖を可視化したり。
「コードを書く」だけじゃなくて「コードを飼いならす」フェーズに入った感じがします。
しかも、すべてローカルで、外部API要らず、オープンソース。この「軽さ」と「自立性」が、これからのAIツールの基準になっていくんじゃないかなあ。
思索は冒険です。今日のツールが、その地図になってくれますように。
参考URL
- DeusData/codebase-memory-mcp (GitHub)
- Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277)
- High-Performance Code Intelligence: A Review of codebase-memory-mcp (DEV Community)
- codebase-memory-mcp: Stop Burning Tokens on Code Exploration (dudarik.com)
- インターネット上のツールは第三者が提供するものです。開発工程や配布経路を悪用した攻撃（サプライチェーン攻撃）が仕掛けられる可能性もゼロではありません。ご利用の際は公式リポジトリの情報をご確認いただき、自己責任でお使いください。
- AIに関する技術や情報は急速に変化します。本記事の内容が公開後に古くなる可能性があります。各サービスの公式ドキュメントや最新情報をご確認ください。