Tablestore：Agent 生態整合

安裝

openclaw plugins install @tablestore/openclaw-tablestore-memory

認證方式

外掛程式支援以下兩種認證方式，選擇其一即可：

• AccessKey（AK/SK）：支援全部功能。使用 AK/SK 認證時，如果未填寫 endpoint 與 otsInstanceName，外掛程式會在 cn-beijing 自動建立並複用受管理的執行個體。

• API Key：設定 apiKey 後優先於 AK/SK 使用。API Key 僅支援記憶服務資料面操作（不含控制面），因此必須填寫 https 協議的 endpoint 與 otsInstanceName，且不支援受管理的執行個體自動建立。

配置

AK/SK 最小配置：

{
  "plugins": {
    "slots": {
      "memory": "tablestore-mem"
    },
    "entries": {
      "tablestore-mem": {
        "enabled": true,
        "config": {
          "endpoint": "https://<instance>.cn-beijing.ots.aliyuncs.com",
          "otsInstanceName": "<instance-name>",
          "accessKeyId": "<AccessKey ID>",
          "accessKeySecret": "<AccessKey Secret>"
        }
      }
    }
  }
}

API Key 配置：

{
  "plugins": {
    "slots": { "memory": "tablestore-mem" },
    "entries": {
      "tablestore-mem": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true },
        "config": {
          "apiKey": "<API Key>",
          "endpoint": "https://<instance>.cn-beijing.ots.aliyuncs.com",
          "otsInstanceName": "<instance-name>"
        }
      }
    }
  }
}

以下配置也可通過環境變數覆蓋：TABLESTORE_MEMORY_APP_ID、TABLESTORE_MEMORY_TENANT_ID、TABLESTORE_MEMORY_API_KEY。

可選配置

Scope 映射

OpenClaw 外掛程式寫入時使用當前運行時身份：

{
  "appId": "openclaw",
  "tenantId": "<current-user>",
  "agentId": "<runtime-agent>",
  "runId": "<runtime-session>"
}

檢索時使用租戶維度跨 Agent、跨會話範圍，agentId 和 runId 通配為 *：

{
  "appId": "openclaw",
  "tenantId": "<current-user>",
  "agentId": "*",
  "runId": "*"
}

運行行為

• 在 before_prompt_build 階段檢索相關長期記憶。

• 將檢索到的記憶注入隱藏上下文，不直接寫入可見會話記錄。

• 在 agent_end 階段收集本輪使用者和助手訊息。

• 預設以非同步方式調用 AddMemories 寫回記憶庫。

記憶整理（Dream）

外掛程式內建離線 Dream 記憶整理，對已寫入的長期記憶做去重、改寫、歸併與清理：

• 每次成功寫回會把該輪的具體 Scope（appId/tenantId/agentId/runId）排隊待整理。

• 後台調度每 dreamIntervalHours（預設 24h）處理隊列中待整理的 Scope，每次最多整理 dreamMaxScopesPerRun 個 Scope，使用 applyMode=safe_auto、incremental=true。

• 開啟 dreamOnSessionEnd（預設）時，會話結束（輪換/重設/空閑/壓縮）會立即整理該會話 Scope；它與後台周期共用每 Scope 水位與 dreamMinIntervalHours，同一 Scope 不會被重複整理。

• safe_auto 自動應用信賴度達標的 add/update/merge 動作，DELETE 永不自動應用。閾值優先順序為 CLI --threshold（所有動作）> 按動作的 dreamConfidenceThresholds > 單一 dreamConfidenceThreshold（預設 0.9）。

• 配置了 dreamInstructions 時，後台、session_end 與 CLI 的每個 Dream 任務都會攜帶該自訂整理指令。

• 整理只針對具體 Scope（非通配），結果保留原位（preserve_scope），完全運行在即時鏈路之外；失敗僅記錄日誌，不影響檢索與寫回。

• 後台調度僅在 OpenClaw 進程存活時運行；非常駐環境可用 CLI 配合 cron 驅動（見下）。

CLI 和 Slash 命令

OpenClaw 外掛程式提供調試與營運命令：

# 寫入 / 檢索
openclaw tablestore-mem add "Alice likes jasmine tea" --uid alice
openclaw tablestore-mem search "what does Alice like" --uid alice
openclaw tablestore-mem search "what does Alice like" --uid alice --top-k 10 --min-similarity 0.3

# 診斷連通性、記憶庫與 Scope 列表
openclaw tablestore-mem doctor --uid alice

# 按需觸發記憶整理（Dream）
openclaw tablestore-mem dream --uid alice --wait
openclaw tablestore-mem dream --uid alice --apply-mode proposal --wait
openclaw tablestore-mem dream --uid alice --threshold 0.8 --wait
openclaw tablestore-mem dream --uid alice --instructions "優先合并重複的偏好" --wait

在 OpenClaw 會話內可使用：

/tablestore-mem-add Alice likes jasmine tea
/tablestore-mem-search jasmine tea

安裝

hermes plugins install https://github.com/aliyun/hermes-tablestore-memory
hermes memory setup

在 hermes memory setup 中選擇 tablestore-mem。

外掛程式依賴 tablestore>=6.4.5。如果 Hermes 使用的 Python 環境未安裝該依賴，需要將 SDK 安裝到 Hermes 實際使用的 Python 環境中。

配置密鑰

密鑰建議寫入 ~/.hermes/.env：

TABLESTORE_MEMORY_AK=<AccessKey ID>
TABLESTORE_MEMORY_SK=<AccessKey Secret>

配置記憶服務

非敏感配置寫入 $HERMES_HOME/tablestore_memory.json：

