表格存储：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 立即抽取。