Build long memory for Hermes with Hologres long memory service - Hologres

Prerequisites

Hermes Agent is deployed (version 0.17.0 or later recommended).
A Hologres long memory service instance is created in the Hologres console. For more information, see Create and use long memory service.
The Hermes host can reach the long memory service endpoint. Use the private endpoint for same-VPC deployments. For cross-VPC or local access, configure the public IP allowlist.

Step 1: Install the mem0ai dependency

The Hermes mem0 plugin requires the mem0ai Python package, which must be installed under the same Python interpreter that Hermes uses.

Check which Python interpreter Hermes uses.
```
head -1 $(which hermes)
```
Example output:
```
#!/usr/bin/python
```
Replace /usr/bin/python in the following commands with the actual interpreter path from the output.
Run the following command to install mem0ai.
```
/usr/bin/python -m pip install "mem0ai>=2.0.7,<3" --index-url https://mirrors.aliyun.com/pypi/simple/
```
Note
Installing mem0ai requires Internet access from the ECS instance. If the instance does not have an EIP or NAT gateway configured, the pip install command will fail due to network timeout.

Verify the installation.

/usr/bin/python -c "import mem0; print(mem0.__version__)"

Expected output:

2.0.7

Important

Do not install the dependency into a .venv or venv directory under the Hermes project. The Hermes CLI shebang points to /usr/bin/python and does not activate virtual environments at runtime, which causes a No module named 'mem0' error when the plugin loads.

Step 2: Install and enable the mem0-hologres-platform plugin

Hermes loads memory backends through user plugins. Download the plugin files from mem0_hologres into the Hermes user plugin directory.

Note

Note The plugin directory name must be mem0-hologres-platform to match the memory.provider configuration value.

Create the plugin directory and download the plugin files.

mkdir -p ~/.hermes/plugins/mem0-hologres-platform
cd ~/.hermes/plugins/mem0-hologres-platform

curl -fsSL -o plugin.yaml https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/plugin.yaml
curl -fsSL -o __init__.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/__init__.py
curl -fsSL -o _backend.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/_backend.py
curl -fsSL -o _oss_providers.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/_oss_providers.py
curl -fsSL -o _setup.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/_setup.py

Enable the plugin.

hermes plugins enable mem0-hologres-platform

Expected output:

✓ Plugin mem0-hologres-platform enabled. Takes effect on next session.

Verify the plugin status.

hermes plugins list --plain --no-bundled

Expected output:

enabled      user     1.1.0    mem0-hologres-platform

Step 3: Configure Hermes to connect to Hologres long memory service

You can configure the connection manually or interactively.

Option 1: Manual configuration

Note

In the following steps, replace the angle-bracket placeholders (<...>) with the actual values described in the parameter table below.

Add the long memory service API key to the Hermes environment file.
```
echo "MEM0_API_KEY=<API_KEY>" >> ~/.hermes/.env
```

Create the ~/.hermes/mem0.json configuration file.

cat > ~/.hermes/mem0.json << 'EOF'
{
  "mode": "platform",
  "api_url": "http://<ENDPOINT>:80",
  "user_id": "hermes-user",
  "agent_id": "hermes",
  "rerank": true
}
EOF

Enable the plugin and specify the memory backend in ~/.hermes/config.yaml.
```
memory:
  provider: mem0-hologres-platform

plugins:
  enabled:
    - mem0-hologres-platform
```
If you already ran hermes plugins enable mem0-hologres-platform, plugins.enabled should already contain mem0-hologres-platform. You only need to add the memory.provider entry.

Note
If you use Alibaba Cloud Model Studio models as the LLM, you also need to configure the model provider in config.yaml. For details, see Hermes Agent in Alibaba Cloud Model Studio documentation.

Option 2: Interactive setup

Note

hermes memory setup lists only built-in memory providers and does not show user plugins. If mem0-hologres-platform does not appear in the interactive menu, use Option 1 to configure manually.

Run the following command and follow the prompts to select mem0-hologres-platform:

hermes memory setup

Select mem0-hologres-platform, choose platform mode, and enter the connection parameters when prompted. For details about each parameter, see the parameter description table below.

Parameters

Parameter	Description
`mode`	The connection mode. Set to `platform` for the Hologres long memory service managed endpoint.
`api_url`	The long memory service endpoint. Must include the `http://` prefix. See Obtain connection information for details. Use a private endpoint within the same VPC, or a public endpoint for cross-VPC or local access (IP allowlist must be configured).
`MEM0_API_KEY`	The API key for the long memory service. For more information, see Obtain connection information.
`user_id`	A user identifier that isolates memory data between different users.
`agent_id`	The agent identifier. Defaults to `hermes`.
`rerank`	Whether to rerank search results. Recommended for platform mode.
`memory.provider`	The memory backend for Hermes. Must match the plugin directory name `mem0-hologres-platform`.
`plugins.enabled`	The list of user plugins to load. Must include `mem0-hologres-platform`.

Use Hermes profiles

If you use Hermes profiles to manage multiple configurations, both the plugin directory and the configuration files reside under the profile directory instead of the default paths used in Step 2 and Step 3. The following example uses a profile named holo.

