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

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, Hermes sends standard chat completion payloads but does not automatically generate conversation tracking headers.

TD Memory Gateway (located in 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) 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) 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.

Hermes Side-car Mode launches the gateway automatically via the Hermes process using the plugin configuration in 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.

# ~/.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:

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, which parses the headers and invokes tdai-core.ts for session handling. Check the gateway logs for successful header parsing and session registration.

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

Summary

• Deploy the TD Memory Gateway via standalone Docker (MemoryCore/Dockerfile) or as a Hermes side-car using 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 proxies requests to 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 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.

Does the integration support OpenAI function calling?

No. According to 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.

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