codebase-memory-mcp

Pure C の単一静的バイナリが tree-sitter と Hybrid LSP で知識グラフを構築し、MCP 経由で AI コーディングエージェントに構造クエリを返す。内蔵 LLM は持たず、接続先エージェントが自然言語→グラフクエリの翻訳を担う。

1 — 概要

Positioning

DeusData/codebase-memory-mcp は、リポジトリをフルインデックスして関数・クラス・呼び出しチェーン・HTTP ルート・クロスサービスリンクを永続グラフ化する MCP サーバー。平均規模のリポジトリはミリ秒、Linux カーネル（28M LOC / 75K ファイル）でも約 3 分でインデックス完了。

158languages

14MCP tools

11agents

<1msCypher query

ファイル逐次 grep/read と比べ、5 本の構造クエリで約 3,400 トークン（対 ~412,000 トークン、約 99.2% 削減）。処理は 100% ローカルで、コードは外部送信されない。

Source: README.md, server.json (v0.8.1)

Design stance

LLM を内蔵しない structural analysis backend。MCP クライアント（Claude Code 等）が既に持つ推論で NL→グラフクエリを行い、サーバーは SQLite 上のグラフを高速に返すだけ。

チーム共有: .codebase-memory/graph.db.zst をコミットすれば、clone 後の初回起動でアーティファクトを展開し増分インデックスのみ実行。merge=ours の .gitattributes でバイナリ競合を回避。

2 — 処理の流れ

Agent ↔ MCP ↔ Graph

sequenceDiagram
  participant U as User
  participant A as MCP Client
(Claude Code 等)
  participant C as codebase-memory-mcp
  participant G as SQLite Graph

  U->>A: "ProcessOrder を呼ぶ関数は?"
  A->>C: trace_path(function_name="ProcessOrder", direction="inbound")
  C->>G: BFS / graph query
  G-->>C: structured call chain
  C-->>A: JSON results
  A-->>U: 自然言語で説明

エージェントは get_graph_schema でスキーマを把握してから search_graph / query_graph / trace_path を組み合わせる。コード断片が必要なら get_code_snippet、全体像は get_architecture。

3 — アーキテクチャ

Source layout

src/ — 主要モジュール

main.c          MCP stdio + CLI + install/update/config
mcp/            14 tools, JSON-RPC 2.0, session detection
cli/            11 agents 向け install/uninstall
store/          SQLite nodes/edges, traversal, Louvain
pipeline/       多段インデックス (structure → calls → HTTP …)
cypher/         openCypher 読み取りサブセット
discover/       .gitignore / .cbmignore / symlink 処理
watcher/        git ポーリングによる auto-sync
traces/         ランタイムトレース取り込み
ui/             3D グラフ UI (localhost:9749)
foundation/     threads, fs, logging, memory
internal/cbm/   158 tree-sitter grammars + AST 抽出

Two-layer parsing

全 158 言語に tree-sitter パスを適用し、9 言語では Hybrid LSP で型解決を追加する二層構成。

Layer 2 — Hybrid LSP（型 aware）

Python, TS/JS/JSX/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust。import グラフ + クロスファイル定義レジストリで CALLS / USAGE エッジを精緻化。別プロセスの language server は不要。

Layer 1 — tree-sitter（構文）

158 言語すべて。定義・呼び出し・import を高速抽出。Hybrid LSP 未対応言語はテキスト解決にフォールバック。

Persistence — SQLite @ ~/.cache/codebase-memory-mcp/

WAL モード、RAM-first インデックス後にダンプ。LZ4 圧縮読み込み → in-memory SQLite → 終了時 1 回書き出し。

flowchart TB
  subgraph ingest [Indexing]
    D[discover files] --> P[pipeline passes]
    P --> TS[tree-sitter AST]
    TS --> LSP[Hybrid LSP refine]
    LSP --> S[(SQLite store)]
  end
  subgraph serve [Query]
    S --> MCP[MCP tools]
    MCP --> CY[cypher executor]
    MCP --> FTS[FTS5 / BM25]
    MCP --> SEM[semantic_query embeddings]
  end

4 — インデックスパイプライン

Multi-pass indexing

Structure

Project / Package / Folder / File 階層、manifest スキャンで bare import を解決

Definitions

Class, Function, Method, Route, Resource 等のノード生成

Calls & links

CALLS, IMPORTS, HTTP_CALLS, EMITS/LISTENS_ON, DATA_FLOWS, SIMILAR_TO

