# Hermes Agent v2 Plugin Environment Variables: Complete Configuration Guide

> Configure Hermes Agent v2 plugins with essential environment variables for authentication and multi-tenant session routing. Master MEMORY_ENDPOINT, MEMORY_API_KEY, and more.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The Hermes Agent v2 plugin requires seven mandatory environment variables—`MEMORY_ENDPOINT`, `MEMORY_API_KEY`, `MEMORY_SERVICE_ID`, `MEMORY_TEAM_ID`, `MEMORY_AGENT_ID`, `MEMORY_TASK_ID`, and `MEMORY_CONVERSATION_ID`—to authenticate with the Memory Proxy and route multi-tenant memory sessions correctly.**

The Hermes Agent v2 plugin acts as the gateway between Hermes clients and the TencentDB Agent Memory Core's Memory Proxy. Located in the `TencentCloud/TencentDB-Agent-Memory` repository, this component relies on specific environment variables to locate the proxy endpoint, authenticate requests, and isolate data across teams and agents.

## Mandatory Environment Variables

The v2 plugin cannot initialize without the following variables set in the runtime environment. Each variable maps to specific headers or query parameters that the Memory Proxy validates according to the logic defined in [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts).

### MEMORY_ENDPOINT

The `MEMORY_ENDPOINT` variable specifies the HTTP address of the Memory Proxy. This value typically follows the format `http://<host>:<port>` and corresponds to the gateway configuration found in [`MemoryCore/tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.standalone.yaml).

### MEMORY_API_KEY

The `MEMORY_API_KEY` serves as the Bearer token for gateway authentication. The proxy expects this key in the `api_key` query parameter or `Authorization` header. According to the [`sdk/memory-core/python/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/README.md), this should be a user-generated secret prefixed with `sk-mem-`.

### MEMORY_SERVICE_ID

