Codebase Memory

codebase-memory-mcp

AI コーディングエージェント向けの、最速かつ最も効率的なコードインテリジェンスエンジンです。 平均的なリポジトリをミリ秒単位で完全インデックス化し、Linux カーネル（28M LOC、75K ファイル）を 3 分で処理します。構造クエリには 1ms 未満で応答します。macOS、Linux、Windows 向けに、検証済みの小さなランタイムアセットセットを伴うネイティブ実行ファイルとして提供されます — ダウンロードして install を実行するだけです。

162 言語すべてにわたる tree-sitter AST 解析による高品質なパースを提供し、Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust、Perl 向けのHybrid LSP セマンティック型解決で強化されています — 関数、クラス、呼び出しチェーン、HTTP ルート、サービス間リンクの永続的なナレッジグラフを生成します。17 個の MCP ツール。言語ランタイム、ホスト型サービス、API キーは不要です。45 個のサポート対象の自動／条件付きクライアントサーフェス全体でプラグアンドプレイに対応します。

研究 — このプロジェクトの背後にある設計とベンチマークは、プレプリントCodebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP（arXiv:2603.27277）で説明されています。31 個の実世界のリポジトリで評価した結果、ファイルごとの探索と比較して回答品質 83%、トークン使用量 10 分の 1、ツール呼び出し回数 2.1 分の 1 を実現しました。

セキュリティと信頼 — このツールはあなたのコードベースを読み取り、エージェントの設定ファイルに書き込みます。それはこのツールが設計上そうするものです。実行前に監査したい場合は、完全なソースはこちらにあります。各リリース製品について、動作が同一の 3 つの実行ファイル候補（非ストリップ、デバッグストリップ、ストリップ）がテスト前に VirusTotal へ送信され、選ばれた候補が SHA-256 を変更せずにそのままパッケージ化されます。リリースノートには、計測されたすべての候補の結果へのリンクが掲載されています。公開にあたって許容されるのは、SECURITY.md に厳密に記載された単一の Microsoft !ml の許容範囲のみです。すべての処理は 100% ローカルで行われ、あなたのコードがマシンから出ることはありません。セキュリティ上の問題を見つけましたか？ 私たちは知りたいと考えています — SECURITY.md をご覧ください。セキュリティは私たちにとって最優先事項 #1 です。

組み込みの 3D グラフ可視化 — localhost:9749 でナレッジグラフを探索できます

codebase-memory-mcp を選ぶ理由

• 圧倒的なインデックス速度 — Linux カーネル（2,800 万行、75,000 ファイル）を 3 分で処理。RAM ファーストのパイプライン: LZ4 圧縮、インメモリ SQLite、融合された Aho-Corasick パターンマッチング。メモリはインデックス後に解放されます。
• プラグアンドプレイ — ネイティブ実行ファイルに加え、リリースが所有する認証済みアセットを macOS（arm64/amd64）、Linux（arm64/amd64）、Windows（amd64）向けに提供。ネイティブインストールには Docker、言語ランタイム、API キーは不要です。ダウンロード → install → エージェントを再起動 → 完了。
• 162 言語 — ベンダリングされた tree-sitter グラマーをバイナリにコンパイル済み。インストールするものも、壊れるものもありません。
• トークン数を 120 分の 1 に削減 — 5 つの構造クエリ: 約 3,400 トークンに対し、ファイル単位の検索では約 412,000 トークン。1 回のグラフクエリが数十回の grep/read サイクルを置き換えます。
• 45 のサポート対象となる自動/条件付きクライアントサーフェス — install は検出されたクライアントを構成し、条件付きクライアントについては、ドキュメント化されたプラットフォーム、マーカー、または明示的に既存の構成パスが存在する場合にのみ安全に有効化します。完全なマトリクスと手動/UI 限定の境界については マルチエージェントサポート を参照してください。
• CBM Atlas — localhost:9749 で提供される組み込みのヒューマンインターフェース: インデックス上で動作する読解用 IDE（エクスプローラーと読み取り専用の Monaco リーダー、キャレットを追従するセマンティックツイン、フロー・バグハント・変更スコープの読解モード、3D ギャラクシー、出典引用付きの回答、プロジェクト管理）を、バイナリ自体から配信します。
• Infrastructure-as-code のインデックス化 — Dockerfile、Kubernetes マニフェスト、Kustomize オーバーレイを相互参照付きのグラフノードとしてインデックス化。K8s の kind には Resource ノード、Kustomize オーバーレイには Module ノードを作成し、参照先リソースへの IMPORTS エッジを持たせます。
• 17 の MCP ツール — 検索、トレース、アーキテクチャ、影響分析、対象を絞ったインデックスカバレッジチェック、Cypher クエリ、デッドコード検出、サービス間の HTTP リンク、ADR 管理など。

クイックスタート

ワンラインインストール（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

Windows（PowerShell）:

# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (Optional but recommended) Inspect the script
notepad install.ps1

# 3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)
Unblock-File .\install.ps1

# 4. Run it
.\install.ps1

Note: スクリプト実行ポリシーのエラーが表示された場合は、先に Set-ExecutionPolicy -Scope Process Bypass を実行するか、PowerShell -ExecutionPolicy Bypass -File .\install.ps1 で起動してください。

オプション: --skip-config（バイナリのみ、エージェント設定なし）、--dir=<path>（カスタム場所）。

アンチウイルスに関する注意: Microsoft Defender がリリースバイナリを Trojan:Script/Wacatac.B!ml として検出する場合があります。これは既知の誤検出です — 通常は 約 62 エンジン中 61 がクリーンと判定し、同じ検出ファミリーは gh、llama.cpp、 Godot、そして Microsoft 自身の Go ツールチェーンも検出します。証拠、成果物を自分で検証する方法、 および誤りだと思われる場合の報告方法については アンチウイルスの誤検出 を参照してください。

コーディングエージェントを再起動してください。「Index this project」 と入力すれば完了です。

install コマンドはインストール済みのコーディングエージェントを自動検出し、ドキュメント化された MCP エントリに加えて、サポートされている場合は永続的な指示、スキル、ライフサイクルフックを構成します。

セッションコーディネーションデーモン

CBM は、Claude Code、Codex、OpenCode、および設定されたその他すべてのクライアント間で、アカウントごとに 1 つのコーディネーションデーモンを自動的に共有します。MCP サーバーやフッククライアント向けのオプトイン設定はありません。最初のデーモン利用 CBM セッションがそれを起動し、各セッションが自身の作業を登録し、最後のセッションがそれをシャットダウンします。デーモンは、ウォッチャー、共有インデックスジョブ、オプションの UI といった長時間稼働するバックグラウンドサービスを所有します。1 つのセッションを閉じると、そのセッションだけが所有する作業はキャンセルされますが、別のセッションでまだ必要な作業は継続されます。

デタッチされたデーモンは、MCP フロントエンドの stderr に依存しません。所有者専用の永続レコードを、正規の ${CBM_CACHE_DIR}/logs ディレクトリ（デフォルトは ~/.cache/codebase-memory-mcp/logs）配下に保持します:

シンなフロントエンドは依然として、起動直後およびセッション固有のエラーを自身の stderr に書き込みます。MCP JSON-RPC の stdout はクリーンなままです。

