engram-setup

Engram 安裝檢測與環境配置

概述

本技能提供一套結構化的 SOP，自動檢測用戶環境是否具備運行 engram 的條件，偵測最佳的 Embedding 提供者與模型，生成設定檔，並引導 MCP 註冊。

觸發條件

• 用戶提到 engram、記憶系統、memory setup 相關的安裝/配置需求
• 使用 /memory-setup 指令
• 用戶想要為新環境配置跨工具記憶系統

---

執行 SOP（7 步驟）

Step 1：Node.js 檢測

node --version

判斷邏輯：

• ✅ 版本 ≥ 18.0.0 → 通過
• ❌ 未安裝或版本太低 → 提供安裝指引：

# macOS（推薦用 fnm）
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22

# 或 Homebrew
brew install node@22

---

Step 2：專案存在性檢測

檢查 engram 專案是否存在於本機。

檢測方式：

# 檢查常見位置
ls -d ~/Documents/code/engram 2>/dev/null || \
ls -d ~/projects/engram 2>/dev/null || \
ls -d ~/code/engram 2>/dev/null || \
echo "NOT_FOUND"

如果不存在 → 引導 clone：

# 如果有 Git repo
git clone https://github.com/rocker027/engram.git ~/Documents/code/engram

# 或手動取得後放到指定位置

⚠️ 記住專案實際路徑，後續步驟會用到。以下用 $PROJECT_DIR 代稱。

---

Step 3：npm 依賴與建構檢測

cd $PROJECT_DIR

# 檢查 node_modules（三個必要套件）
ls node_modules/@lancedb/lancedb/package.json 2>/dev/null && echo "lancedb: OK" || echo "lancedb: MISSING"
ls node_modules/@modelcontextprotocol/sdk/package.json 2>/dev/null && echo "mcp-sdk: OK" || echo "mcp-sdk: MISSING"
ls node_modules/openai/package.json 2>/dev/null && echo "openai: OK" || echo "openai: MISSING"

# 檢查是否已建構
ls dist/server.js 2>/dev/null && echo "build: OK" || echo "build: MISSING"

如果缺少依賴或未建構：

cd $PROJECT_DIR
npm install
npm run build

⚠️ @lancedb/lancedb 含原生二進位檔，會自動下載對應平台（macOS arm64 / x86_64 / Linux）的預編譯版本。

---

Step 4：Embedding 提供者偵測

按優先順序逐一偵測可用的 Embedding 服務：

4a. 偵測 Ollama（推薦 ✅）

# 檢查 Ollama 是否安裝
which ollama && ollama --version

# 檢查 Ollama 服務是否運行
curl -s http://localhost:11434/api/tags | head -c 200

結果判斷：

• ✅ 有回應 → Ollama 運行中，進入 Step 5 偵測模型
• ❌ 連線失敗 → Ollama 未運行或未安裝

安裝指引（如未安裝）：

# macOS
brew install ollama

# 或官方安裝
curl -fsSL https://ollama.com/install.sh | sh

# 啟動服務
ollama serve &

4b. 偵測 oMLX（macOS Apple Silicon）

# 檢查 oMLX 是否安裝
which omlx 2>/dev/null || ls /Applications/oMLX.app 2>/dev/null

# 嘗試偵測 oMLX API（預設端口可能不同）
curl -s http://localhost:8080/v1/models 2>/dev/null | head -c 200

4c. 偵測 OpenAI API Key

# 檢查環境變數
echo ${OPENAI_API_KEY:+SET} || echo "NOT_SET"

4d. 偵測 Jina API Key

# 檢查環境變數
echo ${JINA_API_KEY:+SET} || echo "NOT_SET"

---

Step 5：模型可用性檢測

根據 Step 4 偵測到的提供者，確認 Embedding 模型是否已就緒。

Ollama 模型偵測

# 列出已安裝的模型
ollama list

# 檢查特定 embedding 模型
ollama list | grep -E "(nomic-embed-text|mxbai-embed-large|all-minilm|snowflake-arctic-embed)"

已知支援的模型與維度：

模型	維度	大小	推薦度
nomic-embed-text	768	~274MB	⭐⭐⭐ 推薦（平衡）
mxbai-embed-large	1024	~670MB	⭐⭐ 高品質
snowflake-arctic-embed	1024	~670MB	⭐⭐ 高品質
all-minilm	384	~45MB	⭐ 最輕量

如果沒有任何 embedding 模型：

# 拉取推薦模型
ollama pull nomic-embed-text

雲端提供者

如果使用 OpenAI / Jina，模型不需要本地安裝，直接使用即可。

---

Step 6：設定檔生成

