# 8. Plugin 說明

### 8.1 memory-lancedb-pro（對話記憶）

**功能**：自動從 OpenClaw 對話中捕捉偏好、事實、決策，並在後續對話中自動召回相關記憶。

**與 qmd-brain 的差異**：
| | qmd-brain | memory-lancedb-pro |
|---|-----------|-------------------|
| 資料來源 | ~/home 的 markdown 文件 | OpenClaw 對話本身 |
| 觸發方式 | 手動（「搜尋」「recall」） | 自動捕捉+自動召回 |
| 儲存 | PostgreSQL pgvector | LanceDB（本地檔案） |
| Embedding | llama-embed（本地 GPU） | llama-embed（本地 GPU） |
| 作用域 | 單一 collection | per-agent（global + agent:xxx） |

**設定摘要**：
```json5
// openclaw.json → plugins.entries.memory-lancedb-pro
{
  "enabled": true,
  "config": {
    "embedding": {
      "provider": "openai-compatible",
      "apiKey": "ollama",
      "model": "nomic-embed-text-v1.5",
      "baseURL": "http://127.0.0.1:11435/v1",
      "dimensions": 768
    },
    "dbPath": "/home/selig/.openclaw/memory-lancedb-pro/data",
    "autoCapture": true,        // 自動從對話提取記憶
    "autoRecall": true,         // 查詢前自動注入相關記憶
    "captureAssistant": false,  // 不記錄 assistant 的回覆
    "retrieval": {
      "mode": "hybrid",         // 向量 + BM25 混合
      "vectorWeight": 0.7,
      "bm25Weight": 0.3,
      "rerank": "lightweight"   // 不需外部 API
    },
    "scopes": {
      "default": "global",
      "agentAccess": {
        "main":           ["global", "agent:main"],
        "kaiwu":          ["global", "agent:kaiwu"],
        "tiangong":       ["global", "agent:tiangong"],
        "yucheng":        ["global", "agent:yucheng"],
        "life-assistant": ["global", "agent:life-assistant"]
      }
    }
  }
}
```

**相關路徑**：
```
~/.openclaw/plugins/memory-lancedb-pro/   # plugin 原始碼
~/.openclaw/memory-lancedb-pro/data/      # LanceDB 資料庫
```

**維運注意**：
- 改 plugin `.ts` 後必須清 jiti 快取：`rm -rf /tmp/jiti/`，再重啟 Gateway
- 只改 `openclaw.json` config 不需清 jiti，直接重啟即可
- 舊版 `memory-lancedb` 已設為 `enabled: false`，不會衝突
- **`autoRecall` 的 `before_agent_start` hook 是同步阻塞的**。若 embedding API 無回應，所有 agent 會卡死。llama-embed 異常時必須立即關閉 `autoRecall`（見 04-known-issues.md §4.14、§4.15）
- 容錯腳本 `~/clawd/scripts/embed-health.sh`（已實作，cron */30 分鐘）自動偵測 + 降級 + 通知

**記憶鐵律**（寫入 AGENTS.md，agent 每個 session 都會遵守）：
1. 踩坑後立即存雙層記憶（Technical + Principle）
2. 記憶條目 < 500 字元，原子化，不存大段摘要
3. 遇錯先 `memory_recall` 再重試
4. 改 `.ts` 必清 `/tmp/jiti/`