實戰手冊 · Field Manual 2026 夏季號
github.com/DeusData/codebase-memory-mcp · 34,433 ★
c
GitHub Field Manual · Code Intelligence / MCP

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

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

34.4k
GitHub Stars
158
tree-sitter 語言
15
MCP 工具
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。

程式碼知識圖譜工作流
Discover→ Index→ Search→ Trace→ Verify→ Assess→ Persist
「codebase-memory-mcp is a structural analysis backend — it builds and queries the knowledge graph.」
— DeusData/codebase-memory-mcp README
02
macOS / Linux / Windows

安裝執行檔與
Agent 設定

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

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 調整政策。

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
啟用驗證:重新啟動 coding agent，再要求「Index this project」。通過條件是 MCP client 顯示 codebase-memory-mcp，並可列出 15 個工具。
03
15 個 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_architecture get_code_snippet
誰呼叫指定函式 search_graph trace_path
目前 diff 可能影響哪些符號 detect_changes trace_path
查詢結果能否支持完整或否定性結論 index_status check_index_coverage
04
官方查詢原則

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

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

TIP 01

先列出已索引專案

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

來源 · 官方 MCP 指令
TIP 02

以架構總覽建立方向

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

來源 · 官方 README · MCP Tools
TIP 03

先找 qualified name

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

來源 · 官方工具 schema
TIP 04

呼叫關係交給 trace_path

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

來源 · 官方工具 schema
TIP 05

多跳關係才用 query_graph

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

來源 · 官方 README · CLI Mode
TIP 06

完整結論需要 coverage

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

來源 · 官方 Multi-Agent Support
TIP 07

否定性 claim 擴大檢查範圍

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

來源 · 官方 Multi-Agent Support
TIP 08

以 .cbmignore 控制專案範圍

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

來源 · docs/cbmignore.md
TIP 09

CLI 輸出保持可串流

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

來源 · 官方 README · CLI Mode
TIP 10

版本更新後重啟 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 會影響哪些路徑。
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] Agent › 架構總覽已建立；下一步只在相關 package 內尋找符號。
[search_graph · name_pattern: .*ProcessOrder.* · label: Function] 找到候選後保留 qualified_name、file path 與 pagination 狀態。
[trace_path · function_name: exact qualified name · direction: inbound] [get_code_snippet · exact qualified name]
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]
RESULT: caller 與 impact claim 均附 project、generation、qualified name、 file path、pagination 與 coverage 限制。
無法由索引證明的完整性主張已改為限制說明。
「Use graph tools first.」
— DeusData/codebase-memory-mcp MCP 指令

證據鏈的必要欄位

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

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

06
權限與限制

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

  • 安裝程式會修改 Agent 設定。官方 SECURITY.md 明列此工具會讀取 codebase、寫入 coding-agent 設定並啟動背景程序；執行前先檢查 install script 與變更範圍。
  • 本機處理仍包含更新檢查。索引、query 與 semantic search 在本機執行；server 初始化後會對 GitHub Releases API 發出 bounded update check。
  • clean coverage 不等於完整。check_index_coverage 只能回報已記錄缺口；否定性或 exhaustive claim 仍需檢查 scope、pagination 與原始檔案。
  • 忽略規則會改變答案範圍。hardcoded patterns、.gitignore、.cbmignore 與 symlink skip 都可能讓檔案不進入圖譜。
  • Team-shared graph artifact 是選用項目。.codebase-memory/graph.db.zst 可提交到 repository；不希望共享時將 .codebase-memory/ 加入 .gitignore。
  • 所有作用中的 CBM process 必須版本一致。不同 executable build、coordination ABI 或 cache root 會被 admission barrier 拒絕。
  • 圖譜寫入與刪除需要授權。manage_adr、ingest_traces 與 delete_project 會改變持久化資料；唯讀分析不應自行呼叫。
  • Uninstall 會列出既有索引。codebase-memory-mcp uninstall 移除 owned config、skills、hooks 與 binary；圖譜索引只在確認後刪除。
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