# How to Integrate TencentDB Agent Memory with Hermes Agent (v2 Plugin)

> Integrate TencentDB Agent Memory with Hermes Agent v2 by deploying the TDAI Gateway sidecar. Proxy OpenAI-compatible requests and extract metadata seamlessly.

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

---

**TencentDB Agent Memory integrates with the Hermes v2 plugin by deploying the TDAI Gateway as a sidecar that proxies OpenAI-compatible chat requests while extracting conversation metadata from required HTTP headers.**

The TencentCloud/TencentDB-Agent-Memory repository provides a memory-enabled gateway designed to operate as a sidecar for Hermes Agent v2. By routing Hermes' `POST /v1/chat/completions` calls through the TD Memory Gateway, you enable persistent conversation memory, knowledge-graph retrieval, and skill execution for your agent workflows. This guide walks through the architectural components, deployment modes, and configuration steps required to wire the systems together according to the source implementation.

## Architectural Components

The integration relies on four primary components that handle request proxying, session management, and knowledge retrieval.

**Hermes v2 Plugin** acts as the client generating OpenAI-compatible chat requests. According to [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md), Hermes sends standard chat completion payloads but does not automatically generate conversation tracking headers.

**TD Memory Gateway** (located in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)) implements the HTTP server that receives Hermes requests. The gateway extracts `x-conversation-id`, `x-task-id`, and `x-agent-id` from incoming headers and forwards them to the core memory services.

**MemoryCore** (entry point in [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts)) provides the knowledge-graph, SQLite store, skill management, and LLM binding logic. The gateway calls this core library to persist memory, run skills, and synchronize conversation turns.

**MemoryKnowledge** ([`MemoryKnowledge/src/store/wiki-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/wiki-service.ts)) is an optional service hosting the knowledge-graph API (v3) that the core uses when processing knowledge requests.

## Deployment Modes

The TD Memory Gateway can be started in two distinct configurations depending on your infrastructure requirements.

**Standalone Mode** runs the gateway as an independent Docker container using `MemoryCore/Dockerfile`. This container exposes port `8125` by default and can be deployed via Kubernetes manifests in `MemoryCore/deploy/k8s/` or locally through the All-in-One Docker Compose stack defined in [`deploy/panel-knowledge-combined/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/panel-knowledge-combined/README.md).

**Hermes Side-car Mode** launches the gateway automatically via the Hermes process using the plugin configuration in [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml). In this mode, the gateway runs alongside the Hermes agent process, eliminating the need for separate container orchestration.

## Step-by-Step Integration

Follow these steps to configure Hermes to route traffic through the TD Memory Gateway.

### Deploy the TD Memory Gateway

For local development, use the All-in-One Docker Compose stack that bundles Hermes, the Gateway, and Knowledge services. For production workloads, apply the Kubernetes manifests in `MemoryCore/deploy/k8s/` to deploy the standalone gateway. Ensure the service is reachable at `http://localhost:8125` or your configured host.

### Configure Hermes Headers

Edit `~/.hermes/config.yaml` to set the `gateway_url` parameter to your TD Memory endpoint (e.g., `http://localhost:8125`). You must manually supply three required headers for every request: `x-conversation-id`, `x-task-id`, and `x-agent-id`. Hermes does not generate these identifiers automatically.

```yaml

# ~/.hermes/config.yaml

gateway_url: http://localhost:8125
headers:
  x-conversation-id: "conv-12345"
  x-task-id: "task-abc"
  x-agent-id: "hermes"

```

### Register the Hermes v2 Plugin

Install the plugin SDK within your Hermes virtual environment:

```bash
pip install -e sdk/memory-core/python/

```

When running in side-car mode with `gateway_url` properly configured, Hermes automatically loads the plugin on startup.

### Verify the Integration

Send a chat request to the Hermes endpoint. The request should be proxied to [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts), which parses the headers and invokes [`tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-core.ts) for session handling. Check the gateway logs for successful header parsing and session registration.

```python
import requests
import json

url = "http://localhost:8125/v1/chat/completions"
payload = {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "What is the latest DB backup policy?"}]
}
headers = {
    "Content-Type": "application/json",
    "x-conversation-id": "conv-67890",
    "x-task-id": "task-def",
    "x-agent-id": "hermes"
}

resp = requests.post(url, json=payload, headers=headers)
print(json.dumps(resp.json(), indent=2))

```

## Required Headers and Session Management

The gateway strictly requires three HTTP headers to maintain conversation context. **x-conversation-id** identifies the specific dialog session and must be manually refreshed for each new conversation to prevent context leakage. **x-task-id** categorizes the operational task being performed. **x-agent-id** identifies the calling agent instance (typically "hermes").

When these headers are missing, the gateway implemented in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) bypasses session registration entirely, and memory injection is skipped. All requests from Hermes are treated as **main** requests; there is no "auxiliary" mode for background processing.

## Limitations and Considerations

The Hermes v2 plugin integration has specific constraints that affect implementation choices.

**No Function Call Support**: Hermes cannot handle interactive function calls (the "form" flow) when integrated with TD Memory. If your workflow requires multi-step form interactions, you must implement them outside the Hermes plugin architecture.

**Manual Header Management**: Unlike some agent frameworks, Hermes does not automatically rotate `x-conversation-id` values. Your calling application must generate new conversation IDs for each distinct dialog to avoid unintentional context reuse.

**MemoryKnowledge Dependency**: If your skills require knowledge-graph lookups, ensure the optional MemoryKnowledge service is deployed and reachable, as referenced in [`MemoryKnowledge/src/store/wiki-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/wiki-service.ts).

## Summary

- Deploy the TD Memory Gateway via standalone Docker (`MemoryCore/Dockerfile`) or as a Hermes side-car using [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml).
- Configure `~/.hermes/config.yaml` with the gateway URL and manually supply `x-conversation-id`, `x-task-id`, and `x-agent-id` headers.
- The gateway in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) proxies requests to [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts) for memory persistence and skill execution.
- Rotate conversation IDs manually for each new dialog to ensure proper context isolation.
- Function calls and interactive forms are not supported in the Hermes v2 plugin integration.

## Frequently Asked Questions

### What headers are required for the Hermes v2 plugin integration?

You must provide `x-conversation-id`, `x-task-id`, and `x-agent-id` in every request. These headers are extracted by the gateway at [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) to register the session and route memory operations. Without these headers, the gateway bypasses memory injection entirely.

### Can I use the TD Memory Gateway without Docker?

Yes, you can run the gateway in Hermes side-car mode by configuring `gateway_url` in `~/.hermes/config.yaml` and installing the Python SDK via `pip install -e sdk/memory-core/python/`. This launches the gateway process alongside Hermes without requiring containerization.

### Why are my conversation contexts persisting across different chats?

This occurs when the `x-conversation-id` value is reused between distinct conversations. Unlike some agent frameworks, Hermes does not automatically generate new conversation IDs. You must manually refresh this header value for each new dialog to ensure the gateway creates a fresh session in [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts).

### Does the integration support OpenAI function calling?

No. According to [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md), the Hermes v2 plugin cannot handle interactive function calls (the "form" flow). When memory or skills require function execution, design your workflow to complete all necessary data collection before sending the request to the Hermes endpoint.