アクティブな CBM プロセスはすべて、まったく同じバージョン、実行ファイルビルド、コーディネーション ABI、および正規のキャッシュルートで実行される必要があります。同等の CBM_CACHE_DIR エイリアスは同じルートに解決されます。本当に異なるルートは、CBM プロセスが 1 つでもアクティブな間は拒否されます。MCP サーバー、フック、ワンショットの CLI コマンド、一時的なインデックスワーカー、およびデーモンは、クラッシュセーフな OS の受け入れバリアを共有します。通常の競合するプロセスを起動すると、作業を始める前に失敗し、${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson に明示的な競合を記録します。

ネイティブの install、update、uninstall コマンドは、この競合ルールに対する意図的な例外です。ダウンロード、検証、および同一ファイルシステム上のプライベートなステージングが最初に行われるため、不良な候補がアクティブな作業を妨害することはありません。その後、アクティベーションがアカウント全体のメンテナンスインテントを発行し、デーモンおよびすべての一時的なローカル操作にキャンセルを要求し、調整されたすべての CBM プロセスが終了するまで有限の期限まで待機します。アクティブなバイナリ、設定、PATH、またはインデックスを変更している間は、受け入れバリアとライフタイムバリアを排他的に保持します。このウィンドウ中は、新規の CBM 作業は入ることができません。アクティベーションの進行状況と結果は ${CBM_CACHE_DIR}/logs/activation-events.ndjson に記録され、コマンドが成功すると、開いているコーディングエージェントセッションを再起動してアクティベートされたビルドを起動するよう案内されます。

パッケージマネージャーのセットアップ（npm、PyPI、または Go）は、一貫したプライベートなキャッシュ済みランタイムセットを検証して公開します。サイドカーは実行ファイルより先に、ファイルごとのアトミックなリネームで置き換えられます。中断された複数ファイルの公開は検出され、1 回のクラッシュアトミックなファイルシステムトランザクションとして説明されるのではなく、次回の起動時に修復されます。これはアクティブなネイティブインストールを置き換えるものではないため、実行中の CBM セッションを停止することもありません。そのキャッシュされたバイナリが実行されるときも、同じ完全一致ビルドの受け入れバリアに入ります。シェルおよび PowerShell のインストーラーは、検証済み候補のネイティブ install コマンドを呼び出すため、アカウント全体のアクティベーション保証を完全に受けられます。 通常の cli モードはコマンドをローカルで 1 つ実行しますが、上記のデーモンから切り離されているわけではありません。共有コーディネーションデーモンに接続し（まだ実行されていなければ起動します）、同じアドミッションのバリアとプロジェクトごとのグラフ変更ロックを利用します。その接続は cli_session であり、バックグラウンドウォッチャーには決して登録されず、UI も起動せず、アドミッションリースを保持するのはコマンドの生存期間だけです。コマンド自身の接続がデーモンを起動したのであれば、コマンドが終了して他に接続中のセッションがなければ、そのデーモンも再び終了します。すでにデーモンが実行中だった場合は、コマンドは単に参加し、見つけたままの状態で離れます。コマンドの実行中は、一時的なモニターが別途、アクティベーションによってその操作とその管理対象ワーカーを安全にキャンセルできるようにします。モニターはコマンドとともに終了し、常駐デーモンになることはありません。詳細は CLI モード を参照してください。

CBM Lens Beta — 人間用インターフェース

MCP ツールがエージェントにとってのコードグラフへのインターフェースであるのに対し、CBM Lens Beta は人間にとってのインターフェースです。これはバイナリに組み込まれており、すべてのチャネルのすべてのインストールに含まれます:

codebase-memory-mcp --ui=true --port=9749

ブラウザで http://localhost:9749 を開いてください。UI は共有コーディネーションデーモンが所有しているため、同時に実行中のエージェントセッションが重複した HTTP サーバーを起動することはありません。

CBM Lens は CodeAtlasWeb を基盤としています。これは Bernhard Jackiewicz が CBM の読み取りサーフェス上に構築した読書用 IDE です（設計とトラッキングは #1964）。ループバック上でエアギャップ動作し、クラウドには一切接続せず、すべてのパネルがその事実の出所を明示します。インデックスが記録しなかったものはギャップとして表示され、推測で埋められることは決してありません。

CBM Lens で何かが読み込まれないとき、そのページはすでにそれを書き留めています。コンソール出力、捕捉されなかったエラー、失敗したリクエストは ${CBM_CACHE_DIR}/logs/ui.log（デフォルトは ~/.cache/codebase-memory-mcp/logs/ui.log、1 エントリにつき 1 行の JSON、5 MiB で一度ローテーション）に書き込まれます。プロジェクトパネル（alt+p）は「This server」の下にその末尾を表示し、GET http://localhost:9749/api/ui-log?lines=200 でそれを取得でき、バグレポートにこのファイルを添付できます。

• エクスプローラーとリーダー — インデックス化されたファイルツリーと、ソースがインデックスから供給される読み取り専用の Monaco リーダー。
• セマンティックツイン — キャレットを追従します。その下にあるシンボルが保持し、呼び出し、発生させ、触れるものを、事実として、あるいは擬似コードとして、読み手に合わせて提示します。
• 読み取りモード — [w]hy am I here は入り方（バグを探す、変更の範囲を定める、プロジェクトを理解する、エントリポイントを選ぶ）を選びます。flow は呼び出しを実行される順序でたどります。bug hunt はシンボルへの期待される経路を ingest_traces が観測したものと比較します。change scope は変更がどこまで届き、何がそれをカバーするかを示します。
• Galaxy — 双方向にフォーカスを追従する永続的な 3D グラフと、エントリサブグラフの階層ビュー。
• コマンドライン — 入力しながら意味で検索します。? で終わる行は、インデックス化されたファクトカードから出典付きの回答を構築し、オプションでローカルモデルによる言い回しのパス（自分で起動する llama-server サイドカー、デフォルトではオフ、モデルやバイナリは同梱されません）を適用します。
• ライブエージェント — 同じリポジトリで作業している AI エージェントのオプトインオーバーレイで、ツールフックイベントをループバックブリッジ経由で供給されます（graph-ui/agents/）。
• [p]rojects — リポジトリのインデックス化、インデックスの確認や削除、プロジェクトの決定記録の編集、サーバーのプロセスとログの表示。
• [?]help — 何を読み取るか、何ができないか、そしてリッスンしているすべてのキーを、配線そのものから導出して示します。

アドレスに ?project=<name> を付けてプロジェクトを開くか、プロジェクトパネルで選択してください。フロントエンド自身の README、計画、誠実さのルール、記録された証明実行は graph-ui/ の下にあります。

自動インデックス

MCP セッション開始時に自動インデックスを有効にします:

codebase-memory-mcp config set auto_index true

有効にすると、新しいプロジェクトは最初の接続時に自動的にインデックスされます。以前にインデックスされたプロジェクトは、継続的な git ベースの変更検出のためにバックグラウンドウォッチャーに登録されます。設定可能なファイル上限: config set auto_index_limit 50000。

ウォッチャーは MCP セッションに追随します。開いている各 MCP セッションの基点となるプロジェクト（クライアントの作業ディレクトリ）を監視し、そのプロジェクトの最後のセッションが閉じると停止します。cli index_repository でインデックスされたリポジトリ、または別の場所を基点とするセッションからインデックスされたリポジトリは監視されません。変更後は index_repository を再実行してください。index_status はこれを watch オブジェクトで報告します: watched、およびポーリング間隔と最終スキャン時刻、または監視されていない reason のいずれかです。

ウォッチャーの登録は auto_watch（デフォルト true）によって別途制御されます。config set auto_watch false を設定すると、セッションがそのプロジェクトをバックグラウンドウォッチャーに登録しなくなります。多くのプロジェクトをまたいで作業しており、各セッションを明示的なインデックスに限定したい場合に便利です。

ウォッチャーを完全に無効にするには、config set watcher_enabled false（デフォルト true）を設定します。バックグラウンドのポーリングスレッドは起動されず、どのプロジェクトも登録されませんが、auto_index と手動の index_repository は引き続き動作します。セッションごとに参照される auto_watch とは異なり、watcher_enabled はバックグラウンドデーモンの起動時に一度だけ読み取られるため、変更後は codebase-memory-mcp daemon stop を実行してください。MCP クライアントを再接続するだけではデーモンは再起動しません。詳しくは docs/CONFIGURATION.md を参照してください。

ウォッチャーはデフォルトでは git プロジェクトのみを追随します。git リポジトリではないディレクトリからインデックスされたプロジェクトは監視されず、index_repository を再度実行するまで最後のインデックスのままになります。そのようなルートもポーリングするには、config set watch_non_git true（デフォルト false、デーモン起動時に読み取り）を設定します。設定すると、インデクサー自身の無視ルールを使用するファイルツリーのスキャンによって、同じ間隔でチェックされます。

最新の状態を保つ

更新はすべてのプラットフォームでインストールスクリプトから実行され、実行中のバイナリの内部からは実行されません。 codebase-memory-mcp update はフラグを検証し、実行すべき正確なコマンドを出力します:

# macOS / Linux
bash "<install-dir>/install.sh"

# Windows
powershell -ExecutionPolicy Bypass -File "<install-dir>\install.ps1"

インストールスクリプトはインストール時にバイナリの隣に配置されるため、出力されたパスは実行ファイルの隣で解決されます。これは冪等であるため、再実行すること自体が 更新 です。デーモンを停止し、実行中のバイナリを退役させ、新しいものをインストールし、クリーンアップします。

なぜこのようになっているのか。Windows ではこれは厳格な要件です。実行中の実行ファイルは自身のイメージを置き換えることができないため、入れ替えは置き換え対象のバイナリではないプロセスから行う必要があります。macOS と Linux ではこれは意図的な選択です。インプロセスのアップデーターは構造的にダウンローダー（アーカイブを取得し、検証し、展開し、ファイルを実行可能にし、実行する）であり、ほとんどの人が数回しか実行しないコマンドのためにその複合体をすべてのバイナリに同梱するのは割に合いません。リリースアーカイブは今やダウンロード URL を一切含んでおらず、cbm は自発的にネットワークリクエストを行いません。バックグラウンドで新しいバージョンをチェックすることもなく、どこにも通報しません。リリースを知るのはインストールスクリプト、パッケージマネージャー、または GitHub からです。

ファイルがインターネット由来であるために PowerShell がスクリプトの実行を拒否する場合は、まず Unblock-File を実行してください。

npm または pip 経由でインストールしましたか? すべてのプラットフォームでパッケージマネージャーを使用して更新してください（npm install -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp）。

アンインストール

codebase-memory-mcp uninstall

所有しているエージェント設定エントリ、スキル、フック、インストラクション、およびインストール済みバイナリを削除します。既存のグラフインデックスは一覧表示され、デフォルトでは保持されます。-y/--yes、-n/--no、および非対話入力は、--delete-indexes が明示的に指定されない限りそれらを保持します。そのフラグなしの対話型ターミナルでは個別に確認されます。デフォルトの回答は保持です。

codebase-memory-mcp uninstall -y --delete-indexes   # also delete every project index
codebase-memory-mcp uninstall --dry-run --delete-indexes   # preview; change nothing

--delete-indexes は明示的な同意であり、--no より優先されます。--dry-run は常にファイルを保持します。インデックスが保持される場合、アンインストールはそのキャッシュディレクトリ（${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}）とそれらを削除する方法を出力します。

バイナリの隣に配置されたインストールスクリプトは、報告されるだけで削除されません — アンインストールはそのパスとそれに対する rm コマンドを出力します。これは意図的にそのままにされます。それはあなた自身のコピー、チェックアウトへのシンボリックリンク、またはパッケージマネージャーによって管理されている可能性があり、アンインストーラーは所有を証明できないファイルを削除すべきではないからです。

機能

グラフと分析

• アーキテクチャ概要: get_architecture は言語、パッケージ、エントリポイント、ルート、ホットスポット、境界、レイヤー、クラスターを1回の呼び出しで返します
• アーキテクチャ決定レコード: manage_adr はアーキテクチャ上の決定をセッションをまたいで永続化します
• Louvain コミュニティ検出: 呼び出しエッジをクラスタリングして機能モジュールを発見します
• Git diff 影響マッピング: detect_changes は未コミットの変更を影響を受けるシンボルにマッピングし、リスク分類を行います
• コールグラフ: ファイルとパッケージをまたいで関数呼び出しを解決します（インポート対応、型推論あり）
• デッドコード検出: 呼び出し元がゼロの関数を検出します（エントリポイントを除く）
• Cypher 風クエリ: MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

検索

• セマンティック検索（別個のツールではなく search_graph の semantic_query パラメータ）: グラフ全体にわたるベクトル検索で、バンドルされた Nomic nomic-embed-code 埋め込み（40K トークン、768d int8）によって実現され、バイナリにコンパイルされています — API キー不要、Ollama 不要、Docker 不要。11 シグナルの複合スコアリング（TF-IDF、RRI、API/Type/Decorator シグネチャ、AST プロファイル、データフロー、Halstead-lite、MinHash、モジュール近接性、グラフ拡散）。
• BM25 全文検索: SQLite FTS5 と cbm_camel_split トークナイザー（camelCase / snake_case 対応）を使用
• 構造検索（search_graph）: 正規表現の名前パターン、ラベルフィルター、最小/最大次数、ファイルスコープ
• コード検索（search_code）: インデックス済みファイルのみに対するグラフ拡張 grep

サービス間リンク

• HTTP ルート ↔ 呼び出しサイトのマッチングと信頼度スコアリング
• gRPC、GraphQL、tRPC のサービス検出と protobuf Route 抽出
• チャネル検出（EMITS / LISTENS_ON）: Socket.IO、EventEmitter、および汎用 pub-sub パターンを 8 言語にわたって定数解決付きで検出

リポジトリ間インテリジェンス

• CROSS_* エッジ: 同じストアにインデックスされた複数のリポジトリをまたいでノードをリンクします
• マルチギャラクシー 3D UI レイアウト: リポジトリ間アーキテクチャの可視化用
• リポジトリ間アーキテクチャサマリー: インデックスされたフリート全体にわたるサービス、ルート、依存関係を統合
• 実行ステータス: index_status（および linked_projects の隣の UI レイアウト）は cross_repo オブジェクトを持ち、そのプロジェクトをソースとして index_repository(mode="cross-repo-intelligence") が実行されるまでは {"status":"never_run"}、その後は "ran" となり、last_run_at、outcome、targets、projects_scanned、total_cross_edges、skipped_projects を含みます。これにより「一度もリンクされていない」と「リンクされたが何もマッチしなかった」を区別できます。ステータスはプロジェクト自身のインデックス内の CROSS_* エッジの隣に保存されるため、インデックスを再構築する再インデックスは両方を同時に削除し、ステータスは never_run に戻ります。
• スキップされたストア: target_projects: ["*"] は #768 スキーマ変更前に構築されたインデックスを、実行全体を失敗させるのではなくスキップします。レスポンスはそれぞれを skipped_projects: [{"name", "reason": "pre_768_schema", "hint": "reindex this project"}] として一覧表示します。

エッジの種類（抜粋）

• CALLS — 呼び出し可能な要素が呼び出し元サイトで呼び出されます
• CALL_REFERENCE — 呼び出し可能な要素がサポートされた参照サイト（たとえば、直接の値引数）で使用され、1 つの正確なターゲットに解決されます
• USAGE — 識別子が使用されていますが、一意の呼び出し可能ターゲットは証明されていません（曖昧または複雑な式を含む）
• IMPORTS、DEFINES、IMPLEMENTS、INHERITS
• HTTP_CALLS、ASYNC_CALLS（サービス間）
• SPAWNS — 呼び出し元が別のプログラムを起動します（subprocess.run、exec.Command、posix_spawn、Process.Start、...）。ターゲットはプログラムにちなんで名付けられた Process ノード、またはプログラムがリテラルでない場合は <dynamic> です
• EMITS、LISTENS_ON（チャネル）
• DATA_FLOWS（引数からパラメータへのマッピング + フィールドアクセスチェーン付き）
• SIMILAR_TO（MinHash + LSH によるニアクローン検出、Jaccard スコア）
• SEMANTICALLY_RELATED（語彙の不一致、同一言語、スコア ≥ 0.80）

インデックス作成パイプライン

• 158 個のベンダー提供 tree-sitter 文法がバイナリにコンパイルされます
• 汎用パッケージ / モジュール解決 — @myorg/pkg、github.com/foo/bar、use my_crate::foo のようなベア指定子を、マニフェストのスキャン（package.json、go.mod、Cargo.toml、pyproject.toml、composer.json、pubspec.yaml、pom.xml、build.gradle、mix.exs、*.gemspec）によって解決します
• Infrastructure-as-code のインデックス作成 — Dockerfile、Kubernetes マニフェスト、Kustomize オーバーレイをグラフノードとして扱います
• Python、TypeScript / JavaScript / JSX / TSX、PHP、C#、Go、C、C++、Java、Kotlin、Rust、Perl 向けのハイブリッド LSP セマンティック型解決 — 言語の型解決アルゴリズムの軽量な C 実装であり、tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer を含む主要な言語サーバーに構造的に着想を得て、それらと互換性があります（パラメータバインディング、戻り値型推論、ジェネリック置換、JSX コンポーネントディスパッチ、プレーンな JS ファイル向けの JSDoc 推論、PHP 向けの名前空間 + トレイト + レイトスタティックバインディング解決、C# 向けのファイルスコープ名前空間 + レコード + LINQ メソッド構文、Java 向けのクラス階層 + オーバーロード + ラムダ解決、Kotlin 向けの拡張関数 + スコープ関数解決、Rust 向けのトレイトメソッド + UFCS 解決）
• RAM ファーストのパイプライン: LZ4 圧縮、インメモリ SQLite、最後に一度だけダンプ。その後メモリは解放されます。

配布と運用

• ネイティブランタイムセット、インフラストラクチャサービスはゼロ: SQLite ベースで、~/.cache/codebase-memory-mcp/ に永続化されます
• 自動同期: バックグラウンドウォッチャーが、MCP セッションが作業しているプロジェクト内のファイル変更を検出し、自動的に再インデックスします（その他のインデックス済みリポジトリ: index_repository を再実行してください）
• ルートノード: REST エンドポイントは第一級のグラフエンティティです
• CLI モード: codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'
• 入手可能な場所: npm、PyPI、Homebrew、Scoop、Winget、Chocolatey、AUR、go install

チームで共有するグラフアーティファクト

圧縮された 1 つのファイルをリポジトリにコミットすれば、チームメイトは再インデックスを省略できます。

.codebase-memory/graph.db.zst は、ソースの隣に配置されるナレッジグラフの zstd 圧縮スナップショットです。このアーティファクトはオプトインです。index_repository は persistence: true の場合にのみこれを書き出し（デフォルトは false）、一度存在すれば以降のインデックスがこれを更新します。チームメイトがリポジトリをクローンし、初めて codebase-memory-mcp を実行すると、アーティファクトが展開され、インクリメンタルインデックスがローカルの差分を埋めます。

• フォーマット: SQLite データベース。インデックスを削除し、VACUUM INTO でコンパクト化した後、zstd 1.5.7 で圧縮（通常 8〜13:1 の比率）
• 2 つの階層:
  • Best（zstd -9 + インデックス削除 + VACUUM INTO） — persistence: true を指定した index_repository によって書き出されます
  • Fast（zstd -3） — 既存のアーティファクトを 1 回おきのインデックスで更新します（ウォッチャーの低レイテンシなインクリメンタル更新を含む）
• ブートストラップ: ローカルの DB が存在せず、アーティファクトが存在する場合、index_repository は最初にアーティファクトをインポートし、その後インクリメンタルインデックスを実行します — これにより完全な再インデックスのコストを回避できます
• マージの手間なし: merge=ours を指定した .codebase-memory/.gitattributes の行が初回エクスポート時に自動生成されるため、同時編集がバイナリアーティファクトで競合を引き起こしません
• 意図的にコミットする: アーティファクトはウォッチャーの Fast 階層を含め、インデックスのたびに書き換えられ、git は各書き換えを完全な新しい blob として保存します。更新のたびにコミットすると、20 MB のファイルが数ギガバイトの履歴になるのはこのためです — あるチームでは、この単一パスで約 350 コミットにわたり約 6 GB に達しました。保存のたびにコミットするのではなく、頻度（リリース、マイルストーン、ナイトリージョブ）を決めましょう。
• コミットのたびに移動させる必要がある場合は Git LFS: リポジトリルートの .gitattributes から追跡し、自動生成された .codebase-memory/.gitattributes はそのまま残します — より近いファイルが引き続き merge=ours を提供し、ルートからは filter のみが適用されます:

  .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
  

  .zst のみを追跡してください。artifact.json は小さく、スキーマバージョンを保持しています。この属性は将来のコミットにのみ適用されるため、すでに履歴に blob が存在するリポジトリでは、まず git-filter-repo でそれらを書き換える必要があります。導入前に検討すべき 2 つのコストがあります。GitHub は LFS のストレージと帯域幅を従量制で課金し、そのオブジェクトはサポートに連絡しない限り削除できません。また、すべてのチームメイトが git lfs install を実行する必要があります — これがないと、チェックアウト時にアーティファクトのあるべき場所にポインタファイルが残り、整合性チェック付きのインポートがそれを拒否し、完全な再インデックスにフォールバックします。
• 任意: 望まない限りコミットされません。全員がゼロから再インデックスすることを望む場合は、.codebase-memory/ を .gitignore に追加してください。

その結果は graphify の graphify-out/ ディレクトリと趣旨は似ていますが、明示的な 2 階層エクスポート、整合性チェック付きインポート、マージの摩擦ゼロを備えた単一の圧縮ファイルとなっています。

仕組み

codebase-memory-mcp は構造解析バックエンドです — ナレッジグラフを構築し、クエリを実行します。LLM は含まれていません。代わりに、インテリジェンス層としてあなたの MCP クライアント（Claude Code、または任意の MCP 互換エージェント）に依存します。

You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: executes graph query, returns structured results

Agent: presents the call chain in plain English

なぜ組み込みの LLM がないのか? 他のコードグラフツールは、自然言語 → グラフクエリの変換のために LLM を組み込んでいます。これは追加の API キー、追加コスト、そして設定すべきもう 1 つのモデルを意味します。MCP では、あなたがすでに会話しているエージェントがまさにクエリの翻訳者なのです。

パフォーマンス

Apple M3 Pro でのベンチマーク結果:

RAM ファーストのパイプライン: すべてのインデックス処理はメモリ内で実行されます (LZ4 HC 圧縮読み取り、インメモリ SQLite、最後に一度だけダンプ)。メモリはインデックス処理の完了後に OS へ返却されます。

トークン効率: 5 つの構造クエリは codebase-memory-mcp 経由で約 3,400 トークンを消費しましたが、ファイルごとの grep 探索では約 412,000 トークンを消費しました — 99.2% の削減です。

ご自身のワークロードで同等の品質、レイテンシ、エージェント効率の指標を測定するには、品質、レイテンシ、エージェントの節約量の測定を参照してください。上記の数値を厳密に再現するには、元の入力と生の成果物が必要です。

トラブルシューティングと診断

codebase-memory-mcp は100% ローカルで動作し、テレメトリを一切収集しません — あなたのコード、クエリ、環境、利用状況がマシンの外に出ることはありません。このプライバシー保証は、私たちの側で再現できない問題 (数時間にわたる緩やかなメモリ増加、パフォーマンスの低下、実際に数日使用した後にのみ現れるリークなど) に遭遇したとき、あなたが送信を選ばない限り私たちにはまったくデータがないということも意味します。以下は、それを自分でキャプチャする方法です。

診断ログをキャプチャする

最初のデーモン経由の MCP セッションが開始する前に CBM_DIAGNOSTICS=1 を設定し、その後で問題を再現してください (必要なだけ実行させてください — 緩やかなリークは傾向に現れるまでに時間がかかります)。共有デーモンは、それを起動したセッションからこの設定を取得します。すでに実行中の場合は、設定を変更する前に、すべてのデーモン経由のセッションを閉じてデーモンを終了させてください。デーモンは、システムの一時ディレクトリ (macOS/Linux では $TMPDIR または /tmp、Windows では %TEMP%) の下に、新しくオーナー専用の cbm-diagnostics-<pid>-<random> ディレクトリを作成します。正確なパスは、${CBM_CACHE_DIR}/logs/cbm-daemon.log 内の diagnostics.start イベントによって記録されます:

プライベートなランダム化ディレクトリは、別のローカルアカウントが予測可能な診断パスにリンクや特殊ファイルを事前に配置することを防ぎます。その <pid> コンポーネントは共有デーモンのプロセス ID で、daemon.start イベントによっても記録されます。各エージェントの MCP サーバー設定の env ブロックでこの変数を一貫して設定するか、最初のセッションを起動する前にエクスポートしてください。

共有すべきもの

メモリ/パフォーマンスの問題を起票するときは、.ndjson の軌跡を添付してください — ソースコードやクエリテキストは含まれず、リソースカウンターのみが含まれます。ファイルを添付したくない場合は、それを (またはエージェントによるその要約を) イシューに貼り付けてください。あなたのアシスタントは NDJSON を直接読み取り、rss/committed が単調に増加しているかどうか、どのくらいの速さで、クエリ数に対してどのように増加しているかを報告できます — これはまさに原因を特定するために必要な情報です。

インストール

ビルド済みバイナリ

すべてのリリースには SHA-256 ハッシュを含む checksums.txt が同梱されています。実行ファイルは自己完結型であり、隣接するデータファイルは必要ありません。Linux の -portable アーカイブには完全に静的なビルドが含まれており、通常のプラットフォーム別アーカイブはネイティブのシステム ABI を使用します。

Windows での注意: 署名のないソフトウェアに対して SmartScreen が警告を表示する場合があります。「詳細情報」 → 「実行」 をクリックしてください。checksums.txt で整合性を検証してください。

セットアップスクリプト

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

irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex

AUR (Arch Linux)

yay -S codebase-memory-mcp-bin

paru -S codebase-memory-mcp-bin

codebase-memory-mcp-bin パッケージはこちらから入手できます: https://aur.archlinux.org/packages/codebase-memory-mcp-bin

Nix (flake)

この flake は 2 つのサーバーパッケージとスタンドアロンのフロントエンドを公開しています:

インストールせずに直接実行する:

# Standard server
nix run github:DeusData/codebase-memory-mcp

# Server with the embedded graph UI
nix run github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui -- --ui=true --port=9749
# then open http://127.0.0.1:9749

またはバイナリを ./result/bin/codebase-memory-mcp にビルドする:

nix build github:DeusData/codebase-memory-mcp                          # standard
nix build github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui   # with UI

クローン内で作業していますか? flake URL の代わりに . を使用してください。例: nix run .#codebase-memory-mcp-ui -- --ui=true、または nix shell .#codebase-memory-mcp-ui でバイナリを PATH に通したシェルに入れます。

Note: 手動で起動した場合 (MCP クライアントからではなく)、stdin が閉じるとすぐにサーバーが終了します。これは通常の MCP の動作です。UI をテストする間は stdin を開いたままにしてください。例: sleep infinity | codebase-memory-mcp --ui=true --port=9749。codebase-memory-mcp-ui パッケージはビルド時に UI を組み込みます。標準の default パッケージを --ui=true で nix run すると、HTTP サーバーの起動を拒否します。

Claude Code 経由でのインストール

You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"

ソースからのビルド

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh --with-ui          # the shipped composition (graph UI embedded)
scripts/build.sh                    # without the UI (development only)
# Binary at: build/c/codebase-memory-mcp   (codebase-memory-mcp.exe on Windows)

すべてのプラットフォームで 1 つの自己完結型実行ファイル が提供されます。グラフ UI とエージェント統合テンプレートはバイナリにリンクされているため、展開したアーカイブはすぐに完全な状態になります。

テストスイートを実行する (141 スイートにわたる 8,060 のテスト):

scripts/test.sh                     # full: clean sanitizer build + all suites + guards
scripts/test.sh --suites <name>     # one suite, incremental, seconds
build/c/test-runner --list-suites   # what is available

scripts/test.sh は CI ゲートが実行するのと同じエントリポイントであるため、ローカルでの成功は CI での成功と同じ意味を持ちます。標準的なローカルアーティファクトフローチェックは、stripped/unstripped の両方の候補をビルドし、この明示的にスキャンされていないローカル実行では stripped 候補をデフォルトとし、それらの正確なバイトをパッケージ化し、アーカイブを展開し、スモークテストを実行します:

scripts/ci/smoke-artifact.sh <linux|darwin|windows> <amd64|arm64>

scripts/package-release.sh は意図的に低レベルの不変境界です: すでに最終化された --selected-binary とその --expected-sha256 のみを受け付け、実行ファイルのビルド、strip、署名、再リンクは決して行いません。

手動での MCP 設定

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

マルチエージェント対応

install は 45 のクライアントサーフェスを構成します。39 は自動検出され、6 は条件付きまたは明示的です。「条件付き」とは、文書化されたプラットフォーム、または明示的で既に存在する設定パスが対象がアクティブであることを証明した場合にのみ、インストーラーが書き込むことを意味します。実験的な機能フラグを切り替えたり、プラグイン、YOLO モード、グローバルな権限バイパス、サードパーティの指示の信頼を有効にしたりすることは決してありません。

クライアントに文書化されたカスタムエージェント形式がある場合、インストーラーは 1 つの正規のコントラクトから 3 つの正確に所有された定義を作成します。

• Scout（ティア 1） — 迅速なポジティブかつ暫定的な発見のための、約 3～4 回の限定的な呼び出し。不在、網羅的な影響、デッドコードに関する主張は行いません。
• Verify（ティア 2、デフォルト） — タスク指向のグラフ証拠、正確なソースチェック、引用されたすべてのファイルのパスカバレッジ、およびネガティブな主張を行う前のスコープカバレッジ。
• Auditor（ティア 3） — 範囲を限定したスコープ、現在のインデックス生成、関連するページネーションの完全な処理、より広範な関係チェック、および明示的な未解決の制限事項。

すべての直接ティアは、その証拠パスに対して check_index_coverage をバッチ処理し、フラグが立てられた範囲またはスキップ/除外されたファイルを直接読み取ります。クリーンなカバレッジ結果は「記録されたギャップがない」ことのみを意味し、完全性の証明には決してなりません。安全な子 MCP アクセスを持たないクライアントは、親ハンドオフエージェントとして同じ 3 つのティアを受け取ります。親はプロジェクト、生成、ページネーション状態、グラフ証拠、およびカバレッジ結果を提供する必要があります。更新はバイト単位で同一の以前の Verify 定義のみを移行し、ユーザーが変更したエージェントを上書きすることは決してありません。

セッション、圧縮、サブエージェント

このプロジェクトによってインストールされるフックはフェイルオープンかつコンテキスト専用です。Claude Code の PreToolUse は Grep/Glob/Bash を監視し、一致するグラフシンボルを additionalContext として注入します。Read に対する PostToolUse は、グラフがそのファイルを完全に解析またはインデックス化できなかった場合に、対象を絞ったカバレッジコンテキストを追加します。要求されたツール呼び出しを拒否したり置き換えたりすることは決してありません。

Claude Code、Codex CLI、Qwen Code、GitHub Copilot CLI、および VS Code の Copilot ランタイムは、ベンダーが文書化されたコンテキスト出力契約を公開している場合に、ペアになったセッション/サブエージェントコンテキストを受け取ります。Codex ユーザーは /hooks を通じてインストールされた フックを確認して信頼する必要があります。フック定義を変更するとその信頼ハッシュが変わるため、 更新時に再信頼が必要になることがあります。Qoder は SessionStart、SubagentStart、および Read 後のカバレッジを使用し、Windows 上では文書化された PowerShell エグゼキューターも含みます。 Kimi は UserPromptSubmit を使用し、Hermes は pre_llm_call を使用します。どちらも 文書化された Windows 実行パスを保持します。Devin は macOS/Linux に UserPromptSubmit と PostCompaction をインストールし、Claude の同等の管理対象フックが存在しない場合にのみ SessionStart を追加します。GitLab Duo は実験的なフック サーフェス上で、範囲を狭く限定した macOS/Linux ユーザー SessionStart エントリを取得します。GitLab Duo、Devin、および Factory のフックは Windows では 保留されます。これらのベンダーがそこで決定論的なシェル/エグゼキューター契約を文書化していないためです。Gemini CLI、Factory Droid、および Augment も、文書化された読み取り後/表示後 カバレッジコンテキストを追加しますが、同等の文書化された子起動コンテキストは公開していません。

安定したコンテキスト生成ライフサイクルイベントを持たないランタイムでは、永続ファイルが 新しいセッションと圧縮をまたいで契約を伝えます。グラフプロジェクト とインデックスの鮮度を検証し、親で構造的事実をクエリし、委譲されたすべてのタスクでプロジェクト、 修飾シンボル、パス、およびコールチェーンのエビデンスを渡します。 Claude、Codex、Gemini、Kiro、Qwen、Copilot、CodeBuddy、OpenCode、Kilo、Vibe、 Qoder、Junie、Factory、および Grok Build は Scout、Verify、および Auditor グラフプロファイルを受け取ります。 Kiro はこの MCP サーバーを Scout 用に --tool-profile scout、Verify/Auditor 用に --tool-profile analysis で埋め込みます。Junie は同等の名前付き サーバーエイリアスを登録します。そのサブエージェントスキーマが個々のツールではなくサーバーでフィルタリングするためです。両方のプロセスプロファイルはポジティブ 許可リストを使用します。Scout は 7 つの高速検査ツールを公開し、Analysis は 11 を公開し、将来のまたは変更を加える ツールは明示的にレビューされるまで利用できません。いずれかの Junie エイリアスがユーザー設定と 衝突する場合、インストーラーはそれを保持し、代わりに親ハンドオフプロファイルをインストールします。Qoder は文書化された名前付きサーバー 選択を、正確なティア固有の MCP ツール ID と組み合わせます。Factory は、サーバー全体を公開してしまう追加的な mcpServers フィールドなしで、正確に登録された MCP ツール ID を使用します。Codex、Kilo、Vibe、およびその他の対応フォーマットも同様に、 サポートされる最も狭いツールセットを列挙します。Rovo、Cursor、Augment、Pochi、および Cline は、直接的な 子 MCP が利用できないか安全でない場合に親ハンドオフを使用します。Pochi は readFile に限定され、Cline の子エージェントは MCP を使用できません。 Cline のファイルフックは存在すると自動的に有効化されますが、現在の Cline はそのコンテキスト出力を確実に消費しないため、自動アダプターは見送られ、以前に所有されていたアダプターはクリーンアップされます。CodeBuddy のベータ版であるバージョン制限付きフックは自動インストールされません。Junie の EAP の SessionStart 出力は無視されると文書化されているため、コンテキストフックはインストールされません。 Junie のカスタムエージェントは EAP 依存のままです。Qoder は、同じ名前のユーザーエージェントよりも優先度の高いプロジェクトまたはプラグインのエージェントを先に解決する場合があります。インストール後またはプロファイル変更後にクライアントを再読み込みしてください。 Cursor のコンテキスト フックは見送られます。セッションコンテキストの注入には既知の競合状態があり、subagentStart は制御専用であり、読み取り専用のサブエージェントは MCP アクセスを安全に受け取れません。Grok Build の パッシブフックイベント（SessionStart、SubagentStart、PostToolUse）は stdout を破棄し、PreToolUse は deny/rewrite の決定のみを尊重するため、そのコンテキストフックは 見送られます。また Grok は互換レイヤーを通じて Claude と Cursor の MCP、スキル、フックファイルを読み取り、ネイティブの config.toml エントリがそのコピーを名前でシャドウします。Rovo には文書化されたセッションコンテキスト出力フックがなく、Bob には適切なフックもカスタムエージェントのサーフェスも文書化されていません。これらのサーフェスは 考案された拡張で近似されることはありません。Kimi プラグイン、Amp プラグイン、GitLab の実験的なグローバルスキルはオプトインのままです。

OpenClaw は、圧縮後に Codebase Knowledge Graph (codebase-memory-mcp) の AGENTS セクションを再注入し、同じガイダンスを、そのサブエージェントが継承するブートストラップ ファイルである TOOLS.md に配置します。自動拡張はアクティブ／デフォルトの ワークスペースを対象とします。別々の agents.list[].workspace ディレクトリでは、インストールのためにその ワークスペースをアクティブにするか、管理対象ブロックをそこにコピーする必要があります。

インストールされる Claude シムは後方互換性のために cbm-code-discovery-gate という名前です。 このレガシーな名前にもかかわらず、ゲートやブロックを行うことはありません。

手動または UI 管理の統合

これらは意図的に自動インストールとしてカウントされません。Qodo MCP はその UI を通じて追加され、 エンタープライズ許可リストによって管理される場合があります。Warp MCP は Warp Drive/UI または 呼び出しごとに管理されます（自動なのは共有スキルのみです）。 JetBrains AI Assistant / ACP は IDE 管理です。GitHub Copilot コーディングエージェント、Jules、 および CodeRabbit はクラウド／リポジトリ管理です。Replit は安定したローカルユーザーグローバルクライアントではなく リモート／サービス統合を公開しています。BLACKBOX AI は安定した任意のユーザーグローバル MCP／命令／エージェント スキーマを文書化していません。Plandex には変更しても安全な安定したグローバルレジストリがありません。 また SWE-agent は明示的な YAML を使用しており、もはや適切な自動グローバルターゲットではありません。

CLI モード

すべての MCP ツールは、ローカルのワンショットコマンドとして呼び出すことができます。CLI ツールは共有コーディネーションデーモンに接続し — まだ実行中でなければ起動します — コマンドの存続期間中、クラッシュセーフな正確なビルドのアドミッションリースを取得します。これらはバックグラウンドウォッチャーに登録されることはなく、コマンドが自身で起動しなければならなかったデーモンは、コマンドの接続が閉じられ、他にそれを使用しているセッションがなくなると再び終了します。index_repository は内部的に唯一の例外です。インデックスのために一時的な、正確なビルドの監視付きワーカーを起動し、CLI コマンドが終了する前にそのワーカーを停止します。ワーカーは終了するまで自身のリースを保持します。

グラフデータを変更するコマンドは、共有の OS ベースのプロジェクトごとのロックを使用します。これにより、同じプロジェクト上の CLI セッションと MCP セッションからの競合する作業が直列化され、無関係なプロジェクトは独立して進行できます。 stderr が対話型ターミナルの場合、CLI はライフサイクルとインデックス作成の進捗を自動的に表示します。stderr がリダイレクトされている場合やコマンドが非対話的に実行される場合に同じフィードバックを強制するには、--progress を渡します。自動ターミナル進捗と通常の診断を無効化しつつエラーは保持するには、--quiet を渡します。これは --progress や外側の cli --verbose と組み合わせることはできません。定型的な情報ログはデフォルトで抑止されます。それらを含めるには外側の cli --verbose を渡します。進捗とログは stderr を使用し、stdout はコマンド結果のために予約されたままです。読み取りツールはデフォルトでコンパクトなツリーを返します。機械可読なペイロード JSON にはツールの --format json を、完全な MCP エンベロープには外側の --json を渡します。

大きなコンパクトツリーテーブルは、レスポンスローカルの <section>_refs ディレクトリと明示的な <section>_ref_rule で始まる場合があります。@0+handler.go のようなセルは、ref 0 のプレフィックスと handler.go に再構築されます。参照はその兄弟 <section> テーブルに対してローカルであり、展開は非再帰的です。<section>_refs 内のエントリは常にリテラルのプレフィックスです。これは宣言されたパス列と修飾名の列に限定され、レンダリングされた正確なテーブルが少なくとも 15% かつ 64 バイト小さく、保守的なモデル中立のトークン形状プロキシも少なくとも 1% 改善する場合にのみ有効になります。検索とトレースも同様に、直接およびプレフィックスでグループ化されたツリー形状をレンダリングし、より小さい完全な表現を保持するため、単一または散在する回答がディレクトリのオーバーヘッドを負担することはありません。キーはテーブルごとに一度宣言されますが、不可解に省略されることはなく、--format json は機械的なコンシューマー向けに安定したリテラル文字列を保持します。両方のゲートは決定的です。正確なトークン数は依然として呼び出し元のトークナイザーに依存します。

リーンなレスポンスは意味的に切り詰められ、コードや識別子から任意のバイトを切り取ることは決してありません。ランク付けされたグラフ行は、生の grep 行や診断サマリーよりも優先して保持されます。省略された行やセクションは、合計、has_more、および厳密に進む継続オフセットまたはカーソルを報告します。最初の行全体すら収まらない場合、CBM はより大きな予算を要求し、自己ループするカーソルを出力しません。max_output_tokens はモデル中立のサイズ指定ガイダンスです。CBM は要求されたトークンあたり 4 UTF-8 バイトの決定的な上限を適用するため、トークナイザーに正確なカウントではありません。diagnostics、source_mode、detail などの詳細フラグは、より重いフィールドをオプトインします。search_code はランク付けされた行を result_limit/result_offset（limit は互換エイリアスのままです）でページングし、生の行を raw_limit/raw_offset で、ディレクトリサマリーを directory_limit/directory_offset でページングします。生の行はデフォルトで UTF-8 セーフなマッチ中心のプレビューになります。各行は content_start_byte、返された/合計のバイト数、既知の場合のマッチのバイト範囲、およびコンテンツの継続オフセットを報告します。生の行カーソルを移動せずに元の行をページングするには、raw_content_offset を渡します。match_limit と source_max_lines は、正確な省略メタデータとともに、結果ごとの詳細を制限します。detect_changes は変更されたファイル、影響を受けるシンボル、モジュールサマリーを独立してページングします。変更されたコミット、ワークツリーバイト、グラフ生成、またはセマンティック引数を拒否する、そのスナップショットにバインドされた *_cursor 継続を優先してください。これは行を暗黙にスキップしたり重複したりする代わりになります。

すべてのレスポンスは標準の UTF-8 です。識別子、パス、および生の検索プレビューは POSIX バイト文字列の同一性を保持します。不正な UTF-8 を含む保存された値は、@bytes:<すべての元のバイトの小文字 16 進数> として可逆的に出力されます。予約された @bytes: または @utf8: プレフィックスでリテラルに始まる有効な保存値は、@utf8:<元の値> として出力されるため、デコードは曖昧ではありません。リテラル UTF-8 には @utf8: プレフィックスを 1 つ取り除き、元のバイトには @bytes: プレフィックスを 1 つ 16 進デコードします。通常の有効な UTF-8 は変更されず、出力トークンのオーバーヘッドを負担しません。コードを読みやすく保つため、ソース本体は不正な UTF-8 を U+FFFD に置き換えます。バイト単位で正確なソース検査が必要な場合は、ページング可能な生の検索プレビューを使用してください。 cli <tool> --help を使用すると、そのツールの入力スキーマから生成されたフラグを確認できます:

codebase-memory-mcp cli index_repository --repo-path /path/to/repo
codebase-memory-mcp cli list_projects

# Use the "name" returned by list_projects as the project value.
codebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function
codebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both
codebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Function) RETURN f.name LIMIT 5'

