Hermes Agent 接入 Tablestore Memory 持久化记忆 - 表格存储

通过 hermes-tablestore-memory 插件将 Hermes Agent 接入 Tablestore Memory 服务，为智能体构建云端持久化、跨会话和跨 Agent 共享的语义记忆。

方案介绍

hermes-tablestore-memory 插件将 Hermes Agent 的 MemoryProvider 接口对接到表格存储 Tablestore 的 Memory 服务，为智能体提供云端持久化的语义记忆能力。

云托管，免运维：Tablestore 全托管运行，无需自建数据库或管理向量索引，按量计费。
数据自主可控：记忆数据存储在用户自有的阿里云账号中，可通过 Tablestore 控制台直接查看与审计，并支持 RAM 权限管理。
跨会话、跨 Agent 共享：写入时使用精确 Scope（appId / tenantId / agentId / runId）保留归属信息；检索时自动展开 agentId=* 与 runId=*，按租户维度跨 Agent 与会话召回。
结构化语义记忆：自动从对话中提炼姓名、偏好、技术栈、决策记录等结构化事实，以向量形式存储，支持语义检索与 Rerank 重排。
自动同步与预取：每轮对话结束后自动调用 sync_turn() 同步至 Tablestore；下一轮对话前自动调用 queue_prefetch() 预取相关记忆并注入上下文。

前提条件

已开通表格存储 Tablestore 服务，并在支持 Memory 功能的地域创建实例。
说明
当前仅支持华北 2（北京）。
已安装Hermes Agent。如未安装可按下文提供的操作步骤进行安装。

安装并配置Hermes Agent

说明

如已安装请直接跳过本步骤进入hermes-tablestore-memory 插件的安装和配置。

Hermes Agent 官方提供一键安装脚本，参考Hermes Agent 官方文档或GitHub 仓库进行安装和配置。如因网络问题导致一键安装失败，可参考以下手动安装步骤。

步骤1：安装Hermes Agent

安装 git（以yum为例）。
```
yum install -y git
```
下载并执行 Hermes Agent 安装脚本。其中 --skip-setup 用于跳过交互式 LLM Provider 配置向导，便于在无 TTY 环境下安装，后续手动完成配置。
```
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/hermes-install.sh && bash /tmp/hermes-install.sh --skip-setup
```
说明
如遇依赖安装时间过长，可配置阿里云镜像后重新安装，详见安装时 git clone 失败或 PyPI 下载缓慢。

链接全局命令并验证安装。

ln -sf /root/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes && hermes --version

步骤2：配置 LLM Provider

本节面向首次接入 Hermes Agent 或更换模型 Provider 的用户，以阿里云百炼 qwen3-max 为例，说明如何让 Hermes Agent 正确路由到百炼。Hermes Agent 通过 ~/.hermes/.env（密钥）与 ~/.hermes/config.yaml（普通配置）分别管理敏感信息和一般参数。

说明

需开通阿里云百炼服务并获取 API Key。

通过 hermes config set 写入百炼 API Key 与模型名。

hermes config set DASHSCOPE_API_KEY your-dashscope-api-key
hermes config set model qwen3-max

将 DashScope Endpoint 写入 .env。*_BASE_URL 类配置必须放置于 .env，写入 config.yaml 不会被读取。
```
echo 'DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1' >> ~/.hermes/.env
```
验证 Provider 已自动识别为 Alibaba Cloud（DashScope）。
```
hermes status
```

预期输出包含 Model: qwen3-max 与 Provider: Alibaba Cloud (DashScope)。

说明

Hermes Agent 通过环境变量自动识别 Provider，优先级依次为：

auth.json 中的 active_provider。
OPENAI_API_KEY 或 OPENROUTER_API_KEY，命中则路由到 OpenRouter。
其他 Provider 专用 Key（如 DASHSCOPE_API_KEY 路由到 Alibaba Cloud）。

如果之前配置过 OPENAI_API_KEY 或 OPENAI_BASE_URL，请先从 .env 与 config.yaml 中删除，否则会被自动选为 OpenRouter 而非阿里云百炼。

安装并配置hermes-tablestore-memory插件

步骤1：安装插件

通过 hermes plugins install 命令安装插件。

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

在 Hermes Agent 自带的虚拟环境中安装 Tablestore Python SDK 及相关依赖。

cd /root/.hermes/hermes-agent
source venv/bin/activate
uv pip install tablestore==6.4.5 alibabacloud-tablestore20201209 alibabacloud-credentials

步骤2：配置 Tablestore 实例

登录表格存储 Tablestore 控制台，在华北 2（北京）地域下创建实例，并记录实例名称与 Endpoint。

将 AccessKey写入 ~/.hermes/.env。

echo 'TABLESTORE_MEMORY_AK=your-accesskey-id' >> ~/.hermes/.env
echo 'TABLESTORE_MEMORY_SK=your-accesskey-secret' >> ~/.hermes/.env

在 ~/.hermes/tablestore_memory.json 中配置插件参数。

