使用手冊

GitHub Field Manual · Code Intelligence / MCP

把程式碼庫, 轉成可查詢的知識圖譜

DeusData/codebase-memory-mcp 繁體中文實戰手冊，涵蓋安裝、15 個 MCP 工具、索引查詢流程、權限邊界與進階設定。

codebase-memory-mcp 以 tree-sitter 與 Hybrid LSP 建立持久化程式碼知識圖譜，供 AI coding agent 查詢符號、呼叫鏈、架構與變更影響。專案提供單一靜態執行檔、15 個 MCP 工具，以及 macOS、Linux、Windows 安裝包。

deusdata/codebase-memory-mcp
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
9 分
更新日期
開啟原始報告
GitHub Stars
34.4k
tree-sitter 語言
158
MCP 工具
15
開源授權
MIT
本頁章節

01工具定位

程式碼結構的持久化查詢層

codebase-memory-mcp 是供 MCP client 使用的結構分析後端。它解析 repository，將函式、類別、匯入、呼叫鏈、HTTP route 與跨服務關聯寫入 SQLite 知識圖譜。

全部 158 種語言先經 tree-sitter 產生語法結構；Python、TypeScript／JavaScript、PHP、C#、Go、C／C++、Java、Kotlin、Rust 與 Perl 再由 Hybrid LSP 補強型別解析。圖譜保存在 ~/.cache/codebase-memory-mcp/，可跨 session 重用。

這個 server 不內建 LLM。Agent 負責把自然語言需求轉成 MCP 工具呼叫；server 負責索引、搜尋、圖遍歷、影響分析與 Architecture Decision Record。

  1. Discover

  2. Index

  3. Search

  4. Trace

  5. Verify

  6. Assess

  7. Persist

「codebase-memory-mcp is a structural analysis backend — it builds and queries the knowledge graph.」

— DeusData/codebase-memory-mcp README

02macOS / Linux / Windows

安裝執行檔與 Agent 設定

macOS 或 Linux 可使用官方安裝指令。需要 3D 圖譜介面時加入 --ui；預設安裝 headless server。

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

# 選用：包含 3D graph UI
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Windows PowerShell 安裝

先下載並檢查官方 script，再解除 Mark-of-the-Web 限制並執行。遇到 execution policy 錯誤時，只在目前 Process scope 調整政策。

bash
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
notepad install.ps1
Unblock-File .\install.ps1
.\install.ps1

0315 個 MCP 工具

從索引建立到變更影響分析

工具分成索引管理、結構搜尋、來源查證、架構分析與可選的圖譜寫入。先用 list_projects 確認專案，再依問題選擇窄範圍查詢；刪除索引或寫入 ADR 前先取得明確授權。

Index · 01

index_repository

Repository 索引

解析指定 repository，建立或更新持久化知識圖譜。

Index · 02

list_projects

索引目錄

列出已索引專案，以及各專案的 node 與 edge 統計。

Index · 03

index_status

索引狀態

檢查索引進度、專案健康狀態與未納入範圍。

Index · 04

check_index_coverage

證據覆蓋率

檢查引用路徑與範圍是否存在解析缺口、排除或跳過項目。

Search · 05

search_graph

結構與語意搜尋

依 label、名稱 regex、檔案範圍、degree 或 semantic query 搜尋節點。

Trace · 06

trace_path

呼叫鏈遍歷

以 BFS 查詢函式的 callers、callees 與雙向呼叫路徑。

Verify · 07

get_code_snippet

精確來源

依 qualified name 讀取函式、類別或符號的來源片段。

Explore · 08

get_graph_schema

圖譜結構

回傳 node、edge、relationship pattern 與 label property 定義。

Explore · 09

get_architecture

架構總覽

彙整語言、packages、entry points、routes、hotspots、layers 與 clusters。

Search · 10

search_code

圖譜增強文字搜尋

在已索引檔案內執行 grep-like 搜尋，並保留符號關聯。

Query · 11

query_graph

Cypher-like 查詢

執行 read-only openCypher subset，用於多跳 relationship pattern。

Impact · 12

detect_changes

Diff 影響分析

將 git diff 對應到受影響符號、blast radius 與風險分類。

Persist · 13

manage_adr

架構決策紀錄

建立、更新與讀取 Architecture Decision Record。

Runtime · 14

ingest_traces

執行期追蹤

匯入 runtime trace，以實際資料補強 HTTP_CALLS 等關聯。

Index · 15

delete_project

索引刪除

移除指定專案與其全部圖譜資料；執行前確認 project 名稱。

依問題類型選工具

問題起始工具驗證工具
這個 repository 的主要模組與入口在哪裡get_architectureget_code_snippet
誰呼叫指定函式search_graphtrace_path
目前 diff 可能影響哪些符號detect_changestrace_path
查詢結果能否支持完整或否定性結論index_statuscheck_index_coverage

04官方查詢原則

先確認索引, 再擴大結論範圍

下列操作原則整理自官方 README、工具 schema 與 SECURITY.md。每項結論都要保留 project、index generation、pagination 與 coverage 邊界。

先列出已索引專案

第一次使用先呼叫 list_projects。只有目標 repository 不在清單內時才執行 index_repository。

來源 · 官方 MCP 指令

以架構總覽建立方向

