Tablestore:Tablestore memory in Hermes Agent

Step 1: Install Hermes Agent

1. Install Git (using yum as an example).

   yum install -y git

2. Download and run the Hermes Agent installation script. The --skip-setup parameter is used to skip the interactive LLM Provider configuration wizard. This is useful for installation in a non-TTY environment, and you can complete the configuration manually later.

   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

   Note

   If dependencies take too long to install, you can configure an Alibaba Cloud mirror and try again. For more information, see git clone fails or PyPI downloads are slow during installation.

3. Create a symbolic link for the global command and verify the installation.

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

Step 2: Configure the LLM provider

This section is for users who are using Hermes Agent for the first time or changing their model provider. It uses the qwen3-max model from Alibaba Cloud Model Studio (Bailian) as an example to explain how to configure Hermes Agent to correctly route requests to Bailian. Hermes Agent uses ~/.hermes/.env to manage sensitive information (secrets) and ~/.hermes/config.yaml to manage general parameters.

1. Use hermes config set to set the Bailian API key and model name.

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

2. Write the DashScope Endpoint to .env. Configurations such as *_BASE_URL must be placed in .env. They are not read from config.yaml.

   echo 'DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1' >> ~/.hermes/.env

3. Verify that the provider is automatically identified as Alibaba Cloud (DashScope).

   hermes status

The expected output includes Model: qwen3-max and Provider: Alibaba Cloud (DashScope).

Step 1: Install the plugin

1. Install plugins by using the hermes plugins install command.

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

2. Install the Tablestore Python SDK and its dependencies in the Hermes Agent virtual environment.

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

Step 2: Configure the Tablestore instance

1. Log on to the Tablestore console, create an instance in the China (Beijing) region, and take note of the instance name and endpoint.

2. Write the AccessKey to ~/.hermes/.env.

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

3. Configure the plugin parameters in ~/.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
   }

   Note

   When auto_create_store is set to true, the plugin automatically creates a Memory Store named hermes_mem and its corresponding Search Index when it connects to a Tablestore instance for the first time. No manual operation is required.

4. Activate tablestore-mem as the memory Provider.

   hermes config set memory.provider tablestore-mem

Step 3: Verify the installation

1. Run the plugin's diagnostic command to check its initialization status.

   hermes tablestore-mem doctor

   The expected JSON output is as follows. Key fields include ok: true, provider: tablestore-mem, instance_name, endpoint, and memory_store_name: hermes_mem. In addition, the checks object contains the initialize, describe_memory_store, and list_memories fields, all of which are set to 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}
     }
   }

2. Write a test memory synchronously and verify the semantic search.

   hermes tablestore-mem add --sync "The user prefers concise replies in Chinese"
   hermes tablestore-mem search "response style"

   add --sync forces the operation to wait for vectorization and indexing to complete. Without --sync, the write operation is performed asynchronously, and recently written memories may not be retrievable for a short period.

CLI commands

The hermes tablestore-mem subcommand provides command-line operations for the Memory Store. The following are common commands.

Agent tools

After tablestore-mem is activated, Hermes Agent can autonomously call the following four tools to manage memory during the interaction process.

After each round of conversation, the plugin automatically calls sync_turn() to synchronize key conversation points to Tablestore. Before the next round of conversation, it automatically calls queue_prefetch() to prefetch relevant memories and inject them into the context. You do not need to manually trigger these actions.

Plugin initialization error with 'ListMemoryStores'

The Tablestore Memory Store feature is new and only available in select regions. If you have created an instance in an unsupported region, you must create a new instance in a supported region.

Empty search results after writing

The hermes tablestore-mem add command runs asynchronously by default and returns a status of running. Vectorization and index creation take several to more than ten seconds. To verify the result of the write operation, add the --sync parameter to wait for the process to complete. Similarly, when the Agent automatically calls tablestore_remember, the operation is also asynchronous by default, and search results become consistently available after a delay of a few seconds.

Git clone failures and slow PyPI downloads

Direct connections to GitHub and PyPI can be unstable in some network environments. We recommend configuring an Alibaba Cloud PyPI mirror to accelerate uv package downloads.

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

Because pyproject.toml is configured with exclude-newer = "7 days" and the Alibaba Cloud PyPI mirror is missing upload-date metadata, uv treats packages without a date as newer than the cutoff, which causes a resolution failure.

1. Modify pyproject.toml and comment out the exclude-newer setting.

   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

2. Manually install dependencies within the Hermes virtual environment.

   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]'

3. After installation, create a symbolic link for the global command.

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

LLM requests are routed to OpenRouter

Hermes Agent automatically identifies the provider by using environment variables, and OPENAI_API_KEY and OPENROUTER_API_KEY have a higher priority than keys for other providers. If requests are routed to OpenRouter, check ~/.hermes/.env and ~/.hermes/config.yaml, and remove any remaining OPENAI_API_KEY and OPENAI_BASE_URL configurations.