安裝指南 · codebase-memory-mcp 繁中教學站

先記住這件事：CBM 是單一靜態二進位，零依賴、零 API key。裝完重啟你的 coding agent，然後說「Index this project」就開始用了。更新是重跑 install.sh（idempotent），不是從二進位內部更新。

Step 1 — 安裝（macOS / Linux）

# 標準版（無圖形界面，精簡）
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

# 含 3D 圖形 UI（localhost:9749）
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Step 1' — Windows（PowerShell）

# 1. 下載安裝程式
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. （建議）檢視指令碼內容
notepad install.ps1

# 3. 解除 Mark-of-the-Web 限制
Unblock-File .\install.ps1

# 4. 執行
.\install.ps1

若出現執行原則錯誤：先跑 Set-ExecutionPolicy -Scope Process Bypass，或 PowerShell -ExecutionPolicy Bypass -File .\install.ps1。SmartScreen 警告 →「更多資訊」→「仍要執行」。

Step 2 — 確認安裝

codebase-memory-mcp --version        # 例如 0.9.0
codebase-memory-mcp cli list_projects  # 空的 [] 也正常

Step 3 — 開始使用

install 會自動偵測已安裝的 coding agent（Claude Code / Codex / OpenCode / Cursor / Gemini CLI…共 43 個平台）並寫入 MCP 設定。重啟你的 agent，然後：

你：幫我 index 這個專案
（agent 呼叫 index_repository(repo_path="/絕對路徑")）

你：誰呼叫了 ProcessOrder？
（agent 呼叫 trace_path(function_name="ProcessOrder", direction="inbound")）

安裝選項

旗標	說明
`--ui`	安裝含 3D 圖形界面（`codebase-memory-mcp --ui=true --port=9749` → 開 `http://localhost:9749`）
`--skip-config`	只要二進位，不設定任何 agent
`--dir=<path>`	指定安裝位置

套件管理器

# npm
npm install -g codebase-memory-mcp          # 含 UI：CBM_VARIANT=ui npm install -g codebase-memory-mcp

# PyPI
pip install codebase-memory-mcp             # 含 UI：CBM_VARIANT=ui pip install codebase-memory-mcp

# Homebrew（macOS）
brew install codebase-memory-mcp

# Arch Linux
yay -S codebase-memory-mcp-bin

# 其他
scoop install codebase-memory-mcp   # Windows
winget install codebase-memory-mcp  # Windows
choco install codebase-memory-mcp   # Windows
go install github.com/DeusData/codebase-memory-mcp@latest

注意：npm/PyPI/Go 套件只是「發佈該套件的私有快取二進位」，不會取代 native 安裝；執行時仍會進入 exact-build admission barrier。套件管理器的更新用你的套件管理器（npm i -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp）。

從原始碼建置

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh                # 標準版
scripts/build.sh --with-ui      # 含圖形界面
# 二進位在 build/c/codebase-memory-mcp

需求：C 編譯器（gcc/clang）、C++ 編譯器、zlib、git。跑測試：scripts/test.sh（6,768 tests / 120 suites）。

手動 MCP 設定（不想用 install 指令）

加到 ~/.claude.json（或專案 .mcp.json）：

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

更新與移除

# 更新：重跑安裝指令碼（idempotent）就是更新
bash "<install-dir>/install.sh"        # macOS/Linux
powershell -File "<install-dir>\install.ps1"   # Windows

# 移除
codebase-memory-mcp uninstall

CBM 不會自行檢查新版本、不會發送任何網路請求。更新一律透過 install 指令碼 / 套件管理器 / GitHub releases。

疑難排解

問題	解決方式
`/mcp` 看不到 server	確認 `.mcp.json` 路徑是絕對路徑，重啟 agent。測試：`echo '{}' \| /path/to/binary` 應輸出 JSON
`index_repository` 失敗	傳絕對路徑：`index_repository(repo_path="/absolute/path")`
`trace_path` 回 0 筆	先 `search_graph(name_pattern=".PartialName.")` 找出精確名稱
查詢到錯的專案	加 `project="name"` 參數；用 `list_projects` 看名稱
找不到二進位	`export PATH="$HOME/.local/bin:$PATH"`
UI 沒載入	確認下載的是 `ui` 變體且跑了 `--ui=true`，檢查 `http://localhost:9749`

完整平台矩陣（43 agent）見 Multi-Agent 支援。