# Force human-readable progress without contaminating stdout.
codebase-memory-mcp cli --progress index_repository --repo-path /path/to/repo
# Suppress automatic terminal progress and non-error diagnostics.
codebase-memory-mcp cli --quiet list_projects --format json
codebase-memory-mcp cli search_graph --project my-project --label Function --format json
codebase-memory-mcp cli list_projects --format json --detail stats | jq '.projects[].name'

引数を取るツールでは、JSON 引数を stdin 経由でパイプすることもできます。入力スキーマで引数を何も宣言していないツール — list_projects — は stdin を読み取らないため、呼び出し側が決して閉じないパイプを継承しても応答し続けます(child_process.spawn や同様のラッパーにおけるデフォルトの動作です)。インライン JSON も後方互換性のために引き続き受け付けられますが、フラグ、--args-file、または stdin が推奨され、非推奨となっています。

MCP ツール

インデックス作成

長時間のインデックス作成とクライアントの呼び出し期限。 大規模なリポジトリに対する同期的な index_repository は、MCP クライアントが 1 回のツール呼び出しに許可する時間よりも長くかかることがあります(一部の IDE クライアントは固定の期限を過ぎると諦めます)。クライアントがキャンセルまたは切断すると、デーモンは他に誰も待っていないインデックスをキャンセルするため、同じブロッキング呼び出しを再試行しても完了しません。代わりに非同期モードを使用してください:

