這篇文章要解決什麼問題？

如果你是第一次接觸 Codebase Memory，你可能會問：「它跟 grep、跟 IDE 的搜尋到底差在哪？為什麼 AI 工具需要它？」

一句話：傳統搜尋是「找字」，Codebase Memory 是「找結構、找關係」。 它把你整個專案的程式碼解析成一張「知識圖譜（Knowledge Graph）」——誰定義了誰、誰呼叫了誰、誰實作了哪個介面——全部存進本地資料庫。AI 不必再瞎讀十幾個檔案，而是直接「查圖譜」拿到精準答案。

本指南會帶你：

1. 看懂它能做什麼（功能導覽）
2. 15 分鐘內親手把它跑起來（快速上手）

功能導覽：Codebase Memory 能為你做什麼？

Codebase Memory 提供 16 個 MCP 工具（Model Context Protocol）。新手只需先認識其中 6 個核心能力，就能應付 80% 的場景：

關鍵差異：上述每一個動作，傳統做法都要 AI「讀好幾個檔案進 context window」，燒 token 又容易遺漏。Codebase Memory 只回傳「結構化的關係與目標片段」，號稱可省下約 120 倍的 token 消耗。

它不是什麼

• 不是 雲端服務：圖譜存你本機的 SQLite，資料不出門。
• 不是 需要另外架 Neo4j：單一靜態二進位檔，零相依。
• 不是 取代 IDE：它是 AI 代理的「記憶層」，IDE 還是你寫程式的地方。

15 分鐘快速上手

下面用一個你自己的小專案就能跑。假設你有一個 TypeScript 或 Python 專案（任何語言都行，Codebase Memory 支援 155 種語言）。

第 1 步：安裝本機執行檔（2 分鐘）

Codebase Memory 是用 Go 寫成的單一執行檔，沒有 Docker、沒有 Node.js 相依。

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

若 binary 已由 mise、Homebrew 等套件管理員管理，安裝器不會覆寫它；更新請用對應指令（例如 mise upgrade、brew upgrade）。想只設定特定 AI 工具，安裝時加上 install --clients <名稱> 即可，詳見安裝與配置。

驗證裝好了：

codebase-memory-mcp --version

看到版本號就代表成功。

第 2 步：在你的專案裡初始化（1 分鐘）

切換到你的專案根目錄，執行：

codebase-memory-mcp init

這會產生一個 .codebase-memory.yaml 設定檔。它預設會排除 node_modules/、dist/、圖片等不該被索引的東西。小專案的話，預設值通常就夠用，先不用改。

第 3 步：建立知識圖譜（1～3 分鐘）

codebase-memory-mcp index

這一步會遍歷你專案下所有原始碼，用 Tree-sitter 解析成 AST（抽象語法樹），再把「檔案 → 類別 → 函式 → 呼叫關係」寫進本地圖譜。小專案通常幾秒就完成；10 萬行左右的專案大約 5～10 秒。

第 4 步：發出你的第一次圖譜查詢（透過 AI 工具）

到這裡，圖譜已經建好了，但它要透過 AI 工具（Claude Code、Cursor、Cline 等）來查詢。你需要把 Codebase Memory 註冊成一個 MCP 伺服器（詳細步驟見安裝課），然後在對話裡這樣問 AI：

「用 search_graph 找出專案裡所有 Controller 結尾的類別。」

AI 會幫你呼叫工具，你會看到類似這樣的回傳：

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

這就是圖譜的威力：回傳的不是「檔案裡哪一行出現了 Controller 這個字」，而是「這裡真的有一個類別定義，它在這個檔案、有 5 個方法」——精準、無雜訊。

接著你可以再追問：

「用 trace_path 往上追蹤 UserController.create 被誰呼叫。」

AI 就會回傳完整的入站呼叫鏈——哪些路由、哪些測試、哪些其他服務會觸發它。這在傳統做法裡，你要手動翻好幾個檔案才拼得起來。

第 5 步：讓圖譜自動跟上你的修改（選用）

開發時讓它在背景監聽檔案變動，改一個檔案就只重新解析那一個，毫秒級更新：

codebase-memory-mcp start --watch

第一次使用，最容易踩的 3 個坑

1. 忘記先 index：圖譜是空的，查什麼都找不到。裝完一定要跑一次 index。
2. 把圖譜資料庫放進專案目錄：建議在 MCP 設定裡用 CODEBASE_MEMORY_DB_PATH 指到固定路徑，否則換專案目錄會失效。
3. 期待它能取代閱讀：圖譜幫你「定位」與「看關係」，但理解邏輯還是要 get_code_snippet 讀實際程式碼。它是導航，不是駕駛。

接下來

你現在已經把工具跑起來、也發出過第一次查詢了。建議的下一步：

1. 安裝與配置詳解：把 MCP 伺服器正確接上你的 AI 工具
2. 什麼是 Codebase Memory：深入知識圖譜的底層模型
3. 入門範例：照著 beginner 難度的範例，實際操作 search_graph、trace_path、get_architecture

記住核心心法：「先查圖譜定位，再讀片段理解」——這就是 Codebase Memory 為 AI 協作帶來的範式轉移。