{
  "instance_name": "your-tablestore-instance",
  "endpoint": "https://your-tablestore-instance.cn-beijing.ots.aliyuncs.com",
  "memory_store_name": "hermes_mem",
  "description": "",
  "app_id": "hermes",
  "tenant_id": "",
  "enable_rerank": true,
  "auto_create_store": true,
  "timeout": 30.0
}

说明

auto_create_store 设置为 true 时，插件首次连接 Tablestore 实例会自动创建名为 hermes_mem 的记忆库（Memory Store）及对应的多元索引，无需手动操作。

激活 tablestore-mem 作为记忆 Provider。

hermes config set memory.provider tablestore-mem

步骤3：验证安装

运行插件诊断命令检查初始化状态。

hermes tablestore-mem doctor

预期输出 JSON 如下，关键字段包括 ok: true、provider: tablestore-mem、instance_name 与 endpoint、memory_store_name: hermes_mem，以及 checks 中的 initialize、describe_memory_store、list_memories 三项均为 ok: true。

{
  "ok": true,
  "provider": "tablestore-mem",
  "instance_name": "your-tablestore-instance",
  "endpoint": "https://your-tablestore-instance.cn-beijing.ots.aliyuncs.com",
  "memory_store_name": "hermes_mem",
  "checks": {
    "initialize": {"ok": true},
    "describe_memory_store": {"ok": true},
    "list_memories": {"ok": true}
  }
}

同步写入一条测试记忆并验证语义检索。
```
hermes tablestore-mem add --sync "用户偏好简洁的中文回复"
hermes tablestore-mem search "回答风格"
```
add --sync 会强制等待向量化与索引完成。不加 --sync 时写入异步执行，刚写入的记忆短时间内可能无法被检索。

使用记忆

CLI 命令

hermes tablestore-mem 子命令提供记忆库的命令行操作入口，常用命令如下。

命令	说明
`hermes tablestore-mem add [--sync] <content>`	写入一条记忆。`--sync` 表示同步等待向量化完成。
`hermes tablestore-mem search <query> [--top-k N]`	语义检索记忆，按相关性排序返回。
`hermes tablestore-mem doctor`	只读诊断，验证连接、Memory Store 状态与记忆总数。

Agent 工具

激活 tablestore-mem 后，Hermes Agent 在交互过程中可自主调用以下四个工具进行记忆管理。

工具名	说明
`tablestore_profile`	列出当前作用域下已存储的记忆快照。
`tablestore_search`	语义搜索 Tablestore 长期记忆，返回排序结果。
`tablestore_remember`	持久化保存事实或短文到 Tablestore。
`tablestore_forget`	按 ID 删除指定的 Tablestore 记忆。

每轮对话结束后，插件还会自动调用 sync_turn() 同步对话要点至 Tablestore；下一轮对话前自动调用 queue_prefetch() 预取相关记忆并注入上下文，无需用户手动触发。

常见问题

插件初始化报错 OTSUnsupportOperation: 'ListMemoryStores'

Tablestore Memory 功能为新增能力，仅在部分地域上线。若已在不支持的地域创建实例，需在支持的地域重新创建实例。

写入后立即检索返回空

hermes tablestore-mem add 默认异步执行（返回 status 为 running），向量化与索引建立需要数秒至十余秒。验证写入效果时，建议添加 --sync 参数等待完成；Agent 自动调用 tablestore_remember 时同样默认异步，搜索结果在数秒延迟后稳定可见。

安装时 git clone 失败或 PyPI 下载缓慢

国内网络环境下，从 GitHub 与 PyPI 直连可能不稳定，建议配置阿里云 PyPI 镜像加速 uv 包下载。

mkdir -p ~/.config/uv
cat > ~/.config/uv/uv.toml <<'EOF'
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true
EOF

由于pyproject.toml 里设置 exclude-newer = "7 days"，阿里云 PyPI mirror 缺 upload-date metadata，uv把无日期视为新于 cutoff，导致解析失败。

修改 pyproject.toml，注释 exclude-newer 配置。

sed -i 's/^exclude-newer = "7 days"/# exclude-newer = removed/' /usr/local/lib/hermes-agent/pyproject.toml
rm -f /usr/local/lib/hermes-agent/uv.lock

在 Hermes 虚拟环境内手动安装依赖。

cd /usr/local/lib/hermes-agent
source venv/bin/activate
export VIRTUAL_ENV=/usr/local/lib/hermes-agent/venv
export PATH="$HOME/.local/bin:$PATH"
uv pip install -e '.[all]'

装完链接全局命令。

ln -sf /root/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes && hermes --version

LLM 请求被路由到 OpenRouter 而非阿里云百炼

Hermes Agent 通过环境变量自动识别 Provider，且 OPENAI_API_KEY 与 OPENROUTER_API_KEY 优先级高于其他 Provider 的 Key。如出现请求被路由到 OpenRouter 的情况，请检查 ~/.hermes/.env 与 ~/.hermes/config.yaml，删除遗留的 OPENAI_API_KEY 与 OPENAI_BASE_URL 配置。