1. index_repository(repo_path="/abs/path", async: true) はデーモン内でインデックスを開始し(またはそのプロジェクトですでに実行中のものに参加し)、state(queued/running)とともに即座に戻ります。ジョブはクライアントがキャンセル、タイムアウト、または切断しても実行され続けます。デーモンを停止した場合にのみ終了します。
2. index_repository(repo_path="/abs/path", status: true) は state(queued、running、cancelling、succeeded、failed、cancelled)、started_at、finished_at、および error の概要を報告します。状態が succeeded、failed、または cancelled になるまでポーリングしてください。同じ repo_path(およびインデックス呼び出しで name を使用した場合は name)を渡してください。

async と status は排他的です。async は cross-repo-intelligence には適用されません。どちらもデーモンベースのサーバー(デフォルトの codebase-memory-mcp エントリポイント)が必要です。(codebase-memory-mcp daemon start ではなく)オンデマンドで起動される一時的なデーモンは、最後のクライアントが切断すると停止し、そのジョブをキャンセルします。接続された MCP セッションはそれを存続させるため、エディタからの非同期は機能します。デーモンの唯一のクライアントであるワンショットの codebase-memory-mcp cli index_repository --async は明確なエラーで拒否されます。これはコマンドが終了した瞬間にジョブが終了してしまうためです。まず codebase-memory-mcp daemon start を実行するか、MCP セッションを開いたままにするか、--async なしで呼び出してください。status はどこでも機能します。同期呼び出しが途中で切断された場合、そのプロジェクトに対する次の index_repository または status 呼び出しには、非同期モードを提案する notice が含まれます。index_status は公開されたグラフとその鮮度を引き続き説明します。

