Claude Code のトークン消費を抑える - codebase-memory-mcp の紹介
はじめに
Claude Code のコード探索系ツール(Grep / Glob / Read)を、コードベースをグラフ DB として問い合わせる MCP サーバー codebase-memory-mcp に置き換える話です。
公式ベンチでは、5 件の構造クエリで 約 3,400 トークン に収まります。同じ調査を grep + read の往復でやると 約 412,000 トークン かかります。99.2% 削減、トークン換算で 120 倍の差です。
長時間セッションでは、これがコンテキスト枯渇とまともに会話できる時間を分ける一因になります。
きっかけ
Claude Code を業務で使い倒していて、調査タスクの途中でコンテキストが詰まる事象が頻発していました。原因は明らかで、Grep の長大な出力と Read の多重呼び出しでウィンドウが埋まることです。トークン消費を抑える MCP がないか調べていたところ、Reddit の r/ClaudeAI で DeusData/codebase-memory-mcp の存在を知りました。
実際に手元の中規模リポジトリ(約 4 万ファイル)で試したら、index は数秒、Grep の代わりに search_graph を呼ぶだけでトークン消費が体感で 1〜2 桁減ったので、紹介します。
これは何か
DeusData/codebase-memory-mcp は、AI コーディングエージェント向けのコード理解エンジンです。README から要点を抜き出すと次のとおりです。
- 超高速インデックス ── Linux カーネル(28M LOC、75K ファイル)を 3 分 で index、平均的なリポジトリはミリ秒単位。構造クエリは 1ms 未満で返る
- 155 言語対応 ── tree-sitter 製の文法を全部 binary に同梱。追加インストール不要
- Pure C / 単一バイナリ ── ランタイム依存ゼロ。Docker も不要、API キーも不要
-
macOS / Linux / Windows をサポート。release から落として
installするだけ - ローカル完結 ── コードは外に出ない、API 呼び出しなし
- 11 種類のエージェント対応 ── Claude Code / Codex / Gemini CLI / Zed / OpenCode / Antigravity / Aider / KiloCode / VS Code / OpenClaw / Kiro
- 14 個の MCP ツール ── 構造検索、呼び出しトレース、影響範囲、Cypher、dead code 検出、サービス間 HTTP 連結、ADR 管理など
-
3D グラフ可視化 UI(オプション)──
localhost:9749でブラウザから探索できる
設計の根拠と評価は arXiv preprint Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP に書かれています。31 のリアルなリポジトリで評価し、回答品質 83%、トークン 1/10、ツール呼び出し回数 1/2.1(vs ファイル探索)。
何が問題か
Claude Code が標準で持つコード探索系ツールには、それぞれ次のような役割と限界があります。
-
Grep── ripgrep ベースの全文検索。テキストパターンには強いが、構造(呼び出し関係・実装関係)は読めない -
Glob── ファイル名パターン照合。ファイルの存在は分かるが、中身の関係は分からない -
Read── ファイル単位での読み込み。前後関係を把握するために何度も呼ばれ、トークンを大量に消費する -
WebFetch── 外部ドキュメント取得用。コードベースの探索ではない
これらはすべて テキスト処理 であり、コードを「構造」として扱えません。たとえば次のような問いに、テキストベースの三点セットだけで答えるのは難しいか、答えられても非効率です。
-
UserService.Createを呼んでいる関数を全部教えて - このファイルを変更したとき、影響が及ぶ箇所はどこか
- どこからも呼ばれていない関数(dead code)を一覧してほしい
- HTTP 越しに別サービスを叩いているエッジを全部出して
- 同じコミットでよく一緒に変わるファイル群を出して
Grep は呼び出し名にマッチする箇所を返せますが、メソッド名が衝突するとノイズが増えます。インターフェース実装や override の関係はテキストでは表せません。Read で周辺を辿ろうとすると、間接呼び出しを 1 ファイルずつ追うことになり、出力サイズもコンテキスト消費も雪だるま式に膨らみます。
インストール
macOS / Linux ── ワンライナー
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
graph 可視化 UI 込みで入れるとき:
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui
主なオプション:
-
--ui── 3D グラフ可視化 UI を含める -
--skip-config── binary だけ配置し、エージェント設定は触らない -
--dir=<path>── インストール先を指定
Windows ── PowerShell
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
notepad install.ps1 # 中身を確認してから
.\install.ps1
SmartScreen が出たら「詳細情報」→「実行」で進めます。checksums.txt で SHA-256 を検証できます。
手動インストール
releases ページ から自分の OS 向けの archive を落として展開し、同梱の install.sh(macOS/Linux)または install.ps1(Windows)を実行します。
| プラットフォーム | 標準版 | UI 付き |
|---|---|---|
| macOS Apple Silicon | darwin-arm64.tar.gz |
ui-darwin-arm64.tar.gz |
| macOS Intel | darwin-amd64.tar.gz |
ui-darwin-amd64.tar.gz |
| Linux x86_64 | linux-amd64.tar.gz |
ui-linux-amd64.tar.gz |
| Linux ARM64 | linux-arm64.tar.gz |
ui-linux-arm64.tar.gz |
| Windows x86_64 | windows-amd64.zip |
ui-windows-amd64.zip |
macOS の quarantine 属性除去と ad-hoc 署名は install が自動でやってくれます。xattr や codesign を手で叩く必要はありません。
Claude Code から会話で導入
Claude Code 自身に頼む方法もあります。
You: 「この MCP サーバーを入れて: https://github.com/DeusData/codebase-memory-mcp」
ソースから build
C / C++ コンパイラと zlib があれば build できます。
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh # 標準版
scripts/build.sh --with-ui # UI 付き
# binary: build/c/codebase-memory-mcp
手動の MCP 設定
install を使わず自分で MCP 設定を書きたいときは、~/.claude/.mcp.json または プロジェクトの .mcp.json に次を追記します。
{
"mcpServers": {
"codebase-memory-mcp": {
"command": "/path/to/codebase-memory-mcp",
"args": []
}
}
}
エージェントを再起動して /mcp で codebase-memory-mcp が 14 ツールで認識されていれば成功です。
install コマンドは、検出した全エージェントの設定を自動で書き換えます。
| エージェント | MCP 設定先 | 追加されるもの |
|---|---|---|
| Claude Code | .claude/.mcp.json |
4 つの Skill + PreToolUse hook |
| Codex CLI | .codex/config.toml |
.codex/AGENTS.md |
| Gemini CLI | .gemini/settings.json |
.gemini/GEMINI.md + BeforeTool hook |
| Zed |
settings.json (JSONC) |
— |
| OpenCode | opencode.json |
AGENTS.md |
| Antigravity | mcp_config.json |
AGENTS.md |
| Aider | — | CONVENTIONS.md |
| KiloCode | mcp_settings.json |
~/.kilocode/rules/ |
| VS Code | Code/User/mcp.json |
— |
| OpenClaw | openclaw.json |
— |
| Kiro | .kiro/settings/mcp.json |
— |
セットアップ・初期化
プロジェクトを index する
エージェントを再起動して、こう言うだけです。
このプロジェクトを index して
エージェントが裏で index_repository(repo_path="...") を呼びます。完了するとノード数とエッジ数が返ってきます。
CLI から直接叩くなら次のとおりです。
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
自動 index を有効化
プロジェクトに初めて接続したときに自動で index させたいときは次の設定を入れます。
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000
すでに index 済みのプロジェクトは、background watcher に登録されて git 経由の差分検出で継続的に追従します。
graph 可視化 UI を起動
UI 付きで導入していれば、次のコマンドで可視化サーバーが立ち上がります。
codebase-memory-mcp --ui=true --port=9749
ブラウザで http://localhost:9749 を開くと 3D のグラフを操作できます。MCP サーバーと並行で動くので、エージェントが繋がっている間はずっと見られます。
更新
codebase-memory-mcp update
起動時にも更新確認が走り、新しい release があると最初のツール呼び出し時に通知されます。
アンインストール
codebase-memory-mcp uninstall
エージェント側の設定・skill・hook・instruction はすべて削除されます。binary 本体と SQLite DB(~/.cache/codebase-memory-mcp/)は残るので、不要なら手で消します。
使い方
探索ワークフロー
-
list_projects── index 済みか確認 - 未 index なら
index_repositoryを実行 -
get_graph_schema── ノード・エッジ種別を把握(最初に必ず呼ぶ) -
search_graph(label="Function", name_pattern=".*Handler.*")── 候補を絞る -
get_code_snippet(qualified_name="project.path.FuncName")── 本体を読む
トレースワークフロー
-
search_graph(name_pattern=".*FuncName.*")で qualified name を確定 -
trace_call_path(function_name="FuncName", direction="both", depth=3)で呼び出し関係を辿る -
detect_changes()で git diff を影響シンボルにマップする
Cypher で書く高度なクエリ
複雑な問いは query_graph に Cypher を渡します。
// HTTP 越しの呼び出しを 20 件まで取得
MATCH (a)-[r:HTTP_CALLS]->(b)
RETURN a.name, b.name, r.url_path, r.confidence
LIMIT 20
// Handler という名前のついた関数をすべて取得
MATCH (f:Function)
WHERE f.name =~ '.*Handler.*'
RETURN f.name, f.file_path
// main から直接呼ばれている関数
MATCH (a)-[r:CALLS]->(b)
WHERE a.name = 'main'
RETURN b.name
サポートする Cypher のサブセット: MATCH(label・関係種別・可変長パス)、WHERE(比較・regex・CONTAINS)、RETURN(プロパティ・COUNT・DISTINCT)、ORDER BY、LIMIT。WITH COLLECT OPTIONAL MATCH および書き込み系は未対応です。
CLI モード
すべての MCP ツールはコマンドラインからも叩けます。
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_call_path '{"function_name": "Search", "direction": "both"}'
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'
codebase-memory-mcp cli list_projects
codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'
14 個の MCP ツール
インデックス系
| ツール | 役割 |
|---|---|
index_repository |
リポジトリを graph に取り込む |
list_projects |
index 済みプロジェクト一覧(ノード/エッジ数つき) |
delete_project |
プロジェクトと graph データを削除 |
index_status |
index の進捗・状態を確認 |
クエリ系
| ツール | 役割 |
|---|---|
search_graph |
label・name pattern・file pattern・degree フィルタで構造検索 |
trace_call_path |
BFS で呼び出し関係を辿る(depth 1〜5) |
detect_changes |
git diff を影響シンボルにマップしリスク分類 |
query_graph |
Cypher 風の読み取り専用クエリ |
get_graph_schema |
ノード・エッジの統計とプロパティ定義 |
get_code_snippet |
qualified name でソースを取得 |
get_architecture |
言語・パッケージ・routes・hotspots・clusters・ADR を一括取得 |
search_code |
索引済みファイルだけを対象にした grep |
manage_adr |
Architecture Decision Records の CRUD |
ingest_traces |
実行時 trace を取り込み HTTP_CALLS を補強 |
グラフのデータモデル
ノード種別
Project Package Folder File Module Class Function Method Interface Enum Type Route Resource
エッジ種別
CONTAINS_PACKAGE CONTAINS_FOLDER CONTAINS_FILE DEFINES DEFINES_METHOD IMPORTS CALLS HTTP_CALLS ASYNC_CALLS IMPLEMENTS HANDLES USAGE CONFIGURES WRITES MEMBER_OF TESTS USES_TYPE FILE_CHANGES_WITH
HTTP_CALLS や FILE_CHANGES_WITH のように、テキスト検索では復元が難しいエッジを持つ点が特徴です。
標準ツールとの対応
| 標準ツール | 置き換え先 | 違い |
|---|---|---|
Grep |
search_graph / query_graph
|
構造的にフィルタできる(label・degree・関係) |
Glob |
search_graph(label="File") / get_architecture
|
パッケージ構造とあわせて取得できる |
Read |
get_code_snippet(qualified_name) |
qualified name 単位で必要部分だけ返る |
| 構造的な問いには対応できない |
trace_call_path / query_graph
|
呼び出し関係・実装関係をそのまま辿れる |
Before / After 比較
公式ベンチ(5 件の構造クエリでコード調査)の結果は次のとおりです。
| 指標 | Before(grep + read) | After(codebase-memory-mcp) |
|---|---|---|
| トークン消費 | 約 412,000 | 約 3,400 |
| 削減率 | 基準 | 99.2% 削減 |
| ツール呼び出し回数 | 基準 | 2.1 倍少ない |
| 回答品質(31 リポジトリ評価) | — | 83% |
性能ベンチ(Apple M3 Pro):
| 操作 | 時間 | 補足 |
|---|---|---|
| Linux カーネル full index | 3 分 | 28M LOC → 2.1M ノード、4.9M エッジ |
| Linux カーネル fast index | 1m 12s | 1.88M ノード |
| Django full index | 約 6s | 49K ノード、196K エッジ |
| Cypher クエリ | 1ms 未満 | 関係トラバース |
| 名前検索(regex) | 10ms 未満 | SQL LIKE 前段フィルタ |
| dead code 検出 | 約 150ms | degree フィルタ込みの全走査 |
| 呼び出しパス追跡(depth=5) | 10ms 未満 | BFS |
index は in-memory SQLite と LZ4 圧縮の RAM-first パイプラインで走り、終わると OS にメモリを返却します。
hook でテキスト探索系ツールを抑制する
install で Claude Code を選ぶと、~/.claude/hooks/ に 2 つの hook が入ります。
-
cbm-session-reminder── SessionStart 時に「コード探索はまず codebase-memory-mcp を使え」というプロトコルを Claude に流す -
cbm-code-discovery-gate── PreToolUse hook でGrep/Glob/Readの最初の呼び出しに対し、グラフツール優先のリマインドを出す
リマインドは exit code 0 の advisory なので、ツール呼び出し自体はブロックされません。設定値・YAML/JSON・コメントなどテキスト検索が必要なケースを潰さない、現実的な落としどころです。Gemini CLI 用にも同等の BeforeTool hook が入ります。
チーム共有 ── .codebase-memory/graph.db.zst
graph を zstd 圧縮した 1 ファイルとしてリポジトリに commit すると、チームメンバーは初回の full index をスキップできます。
- フォーマット ── SQLite を
VACUUM INTOで詰めて zstd 圧縮(圧縮率 8〜13:1) - 2 階層保存 ──
index_repositoryの明示実行で best(zstd -9+ index 削除)、watcher の自動更新で fast(zstd -3) - bootstrap ── ローカル DB がなく artifact だけある状態で起動すると、artifact を import してから差分 index を走らせる
- merge コンフリクト回避 ── 初回 export 時に
.gitattributesにmerge=oursを自動追加 - オプション ── 嫌なら
.codebase-memory/を.gitignoreに入れて使わない選択もできる
設定
codebase-memory-mcp config list # 全設定を表示
codebase-memory-mcp config set auto_index true # 自動 index
codebase-memory-mcp config set auto_index_limit 50000 # 自動 index の上限ファイル数
codebase-memory-mcp config reset auto_index # 既定値に戻す
環境変数
| 変数 | 既定値 | 用途 |
|---|---|---|
CBM_CACHE_DIR |
~/.cache/codebase-memory-mcp |
DB 保存先を上書き |
CBM_DIAGNOSTICS |
false |
1 / true で /tmp/cbm-diagnostics-<pid>.json に periodic 診断を出力 |
CBM_DOWNLOAD_URL |
GitHub releases | 更新ダウンロード元の上書き(自前ホスト用) |
export CBM_CACHE_DIR=~/my-projects/cbm-data
拡張子マッピング
.blade.php のようなフレームワーク固有拡張子を既存言語に紐づけられます。
プロジェクト単位(リポジトリ root):
// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}
グローバル:
// ~/.config/codebase-memory-mcp/config.json
{"extra_extensions": {".twig": "html", ".phtml": "php"}}
衝突したらプロジェクト設定が優先されます。
無視ルール
階層的に適用されます。
- ハードコーディング済みのパターン(
.git、node_modulesほか) -
.gitignore階層 -
.cbmignore(プロジェクト固有、gitignore 構文)
シンボリックリンクは常にスキップされます。
落とし穴
| 症状 | 対処 |
|---|---|
/mcp でサーバーが見えない |
.mcp.json のパスが絶対パスか確認、エージェント再起動。echo '{}' | /path/to/binary で JSON が返るかテスト |
index_repository が失敗する |
repo_path を絶対パスで渡す |
trace_call_path の結果が 0 件 |
先に search_graph(name_pattern=".*PartialName.*") で正確な名前を取得 |
| プロジェクトが混ざった結果が返る |
project="name" を引数に追加。list_projects で名前確認 |
| install 後 binary が見つからない | export PATH="$HOME/.local/bin:$PATH" |
| UI が開かない | UI 付き variant を入れたか、--ui=true 起動か、ポート 9749 が空いているか |
ドキュメント由来の細かい注意:
-
search_graph(relationship="HTTP_CALLS")はノードを degree でフィルタするだけです。実際のエッジを見たいときはquery_graphで Cypher を書きます -
query_graphには 200 行の上限があります。件数を数える用途ではsearch_graphの degree フィルタを使います -
direction="outbound"ではサービスを越える呼び出し元を取りこぼします。両方向が必要ならdirection="both"を使います - 結果はデフォルトで 10 件ずつ返ります。
has_moreを確認してoffsetでページングします
言語サポート
155 言語、すべて binary 同梱の tree-sitter 文法で parse します。64 のリアルなオープンソースリポジトリでベンチした結果は次のとおりです。
| ティア | 含まれる言語 |
|---|---|
| Excellent (>=90%) | Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile |
| Good (75-89%) | Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#, SQL |
| Functional (<75%) | OCaml, Haskell |
このほか、Solidity・GraphQL・Terraform/HCL・Protobuf・Gleam・Vue・Svelte などフレームワーク・DSL を含む 100 以上の言語も parse できます。
永続化と所在
SQLite DB は ~/.cache/codebase-memory-mcp/ に保存されます。WAL モードで ACID-safe、再起動を跨いで残ります。リセットしたいときは次のとおりです。
rm -rf ~/.cache/codebase-memory-mcp/
セキュリティ
release は多層パイプラインで検証されてから公開されます。
- VirusTotal ── 70 以上のアンチウイルスエンジンでスキャン(検出ゼロが必須)
- SLSA Level 3 ── GitHub Actions が暗号学的 build provenance を発行。
gh attestation verifyで検証可能 - Sigstore cosign ── キーレス署名つき
- SHA-256 checksum ──
checksums.txtを release に同梱、install スクリプトが自動検証 - CodeQL SAST ── 未解決の alert があると release pipeline が止まる
- ランタイム依存ゼロ ── ライブラリは全部 vendored
コードは外に出ない、API キーも要らない、binary は単体で完結する、という前提が崩れない設計です。
向き不向き
向いている場面は次のとおりです。
- 中〜大規模なコードベースで影響範囲調査をしたいとき
- リファクタリング前に dead code や fan-out を洗い出したいとき
- マイクロサービス間の HTTP 呼び出しグラフを把握したいとき
- 長時間セッションでコンテキストを温存したいとき
- チームで graph を共有して新メンバーの初回 index コストを削りたいとき
向いていない場面もあります。
- 小規模リポジトリでは index コストが見合わない場合があります
- コメント・文字列リテラル・設定値・YAML/JSON など、純粋なテキスト探索には
Grepかsearch_codeのほうが向きます - ファイル名規約だけを当てたいときは
Globのほうが速いです - ファイル全体を頭から読みたいとき(README・設定ファイル)は
Readのままで良いです - 言語サポートに穴がある場合、グラフが疎になります(事前に
get_graph_schemaで確認すると安全です)
おわりに
codebase-memory-mcp は、Claude Code を「ファイルを順に読むエージェント」から「コードベースを構造として問い合わせるエージェント」に引き上げる MCP です。Grep / Glob / Read が暗黙に消費していたトークンと時間を、構造クエリに置き換えると、長いタスクの完走率が体感で大きく変わります。
導入後は最初の数回、テキスト探索系ツールを使おうとしてリマインドが出ますが、これは設計どおりの行動なので慌てずグラフツールへ切り替えれば問題ありません。
参考
「Make it simple」をテーマに、コンサルティング・システム開発を行うomeroid株式会社のテックブログです。 会社HP→ omeroid.com/ 採用情報→ wantedly.com/companies/company_5409883
Discussion