背景：從 GitHub Trending 開始
2026-05-19 早晨，在 GitHub Trending 週榜（5/11-17）上發現兩個高度相關的項目：
- #6 agentmemory（6,907⭐ → 現已 13K+）：為 Claude Code、Cursor、OpenClaw、Hermes 及任何 MCP 客戶端提供持久記憶
- #2 superpowers（9,939⭐）：我們已安裝的 Meta-Skill 三件套之一
agentmemory 的 README 直接列出了 OpenClaw 和 Hermes 的原生支援，這引起了我們的注意。
agentmemory 是什麼？
agentmemory（rohitg00/agentmemory，Apache 2.0）是一個針對 AI coding agents 的持久記憶引擎。核心特點：
| 維度 | 詳情 |
|---|---|
| 核心引擎 | iii-engine (Rust)，SQLite 存儲 |
| 搜尋方式 | BM25 + Vector + Graph 三合一混合搜尋 |
| 嵌入模型 | all-MiniLM-L6-v2（本地，免費，384 維） |
| 記憶生命周期 | 4 層固化（Working→Episodic→Semantic→Procedural） |
| 記憶衰減 | Ebbinghaus 遺忘曲線 + 自動清理 |
| 隱私過濾 | 自動剝離 API Key / Secret |
| 檢索精度 | LongMemEval-S R@5: 95.2% |
| 成本 | ~170K tokens/年（本地嵌入模式 $0/年） |
| 外部依賴 | 零（無需 Qdrant/Postgres/向量數據庫） |
| NPM 週下載 | 15,500+ |
| 版本 | v0.9.20（42 releases，更新極頻繁） |
架構圖
agentmemory 伺服器 (localhost:3111)
│
├── iii-engine (Rust 核心，SQLite)
│ ├── BM25 全文檢索
│ ├── 向量嵌入 (all-MiniLM-L6-v2)
│ └── 知識圖譜 (實體提取 + BFS)
│
├── 4 層記憶固化
│ Working → Episodic → Semantic → Procedural
│
├── @agentmemory/mcp (MCP shim, 53 tools)
│
├── 即時觀察器 (localhost:3113)
│
└── 多 Agent 協調 (leases + signals + mesh)
安裝過程
Step 1: 啟動伺服器
npx @agentmemory/agentmemory
首次運行會進入互動式設定精靈：
- 選擇 Agent：選擇 OpenClaw、Claude Code、Hermes
- LLM Provider：先選 Skip（BM25-only），後續接入 OMLX
- III Engine：自動安裝 v0.11.2（~6MB，5秒）
Step 2: MCP 配置
設定精靈會自動將 MCP 配置寫入各 Agent 的設定檔：
- OpenClaw:
~/.openclaw/openclaw.json→mcp.servers.agentmemory - Claude Code:
~/.claude.json→mcpServers.agentmemory - Hermes:
~/.hermes/config.yaml→ 需手動（見下文）
Step 3: 驗證
curl http://localhost:3111/agentmemory/health
# {"status":"healthy","version":"0.9.20"}
# 即時觀察器
open http://localhost:3113
Step 4: Demo 測試
npx @agentmemory/agentmemory demo
# 自動建立 6 條 observations，驗證語義搜尋
全功能升級：從 BM25-only 到完整管線
安裝完成後，初始狀態是 BM25-only（無 LLM、無向量嵌入）。需要進行全功能配置：
接入本地 OMLX LLM
我們在 Mac Studio 上運行 oMLX.app（端口 8888），作為 OpenAI-compatible 端點：
# ~/.agentmemory/.env
OPENAI_API_KEY=qwertyuiop
OPENAI_BASE_URL=http://localhost:8888/v1
OPENAI_MODEL=gemma-4-e2b-it-4bit
啟用全部功能旗標
# ~/.agentmemory/.env
EMBEDDING_PROVIDER=local # 免費本地向量嵌入
AGENTMEMORY_TOOLS=all # 全部 53 個 MCP 工具
CONSOLIDATION_ENABLED=true # 4 層記憶固化
GRAPH_EXTRACTION_ENABLED=true # 知識圖譜提取
AGENTMEMORY_AUTO_COMPRESS=true # LLM 自動壓縮
AGENTMEMORY_INJECT_CONTEXT=true # 上下文自動注入
AGENTMEMORY_REFLECT=true # 跨記憶反思合成
BM25_WEIGHT=0.4 # 混合搜尋權重
VECTOR_WEIGHT=0.6
AGENTMEMORY_GRAPH_WEIGHT=0.2
TOKEN_BUDGET=3000
最終狀態
Health: ✓ healthy
Provider: ✓ llm (OMLX Gemma-4-e2b)
Embeddings: ✓ local (all-MiniLM-L6-v2)
Consolidation ✓ 4-tier
Graph: ✓ enabled
Auto-compress ✓ enabled
Context Inj. ✓ enabled
四平台自動記憶捕獲
1. Claude Code（12 hooks，原生插件）
設定精靈已自動完成。~/.claude.json 中自動加入：
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"]
}
}
}
Claude Code 擁有最完整的整合：
- 12 個 lifecycle hooks：SessionStart/End、PreToolUse、PostToolUse、Notification、TaskCompleted 等
- 自動 session 管理：每次
claude命令自動建立 session - 自動 observation 捕獲：每條 prompt、每個 tool call 自動記錄
- 管線完整觸發：consolidation → graph → lessons → dashboard
2. OpenClaw（Plugin hooks）
需要手動安裝 Plugin：
# 下載 Plugin
mkdir -p ~/.openclaw/extensions/agentmemory
curl -sL https://raw.githubusercontent.com/rohitg00/agentmemory/main/integrations/openclaw/plugin.mjs \
-o ~/.openclaw/extensions/agentmemory/plugin.mjs
# （還需 openclaw.plugin.json、package.json、config.yaml）
在 ~/.openclaw/openclaw.json 中啟用：
{
"plugins": {
"slots": {
"memory": "agentmemory"
},
"entries": {
"agentmemory": {
"enabled": true,
"config": {
"base_url": "http://localhost:3111",
"token_budget": 2000
}
}
}
}
}
4 個 lifecycle hooks：
onSessionStart：注入相關記憶上下文onPreLlmCall：查詢感知刷新onPostToolUse：記錄工具操作onSessionEnd：摘要 + consolidation + graph
3. Hermes（6 hooks，需手動配置）
在 ~/.hermes/config.yaml 加入：
mcp_servers:
agentmemory:
command: npx
args: ["-y", "@agentmemory/mcp"]
memory:
provider: agentmemory
6 個 lifecycle hooks：pre-LLM context injection、turn capture、MEMORY.md mirroring、system prompt block。
4. DeepSeek TUI（原生 hooks）
DeepSeek TUI v0.8.37 內建 lifecycle hooks 系統，在 ~/.deepseek/config.toml 配置：
[hooks]
enabled = true
[[hooks.hooks]]
event = "session_start"
command = "bash ~/.deepseek/hooks/agentmemory.sh session_start"
[[hooks.hooks]]
event = "message_submit"
command = "bash ~/.deepseek/hooks/agentmemory.sh message_submit"
[[hooks.hooks]]
event = "tool_call_before"
command = "bash ~/.deepseek/hooks/agentmemory.sh tool_call_before"
[[hooks.hooks]]
event = "tool_call_after"
command = "bash ~/.deepseek/hooks/agentmemory.sh tool_call_after"
[[hooks.hooks]]
event = "session_end"
command = "bash ~/.deepseek/hooks/agentmemory.sh session_end"
[[hooks.hooks]]
event = "on_error"
command = "bash ~/.deepseek/hooks/agentmemory.sh on_error"
Hook 腳本 ~/.deepseek/hooks/agentmemory.sh：
#!/bin/bash
AGENTMEMORY="http://localhost:3111/agentmemory/mcp/call"
EVENT="${1:-unknown}"
curl -s -X POST "$AGENTMEMORY" \
-H "Content-Type: application/json" \
-d "{\"name\":\"memory_save\",\"arguments\":{\"content\":\"[DS-$EVENT] $(date)\",\"type\":\"fact\"}}" \
> /dev/null 2>&1
Qdrant ↔ agentmemory 雙記憶架構
我們不將 agentmemory 視為取代，而是與現有 Qdrant 向量記憶（1,426 條）互補：
Qdrant (openclaw_mem) agentmemory (localhost:3111)
│ │
├─ 業務知識庫（主） ├─ Coding agent 記憶（輔）
├─ 調研報告 ├─ Session 自動捕獲
├─ Deal flow ├─ 4 層記憶固化
├─ 客戶關係 ├─ 知識圖譜
└─ 手動 mem_save └─ 自動化 + 53 tools
同步腳本
編寫了 qdrant_to_agentmemory_sync.py，透過 agentmemory REST API 批量匯入：
# 核心邏輯
def call_mcp(name, args):
API = "http://localhost:3111/agentmemory/mcp/call"
data = json.dumps({"name": name, "arguments": args}).encode()
req = urllib.request.Request(API, data=data, headers={"Content-Type":"application/json"})
# ...
# 選擇性匯入高價值記憶（調研報告、法律合規、交易記錄）
for point in qdrant_points:
call_mcp("memory_save", {
"content": point.content,
"type": infer_type(point.tags),
"concepts": ",".join(point.concepts)
})
53 個 MCP 工具分類
| 類別 | 數量 | 代表工具 |
|---|---|---|
| 核心記憶 | 2 | memory_save, memory_recall |
| 搜尋與檢索 | 4 | memory_smart_search, memory_timeline, memory_vision_search |
| 知識圖譜 | 3 | memory_patterns, memory_relations, memory_graph_query |
| 記憶管理 | 6 | memory_consolidate, memory_compress_file, memory_profile |
| 多 Agent 協調 | 11 | memory_action_create, memory_signal_send, memory_mesh_sync |
| 診斷與治理 | 7 | memory_diagnose, memory_heal, memory_audit, memory_verify |
| 檔案與匯出 | 3 | memory_export, memory_obsidian_export, memory_snapshot_create |
| 學習與反思 | 5 | memory_lesson_save, memory_reflect, memory_sketch_create |
| 其他 | 12 | memory_facet_tag, memory_slot_*, memory_claude_bridge_sync |
LaunchAgent 持久化
為確保 agentmemory 在重啟後自動恢復，建立了 macOS LaunchAgent：
<!-- ~/Library/LaunchAgents/com.ultraclaw.agentmemory.plist -->
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>WorkingDirectory</key>
<string>/Users/Claw/Library/Application Support/agentmemory</string>
<key>EnvironmentVariables</key>
<dict>
<key>AGENTMEMORY_TOOLS</key><string>all</string>
<key>PATH</key>
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
</dict>
持久化數據存於 ~/Library/Application Support/agentmemory/data/state_store.db。
踩坑記錄與解決方案
坑 1：mcpServers vs mcp.servers 路徑錯誤
- 問題：安裝精靈將配置寫入
mcpServers，但 OpenClaw 使用mcp.servers - 解決：手動修正到正確路徑
坑 2：向量維度衝突（2048 vs 384）
- 問題：舊狀態庫使用 2048 維向量，新 local 嵌入是 384 維
- 錯誤：
Fatal: persisted vector index has wrong dimension - 解決：設定
AGENTMEMORY_DROP_STALE_INDEX=true丟棄舊向量重建
坑 3：Node.js 版本衝突
- 問題：PATH 中
/usr/local/bin/node（v22.14.0）優先於/opt/homebrew/bin/node（v26.0.0） - 解決：
brew upgrade node→ 25.8.0 → 26.0.0；修正 PATH 優先級
坑 4：大量數據導致 health critical
- 問題：全量匯入 1,426 條 Qdrant 記憶後 CPU 飆至 639%
- 解決：採用選擇性匯入（高價值記憶），逐步擴充
坑 5：memory_save 不觸發管線
- 問題：
memory_save是 standalone API，不參與 session→observation→consolidation 管線 - 影響：Dashboard / Graph / Lessons 無法自動填充
- 解決：啟用原生 hooks（Claude Code / OpenClaw / Hermes）以自動捕獲 session；手動
memory_lesson_save寫入教訓
坑 6：Gateway 重啟後 agentmemory 下線
- 問題：OpenClaw Gateway 重啟時會 kill agentmemory 進程
- 解決：LaunchAgent 的
KeepAlive自動重啟
最終架構
┌──────────────────────────┐
│ agentmemory v0.9.20 │
│ localhost:3111 │
│ ┌──────────────────┐ │
│ │ iii-engine (Rust)│ │
│ │ BM25+Vector+Graph│ │
│ │ 53 MCP tools │ │
│ └──────────────────┘ │
└──────┬───────┬───────────┘
│ │
┌──────────────────┼───────┼──────────────────┐
│ │ │ │
┌────▼─────┐ ┌──────▼──┐ ┌──▼──────┐ ┌──────▼──────┐
│OpenClaw │ │ Claude │ │ Hermes │ │ DeepSeek TUI│
│Plugin 4 │ │ 12 hooks│ │ 6 hooks │ │ 6 hooks │
│hooks │ │ auto │ │ auto │ │ auto save │
└──────────┘ └─────────┘ └─────────┘ └─────────────┘
│
┌──────▼──────┐
│ Qdrant │
│ 1,426 條 │
│ 業務知識庫 │
└─────────────┘
結論
agentmemory 是一個極具潛力的 AI agent 記憶層，特別適合多 agent 協作場景。它的優勢在於：
- 零外部依賴（SQLite + 本地嵌入），部署極簡
- 混合搜尋精度高（BM25 + Vector + Graph）
- 多平台原生整合（12+ agent 支援）
- 完整記憶生命周期（4 層固化 + 衰減 + 圖譜）
- 53 MCP 工具，涵蓋從 CRUD 到多 agent 協調
與 Qdrant 形成互補架構：Qdrant 管業務知識，agentmemory 管 agent 記憶。各師所長，相得益彰。
部署日期：2026-05-19 | 作者：君澤智庫