The `MEMORY_SERVICE_ID` provides a logical service identifier that the proxy uses to isolate data sets. As defined in [`MemoryCore/src/core/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/types.ts), common values include `default` or custom service names that partition memory storage.

### MEMORY_TEAM_ID

The `MEMORY_TEAM_ID` enables multi-tenant routing within the proxy. This identifier, referenced in [`MemoryPanel/web/src/pages/ApiKeysPage/components/ApiKeyPanel.tsx`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/ApiKeysPage/components/ApiKeyPanel.tsx), should match the team identifier provisioned in the Memory Panel.

### MEMORY_AGENT_ID

The `MEMORY_AGENT_ID` identifies the specific Hermes client instance. The proxy uses this value to store per-agent data, as documented in [`MemoryPanel/web/src/pages/GuidePage/index.tsx`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/GuidePage/index.tsx). Use a descriptive identifier such as `hermes-agent-001`.

### MEMORY_TASK_ID

While technically optional, `MEMORY_TASK_ID` must be set to a static placeholder like `no-task` to prevent the proxy from presenting a form-based session registration. The [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md) explicitly warns that Hermes cannot handle form responses, making this variable effectively mandatory.

### MEMORY_CONVERSATION_ID

The `MEMORY_CONVERSATION_ID` must be a unique identifier for every new chat session. The proxy binds this UUID-style string to a memory marker to maintain session context. According to the Hermes README, failing to change this value between sessions causes memory leakage across conversations.

## Optional LLM Configuration Variables

For deployments using a custom LLM endpoint rather than the built-in compatibility layer, the plugin accepts two additional variables referenced in [`MemoryPanel/web/src/pages/GuidePage/index.tsx`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/GuidePage/index.tsx).

### MODEL_API_KEY

The `MODEL_API_KEY` authenticates requests to external LLM providers. This is only required when forwarding calls to custom endpoints such as OpenAI-compatible APIs.

### MODEL_BASE_URL

The `MODEL_BASE_URL` specifies the root address of the custom LLM endpoint (e.g., `https://api.openai.com/v1`). The plugin appends standard v1 paths to this base when routing generation requests.

## Technical Implementation Details

When the Hermes client starts, it reads `~/.hermes/config.yaml` and injects environment variables into HTTP transactions. According to [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts), the plugin transmits:

- **Headers**: `x-team-id`, `x-agent-id`, `x-task-id`, and `x-conversation-id` corresponding to the respective `MEMORY_*` variables
- **Query Parameters**: `endpoint`, `api_key`, and `service_id` derived from `MEMORY_ENDPOINT`, `MEMORY_API_KEY`, and `MEMORY_SERVICE_ID`

The proxy validates the `api_key` against its internal configuration, then uses the header trio (team, agent, conversation) to locate or create a memory session. Missing headers trigger the form-based fallback registration, which Hermes cannot process, so explicit configuration of all IDs is critical.

## Configuration Examples

### Hermes Client Configuration (YAML)

Configure the Hermes client by expanding environment variables in `~/.hermes/config.yaml`:

```yaml
model:
  default: gpt-4
  provider: custom
  base_url: http://127.0.0.1:8420
  api_key: ${MEMORY_API_KEY}
  extra_headers:
    x-team-id: "${MEMORY_TEAM_ID}"
    x-agent-id: "${MEMORY_AGENT_ID}"
    x-task-id: "${MEMORY_TASK_ID}"
    x-conversation-id: "${MEMORY_CONVERSATION_ID}"

```

The `${...}` placeholders automatically expand from the environment at runtime.

### Unix Shell Environment Setup

Export the required variables before invoking the Hermes binary:

```bash
export MEMORY_ENDPOINT=http://127.0.0.1:8420
export MEMORY_API_KEY=sk-mem-abc123def456
export MEMORY_SERVICE_ID=default
export MEMORY_TEAM_ID=team-001
export MEMORY_AGENT_ID=hermes-agent-001
export MEMORY_TASK_ID=no-task
export MEMORY_CONVERSATION_ID=$(uuidgen)

# Optional custom LLM configuration

export MODEL_API_KEY=sk-openai-xyz789
export MODEL_BASE_URL=https://api.openai.com/v1

hermes

```

### Docker Compose Deployment

Deploy Hermes as a sidecar container with environment injection:

```yaml
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    environment:
      - MEMORY_ENDPOINT=http://memory-proxy:8420
      - MEMORY_API_KEY=${MEMORY_API_KEY}
      - MEMORY_SERVICE_ID=default
      - MEMORY_TEAM_ID=team-001
      - MEMORY_AGENT_ID=hermes-001
      - MEMORY_TASK_ID=no-task
      - MEMORY_CONVERSATION_ID=${CONV_ID}
    volumes:
      - $HOME/.hermes:/root/.hermes

```

### Python SDK Integration

When using the `tdai_memory` Python SDK directly, pass environment variables to the constructor:

```python
from tencentdb_agent_memory.v3 import MemoryClient
import os

client = MemoryClient(
    endpoint=os.getenv("MEMORY_ENDPOINT"),
    api_key=os.getenv("MEMORY_API_KEY"),
    service_id=os.getenv("MEMORY_SERVICE_ID")
)

client.skill.upload(
    team_id=os.getenv("MEMORY_TEAM_ID"),
    agent_id=os.getenv("MEMORY_AGENT_ID"),
    skill_name="diagnostic_skill",
    skill_body="..."
)

```

## Summary

- **Seven mandatory variables** (`MEMORY_ENDPOINT`, `MEMORY_API_KEY`, `MEMORY_SERVICE_ID`, `MEMORY_TEAM_ID`, `MEMORY_AGENT_ID`, `MEMORY_TASK_ID`, `MEMORY_CONVERSATION_ID`) are required for the v2 plugin to authenticate and route requests.
- The plugin maps these variables to HTTP headers (`x-team-id`, `x-agent-id`, `x-task-id`, `x-conversation-id`) and query parameters consumed by the Memory Proxy.
- `MEMORY_TASK_ID` must be set to `no-task` to prevent form-based registration that Hermes cannot handle.
- `MEMORY_CONVERSATION_ID` requires a fresh UUID for every new chat session to prevent memory cross-contamination.
- Optional `MODEL_API_KEY` and `MODEL_BASE_URL` variables enable custom LLM endpoints beyond the default gateway.

## Frequently Asked Questions

### What happens if MEMORY_TASK_ID is not set?

If `MEMORY_TASK_ID` is undefined, the Memory Proxy falls back to form-based session registration. According to [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md), Hermes lacks the capability to respond to these forms, causing the initialization to hang or fail. Always set this variable to `no-task` when no specific task identifier exists.

### How do I generate a valid MEMORY_CONVERSATION_ID?

Generate a unique UUID for every new chat session using tools like `uuidgen` on Unix systems or Python's `uuid.uuid4()`. The proxy binds this identifier to memory markers in [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts), and reusing IDs causes previous session data to leak into new conversations.

### Are MODEL_API_KEY and MODEL_BASE_URL required?

No, these variables are optional. They are only necessary when configuring Hermes to forward generation requests to a custom LLM endpoint rather than using the built-in OpenAI compatibility layer provided by the Memory Proxy, as shown in [`MemoryPanel/web/src/pages/GuidePage/index.tsx`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/GuidePage/index.tsx).

### Where does the plugin load its configuration from?

The Hermes client reads `~/.hermes/config.yaml` at startup. Environment variables referenced with `${VAR_NAME}` syntax in this file expand at runtime, allowing dynamic configuration without modifying the YAML between deployments.