Hermes Agent 接入 Tablestore Memory 持久化記憶 - Tablestore

通過 hermes-tablestore-memory 外掛程式將 Hermes Agent 接入 Tablestore Memory 服務，為智能體構建雲端持久化、跨會話和跨 Agent 共用的語義記憶。

方案介紹

hermes-tablestore-memory 外掛程式將 Hermes Agent 的 MemoryProvider 介面對接到Table Store Tablestore 的 Memory 服務，為智能體提供雲端持久化的語義記憶能力。

雲託管，免營運：Tablestore 全託管運行，無需自建資料庫或管理向量索引，隨用隨付。
資料自主可控：記憶資料存放區在使用者自有的阿里雲帳號中，可通過 Tablestore 控制台直接查看與審計，並支援 RAM 許可權管理。
跨會話、跨 Agent 共用：寫入時使用精確 Scope（appId / tenantId / agentId / runId）保留歸屬資訊；檢索時自動延伸 agentId=* 與 runId=*，按租戶維度跨 Agent 與會話召回。
結構化語義記憶：自動從對話中提煉姓名、偏好、技術棧、決策記錄等結構化事實，以向量形式儲存，支援語義檢索與 Rerank 重排。
自動同步與預取：每輪對話結束後自動調用 sync_turn() 同步至 Tablestore；下一輪對話前自動調用 queue_prefetch() 預取相關記憶並注入上下文。

前提條件

已開通 Table Store 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 執行個體

登入 Table Store 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 配置。