{
  "endpoint": "https://<instance>.cn-beijing.ots.aliyuncs.com",
  "instance_name": "<instance-name>",
  "memory_store_name": "hermes_mem",
  "description": "",
  "app_id": "hermes",
  "tenant_id": "",
  "enable_rerank": true,
  "auto_create_store": true,
  "timeout": 30
}

預設值

Scope 映射

Hermes 外掛程式按以下規則填充 Scope 4 段：

寫入時使用當前會話的精確 Scope；檢索時使用當前租戶下的跨 Agent、跨會話範圍，即 agentId=""、runId=""。

提供的工具

外掛程式還會在每輪對話完成後自動同步處理的使用者和助手訊息，並在下一輪對話前預取相關記憶。

Hermes CLI 命令

當 memory.provider 設定為 tablestore-mem 後，可使用：

hermes tablestore-mem add "使用者偏好簡潔回答"
hermes tablestore-mem add "使用者喜歡 Rust" --metadata source=manual --metadata topic=preferences
hermes tablestore-mem add "同步寫入這條記憶" --sync
hermes tablestore-mem search "簡潔回答"
hermes tablestore-mem search "Rust" --top-k 10

能力

• 每輪自動檢索（UserPromptSubmit 鉤子）：在你提交 prompt 前檢索相關長期記憶，以隱藏上下文注入模型，不列印到可見對話。

• 每輪自動回寫（Stop 鉤子）：對話結束後，將本輪新增的 user/assistant 訊息增量寫入記憶庫（按服務限制分塊：≤20 條 / ≤32000 位元組）。

• 離線記憶整理 Dream（SessionEnd 鉤子 + CLI/cron）：去重、改寫、合并、淘汰過時記憶。

• MCP 工具（模型可顯式調用）：search_memory、add_memory、consolidate_memory。

• 斜杠命令：/search、/add、/doctor、/dream。

• CLI：search / add / doctor / dream。

• 同時支援 API Key 與 AccessKey（AK/SK） 認證。

要求

• Node.js ≥ 18

• 一個已建立好的 Tablestore 執行個體（僅華北 2 / 北京地區提供記憶服務），擷取 https endpoint 與執行個體名；以及 API Key 或 AK/SK。

• 本外掛程式不自動建立執行個體，需顯式提供 endpoint + 執行個體名。

安裝

倉庫：https://github.com/aliyun/tablestore-memory-claude-plugin 依賴已用 esbuild 打包進 dist/（隨倉庫發布），安裝時無需執行 npm install。

# 方式一（推薦）：從 GitHub marketplace 安裝
claude plugin marketplace add aliyun/tablestore-memory-claude-plugin
claude plugin install tablestore-memory@tablestore-memory-marketplace

# 方式二：複製後從本地目錄安裝
git clone https://github.com/aliyun/tablestore-memory-claude-plugin.git
claude plugin marketplace add ./tablestore-memory-claude-plugin
claude plugin install tablestore-memory@tablestore-memory-marketplace

調試期間可跳過 marketplace 直接指定目錄：

claude --plugin-dir /path/to/tablestore-memory-claude-plugin

修改外掛程式源碼後需重新打包：

npm run build      # 重新打包到 dist/

配置

在 ~/.claude/settings.json 的 env 中設定（會同時注入鉤子與 MCP server）：

{
  "env": {
    "TABLESTORE_MEMORY_ENDPOINT": "https://<instance>.cn-beijing.ots.aliyuncs.com",
    "TABLESTORE_MEMORY_INSTANCE": "<instance>",
    "TABLESTORE_MEMORY_API_KEY": "<api-key>"
  }
}

AK/SK 方式：用 TABLESTORE_ACCESS_KEY_ID + TABLESTORE_ACCESS_KEY_SECRET 替代 TABLESTORE_MEMORY_API_KEY。

認證優先順序：TABLESTORE_MEMORY_API_KEY 存在則用 API Key（要求 https endpoint），否則用 AK/SK；都沒有則外掛程式靜默禁用。

也可用設定檔兜底：~/.tablestore-memory/config.json（鍵為小駝峰 endpoint/instanceName/apiKey/accessKeyId/accessKeySecret/storeName）。環境變數優先於設定檔。

完整環境變數列表：

Scope 設計（全域單使用者池）

• 寫入錨定具體會話：appId / tenantId / agentId / runId=<session_id>。

• 檢索在固定租戶下放寬：agentId=*、runId=*，實現跨會話、跨專案召回。

• 萬用字元遵循服務層級規則：某層用 * 後更深層必須 *。

Dream（記憶整理）

• 會話結束（SessionEnd）時按租戶 scope 觸發一次整理，受 DREAM_MIN_INTERVAL_HOURS 節流（狀態記於 ~/.tablestore-memory/dream-state.json）。

• 由於外掛程式不能常駐後台，周期整理用 cron 調用 CLI：

# 例：每天 03:17 整理某租戶記憶並等待結果
17 3 * * *  node /path/to/tablestore-memory/dist/cli.mjs dream --uid <tenant> --wait

CLI

node dist/cli.mjs search "使用者喜歡什麼飲品" --top-k 5
node dist/cli.mjs add "使用者喜歡美式咖啡" --sync
node dist/cli.mjs doctor
node dist/cli.mjs dream --uid <tenant> --apply-mode safe_auto --wait

--uid 覆蓋租戶（營運/cron 用）；-q/--quiet 僅輸出資料欄位。

行為與邊界

• Fail-open：缺配置或任何 SDK 異常都不會阻斷對話（鉤子寫 stderr 日誌後退出 0）。

• 鉤子 stdout 只輸出協議 JSON，日誌輸出到 stderr。

• 非同步寫入（sync=false）後約 15 秒內長期記憶可被檢索；--sync 立即抽取。