クエリ

manage_adr(mode='set_sections') は名前で 1 つ以上のセクションを書き込み、保存済みドキュメントにスプライスするため、指定したセクションの外側のテキスト — 前書き、コードフェンス、セクションの順序など — はバイト単位で保持されます。従来の PURPOSE / STACK / ARCHITECTURE / PATTERNS / TRADEOFFS / PHILOSOPHY のセットだけでなく、任意の ## Heading が機能します。名前は大文字小文字を含め完全一致で照合されます。同じセクションを 2 回書き込んでも no-op であるため、レスポンスが失われた後の再試行でコンテンツが重複することはありません。

manage_adr のクエリモード（get と sections）はサーバーのキャッシュされたクエリストアを使用するため、同一プロジェクトの再インデックスが実行中でも処理を進められます。再インデックス中に別のプロセスが置換用ストアを公開した場合、アイドル時のエビクションがそのキャッシュを更新するまで、公開前の ADR を返すことがあります。更新はプロジェクトのミューテーションガードを通じて引き続き直列化されます。

グラフデータモデル

ノードラベル

Project、Package、Folder、File、Module、Class、Function、Method、Interface、Enum、Type、Route、Resource

エッジタイプ

CONTAINS_PACKAGE、CONTAINS_FOLDER、CONTAINS_FILE、DEFINES、DEFINES_METHOD、IMPORTS、CALLS、CALL_REFERENCE、HTTP_CALLS、ASYNC_CALLS、SPAWNS、IMPLEMENTS、HANDLES、USAGE、CONFIGURES、REFERENCES_FILE、MENTIONS、WRITES、MEMBER_OF、TESTS、USES_TYPE、FILE_CHANGES_WITH