Sync

watcher が git 変更を検知し増分再インデックス。graph.db.zst を fast tier で更新可

ベンチマーク（Apple M3 Pro）

操作	時間	備考
Linux kernel フルインデックス	3 min	28M LOC → 4.81M nodes / 7.72M edges
Django フルインデックス	~6s	49K nodes / 196K edges
Cypher クエリ	<1ms	関係トラバーサル
trace_path (depth=5)	<10ms	BFS
dead code 検出	~150ms	degree フィルタ付き全走査

5 — MCP ツール

14 tools

カテゴリ	ツール	用途
Indexing	`index_repository`	リポジトリをグラフ化。以降 auto-sync
	`list_projects`	インデックス済みプロジェクト一覧
	`delete_project`	プロジェクトとグラフデータ削除
	`index_status`	インデックス状態確認
Query	`search_graph`	ラベル・正規表現名・degree フィルタ
	`trace_path`	呼び出しチェーン BFS（depth 1–5）
	`detect_changes`	git diff → 影響シンボル + リスク分類
	`query_graph`	openCypher 読み取りサブセット
	`get_graph_schema`	ノード/エッジ定義（最初に実行推奨）
	`get_code_snippet`	qualified name でソース取得
	`get_architecture`	言語・パッケージ・ルート・ホットスポット概要
	`search_code`	インデックス済みファイル内 grep
	`manage_adr`	Architecture Decision Records CRUD
	`ingest_traces`	ランタイムトレースで HTTP_CALLS 検証

検索系の拡張として semantic_query（Nomic nomic-embed-code 内蔵、API キー不要）と BM25 FTS5（camelCase/snake_case 対応 tokenizer）も README に記載。CLI からは codebase-memory-mcp cli <tool> '{...}' で同一 API を呼べる。

Cypher 例

MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name
WHERE NOT EXISTS { (f)<-[:CALLS]-() }  -- dead code 検出

6 — セットアップ

Quick start

Install

curl install.sh または release バイナリ + install.sh/ps1

Restart agent

MCP 設定・skills・hooks が自動配置される

Index

「Index this project」または index_repository

Query

trace / search / architecture / Cypher

macOS / Linux — one-line

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
# UI 付き: bash -s -- --ui

主要オプション

項目	値 / コマンド	説明
Graph UI	`--ui=true --port=9749`	ui バリアントのみ。MCP と並行起動
Auto-index	`config set auto_index true`	セッション開始時に自動インデックス
Cache dir	`CBM_CACHE_DIR`	デフォルト `~/.cache/codebase-memory-mcp`
Update	`codebase-memory-mcp update`	起動時にも新版通知
Uninstall	`codebase-memory-mcp uninstall`	エージェント設定のみ削除（DB は残る）

配布: GitHub Releases, npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install。SLSA 3 + Sigstore cosign + VirusTotal スキャン付き。

7 — エージェント連携

install auto-detect

install はインストール済みエージェントを検出し、MCP エントリ・instruction ファイル・hooks を配置する。Claude Code では PreToolUse が Grep/Glob を傍受し、インデックス済みシンボルを search_graph 結果として additionalContext に注入（非ブロッキング、exit 0）。Codex / Gemini CLI / Antigravity は SessionStart リマインダー。

エージェント	MCP 設定	Instructions	Hooks
Claude Code	`.claude/.mcp.json`	4 Skills	PreToolUse (Grep/Glob augment)
Codex CLI	`.codex/config.toml`	`.codex/AGENTS.md`	SessionStart
Gemini CLI	`.gemini/settings.json`	`.gemini/GEMINI.md`	BeforeTool + SessionStart
Zed / OpenCode / VS Code / …	各 settings	—	—

手動 MCP 設定: ~/.claude/.mcp.json またはプロジェクト .mcp.json にバイナリへの絶対パスを指定。/mcp で 14 tools が見えれば成功。

8 — 参考リンク

Source references

GitHub: DeusData/codebase-memory-mcp — ソース・リリース・CI
Project site — 公式ドキュメント
arXiv:2603.27277 — Tree-Sitter 知識グラフ設計とベンチマーク
README.md — Quick Start, MCP Tools, Hybrid LSP, Performance
server.json — MCP レジストリメタデータ (npm / PyPI)
docs/BENCHMARK.md — 詳細ベンチマーク
SECURITY.md — 脆弱性報告手順