Hermes Agent v2 Plugin Environment Variables: Complete Configuration Guide

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.

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.

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, 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, 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, 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. 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 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.

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, 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:

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:

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:

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:

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, 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, 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}