MENTIONS は、ドキュメント化された定義をその doc コメントが参照するコードにリンクします（C# の <see cref>、<seealso cref>、<exception cref>、<inheritdoc cref>）。ペアごとに 1 つのエッジで、via、syntax、tier（exact または unique）、最初の line、count を持ちます。参照は、その言語自身の名前解決ルールの下でちょうど 1 つの定義を指す場合にのみバインドされます。残りは index_status 内の doc_links で理由ごとにカウントされます（diagnostics='full' のサンプル）。

修飾名

get_code_snippet は修飾名 <project>.<path_parts>.<name> を使用します。まず search_graph を使ってそれらを見つけてください。

サポートされている Cypher（openCypher 読み取りサブセット）

query_graph は読み取り専用の openCypher サブセットです：

• 句: MATCH、OPTIONAL MATCH、複数の MATCH、WHERE、WITH（+ WITH … WHERE）、RETURN、ORDER BY、SKIP、LIMIT、DISTINCT、UNWIND、UNION / UNION ALL、CASE。
• パターン: ラベル付きノード、ラベルの選択 (n:A|B)、リレーションシップの型/方向、可変長パス [*1..3]、インラインプロパティマップ。
• WHERE: = <> < <= > >=、AND/OR/XOR/NOT、IN、CONTAINS、STARTS WITH、ENDS WITH、IS [NOT] NULL、正規表現 =~、ラベルテスト n:Label、および EXISTS { (n)-[]->() }（シングルホップの存在確認 — デッドコードに最適です。例：WHERE NOT EXISTS { (f)<-[:CALLS]-() }）。
• 集計関数: count（+DISTINCT）、sum、avg、min、max、collect。
• 関数: labels、type、id、keys、properties；toLower/toUpper/toString/toInteger/toFloat/toBoolean；size、length、trim/ltrim/rtrim、reverse；coalesce、substring、replace、left、right。