Create a profile.
```
hermes profile create holo
```

Install and enable the mem0-hologres-platform plugin. Unlike Step 2, the plugin directory is located under the profile directory, and the command prefix changes from hermes to the profile name holo.

Create the plugin directory and download the plugin files from mem0_hologres.

mkdir -p ~/.hermes/profiles/holo/plugins/mem0-hologres-platform
cd ~/.hermes/profiles/holo/plugins/mem0-hologres-platform

curl -fsSL -o plugin.yaml https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/plugin.yaml
curl -fsSL -o __init__.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/__init__.py
curl -fsSL -o _backend.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/_backend.py
curl -fsSL -o _oss_providers.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/_oss_providers.py
curl -fsSL -o _setup.py https://raw.githubusercontent.com/aliyun/mem0_hologres/main/hermes-platform/_setup.py

Note

The plugin directory name must match the memory.provider configuration value, that is, mem0-hologres-platform.

Enable the plugin.

holo plugins enable mem0-hologres-platform

Expected output:

✓ Plugin mem0-hologres-platform enabled. Takes effect on next session.
Allow this plugin to replace built-in tools (e.g. shell_exec, write_file)?
  This is a privileged capability: an override can intercept everything the agent routes through that tool.
  Grant it? y
✓ Granted mem0-hologres-platform permission to override built-in tools (plugins.entries.mem0-hologres-platform.allow_tool_override: true).

When the permission prompt appears, enter y to allow the plugin to override built-in tools.

Add the configuration. You can configure the connection interactively or manually.
1. Interactive setup. Run the following command and follow the prompts to select mem0-hologres-platform. If the option does not appear in the interactive menu, use the manual configuration described below.
```
holo memory setup
```
  Run the following commands to enable the memory tool.
```
holo tools enable memory
holo config set memory.memory_enabled true
```
2. Manual configuration.
  1. Add the Hologres long memory service API key to the profile environment file.
```
echo "MEM0_API_KEY=<API_KEY>" >> ~/.hermes/profiles/holo/.env
```
  2. Create the ~/.hermes/profiles/holo/mem0.json configuration file.
```
cat > ~/.hermes/profiles/holo/mem0.json << 'EOF'
{
  "mode": "platform",
  "api_url": "http://<ENDPOINT>:80",
  "user_id": "hermes-user",
  "agent_id": "hermes",
  "rerank": true
}
EOF
```
  3. In ~/.hermes/profiles/holo/config.yaml, enable the plugin, specify the memory backend, and add memory to platform_toolsets.
```
memory:
  memory_enabled: true
  provider: mem0-hologres-platform

plugins:
  enabled:
    - mem0-hologres-platform

platform_toolsets:
  cli:
  - memory
```
For the meaning of each parameter, see the parameter table in Step 3.

Step 4: Verify the plugin status

Run the following command to confirm the memory provider is active:

hermes chat -q "hello" -Q -v --max-turns 5 2>&1 | grep -i "memory provider"

Expected output:

Memory provider 'mem0-hologres-platform' registered (5 tools)
Memory provider 'mem0-hologres-platform' activated

Step 5: Use the long memory service

Add a memory

Start a session and ask the agent to remember a fact:

hermes chat -q "My favorite programming language is Python. Please remember this." -Q --max-turns 5

Expected response:

Got it! I've saved that your favorite programming language is Python.

Recall memory across sessions

Open a new session and verify that long-term memory works:

hermes chat -q "What is my favorite programming language?" -Q --max-turns 5

Expected response:

Your favorite programming language is Python.

View mem0 tool calls

Use verbose mode to confirm that the agent called the mem0 tool:

hermes chat -q "What is my favorite programming language?" -Q -v --max-turns 5 2>&1 | grep -i "mem0"

Expected output:

Tool call: mem0_list with args: {}...
tool mem0_list completed (0.12s, 212 chars)

FAQ

The mem0-hologres-platform option does not appear in hermes memory setup

hermes memory setup lists only built-in memory providers and does not show user plugins. Use the manual configuration method described in Step 3.

The plugin is enabled but verbose logs show Memory provider 'mem0-hologres-platform' not found

Hermes resolves memory providers by plugin directory name. Make sure the plugin directory is ~/.hermes/plugins/mem0-hologres-platform/ and that the memory.provider value matches the directory name exactly.

The plugin reports No module named 'mem0' after loading

The mem0ai package is not installed in the Python environment that Hermes uses. Run /usr/bin/python -m pip install "mem0ai>=2.0.7,<3" to install it under the system Python, not a virtual environment.

The agent does not call mem0 tools

Troubleshoot as follows:

Verify that MEM0_API_KEY is set correctly in ~/.hermes/.env.
Verify that api_url in ~/.hermes/mem0.json includes the http:// prefix and port number (for example, :80).
Verify that the outbound IP of the Hermes environment is added to the Hologres IP allowlist. A successful ping does not guarantee HTTP-level access.
Verify that plugins.enabled includes mem0-hologres-platform.