安裝與配置 Codebase Memory · Codebase Memory

安裝本地可執行檔

Codebase Memory 採用 Go 語言編寫，被編譯成一個零相依的單一靜態二進位可執行檔。你不需要在本地電腦安裝 Docker、Node.js 或是配置複雜的 Neo4j 圖資料庫服務，只需執行一條下載腳本即可開箱即用。

根據你的作業系統，開啟終端機執行對應的安裝命令：

1. macOS 與 Linux 系統

使用 curl 安全下載並自動賦予執行權限：

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

2. Windows 系統 (PowerShell)

請以系統管理員身份開啟 PowerShell，並執行：

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

[!NOTE]

安裝時可用 install --clients claude,codex 只替指定 client 寫入 MCP 配置、agents、skills 與 hooks；單獨執行 install --clients 會列出所有支援的 token。

若 binary 已由 mise、Homebrew、nix、asdf 或 cargo 管理，install 不會在 ~/.local/bin 另放一份、也不會改動 shell rc；此時更新請直接使用對應套件管理員的指令，例如 mise upgrade、brew upgrade。

3. 手動安裝方式

如果你處於離線或受限的企業網路環境，可以手動至 GitHub Releases 下載對應平台的壓縮檔（如 codebase-memory-mcp_Windows_x86_64.zip），解壓後將 codebase-memory-mcp 可執行檔手動移動至你的系統環境變數 PATH 目錄下（例如 Windows 的 C:\Windows\system32 或 Linux 的 /usr/local/bin）。

驗證安裝是否成功：

codebase-memory-mcp --version

連接 AI 工具：MCP 伺服器配置

Codebase Memory 遵循 Model Context Protocol (MCP) 規範。你需要將它註冊到你的 AI 代理工具中，使其成為 AI 能夠隨時調用的外掛能力。

1. 註冊到 Claude Code

Claude Code 預設會讀取用戶目錄下的全域 mcp.json 設定檔。請編輯該檔案：

macOS / Linux 路徑：~/.config/Claude/mcp.json
Windows 復原路徑：C:\Users\<您的用戶名>\AppData\Roaming\Claude\mcp.json

在設定檔的 mcpServers 結構中加入以下 JSON 配置：

{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": ["start"],
      "env": {
        "CODEBASE_MEMORY_DB_PATH": "D:/Repo/TechSpecs/codebase-memory.db",
        "CODEBASE_MEMORY_LOG_LEVEL": "info"
      }
    }
  }
}

[!IMPORTANT]

CODEBASE_MEMORY_DB_PATH：指定圖譜 SQLite 資料庫的儲存路徑。強烈建議指定到一個固定的磁碟位置，避免資料庫隨專案目錄改變而失效。

args: ["start"]：這是啟動本機 MCP 伺服器的核心參數。

2. 註冊到 Cursor IDE

Cursor 支援直接在設定畫面中註冊 MCP 服務：

點擊右上角 Gear 圖示 (Settings) -> 選擇 Features 頁籤。
滾動至最下方的 MCP 區域。
點擊 + Add New MCP Server 按鈕，填入：
- Name：codebase-memory
- Type：command
- Command：codebase-memory-mcp start
點擊 Save 保存。Cursor 會顯示一個綠色的圓點，代表 MCP 伺服器已成功在背景握手連結。

3. 註冊到 VS Code 插件 Cline / Roo Code

如果您使用的是 VS Code 搭配 Cline 或 Roo Code 插件，請點擊插件面板的 MCP Settings 按鈕（通常會開啟 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json），並寫入以下內容：

{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": ["start"],
      "disabled": false
    }
  }
}

專案初始化與排除規則配置

當你安裝並註冊好 MCP 伺服器後，需要告訴 Codebase Memory 如何索引你的專案。

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

codebase-memory-mcp init

這會在專案根目錄下產生一個預設的 .codebase-memory.yaml 檔案。編輯此檔案以避開龐大的依賴包或二進位檔案，以防圖譜肥大：

# .codebase-memory.yaml 配置說明
project_name: "PlcControlSystem"
database:
  max_connections: 5
  
indexing:
  # 排除路徑使用 glob 語法
  exclude:
    - "**/node_modules/**"
    - "**/bin/**"
    - "**/obj/**"
    - "**/dist/**"
    - "**/.git/**"
    - "**/*.{png,jpg,jpeg,gif,mp4,zip,pdf}"
  # 強制包含的程式語言副檔名
  include_extensions:
    - "cs"
    - "ts"
    - "tsx"
    - "json"

首次構建與增量更新

首次全域掃描 (Full Scan)

在設定好排除規則後，在專案根目錄執行：

codebase-memory-mcp index

Codebase Memory 將遍歷專案下所有符合規則的檔案，解析 AST 並在本地 SQLite 中構建關係圖。對於 10 萬行左右的專案，通常在 5 到 10 秒內即可完成建置。

背景監聽增量同步 (Incremental watch)

為了讓圖譜與你的實際代碼編輯保持 100% 同步，你可以讓 MCP 伺服器在背景以監聽模式啟動：

codebase-memory-mcp start --watch

當你儲存任何程式碼變更時，檔案系統監聽器 (FsWatcher) 會觸發增量分析，僅對該變更檔案的局部 AST 進行重新計算，耗時小於 50 毫秒，且完全不消耗任何 token。