コードベースが大きくなるほど、AIとのやり取りが重くなっていく感覚は、多くのエンジニアが覚えがあるはずです。cat src/**/*.ts | pbcopy してClaudeに貼り付け、「このコードベース全体を踏まえて」と前置きしてから質問する——その運用が限界を迎えるのは、たいてい突然です。
codebase-memory-mcp は、コードベースを知識グラフとしてインデックス化し、MCPサーバーとしてClaudeに接続するツールです。導入の最短手順と実務クエリのパターンを具体的に示しながら、なぜこのアーキテクチャがコンテキスト貼り付け運用の代替として成立するのかを設計レベルで整理します。ベクトルRAGやCopilot Workspaceとの使い分け判断軸も、後半でまとめます。
コンテキストに貼り付ける運用の、本当のコスト
ファイルを丸ごとコピペする運用が最初に破綻するのは、たいていトークン上限ではなく精度です。Claude Sonnetのコンテキストウィンドウは広いので、中規模リポジトリならそのまま流し込めてしまいます。問題は、コンテキストの後半に詰め込まれたコードほど、モデルが参照しにくくなるという特性にあります。
「ファイルを全部渡したのに、なぜか関係ないファイルの関数を参照してくる」という経験は、この現象の典型です。コンテキストの中盤以降に埋もれた情報は、モデルの注意が薄れやすいという構造的な問題があります。
トークン消費の問題も、スケールすると無視できなくなります。1万行規模のリポジトリを毎回丸ごと渡していると、1回の会話で消費するトークンが跳ね上がります。APIを直接使っているチームなら請求額に、Claude Desktopを使っているなら1日の利用上限に、それぞれ跳ね返ってきます。
速度の問題も見落とされがちです。大きなコンテキストを処理する時間は、体感できるほど長くなります。「ちょっと確認したい」という軽い質問でも数十秒待つことになれば、思考のリズムが壊れます。
ただ、これらの問題よりも根本的な話があります。「コードを読ませる」と「コードの構造を問い合わせる」は、本質的に別の操作です。「UserService がどのリポジトリに依存しているか」を知りたい時、モデルにファイルを読ませる必要はありません。依存関係のグラフさえあれば、その問いには一瞬で答えられます。コンテキストに貼り付ける運用は、この二つを混同したまま力技で解決しようとしている状態です。
codebase-memory-mcp が知識グラフとして何をしているか
知識グラフというと難しく聞こえますが、構造はシンプルです。ノードが関数・クラス・ファイル・HTTPルートなどのコード要素で、エッジがそれらの間の関係（呼び出し・参照・継承・インポート）を表します。UserService.create() が UserRepository.save() を呼んでいれば、その呼び出し関係がエッジとして記録されます。
これがベクトルRAGと何が違うかというと、検索の性質が根本的に異なります。ベクトルRAGは「意味的に似ているテキスト」を探します。「ユーザーを保存する処理」と問えば、それに意味的に近いコードチャンクが返ってきます。一方、知識グラフは構造的な関係を辿ります。「UserService.create() から辿れる全ての関数呼び出しを列挙する」という問いに対して、グラフは正確に答えられますが、ベクトル検索はそもそもその問いに向いていません。
依存関係のトレース・影響範囲の特定・定義ジャンプ相当の操作——これらは「構造的正確さ」が要求される問いで、知識グラフが本領を発揮する場面です。逆に「エラーメッセージに含まれる文字列を含むファイルを探す」はグラフの仕事ではなく、grepの仕事です。
実装面では、GitHubの公開情報によると、LZ4圧縮・インメモリSQLite・Aho-Corasickパターンマッチングを組み合わせることでサブミリ秒のクエリを実現しています。Linuxカーネル（2800万行・7万5千ファイル）を3分でインデックス化できるという公開ベンチマークも示されており、大規模リポジトリでも実用的な速度で動作します。
単一静的バイナリ・依存ゼロという設計も、実務上の意味があります。Node.jsやPythonのランタイムが不要なので、CI環境やオフライン環境でも動きます。コードはすべてローカルで処理され、外部に送信されません。セキュリティポリシーが厳しい環境でも、この点は導入の障壁を下げます。
対応言語数については、公式リポジトリの説明文では158言語と記載されていますが、サードパーティのレジストリサイトでは異なる数値が掲載されているケースもあります。最新の対応状況はGitHubリポジトリで確認するのが確実です。
3つのアプローチを並べると、それぞれの立ち位置が見えやすくなります。
| 観点 | codebase-memory-mcp | ベクトルRAG | Copilot Workspace |
|---|---|---|---|
| 検索の性質 | 構造的・正確 | 意味的・近似 | IDE統合・クラウド処理 |
| 得意なクエリ | 依存関係・呼び出しトレース | 自然言語での類似コード検索 | タスク指向の変更提案 |
| クラウド依存 | なし（ローカル完結） | 埋め込みAPIに依存する場合あり | あり |
| セットアップコスト | バイナリ取得のみ | 埋め込みモデル・DBの構築が必要 | IDE拡張のインストール |
インストールから動作確認まで
インストールはワンライナーで完結します。macOS・Linuxであれば以下のように curl でインストールスクリプトを取得して実行します（具体的なURLはGitHubリポジトリのREADMEに記載されています）。
curl -fsSL <インストールスクリプトURL> | bash
このスクリプトは、プラットフォームを自動検出してバイナリをダウンロードし、パスを通します。Claude Desktopを含む10以上のエージェントを自動検出して、MCP設定ファイルへの登録まで行います。Windowsの場合はPowerShellで対応するスクリプトが提供されています。
WindowsではSmartScreen警告が出ることがあります。これはバイナリが署名されていないためで、開発者自身が Discussion #259 で「現時点での既知の制約」として言及しています。「詳細情報」→「実行」で続行できます。気になる場合は、リリースページに掲載されている checksums.txt でハッシュ値を確認してください。
macOSでもGatekeeperが反応することがあります。その場合の対処手順は GitHubのREADME に記載されているので、そちらを参照してください。
バイナリが入ったら、次はインデックス化です。インストーラーが自動でMCP設定を行う場合、手動でのインデックス化コマンドや設定ファイルの編集が不要なケースもあります。自動設定が期待通りに動いているか確認してから、必要に応じてREADMEの手動設定手順を参照するのが確実です。
MCPツールとして認識されると、Claudeとのチャット画面からツールを呼び出せるようになります。search・trace・architecture などのツール名が利用可能な状態になっていれば、接続は成功しています（UIの表示はClaudeのバージョンによって異なる場合があります）。
複数プロジェクトを扱う場合は、MCPサーバーの設定にエントリを増やすことで対応できます。詳細な設定オプションはGitHubリポジトリのREADMEに整理されています。
実務クエリのパターンと、グラフが苦手な場面
接続できたら、実際にどう使うかです。基本的な操作は search_graph と trace_call_path の2つのツールを中心に回ります。
シンボル検索は最もシンプルなパターンです。Claudeに次のように伝えれば、自動的にツールが呼ばれます。
`UserService` クラスがどのファイルで定義されているか、
そのメソッド一覧とともに教えてください。
内部では search_graph が呼ばれ、ノード名でフィルタリングした結果が返ります。ベクトル検索と違い、名前の完全一致・部分一致で確実に引っかかります。
依存関係のトレースは、知識グラフが最も力を発揮する場面です。「processPayment 関数が最終的にどのデータベース操作を呼ぶか」を追いたい場合、trace_call_path を使います。
`processPayment` から辿れる全ての関数呼び出しチェーンを、
末端の関数まで列挙してください。
グラフのエッジを再帰的に辿ることで、呼び出しチェーン全体が返ってきます。これをコンテキスト貼り付けで実現しようとすると、関連する全ファイルを手動で特定して渡す必要があり、どこかで漏れが出ます。
影響範囲の特定も実務でよく使います。「UserRepository のインターフェースを変更したら、どこに影響するか」という問いに対して、参照エッジを逆向きに辿ることで影響を受けるシンボルを列挙できます。
`UserRepository` を参照しているクラスと関数を全て列挙してください。
ただし、グラフが苦手な場面も正直に書いておきます。文字列リテラル・コメント・設定ファイルの値——こういったテキストコンテンツはグラフにインデックスされません。「エラーメッセージ 'Invalid token' がどこで出力されているか」を探したいなら、grepやripgrepの仕事です。公式ドキュメントも「テキスト検索にはgrep/globを使え」と明記しています。
インデックスの鮮度も注意点です。コードを変更した後は、MCPツールの index_repository を呼び出してグラフを更新する必要があります。自動的には更新されないので、大きなリファクタリングの後は忘れずに再インデックスをかけてください。前述のベンチマーク通り高速に処理されるので、CI/CDのステップに組み込むことも現実的な選択肢です。
Copilot Workspaceとの使い分けは、「何を知りたいか」で判断するのが一番シンプルです。「このコードをどう変更すればいいか」「バグを直すPRを作りたい」といったタスク指向の問いには、IDE統合されたCopilot Workspaceが向いています。一方、「このシステムの構造を理解したい」「依存関係を整理したい」「影響範囲を把握したい」という構造理解を目的とした問いには、codebase-memory-mcp の知識グラフが適しています。クラウドにコードを送りたくない場合も、ローカル完結のこちらを選ぶ理由になります。
導入コストが低い（バイナリを入れるだけ）ので、まず試してみて、自分のワークフローのどこに刺さるかを確認するのが早いです。コードベースの構造を頻繁に問い合わせる機会があるなら、コンテキスト貼り付けの運用から切り替える価値は十分あります。
株式会社ホコサキは、山口県宇部を拠点にAI活用支援・業務システム開発・DX推進に取り組んでいます。MCPサーバーの導入支援や、開発ワークフローへのAI組み込みについてご相談があれば、お問い合わせページからお気軽にどうぞ。