このサブセット外のもの（書き込み/MERGE/CALL 句、サポートされていない関数、リスト/マップリテラル、内包表記、パス関数、パラメータ）は、空の結果を返すのではなく、明確な unsupported … エラーで失敗します。

ファイルの無視

階層化されています：ハードコードされたパターン（.git、node_modules など）→ .gitignore 階層 → .cbmignore（プロジェクト固有、gitignore 構文）。シンボリックリンクは常にスキップされます。

.cbmignore の完全な使い方については docs/cbmignore.md を参照してください：構文、無視レイヤー間の優先順位、否定のセマンティクスについて説明しています。

設定

codebase-memory-mcp config list                          # show all settings
codebase-memory-mcp config set auto_index true           # auto-index on session start
codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
codebase-memory-mcp config set watcher_enabled false     # stop the watcher thread entirely (default: true)
codebase-memory-mcp config set watch_non_git true        # also poll non-git project roots (default: false)
codebase-memory-mcp config set index_max_files 250000    # optional per-index source-file limit
codebase-memory-mcp config set index_max_source_mb 16384 # optional per-index source-size limit
codebase-memory-mcp config reset auto_index              # reset to default

2 つの index_max_* 設定はデフォルトで off です。いずれかを超過すると、部分的なグラフを公開するのではなく、インデックス試行全体が失敗します。既存の提供中のインデックスは保持されます。詳細は Index resource limits を参照してください。

環境変数

デーモンが所有するコンポーネント — 診断、デーモンのログ記録、プロセス全体のインデックス作成リソース制限など — で使用される環境は、デーモンを起動する最初のデーモンバックのセッションから取得されます。以降のセッションはそのプロセスに参加し、これらの値を置き換えることはできません。変更するには、すべてのデーモンバックのセッションを閉じ、関連するエージェント設定を一貫して更新し、セッションを再起動してください。CBM_ALLOWED_ROOT はセッション固有のままですが、競合する CBM_CACHE_DIR は拒否され、ワンショットの CLI コマンドも上記のルールから免除されません。これは他のセッションと同様にコーディネーションデーモンに接続し、実行中のデーモンがなければ 1 つ起動するため、その呼び出しがデーモンを起動するものである場合にのみ、自身の環境が取得されたデーモン所有の環境になります — すでに実行中のデーモンに参加する場合は、代わりにそのデーモンがすでに取得済みの値を継承します。

# Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data

カスタムファイル拡張子

