情境

你剛聽完同事介紹 Codebase Memory（簡稱 CM），想把手上這個小小的 TypeScript todo-API 專案跑一遍，看看知識圖譜到底長什麼樣子。

這個 repo 只有三個檔案：UserController.ts、TaskController.ts、app.ts。用 grep 看也只要幾秒鐘,但你希望先在簡單的專案上把流程跑通,之後遇到大 repo 才不會手忙腳亂。

本篇是 CM 的 hello-world 走一遍,從安裝、初始化、索引到第一個 search_graph 查詢。

步驟一：安裝 CM CLI

── 在 macOS / Linux ──

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

── 在 Windows (PowerShell) ──

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

裝完後驗證版本:

codebase-memory-mcp --version

看到版本號代表安裝成功。

步驟二：在專案裡初始化

切到 todo-api 的根目錄,執行:

cd ~/projects/todo-api
codebase-memory-mcp init

init 會在專案根目錄產生一份 .codebase-memory.yaml 設定檔。這份檔案記錄了要索引哪些路徑、用哪些 parser。預設值通常就夠用,先別改它。

步驟三：建立知識圖譜

codebase-memory-mcp index

這個指令會做幾件事:

1. 用 tree-sitter 解析每個原始碼檔案的語法樹 (AST)。
2. 從 AST 抽出符號 (symbol):類別、函式、方法、變數。
3. 計算符號之間的關係:誰定義了誰、誰呼叫了誰。
4. 把全部結果寫進專案本地端的 SQLite 資料庫。

索引完之後,輸出會告訴你建了幾個 node、幾條 edge。todo-api 這種小專案大概只有幾十個符號,跑完不到一秒。

── 想要邊寫邊更新? ──

開發時可以讓 CM 自動追蹤檔案變動:

codebase-memory-mcp start --watch

存檔後大約一秒,新的程式碼就會同步進圖譜。

步驟四：連上你的 AI 助手

CM 是一個 MCP server,任何支援 MCP 的用戶端(Claude Desktop、Cursor、Continue 等)都能接。把專案的 SQLite 路徑填進用戶端的 MCP 設定後,助手就能呼叫 CM 的 16 個工具,例如 search_graph、trace_path、get_architecture。

連線成功後,接下來這一步才是重頭戲。

步驟五：檢查索引狀態(可選)

索引跑完後,想確認圖譜裡到底裝了什麼,可以請 AI 查一下狀態:

── 跟 AI 對話 ──

• You:

  確認一下目前這個專案的索引狀態,有多少 node 跟 edge?

• AI:

  我呼叫 index_status 看專案的圖譜健康度。

  CM 呼叫: index_status() CM 回傳(摘要):

  {
    "nodes": 47,
    "edges": 63,
    "languages": ["TypeScript"],
    "lastIndexed": "2026-08-13T10:24:01Z"
  }

  分析： 47 個符號、63 條邊,符合 todo-api 這種小專案的規模。沒有 skipped 檔案,代表 tree-sitter 沒有解析失敗的原始碼。

如果 index_status 顯示有 skipped 檔案(例如超大檔、解析失敗),那些檔案內的符號就不會出現在後續的查詢結果裡。遇到這種情況,直接用 grep 補查那些檔案就好。

步驟六：第一次符號搜尋

你想看看這個專案裡有沒有以 Controller 結尾的類別。

── 跟 AI 對話 ──

• You:

  幫我列出這個專案裡所有名字以 Controller 結尾的 class。

• AI:

  我呼叫 search_graph 搜尋符合條件的 class 符號。

  CM 呼叫: search_graph(query: "Controller", type: "class") CM 回傳:

  [
    {
      "qualifiedName": "app.controllers.UserController",
      "type": "class",
      "filePath": "/src/controllers/UserController.ts",
      "methodsCount": 5
    },
    {
      "qualifiedName": "app.controllers.TaskController",
      "type": "class",
      "filePath": "/src/controllers/TaskController.ts",
      "methodsCount": 4
    }
  ]

  分析： 專案裡有兩個 Controller:UserController(5 個方法)和 TaskController(4 個方法),都放在 /src/controllers/。

為什麼跟 grep 不一樣?

很多人第一個反應是「這跟我 grep -r "Controller" src/ 有什麼差?」差別在於搜尋的對象:

換句話說,search_graph 回的是「語意上的 class」,而不是「字面長得像 Controller 的字串」。註解裡寫的 Controller、CSS class 名稱裡的 controller,都不會誤中。

關鍵學習點

• CM 三步流程:init 產生設定 → index 建圖譜 → start --watch 邊寫邊更新。小專案跑完不用一秒。
• 圖譜存在本地端 SQLite:不需要雲端帳號,資料不會外送。
• 符號搜尋 ≠ 文字搜尋:search_graph 回的是 class/function/method 定義,不會被註解或字串誤導,還會附上方法數、qualified name 這類結構資訊。
• 圖譜已經準備好了:下一步可以問更複雜的問題,例如「誰呼叫了這個函式?」「整個專案的架構長怎樣?」(參見範例 010 與 011)。