廣泛問題先使用 get_architecture；後續再以符號搜尋與來源片段驗證具體 claim。

來源 · 官方 README · MCP Tools

先找 qualified name

get_code_snippet 與 trace_path 前先用 search_graph 找到精確符號名稱。

來源 · 官方工具 schema

呼叫關係交給 trace_path

search_graph 的 degree 是圖譜 edge 數量；caller 與 callee 關係改用 trace_path。

來源 · 官方工具 schema

多跳關係才用 query_graph

一般探索先使用 search_graph 與 pagination；需要多跳 pattern 時再使用 read-only Cypher subset。

來源 · 官方 README · CLI Mode

完整結論需要 coverage

對每個引用路徑呼叫 check_index_coverage。clean result 只表示沒有已記錄缺口，不代表內容完整。

來源 · 官方 Multi-Agent Support

否定性 claim 擴大檢查範圍

「沒有 caller」或「沒有受影響符號」需要檢查相關 scope、pagination 與 skipped files。

來源 · 官方 Multi-Agent Support

以 .cbmignore 控制專案範圍

使用 gitignore syntax 排除 generated、fixtures 或大型資料；hardcoded ignore 與 repository 的 .gitignore 仍會先套用。

來源 · docs/cbmignore.md

CLI 輸出保持可串流

--progress 將進度寫到 stderr；stdout 保留工具結果。需要完整 MCP envelope 時加入 --json。

來源 · 官方 README · CLI Mode

版本更新後重啟 Agent

codebase-memory-mcp update 會切換 account-wide binary；成功後重新啟動已開啟的 coding-agent sessions。

來源 · 官方 README · Coordination Daemon

05結構證據工作流

從 repository 索引到變更影響結論

下列示例示範一個不依賴特定 repository 統計值的查詢流程。Agent 先選定索引，再以 architecture、search、trace、snippet 與 coverage 組成可查證的答案。

~/projects/order-service · MCP client · codebase-memory-mcp


$ You ›
  找出 ProcessOrder 的 callers，並說明目前 diff 會影響哪些路徑。


claude: Agent ›
  先確認可用的 project 與索引狀態，再查詢符號與呼叫鏈。


# [list_projects]
# [selects exact project name returned by the server]
# [index_status · records current generation and coverage summary]


# [get_architecture · aspects: entry points, packages, routes]
claude: Agent ›
  架構總覽已建立；下一步只在相關 package 內尋找符號。


# [search_graph · name_pattern: .*ProcessOrder.* · label: Function]
  hl: 找到候選後保留 qualified_name、file path 與 pagination 狀態。


# [trace_path · function_name: exact qualified name · direction: inbound]
# [get_code_snippet · exact qualified name]


claude: Agent ›
  呼叫鏈已取得；現在將 working tree diff 映射到符號與 blast radius。


# [detect_changes · base_branch: main · direction: both]
# [trace_path · for each directly affected symbol]


  [evidence set]
    1. 精確符號名稱與來源檔
    2. inbound callers 與查詢 depth
    3. diff 直接影響符號
    4. 受影響的下游路徑
    5. 每個引用路徑的 index coverage


# [check_index_coverage · all cited paths and relevant scope]
# [reads flagged or skipped ranges directly when present]


  ok: RESULT:
    ok: caller 與 impact claim 均附 project、generation、qualified name、
    ok: file path、pagination 與 coverage 限制。


claude: 無法由索引證明的完整性主張已改為限制說明。

「Use graph tools first.」

— DeusData/codebase-memory-mcp MCP 指令

證據鏈的必要欄位

結果必須包含 project、index generation、qualified symbol、檔案路徑與查詢方向。使用 pagination 的工具另記錄 has_more、limit 與 offset。

check_index_coverage 回報缺口時，直接讀取相關檔案範圍。索引外的證據不能以圖譜查詢結果替代。

06權限與限制

索引覆蓋率與本機存取邊界

07進階路徑

從單一 repository 到跨服務圖譜

完成單一 repository 的索引與查詢後，再啟用 auto-index、跨 repository 關聯、runtime trace 或共享圖譜 artifact。每次擴大範圍都要重新記錄 project、generation 與 coverage。

進階玩法地圖

**1. 啟用自動索引。**執行 codebase-memory-mcp config set auto_index true。需要限制 watcher 時另設 auto_watch false。

**2. 調整自訂副檔名。**在 global 或 per-project config 將非標準副檔名映射到既有 parser，再重新建立索引。

**3. 建立跨 repository 關聯。**將多個服務索引到同一 store，利用 CROSS_* edge 與 architecture summary 查詢跨服務 route 與 dependency。

**4. 匯入 runtime trace。**以 ingest_traces 補強靜態圖譜中的 HTTP_CALLS 關聯；執行前確認資料來源與持久化範圍。

**5. 分享壓縮圖譜。**需要團隊共用時提交 .codebase-memory/graph.db.zst；clone 後由 incremental indexing 補上本機差異。

最該讀的三份延伸閱讀

① README.md：安裝、15 個工具、CLI 與 Multi-Agent Support。 ② docs/CONFIGURATION.md：runtime settings、環境變數與 extension mapping。 ③ SECURITY.md：本機處理、更新檢查、binary verification 與揭露流程。

「One graph query replaces dozens of grep/read cycles.」

— DeusData/codebase-memory-mcp README