メインコンテンツへスキップ

Claude Code のトークンを99%減らす codebase-memory-mcp とは — grep をやめてコードを「知識グラフ」で引く

    同じ5つの質問をコードベースに投げたとき、grep ベースの探索では約412,000トークンを消費しました。

    ところが、同じ質問を「知識グラフ」に問い合わせると、約3,400トークンで済んでいます。

    その差、99.2%削減です(GitHub: DeusData/codebase-memory-mcp の計測値)。

    これは codebase-memory-mcp という MCP サーバーを Claude Code に組み込んだ結果として報告されている数字です。

    Max プランでも「大きなリポジトリだと数時間でコンテキストが尽きる」と感じている人は多いと思います。

    原因の多くは、Claude が同じファイルを何度も読み込みながらコードを探していることにあります。

    この記事では、なぜグラフにするとここまで減るのかという仕組みと、インストールから最初のクエリ、そして「入れても効かない」を防ぐ運用までを整理します。

    codebase-memory-mcp とは — Claude に「コードの地図」を持たせる

    codebase-memory-mcp は、コードベースを丸ごと「知識グラフ」にインデックスして、AIエージェントに構造的なクエリを提供する MCP サーバーです。

    ふだん Claude Code がやっている「ファイルを開いて読む」を、「グラフに問い合わせて答えだけ受け取る」に置き換えます。

    特徴は、単一の静的バイナリで動き、追加の依存もAPIキーも要らず、処理がすべてローカルで完結する点です。

    158言語を tree-sitter で解析でき、インストールは1行のコマンドで終わります。

    Claude Code を含む11種類のエージェントに対応していて、Codex CLI や Cursor でもそのまま使えます。

    要するに、Claude に「コードベースの地図」を1枚渡しておくイメージです。

    地図があれば、毎回ファイルをめくって現在地を確認する必要がなくなります。

    なぜ grep と Read ではトークンが溶けるのか

    Claude Code の標準ツール(Grep / Glob / Read)は、すべて「テキスト処理」です。

    文字列としてのマッチや、ファイルの中身の読み込みはできますが、コードの「構造」は理解していません。

    たとえば「この関数はどこから呼ばれているのか」を知りたいとします。

    grep でできるのは、関数名にヒットしたファイルを片っ端から開いて読むことだけです。

    呼び出し元が10ファイルに散っていれば、10ファイルを読みます。

    さらにその呼び出し元をたどると、また別のファイルを読みます。

    この「読んでは辿る」の連鎖で、関連ファイルが増えるほどトークンは線形に膨らんでいきます。

    長時間のセッションで「さっき読んだはずのファイルをまた読んでいる」と感じるのは、Claude が構造を覚えておらず、毎回テキストとして探し直しているからです。

    呼び出し関係・import 関係・サービス間の HTTP 呼び出しといった「関係」は、本来テキスト検索で表現するものではありません。

    ここが、トークンが溶ける本当の理由です。

    知識グラフが「全文読み」を「1クエリ」に変える

    知識グラフは、コードを「ノード」と「エッジ」で表現したデータベースです。

    ノードは Function・Class・File・Route といったコードの構成要素を指します。

    エッジは CALLS(呼び出し)・IMPORTS・HTTP_CALLS・IMPLEMENTS といった「関係」を指します。

    codebase-memory-mcp は、tree-sitter でコードを構文解析し、この関係をすべて抽出して SQLite に保存します。

    一度インデックスしてしまえば、あとは Cypher というグラフ用のクエリで問い合わせるだけです。

    「この関数を呼んでいる関数を全部出して」を、ファイルを1つも開かずに1クエリで返します。

    クエリの実行は1ミリ秒未満で、返ってくるのは「答え」だけなので、コンテキストにファイル全文が積み上がりません(Zenn: Claude Codeのトークン消費を抑える)。

    ポイントは「最初の1回のインデックスが投資で、以後の質問はすべて回収」という構造です。

    grep が毎回ゼロから探し直すのに対し、グラフは一度作った地図を使い回します。

    この発想の違いが、そのままトークン差として現れます。

    どれだけ減るのか — 99.2%削減の中身

    数字は2つの独立した計測で報告されています。

    1つ目は、同じ5つの構造的な質問での比較です。

    grep による全文探索が約412,000トークンだったのに対し、グラフへの5クエリは約3,400トークンでした。

    これが99.2%削減の中身です。

    2つ目は、31リポジトリを対象にした評価です。

    回答品質を83%に保ったまま、トークン消費は約10分の1、ツール呼び出し回数は約2.1分の1になったと報告されています。

    ここで大事なのは、品質を犠牲にして圧縮しているわけではないという点です。

    「答えの精度はほぼ維持したまま、無駄な読み込みだけが消える」から効きます。

    速度も実用十分です。

    Linux カーネル(2800万行)の完全インデックスが3分、Django(約4.9万行)なら6秒で終わります。

    インデックスは一瞬の投資で、その後のセッションがずっと軽くなる、という体感に近いはずです。

    画像
    同じ5問でのトークン比較(grep探索 → グラフ探索)

    5分で試す — インストールから最初のクエリまで

    導入はワンライナーです(macOS / Linux)。

    curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

    このスクリプトが Claude Code の MCP 設定を自動で書き込み、すぐ使える状態にしてくれます。

    次に、対象リポジトリをインデックスします。

    Claude Code に対して、自然な言葉で「このプロジェクトを index して」と頼むだけで動きます。

    インデックスが終わったら、最初のクエリを投げてみます。

    おすすめは、いきなり全体像をつかむこの3つです。

    • このリポジトリのアーキテクチャ(言語・パッケージ・ルート・ホットスポット)を出して

    • この関数を呼び出している箇所を全部たどって

    • いまの差分が影響するファイルを列挙して

    ツールは14個ありますが、最初から全部覚える必要はありません。

    やりたいことベースで、次のように使い分けると迷いません。

    • 未知のコードの全体像をつかむ → get_architecture

    • 関数の呼び出し元・呼び出し先をたどる → trace_path

    • 変更の影響範囲を知る → detect_changes(git の差分から影響を割り出す)

    • 名前で関数やクラスを探す → search_graph

    • 自由なグラフ問い合わせ → query_graph(Cypher)

    「全体把握は get_architecture、関係を追うなら trace_path」とだけ覚えておけば、最初の1日は十分回せます。

    「入れたのに効かない」を防ぐ運用と、向き不向き

    導入してすぐ気づくのが、「Claude が相変わらず grep を使う」という現象です。

    Claude は標準で Grep や Read を使う習慣が強く、MCP を入れただけでは自動的にグラフへ切り替わらないことがあります(russ.cloud の紹介記事 でも指摘されています)。

    ここで効くのが Claude Code の hook です。

    テキスト探索系のツールを hook で抑制し、「まずグラフに聞く」へ誘導すると、削減効果が安定して出るようになります。

    チームで使うなら、インデックス結果は graph.db.zst という圧縮ファイルとして共有できます。

    これを配れば、メンバー全員がインデックスのコストをかけずに同じ地図を使い始められます。

    一方で、万能ではありません。

    向いているのは、中〜大規模リポジトリ、長時間のセッション、マイクロサービス間の呼び出し追跡です。

    逆に、小規模リポジトリ(grep で十分)、YAML や JSON のテキスト検索、ファイル名の単純な照合には向きません。

    言語による精度差もあります。

    158言語は tree-sitter で構文解析できますが、型まで解決する Hybrid LSP の対象は Python・TypeScript・JavaScript・Go・Rust・Java・Kotlin・C#・PHP・C・C++ などの13言語です。

    自分のメイン言語が型解決の対象かどうかで、得られる精度が変わる点だけ先に押さえておくとよいです。

    まとめ

    codebase-memory-mcp は、Claude のコード探索を「ファイルを読む」から「地図に聞く」へ変えるツールです。

    grep の全文探索が約412,000トークンだった調査が、グラフへの数クエリで約3,400トークンになる。

    この差を生むのは、関係を一度グラフに固めて使い回すという発想の転換です。

    まずは手元の中規模リポジトリで index して、get_architecture を1回投げてみてください。

    「同じファイルを何度も読まれている」感覚が消えるのが、いちばんの効果実感だと思います。

    さらに踏み込んだ計測や14ツールの詳細は、Zenn の解説記事 が具体的でおすすめです。

    あなたへのおすすめ