---
slug: code-intelligence-graph-tools-comparison
title: codebase-memory-mcp：Agent 怎麼調用程式碼記憶？附 GitNexus 與 CodeGraph 對照
status: published
excerpt: 比較 codebase-memory-mcp、GitNexus 與 CodeGraph 如何被 coding agent 調用：查什麼、帶回什麼、漏什麼，以及重要性與遺漏率該怎麼分開量。
category: AI
tags: [codebase-memory-mcp, GitNexus, CodeGraph, MCP, coding-agent, code-intelligence]
author: Seer
author_role: Author
read_time: 16 min
cover: "/static/code-intelligence-graph-tools-comparison-cover.png"
closing_note: Token 省下來，不代表證據到齊。真正要量的，是漏在哪一層。
published_at: "2026-09-28T13:20:00Z"
updated_at: "2026-09-28T13:20:00Z"
---

`codebase-memory-mcp`、[GitNexus](https://github.com/abhigyanpatwari/GitNexus) 與 [CodeGraph](https://github.com/colbymchenry/codegraph) 的共通點，都在於先將程式碼庫整理為可供本機查詢的知識層，再讓 coding agent 透過 MCP 取回所需的上下文。選型時真正要問的是：當 agent 拋出一個問題時，工具究竟如何鎖定切入點？如何循線展開呼叫鏈？哪些程式碼會被送進 context，又有多少資訊在檢索途中被悄悄裁切？[1][2][3]

本文所指的「程式碼記憶」，特指經過結構化索引後的 codebase memory，不與對話歷程或模型本身的記憶混為一談。全文將聚焦於四個核心面向：**調用路徑、重要性排序、召回遺漏機制、評估方法**。底層架構與硬體僅作選型評估所需的扼要梳理；凡官方未明確揭露之處均直接標示為資訊缺口，避免將單純的 token 節省量或單一基準測試誤讀為精確的召回率。

本文梳理基準為 2026-09-28 時點各專案官方 repository 的 `main` 分支、README、原始碼、架構說明與評測文件。由於本次未進行本機安裝與實機運行，文中所引數據皆為專案官方或 repo 內載明之數據，非筆者獨立實測。鑑於 `main` 分支持續變動，正式導入前仍建議鎖定特定 commit 或 release 版本。

## 快速跳轉

- [先看三個工具的記憶調用定位](#先看三個工具的記憶調用定位)
- [codebase-memory-mcp](#1-codebase-memory-mcp工具介面最完整但考驗-agent-的調用策略)
- [GitNexus](#2-gitnexus將檢索結果收斂為執行流程無縫銜接影響分析與工作流)
- [CodeGraph](#3-codegraph將召回源碼分配與缺口偵測收斂至單一-explore-工具)
- [遺漏率判定](#6-遺漏率的判定標準釐清資訊究竟在哪個環節遺失)
- [重要性評估](#7-如何定義與評估程式碼的重要性)
- [選型](#9-選型評估依據團隊所需的記憶調用模式進行決策)

## 先看三個工具的「記憶調用」定位

| 工具 | Agent 主要調用方式 | 重要性評估依據 | 主要遺漏／失真訊號 | 適用場景 |
|---|---|---|---|---|
| **codebase-memory-mcp** | 組合多個專用 MCP tool：`search_graph` → `trace_path`／`query_graph` → `get_code_snippet` | 結合 BM25、正規表達式、內建 code embedding、11 種特徵評分與圖譜關係 | `index_coverage`、分頁限制、row／byte／token 門檻；clean coverage 不等於完全無缺漏 | 多語言支援、跨服務架構、IaC、精確呼叫鏈追蹤 |
| **GitNexus** | `query` 定位 execution process → `context` 檢視 symbol 上下游 → `impact`／`trace` 驗證影響範圍 | BM25 與語意檢索之 RRF 融合、流程關聯度、圖譜邊、信心度與風險評分 | `maxTokens`、分頁截斷、索引過期、truncated lower bound、PDG 降級／未知狀態 | 多 repo 管理、執行流程理解、改動波及範圍分析、plan／work／review 流程 |
| **CodeGraph** | 以單一 `codegraph_explore` 為主：自然語言 → 提取 seed → 圖譜展開 → 源碼預算分配 | 精確符號比對、全文檢索（FTS）、路徑與共現加權、RWR 圖譜權重、節點類型加權、源碼預算 | recall miss、allocation miss、明確 gap pointer、過期缺漏、context 佔用率 | 日常功能開發、快速擷取可直接閱讀的調用流程 |

這三款工具都先解析 AST、抽取 symbol、建立關係邊、全文索引或向量，再由 MCP 工具依查詢動態組裝出有限的 context。這也意味著「召回失敗」至少存在四個不同層次：索引階段根本未收錄、找到入口但關聯邊缺失、鎖定正確檔案卻未獲配足夠源碼，或是 agent 取得上下文後未能正確理解與引用。以下將逐層剖析。

## 1. codebase-memory-mcp：工具介面最完整，但考驗 agent 的調用策略

[codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)（以下簡稱 CBM）採用原生 C 開發的結構分析後端，本體不內建推理模型。它整合 Tree-sitter、Hybrid LSP、SQLite／FTS5、圖譜查詢與本地 code embedding，構成純粹的 MCP 資料提供層，交由上層 agent 自行決策何時該搜尋、追蹤、圖譜查詢或讀取原始碼。[1][9]

### 實際調用路徑：先定位，再展開，後取證

CBM 是一組可組合的 MCP 工具。其典型調用流程如下：

```text
自然語言問題
  → search_graph：透過 BM25／regex／semantic_query 定位 symbol 或檔案
  → trace_path：沿著 caller、callee、資料流或服務邊界追蹤
  → query_graph：遇多跳、聚合或跨服務條件時深入查詢圖譜
  → get_code_snippet／get_file_outline：精確取得所需片段或結構
  → agent 彙整推論，必要時以 check_index_coverage 驗證資訊涵蓋範圍
```

`search_graph` 支援 BM25、正規表達式、name／qualified-name filter、degree filter 以及 `semantic_query`。依其 README 說明，語意查詢結合了 11 種訊號進行混合排序，涵蓋 TF-IDF、API／型別／裝飾器簽名、AST 特徵、資料流向、模組鄰近度與圖譜擴散分析。這些機制主要用於篩選出優質的「候選入口」，不能直接等同最終解答的正確性。[9][14]

在資料回傳設計上，CBM 設有明確的分頁與輸出上限：`trace_path` 預設深度為 3、每頁 100 筆，上限 5,000 筆；`query_graph` 預設呈現 200 筆，並提供總數、截斷標記與 cursor；`get_code_snippet` 則可指定 `auto`、`outline` 或 `full` 模式，並限制讀取行數。一旦資料量超出限制，agent 必須主動依循 cursor 分頁或收窄條件，否則就會產生上下文遺失。[14]

### CBM 如何判定「重要性」？

CBM 的重要性評估採取動態、查詢導向的組合邏輯，沒有為每個 symbol 賦予固定的全域分數：

- 符號名稱、完整路徑名稱、docstring 與程式碼詞彙是否符合提問。
- 語意 embedding 能否找出用詞不同但概念相近的程式碼節點。
- 節點標籤、caller／callee 連接數、關係型態與圖譜路徑是否吻合查詢脈絡。
- `trace_path` 中的跳數、邊類型、資料流或跨服務鏈路是否能串起因果關係。
- 上層 agent 是否決定調用下一個工具，直接決定了候選節點能否化為具體的程式碼證據。

因此，CBM 相當適合「以語意搜尋切入、再以結構查詢嚴格驗證」的思維；若僅依賴語意搜尋的前幾筆回傳，並無法保證完整召回。

### CBM 的遺漏率該如何看待？

官方 README 指出在 31 個真實 repo 上取得 83% answer quality、減少 10 倍 token 消耗與 2.1 倍 tool call 的成果，但這些數據屬於綜合指標，不能直接當成標準定義下的 `Recall@K` 或符號遺漏率。[9] 官方的評測文件也將答案品質、延遲與穩定度、token 與工具調用節省量拆開評估，要求在固定 commit SHA、固定題庫、模型、提示詞、context 上限與預算下，以 source evidence 為基準給予 PASS／PARTIAL／FAIL 判定。[13]

CBM 亦內建 `index_coverage` 與 `check_index_coverage` 等診斷工具，可標出解析不全、解析失敗、忽略或排除的檔案清單，並在回傳結果中附註覆蓋缺口。但官方也強調：clean coverage 僅代表「系統未記錄到異常」，不能直接作為程式碼庫 100% 完整被理解的證明。[1][14]

總結來說，CBM 具備完善的「防遺漏回報機制」，但尚無單一官方數據能直接斷言「遺漏率是多少」。嚴謹的遺漏率必須在固定測試集下，針對應出現的符號、關係邊、檔案與關鍵區間建立標準答案，再比對 top-K、分頁完整性與最終進入 context 的證據比例。

**適用對象：**專案涉及多種程式語言、跨服務或 IaC 拓撲，需要靈活多元的查詢能力，且能引導 agent 確實執行「搜尋 → 追蹤 → 取證 → 覆蓋驗證」嚴謹流程的團隊。

## 2. GitNexus：將檢索結果收斂為執行流程，無縫銜接影響分析與工作流

[GitNexus](https://github.com/abhigyanpatwari/GitNexus) 的索引管線涵蓋 Tree-sitter 語法解析、跨檔案符號關聯、社群分群（community clustering）與執行流程追蹤（process tracing），並建立 BM25 與語意混合檢索。索引資料儲存於 `.gitnexus/`，透過 registry 機制支援多 repo，可同時供 MCP、CLI、Web UI 及 eval-server 讀取。[2][5][16]

### 實際調用路徑：從概念定位流程，再循線取得證據

GitNexus 的官方 tool contract 呈現了標準的階層式調用邏輯：

```text
query(search_query / goal / task_context)
  → 取得排序後的 processes 與 process_symbols
  → context(uid, include_content=true, chain_depth=N)
  → impact 或 trace：驗證 caller、callee、波及範圍（blast radius）與調用路徑
  → plan / work / review：以同一份圖譜證據推進實作任務
```

`query` 透過 Reciprocal Rank Fusion（RRF）融合 BM25 與語意檢索結果，並將命中項目依 execution process 進行分組；回傳結構整合了 `processes`、`process_symbols` 與定義內容，且 `task_context` 與 `goal` 都會納入排序加權。隨後，`context` 工具可針對特定符號展開其 caller、callee、分類引用與流程歸屬，並可選擇性包含源碼與最多三層的調用鏈。[16][17]

這種設計的優勢在於 agent 不必自行在多筆零散搜尋結果中拼湊執行邏輯；相對的限制則是檢索高度依賴初期的流程判定。一旦查詢未能命中正確的 execution flow，後續即使完整展開 `context`，也只是在錯誤的起點上做深入推論。

### GitNexus 如何判定「重要性」？

GitNexus 的重要性評估主要分為三個層次：

- **搜尋關聯度：**整合 BM25 與語意排序，透過 RRF 機制加權；同時被兩者命中的符號能獲得更高的融合排序分數。[17]
- **流程重要性：**將同一批命中的 symbol 組織為 execution process，並依流程重要性排定優先級；藉由入口、路由與上下游調用鏈，讓 agent 獲取具脈絡的執行流程。
- **影響重要性：**`impact` 工具沿 CALLS、IMPORTS、EXTENDS、IMPLEMENTS 或 PDG 關係展開，回傳深度、流程歸屬、信心度與風險等級；並可利用 `minConfidence`、`relationTypes`、`maxDepth` 參數收斂分析範圍。[16][19]

這套機制把重要性定義為「與當前提問的高度關聯」加上「在整體執行流程與依賴圖譜中的定位」，沒有先給全專案一個固定靜態排名。

### GitNexus 如何標記不完整召回？

GitNexus 的特色在於將檢索邊界與不完整性直接內建於 API response 規範中：query、context 與 impact 皆受限於分頁大小與 output budget，並由 `maxTokens` 控制回傳長度。當跨 repo 分析遇到分支發散（fan-out）、連線逾時、部分同步或未完成同步時，系統會主動標示 `truncated`、`truncatedRepos`、`truncationReason` 與 `riskEpistemic: lower-bound`。這明確提醒 agent 目前看到的波及範圍僅為「下限」，絕不能將未列出的項目逕自視為不受影響。[16][18]

在程式相依圖（PDG）路徑上，系統亦不會以偽安全的方式隱藏缺漏。當 PDG 層不完整、callee 清單遭截斷、間接呼叫無法解析或中繼資料無法讀取時，狀態會直接被標記為 degraded 或 UNKNOWN，並同步提供證據層級與涵蓋範圍的補充說明。[19]

在 GitNexus 的 repo 中，內建的評測框架包含 `baseline`、`native`、`native_augment` 三種測試條件，負責記錄解析率（resolve rate）、成本、token 消耗、工具調用次數、GitNexus 使用率與 augment hit rate。這是一套評估 agent 是否有效利用記憶的具體方案，但本輪沒有執行它，也沒有可與另外兩個工具對齊的官方 recall 數字。[6]

**適用對象：**核心需求偏向「理解特定概念在整體執行流程中的運作方式」或「評估修改特定符號後的系統波及範圍」，且需要多 repo 管理、PDG 分析及完整 plan／work／review 流程串接的團隊；商業產品、團隊商用流程或 SaaS 使用前，PolyForm Noncommercial 授權仍需依具體用途交由法務審查。[2][4]

## 3. CodeGraph：將召回、源碼分配與缺口偵測收斂至單一 explore 工具

先前已另文說明 [CodeGraph 的本地知識圖譜定位](/codegraph-semantic-code-intelligence)。[CodeGraph](https://github.com/colbymchenry/codegraph) 的設計哲學認為：多數情況下，agent 需要一個能同時完成檢索、圖譜展開與源碼組裝的統一入口 `codegraph_explore`。雖然它仍保留 node、search、callers、callees、impact 等底層工具，但 explore 才是官方推薦的預設入口。[3][20][21]

### 實際調用路徑：混合起點 → 圖譜擴展 → 源碼預算分配

其核心函式 `findRelevantContext` 的處理邏輯大致如下：

```text
自然語言／符號查詢
  → 提取查詢符號（query symbol extraction）
  → 進行精確符號、名稱片段、CamelCase 詞綴與 FTS 全文比對
  → 合併結果，並結合路徑／多詞命中／共現關係（co-location）加權排序
  → 透過隨機漫步（RWR）等圖譜走訪演算法找出相關子圖
  → 產生調用路徑（call paths）、源碼區塊與 gap marker
  → 依據 output budget 將有限的字節預算分配給各檔案源碼
```

在預設配置下，context builder 僅選取最多 3 個搜尋入口、展開 1 層圖譜、納入 20 個節點與 5 個程式碼區塊（每區塊上限 1,500 字元）。系統預先鎖定 function、method、class、interface、route 等高資訊密度的節點類型；import 與 export 預設予以排除，因為這類語句通常僅能證明符號存在，無助於解釋實際運作邏輯。[21]

此外，CodeGraph 會從已取得的 `calls` 關聯中自動拼裝最多 6 跳的 call paths。若涉及 callback、事件機制、HTTP 客戶端、訊息佇列或框架 dispatch 等啟發式推導邊界，會在流程中特別標註註冊點；當靜態圖譜僅能解析至特定節點時，也會誠實標記截斷邊界，避免產生資訊完整的假象。[21]

### CodeGraph 如何判定「重要性」？

CodeGraph 的重要性計算採用多維度綜合評分：

- 精確命中與查詢中明確提及的識別字享有最高優先級。
- 多個查詢詞同時出現在同一 symbol 或路徑中，或單一檔案內命中多個關鍵字時，享有共現加權（co-location boost）。
- 圖譜關聯度參考隨機漫步（RWR）質量、調用／依賴關係與起點連通性；能串聯多個查詢起點的路徑獲得優先。
- 函式、方法、類別、路由等高資訊節點，其優先級顯著高於僅具宣告意義的 import／export。
- 自動產生的檔案、測試檔或低價值檔案會被降權；源碼分配階段進一步考量檔案大小、骨幹架構（spine）、群組關聯與關聯分數，防止單一肥大檔案佔滿整個上下文預算。[20][21][23]

此處揭示了一個工程實務上的重要觀點：**排序拔得頭籌，不保證能分到足夠的源碼容量。** CodeGraph 的設計文檔曾記錄過，某個強相關的重要檔案即便排名第一，也可能因檔案過大與容量規則而僅被截取部分內容。因此，系統將「關聯度排序」與「源碼預算分配」明確拆成兩個獨立且可被觀測的階段。[23]

### CodeGraph 如何定義遺漏？

CodeGraph 在 `explore sufficiency` 評測文件中提出了三個具實用價值的行為判定指標：

| Agent 後續行為 | 判定類別 | 代表意涵 |
|---|---|---|
| 再次呼叫 `explore` | insufficient | 首次召回資訊不足，agent 尚無法作答 |
| 讀取「已回傳」的檔案 | allocation miss | 檔案定位正確，但所分配的源碼行數或字節不足 |
| 讀取「未回傳」的檔案 | recall miss | 正確的目標檔案根本未被檢索系統找出 |
| 執行 Grep 或 Glob | weak recall signal | agent 仍需自行搜尋，代表目前 context 支援力薄弱 |
| 進行 Edit／build／給出解答 | sufficient | agent 判斷現有資訊已足夠繼續推進任務 |

這項指標衡量的是「回傳資訊是否足以促使 agent 停止漫無目的的搜尋」，並不代表最終答案必然正確，官方文檔也特別強調 sufficient 不等於 correctness。若要推導真實的遺漏率，依然需要將回答內容與人工或測試定義的 ground truth 嚴格對照。[24]

此外，CodeGraph 會在回傳資料中附帶檔案分數、RWR 權重、關鍵字命中數、配置與實際輸出字節數、截斷狀況，以及因 `max-files`、分數門檻、預算限制或讀取失敗而未渲染的原因。這讓工程團隊能精確定位遺漏究竟源自排序失誤（ranking miss）、預算截斷（budget miss）還是語法抽取失敗（extraction miss）。[23]

其 README 所列的 A/B 測試數據顯示平均減少 88% 工具調用、速度提升 53%、節省 62% token，但這些指標無法直接換算為檢索召回率；且殘留上下文（residual-context）基準測試亦顯示，高密度的單次回傳可能導致後續對話 context 顯著膨脹。CodeGraph 的實質價值在於建立了透明的診斷與預算分配架構；官方數據仍不足以當作跨工具可比的絕對召回數字。[3][7][24]

**適用對象：**偏好以極簡、單一入口快速取得程式碼流向與關鍵源碼，並重視源碼預算配置、召回診斷與 context 佔用率的開發團隊。

## 4. 底層架構解析：索引層、儲存檢索層、MCP 工具層與 Context 組裝層

儘管三個專案在實作細節上各有取捨，但整體架構皆可收斂為四層處理模型：

```text
專案原始碼 (Repo Source)
  → 語法解析器 / LSP / 符號關聯解析器 (Parser & Resolver)
  → 符號 + 關聯邊 + 全文索引 + 選擇性向量 (Index & Embedding Store)
  → 排序演算法 / 圖譜遍歷 / 源碼預算分配器 (Ranking & Allocator)
  → MCP 工具回傳 (Tool Response)
  → Agent 思考上下文與後續工具決策 (Context & Agent Action)
```

- **索引層：**透過 Tree-sitter 或原生 parser 將程式碼剖析為 symbol，再由 resolver 建立 calls、imports、繼承、路由、事件或跨服務關聯邊。在此階段遺漏的節點與邊，後續任何先進的排序演算法都無法補救。
- **儲存與搜尋層：**CBM 以 SQLite／FTS5 與本機 embedding 為主，其內部儲存結構同時維護 symbol、edge、源碼與查詢所需的輔助資料。[15] GitNexus 採用 LadybugDB、BM25、選用之 embedding 與 process 圖譜；CodeGraph 則基於 SQLite／FTS5 加 Rust／portable extraction。[2][3]
- **檢索與分配層：**將查詢轉化為候選節點後，綜合考量關聯分數、圖譜權重、呼叫鏈、執行流程與 token／byte 預算進行動態篩選。在此階段最常發生「精準鎖定目標檔案，卻因預算限制遭截斷」的 allocation loss。
- **MCP 與 Context 層：**將萃取後的資料格式化為 agent 易於理解的 tool response，並附帶 cursor、截斷標記、覆蓋率、信心度與 lower-bound 等狀態訊號。若回傳遭截斷卻缺乏明確提示，LLM 極易將局部片段誤判為系統全貌。

真正應檢驗的是：向量找到的種子節點能否被靜態圖譜交叉驗證？圖譜延伸出的關聯邊是否有具體的源碼作為佐證？以及這些關鍵佐證能否在 context 預算限制下完整送達模型？[1][2][3]

## 5. 硬體配置概算：依資源瓶頸評估，不將單一測試作為通用規格

這三款工具皆可本地部署，核心索引流程無須將原始碼外傳至第三方 API；但啟用 embedding、PDG 分析、Web UI、檔案監聽（watcher）或多 repo registry 時，資源負擔將有顯著差異。評估硬體需求時，建議著眼於四個維度：檔案量與語言多樣性、索引架構是否高度依賴記憶體（RAM-first）、是否啟用向量／PDG，以及需同時承載的 agent session 數量。[9][10][11]

在實務規劃上，一般開發機或標準規格的虛擬機器已足夠作為起點：中小型專案建議以 4 核心 CPU、8–16 GB RAM 與 SSD 作為基準配置；若是大型 monorepo、多 repo，或是需要平行執行向量建置與 PDG 分析，預留 16–32 GB 以上的記憶體能提供較充裕的緩衝空間。此處僅為架構規劃之估算，非各專案官方發布之最低系統需求；CodeGraph 的 regression audit 數字，亦僅適用於其測試所列之特定專案規模與 worker 條件。[12]

- **CPU：**AST 解析、符號關聯、全文檢索與圖譜建構均屬 CPU 密集作業；多核心效能直接決定初次冷啟動索引與增量更新的速度。
- **記憶體（RAM）：**CBM 採用的 RAM-first 索引架構對記憶體峰值較為敏感；GitNexus 需一併考量 V8 heap、worker 行程與 LadybugDB buffer pool 的消耗；CodeGraph 雖會依可用記憶體動態調節，但仍需持續監控 RSS 佔用。
- **磁碟 I/O：**固態硬碟（SSD）效能攸關索引讀寫、SQLite／LadybugDB 事務處理、embedding 快取、WAL 記錄與源碼快照；建議將原始碼庫、索引庫、暫存區與 WAL 的空間分開估算。
- **GPU：**核心語法解析、圖譜遍歷與 MCP 調用路徑均無須 GPU 參與；僅在選用本機 embedding 或額外神經網絡模型時，GPU 方能發揮加速向量建置的效益。
- **常駐服務架構：**單一 agent 獨立運作與多用戶共用常駐 daemon 的記憶體模型截然不同；壓測時應分別觀察冷啟動索引、熱查詢、背景檔案監聽與多連線併發四種狀態。若部署於離線（air-gapped）隔離環境，亦需確認已依規範關閉 CodeGraph 的匿名遙測。[8]

## 6. 遺漏率的判定標準：釐清資訊究竟在哪個環節遺失

目前尚無公開證據顯示三個專案曾在相同規格的程式碼庫、相同基準題庫、相同模型與相同 context budget 下，發布過具標準化定義的 `Recall@K` 對比數據。因此，本文不推估未經實測的百分比數據，改將可被客觀重現的評估維度拆解為五個關鍵指標：

1. **Index coverage（索引覆蓋率）：**標準答案（ground truth）中的符號與關係邊，實際進入索引結構的比例；解析失敗、規則忽略、主動排除與過期未更新應分項統計。
2. **Retrieval Recall@K（檢索召回率）：**解答提問所需的目標節點與邊，出現在檢索結果前 K 名的比例；不能僅以語意搜尋的排名概括整體召回能力。
3. **Context evidence coverage（上下文證據涵蓋率）：**在已成功檢索的目標項目中，帶有必要源碼範圍、完整定義與 caller／callee 關聯並成功進入 MCP 回傳的比例。
4. **Allocation loss（預算分配損失）：**目標檔案雖已命中，但解答關鍵的源碼區塊因 byte、行數或 token 預算限制而遭截斷或未被渲染的比例。
5. **Agent recovery loss（推論理解損失）：**檢索工具已完整提供必要證據，但 agent 仍推導出錯誤結論的比例；此屬模型理解與推論層問題，不應歸咎於檢索系統。

在單一問題的診斷上，遺漏成因可系統化歸納為：

```text
index miss       = 目標符號或邊根本未被建立索引
ranking miss     = 目標存在於索引中，但未擠入前 K 名候選
allocation miss  = 目標檔案已成功出現在結果中，但關鍵源碼因預算不足未進入 context
agent miss       = 所有必要上下文皆已送達，但 agent 仍未能給出正確解答
```

CodeGraph 的 `explore sufficiency` 架構提供了極具參考價值的行為訊號：主動讀取「未回傳」檔案代表 recall miss，手動讀取「已回傳」檔案代表 allocation miss，而重複呼叫 `explore` 則反映了 initial context insufficient。[24]

GitNexus 則透過 resolve rate、augment hit rate 以及 truncated、lower-bound、UNKNOWN 等欄位呈現分析完整度；CBM 則藉由 index coverage 覆蓋率檢查、cursor 分頁標記、截斷指示與 source-evidence 評分模型來把關資訊品質。[6][13][14]

## 7. 如何定義與評估程式碼的「重要性」？

在程式碼檢索領域，重要性既不能單純簡化為向量空間的餘弦相似度，也不宜僅看靜態的調用次數。建議將所有候選程式碼標記為三種語意層級：

- **Answer-critical（核心依據）：**缺少即無法作答的資訊，例如被查詢的函式本體、完整的「路由—服務—資料庫」調用鏈、關鍵 caller 或改動直接衝擊的相依邊。
- **Supporting（輔助佐證）：**能提升答案可信度，但缺失時仍可依賴其他線索推導的資訊，例如相關型別宣告、介面定義、設定檔來源、單元測試或框架註冊點。
- **Incidental（附帶雜訊）：**純粹因關鍵字重疊而命中、物理位置相鄰、自動生成的模板程式碼、重複的 import 宣告或低資訊量之中繼資料。

在排序演算法的設計上，可由以下五個維度進行綜合評量：

| 評估維度 | 核心檢驗問題 | 對應的分析證據 |
|---|---|---|
| 查詢關聯性 | 此程式碼片段是否真正切中提問核心？ | 精確符號比對、BM25 關鍵字、語意向量相似度、查詢詞命中數 |
| 結構關聯性 | 它是否構成了串聯起點與目標解答的結構橋樑？ | call、import、繼承、路由綁定與事件監聽等關聯邊 |
| 影響重要性 | 修改此符號將在系統中引發多大範圍的連鎖反應？ | 波及範圍（blast radius）、流程歸屬、圖譜結構質量（graph mass） |
| 執行路徑重要性 | 它是否位處實際的動態執行流程之中？ | caller→callee 調用鏈、動態 trace、隨機漫步路徑、動態註冊機制 |
| 證據資訊密度 | 此段源碼是否包含足以驗證推論的實質邏輯？ | 函式定義、關鍵實作本體、精確行號區間、測試與配置檔案 |

這五個維度有助於釐清三者的實作差異：CBM 傾向透過多訊號評分搭配彈性圖譜查詢；[9]

GitNexus 將重要性具體收斂為 execution process、影響範圍與信心度指標；[16]

CodeGraph 則將高價值節點過濾、RWR 漫步權重與源碼動態預算整合成單一 explore 輸出。三者都在處理「特定問題情境下的動態重要性」，沒有建立一個靜態不變的全域排名。[21][23]

此外，CodeGraph 在測試套件中將關聯度評分（relevance scoring）與上下文排序（context ranking）切分為獨立測試案例，這也體現了「找對目標」與「將目標妥善排進有限 context」是兩個截然不同的工程挑戰。[25][26]

## 8. 建立客觀評測方案：避免將 Token 節省率等同於檢索召回率

若要對這類工具進行公平的橫向對比，測試環境必須嚴格控制以下變因：鎖定同一專案 commit SHA、設計涵蓋五大典型場景的題庫、使用相同的 MCP 用戶端與基礎模型、設定一致的 context 預算與工具調用上限，並搭配人工審查建立的標準答案（gold manifest）。基準題庫至少應涵蓋：

1. 找出特定函式的所有 caller。
2. 完整追蹤從對外 API 路由經由 service、repository 至 database 的全路徑。
3. 評估修改特定核心檔案後的系統波及範圍（blast radius）。
4. 找出跨服務非同步事件的 producer 與 consumer 節點。
5. 在修改源碼或新增依賴邊後，驗證增量索引能否正確反映最新狀態。

每道題目應預先建立標註清單：列出必要的節點、關係邊、檔案與源碼區間，並清楚標示為 answer-critical、supporting 或 incidental。測試執行期間應完整記錄每次 MCP tool 調用、候選節點排序、最終回傳結構、cursor 狀態、截斷標記、覆蓋率、信心度、agent 的後續動作及最終回答。結算時應同步呈現多元指標：Recall@K、路徑覆蓋率、上下文證據涵蓋率、預算分配損失（allocation miss）、推論理解損失（agent recovery loss）、工具調用總數、回應延遲與 token 佔用量。

在評測思維上，CodeGraph 的 quality loop 強調以真實程式碼庫與多樣化查詢驗證上下文是否足以支持 LLM 正確作答；GitNexus 的評測框架則聚焦於拆解 baseline、native 與 native_augment 條件下的解析率、成本、token 與調用次數。兩者各有側重且具互補價值；但在基於相同條件完成嚴謹的對照實驗前，不宜斷言特定工具的召回率具絕對優勢。[6][22][24]

## 9. 選型評估：依據團隊所需的記憶調用模式進行決策

| 核心需求場景 | 優先評估工具 | 核心優勢 | 關鍵防範風險 |
|---|---|---|---|
| 多語言混編、跨服務架構、需由 agent 自行組合精確圖譜查詢 | codebase-memory-mcp | 工具鏈完整，涵蓋語意、圖譜遍歷、鏈路追蹤、精確取碼與索引覆蓋驗證 | Agent 選擇錯誤調用順序；未確實處理分頁 cursor 或忽略未涵蓋警示 |
| 需將檢索脈絡無縫導入架構規劃、程式實作、代碼審查與影響分析 | GitNexus | 完整整合 execution process、符號上下文、影響分析、PDG 與工作流機制 | 初始流程識別偏離；索引過期未同步；將截斷的 lower-bound 誤判為全貌 |
| 偏好以單一低摩擦入口快速獲取關鍵流程與核心源碼 | CodeGraph | explore 工具高度整合排序、圖譜擴展、源碼預算分配與即時診斷訊號 | 排序正確但源碼預算不足（allocation miss）；高密度回傳導致後續 context 迅速膨脹 |

最終的選型思考應回歸核心本質：**程式碼記憶工具的核心價值，在於能否穩定地將關鍵程式碼證據注入 agent 的上下文窗口。** 任何系統性的評估方案，都應將索引覆蓋率、檢索召回率、上下文證據涵蓋率、源碼分配損耗與最終作答品質分開檢驗。目前各專案官方釋出的多為不同面向的基準測試與診斷數據，尚無足以一錘定音的跨工具統一遺漏率結論。

## Sources

- [1：codebase-memory-mcp official repository](https://github.com/DeusData/codebase-memory-mcp)
- [2：GitNexus official repository](https://github.com/abhigyanpatwari/GitNexus)
- [3：CodeGraph official repository](https://github.com/colbymchenry/codegraph)
- [4：GitNexus license](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/LICENSE)
- [5：GitNexus architecture](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/ARCHITECTURE.md)
- [6：GitNexus evaluation harness](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/eval/README.md)
- [7：CodeGraph residual context benchmark](https://raw.githubusercontent.com/colbymchenry/codegraph/main/docs/benchmarks/residual-context-occupancy.md)
- [8：CodeGraph telemetry policy](https://raw.githubusercontent.com/colbymchenry/codegraph/main/TELEMETRY.md)
- [9：codebase-memory-mcp current README](https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/README.md)
- [10：GitNexus current README](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/gitnexus/README.md)
- [11：CodeGraph current README](https://raw.githubusercontent.com/colbymchenry/codegraph/main/README.md)
- [12：CodeGraph regression audit memory measurements](https://raw.githubusercontent.com/colbymchenry/codegraph/main/docs/benchmarks/regression-audit-2026-09.md)
- [13：CBM measuring quality latency and agent savings](https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/docs/MEASURING_SAVINGS.md)
- [14：CBM MCP tool schemas and output bounds](https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/src/mcp/mcp.c)
- [15：CBM store schema and search implementation](https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/src/store/store.c)
- [16：GitNexus MCP tool contracts](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/gitnexus/src/mcp/tools.ts)
- [17：GitNexus hybrid search implementation](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/gitnexus/src/core/search/hybrid-search.ts)
- [18：GitNexus MCP output budget implementation](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/gitnexus/src/mcp/output-budget.ts)
- [19：GitNexus PDG impact evidence and lower-bound handling](https://raw.githubusercontent.com/abhigyanpatwari/GitNexus/main/gitnexus/src/mcp/local/pdg-impact.ts)
- [20：CodeGraph explore implementation and output allocation](https://raw.githubusercontent.com/colbymchenry/codegraph/main/src/mcp/tools.ts)
- [21：CodeGraph context builder and relevance defaults](https://raw.githubusercontent.com/colbymchenry/codegraph/main/src/context/index.ts)
- [22：CodeGraph search quality loop](https://raw.githubusercontent.com/colbymchenry/codegraph/main/docs/SEARCH_QUALITY_LOOP.md)
- [23：CodeGraph explore budget allocation design](https://raw.githubusercontent.com/colbymchenry/codegraph/main/docs/design/explore-budget-allocation.md)
- [24：CodeGraph explore sufficiency benchmark](https://raw.githubusercontent.com/colbymchenry/codegraph/main/docs/benchmarks/explore-sufficiency.md)
- [25：CodeGraph relevance scoring tests](https://raw.githubusercontent.com/colbymchenry/codegraph/main/__tests__/explore-relevance-scoring.test.ts)
- [26：CodeGraph context ranking tests](https://raw.githubusercontent.com/colbymchenry/codegraph/main/__tests__/context-ranking.test.ts)