根據偵測結果自動產生最佳設定。

決策矩陣：

偵測到 Ollama + nomic-embed-text       → 配置 A（推薦 ✅）
偵測到 Ollama + mxbai-embed-large      → 配置 B
偵測到 Ollama + all-minilm             → 配置 C
偵測到 Ollama + snowflake-arctic-embed → 配置 D
偵測到 oMLX + 相容模型                  → 配置 E
偵測到 OpenAI API Key                  → 配置 F
偵測到 Jina API Key                    → 配置 G
均未偵測到                              → 先安裝 Ollama（回到 Step 4a）

生成設定檔：

設定檔路徑：~/.engram/config.json

mkdir -p ~/.engram

配置 A — Ollama + nomic-embed-text（推薦）：

{
  "embedding": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "nomic-embed-text",
    "dimensions": 768
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

配置 B — Ollama + mxbai-embed-large：

{
  "embedding": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "mxbai-embed-large",
    "dimensions": 1024
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

配置 C — Ollama + all-minilm：

{
  "embedding": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "all-minilm",
    "dimensions": 384
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

配置 D — Ollama + snowflake-arctic-embed：

{
  "embedding": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "snowflake-arctic-embed",
    "dimensions": 1024
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

配置 E — oMLX：

{
  "embedding": {
    "baseURL": "http://localhost:<PORT>/v1",
    "apiKey": "<API_KEY>",
    "model": "<MODEL_NAME>",
    "dimensions": <DIMENSIONS>
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

配置 F — OpenAI：

{
  "embedding": {
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "<OPENAI_API_KEY>",
    "model": "text-embedding-3-small",
    "dimensions": 1536
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

配置 G — Jina：

{
  "embedding": {
    "baseURL": "https://api.jina.ai/v1",
    "apiKey": "<JINA_API_KEY>",
    "model": "jina-embeddings-v5-text-small",
    "dimensions": 1024
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

⚠️ 重要：如果已有 ~/.engram/lancedb 資料庫，且想更換模型（維度不同），必須先刪除舊資料庫：

rm -rf ~/.engram/lancedb

否則會因向量維度不匹配而啟動失敗。

---

Step 7：MCP 註冊配置

根據用戶使用的 AI 工具，引導加入 MCP 配置。

Antigravity（mcp_config.json）

找到 Antigravity 的 MCP 設定檔（通常在 ~/.gemini/antigravity/mcp_config.json 或 IDE 設定中），加入：

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["$PROJECT_DIR/dist/server.js"]
    }
  }
}

Claude Code（claude_mcp_config.json）

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["$PROJECT_DIR/dist/server.js"]
    }
  }
}

💡 將 $PROJECT_DIR 替換為 Step 2 偵測到的專案實際絕對路徑。

---

驗證清單

完成所有步驟後，執行以下驗證：

# 1. 確認設定檔已建立
cat ~/.engram/config.json

# 2. 手動啟動測試（應無錯誤輸出）
cd $PROJECT_DIR && timeout 3 node dist/server.js 2>&1 || true

# 3. 在 AI 工具中測試 MCP Tool
# 呼叫 memory_stats 應回傳記憶庫統計

如果 memory_stats 成功回傳統計數據，代表安裝完成 ✅。

---

常見問題排除

問題	原因	解法
嵌入失敗	Ollama 未啟動或模型未拉取	ollama serve & 然後 ollama pull nomic-embed-text
向量維度不匹配	切換了模型但未清除舊 DB	rm -rf ~/.engram/lancedb
ENOENT: no such file	未建構或路徑錯誤	npm run build 並確認路徑
Connection refused	Embedding 服務未運行	確認對應服務已啟動
LanceDB 原生模組錯誤	平台不支援或 Node 版本不對	確認 Node ≥ 18 並重新 npm install

---

輸出格式

完成檢測後，以結構化報告呈現結果：

## 🔍 Engram 環境檢測報告

| 檢查項目 | 狀態 | 詳情 |
|---------|------|------|
| Node.js | ✅ / ❌ | v22.x.x |
| 專案位置 | ✅ / ❌ | /path/to/engram |
| npm 依賴 | ✅ / ❌ | 3/3 已安裝 |
| 建構產物 | ✅ / ❌ | dist/server.js |
| Embedding 提供者 | ✅ / ❌ | Ollama / OpenAI / Jina / oMLX |
| Embedding 模型 | ✅ / ❌ | nomic-embed-text (768 維) |
| 設定檔 | ✅ / ❌ | ~/.engram/config.json |

### 建議動作
1. [如有缺項，列出修復步驟]

### 推薦配置
[根據偵測結果顯示的最佳 config.json]