JSON 設定ファイルは extra_extensions という単一のキーをサポートしており、追加のファイル拡張子をサポート対象の言語にマッピングします。.blade.php (Laravel) や .mjs (ES モジュール) のようなフレームワーク固有の拡張子に便利です。(その他の調整可能な項目については、環境変数 と上記の config サブコマンドを参照してください。)

設定ファイルの完全なリファレンスが必要ですか？ docs/CONFIGURATION.md を参照してください。

プロジェクト単位 (リポジトリのルートに配置):

// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}

グローバル (すべてのプロジェクトに適用):

// ~/.config/codebase-memory-mcp/config.json  (or $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}

各エントリは、拡張子 (必ず . で始まる必要があります) を言語名にマッピングします。言語名は大文字と小文字を区別せずに照合されます。受け入れられる値 (括弧内はエイリアス) は次のとおりです:

bash (sh), c, c++ (cpp), c# (csharp), clojure, cmake, cobol, common lisp (commonlisp, lisp), css, cuda, dart, dockerfile, elixir, elm, emacs lisp (emacslisp), erlang, f# (fsharp), form, fortran, glsl, go, graphql, groovy, haskell, hcl (terraform), html, ini, java, javascript, json, julia, kotlin, lean, lua, magma, makefile, markdown, matlab, meson, nix, objective-c (objc), ocaml, perl, php, protobuf, python, r, ruby, rust, scala, scss, sql, svelte, swift, toml, tsx, typescript, verilog, vimscript, vue, wolfram, xml, yaml, zig.

競合する拡張子については、プロジェクト設定がグローバル設定を上書きします。言語名が不明なエントリ、または拡張子が . で始まらないエントリはスキップされ、警告が stderr にログ出力されます (デフォルトの info ログレベルで表示されます)。存在しない設定ファイルは無視されます。

永続化

SQLite データベースは ~/.cache/codebase-memory-mcp/ に保存されます。再起動をまたいで永続化されます (WAL モード、ACID 安全)。リセットするには: rm -rf ~/.cache/codebase-memory-mcp/。

トラブルシューティング

ハイブリッド LSP

tree-sitter を超えたセマンティック型解決。

tree-sitter 単体では構文上の AST が得られます。これにより命名、構造、呼び出し箇所はうまく扱えますが、user.profile.display_name() が 3 モジュール離れた場所で宣言された Profile.display_name に解決されることを教えてはくれません。tree-sitter はインポート、ジェネリクス、継承、標準ライブラリの型を追跡しません。

codebase-memory-mcp は、主要な言語サーバー (tsserver / typescript-go、pyright、gopls、Roslyn、Eclipse JDT、rust-analyzer) に構造的に着想を得て、それらと互換性のある、言語の型解決アルゴリズムの軽量な C 実装を、ネイティブ実行ファイルに直接組み込んで同梱しています。言語サーバープロセスも、プロジェクトごとのセットアップも、API キーも不要です。このレイヤーを ハイブリッド LSP と呼びます。これは毎回のパースで tree-sitter と並行して動作し、型情報を用いて呼び出し解決 (CALLS / RESOLVED_CALLS) と呼び出し可能な値の解決 (CALL_REFERENCE、曖昧な値は USAGE として保持) を精緻化するため、結果として得られるグラフは IDE の「定義へ移動」が解決するものを反映します。

完全なハイブリッド LSP をサポートする言語:

2 層アーキテクチャ:

1. Tree-sitter パス — 高速で構文的。162 言語すべてで実行されます。定義、呼び出し、インポートを抽出します。
2. ハイブリッド LSP パス — 型を考慮。Tree-sitter パスの上で言語ごとに実行されます。インポートグラフと、ファイル単位または事前構築されたファイル横断定義レジストリを用いて呼び出しエッジを精緻化します。ハイブリッド LSP パスがまだない言語はテキストベースの解決にフォールバックするため、常に何らかの答えが得られます。

その結果、パッケージ、継承階層、標準ライブラリの呼び出しをまたいで trace_path を駆動するのに十分な精度を持つナレッジグラフが得られます — しかもプロジェクトごとに言語サーバープロセスを動かすコストはかかりません。

言語サポート

162 言語に対応しており、すべてバイナリにコンパイルされたベンダリング済みの tree-sitter 文法を介して解析されます。64 の実際のオープンソースリポジトリ（78 から 49K ノード）に対してベンチマークを実施しています。

その他にも対応（まだベンチマーク未実施）：Ada、Agda、Apex、Assembly (NASM)、Astro、AWK、Beancount、BibTeX、Bicep、Bitbake、Blade、Cairo、Cap'n Proto、Clojure、CMake、COBOL、Common Lisp、Crystal、CSV、CUDA、D、Devicetree、Diff、.env、Elm、Emacs Lisp、F#、Fennel、Fish、FORM、Fortran、FunC、GDScript、.gitattributes、.gitignore、Gleam、GLSL、GN、Go module、Go template、GraphQL、Hare、HLSL、Hyprlang、INI、ISPC、Janet、Jinja2、JSDoc、JSON、JSON5、Jsonnet、Julia、Just、Kconfig、KDL、Lean 4、Linker Script、Liquid、LLVM IR、Luau、Magma、Makefile、Markdown、MATLAB、Mermaid、Meson、Move、Nickel、Nim、Nix、Odin、Pascal、Pkl、PO (gettext)、Pony、PowerShell、Prisma、.properties、Protobuf、Puppet、PureScript、Racket、Regex、requirements.txt、ReScript、RON、reStructuredText、Scheme、Slang、Smali、Smithy、Solidity、SOQL、SOSL、Squirrel、SSH config、Starlark、Svelte、Sway、SystemVerilog、TableGen、Tcl、Teal、Templ、Thrift、TLA+、Typst、Verilog、VHDL、Vim script、Vue、WGSL、WIT、Wolfram、XML、Zsh。

アーキテクチャ

src/
  main.c              Entry point (MCP stdio server + CLI + install/update/config)
  daemon/             Per-account session coordination, IPC, lifecycle, shared jobs/watchers
  mcp/                MCP server (17 tools, JSON-RPC 2.0, session detection, auto-index)
  cli/                Install/uninstall/update/config (45 client surfaces, hooks, instructions)
  store/              SQLite graph storage (nodes, edges, traversal, search, Louvain)
  pipeline/           Multi-pass indexing (structure → definitions → calls → HTTP links → config → tests)
  cypher/             Cypher query lexer, parser, planner, executor
  discover/           File discovery (.gitignore, .cbmignore, symlink handling)
  watcher/            Background auto-sync (git polling, adaptive intervals)
  traces/             Runtime trace ingestion
  ui/                 Local HTTP server + verified external 3D-UI asset pack
  foundation/         Platform abstractions (threads, filesystem, logging, memory)
internal/cbm/         Vendored tree-sitter grammars (162 languages) + AST extraction engine

セキュリティ

すべてのリリースは、公開前に多層パイプラインを通じて検証されます。

• VirusTotal — 8 つのリリース製品にわたる全 24 の実行可能候補（unstripped、debug-stripped、stripped）がスモーク/ソークテストの前にスキャンされます（クリーンであることが望ましく、SECURITY.md に記載されている単一の Microsoft !ml 許容のみが通過できます。決定的な結果を返したエンジンの数は証拠として記録されますが、これは VirusTotal のフリートの可用性であり、合格条件ではありません）。選択された実行可能ファイルは SHA-256 を変更せずにパッケージ化され、リリースノートには出荷される正確なバイト列に対する判定結果がリンクされ、候補ごとの完全な証拠は選択を監査する誰でも利用できるよう TSV としてリリースとともに公開されます。出荷されるコンテナから抽出されたすべての個別オブジェクト — install.sh、install.ps1、LICENSE、THIRD_PARTY_NOTICES.md、MCPB の manifest.json、および展開された UI アセット — も同様にスキャンされるため、実行可能ファイルだけでなく、公開される表面全体がカバーされます。
• SLSA レベル 3 — 信頼された GitHub Actions ビルドワークフローによって生成された暗号化されたビルド来歴。gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml で検証できます。
• Sigstore cosign — すべての成果物に対するキーレス署名。バンドルはすべてのリリースに含まれています
• SHA-256 チェックサム — checksums.txt がすべてのリリースとともに公開され、両方のインストールスクリプトによって展開前に検証されます
• CodeQL SAST — 未解決のアラートが残っている場合、リリースパイプラインをブロックします
• 言語ランタイムへの依存チェーンなし — ライブラリはコンパイル時にベンダリングされ、リリースが所有する小さなランタイムアセットはチェックサム検証され、コンテンツアドレス指定されます

v0.7.0 VirusTotal スキャン

すべてのリリースのスキャンリンクは、GitHub のリリースノートにも自動的に含まれます。

ライセンス

MIT