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

> Learn how to integrate TencentDB Agent Memory with Hermes Agent using the v1 plugin. Expose an OpenAI-compatible gateway and configure essential headers for seamless integration and memory prefetching.

- 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 Hermes Agent via the v1 plugin by exposing an OpenAI-compatible HTTP gateway at `http://127.0.0.1:8420/v1/chat/completions` and requiring specific headers (`x-conversation-id`, `x-task-id`, `x-request-id`) for session management and cross-session memory prefetching.**

The TencentDB Agent Memory repository provides persistent vector storage and multi-tenant memory management for LLM agents. When you integrate TencentDB Agent Memory with Hermes Agent using the v1 plugin, Hermes treats Memory as an OpenAI-compatible backend, enabling automatic memory injection and retrieval across conversational sessions through HTTP API calls.

## Architecture Overview

The integration relies on three core components working together through **Header preselection** (Header 预选), since Hermes Agent does not support interactive forms.

- **Memory Core Gateway**: Implemented in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts), this component exposes the OpenAI-compatible endpoint at `http://127.0.0.1:8420/v1/chat/completions`. It manages the L0-L3 memory hierarchy (Conversation → Atomic Memory → Scene Blocks → Persona) and handles session registration via custom headers.

- **Hermes Agent (v1 plugin)**: Configured through `~/.hermes/config.yaml`, the agent uses the `memory_tencentdb` package to call the **prefetch** interface before each request, retrieving relevant memories for the current session context.

- **Memory Proxy** (optional): Located at [`agents/skills/setup-proxy/setup-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/skills/setup-proxy/setup-proxy.sh), this script manages uniform header generation when multiple Hermes Agents share a single Memory instance.

## Prerequisites

Before starting the integration, ensure you have:

- Node.js and npm installed for the Memory Core Gateway
- Hermes Agent installed with v1 plugin support
- Valid LLM API credentials (DeepSeek, OpenAI, or compatible providers)
- Network access between Hermes Agent and the Memory Gateway (default port 8420)

## Step-by-Step Integration Guide

### Step 1: Start the Memory Core Gateway

Navigate to the MemoryCore directory and install dependencies. The gateway server in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) requires environment variables for your upstream LLM provider.

```bash
cd MemoryCore
npm install

export TDAI_LLM_API_KEY="sk-xxxx"
export TDAI_LLM_BASE_URL="https://api.deepseek.com/v1"
export TDAI_LLM_MODEL="deepseek-chat"

npx tsx src/gateway/server.ts

```

The Gateway binds to port **8420** by default and implements the OpenAI Chat Completions protocol according to [`MemoryCore/src/gateway/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/config.ts).

### Step 2: Configure Hermes Agent Headers

Create or edit `~/.hermes/config.yaml` to point at the Memory Gateway. The **v1 plugin** requires three specific headers for session tracking and memory retrieval:

```yaml

# ~/.hermes/config.yaml

api_key: "any-value"          # Memory Gateway does not validate this field

base_url: "http://127.0.0.1:8420"
headers:
  x-conversation-id: "conv-001"
  x-task-id: "task-abc"
  x-request-id: "req-123"
model: "gpt-4o"

```

- **x-conversation-id**: Unique identifier for the current chat session; change this for new conversations
- **x-task-id**: Business task identifier that persists across multiple sessions
- **x-request-id**: Unique request identifier for the specific operation

As documented in [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md), these headers enable the **Header preselection** mechanism that replaces interactive authentication.

### Step 3: Enable the v1 Plugin for Memory Prefetching

The v1 plugin automatically calls the `prefetch` interface to retrieve relevant memories before processing each request. Implement your Hermes client as follows:

```python
from hermes import HermesClient

client = HermesClient(
    base_url="http://127.0.0.1:8420",
    api_key="any",                                 # Placeholder only

    default_headers={
        "x-conversation-id": "conv-001",
        "x-task-id": "task-abc",
        "x-request-id": "req-123",
    },
)

# Memory automatically injects relevant context

resp = client.chat_completions(
    messages=[{"role": "user", "content": "请帮我回忆上次的需求"}]
)
print(resp.choices[0].message.content)

```

The `memory_tencentdb` package handles the **prefetch** call transparently, querying the Memory Gateway for vectors matching the current conversation context before forwarding the request to the LLM.

### Step 4: Verify Cross-Session Memory Persistence

Test the end-to-end flow to confirm memory writes and retrieval:

1. **First session**: Send a message with `x-conversation-id: "conv-001"`. The Gateway automatically writes memories through the L0-L3 layers.
2. **Same session**: Send another message with identical headers. The v1 plugin **prefetch** recalls the previous context.
3. **New session**: Change to `x-conversation-id: "conv-002"` while keeping `x-task-id: "task-abc"`. The Gateway detects the shared task ID and retrieves relevant cross-session memories.

This behavior is implemented in the gateway logic referenced in [`README.deployment.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.deployment.md) (lines 553-560).

## Managing Multiple Agents with Memory Proxy

When deploying multiple Hermes Agents against a single Memory instance, use the setup script to synchronize headers:

```bash
cd agents/skills/setup-proxy
./setup-proxy.sh

```

This script, located at [`agents/skills/setup-proxy/setup-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/skills/setup-proxy/setup-proxy.sh), scans `~/.hermes/config.yaml` across agent instances and generates unified headers to prevent session conflicts. The proxy ensures consistent **Header preselection** without manual configuration of each agent.

## Testing the Integration with cURL

You can verify the Gateway independently of Hermes using standard HTTP requests. Include all three required headers to trigger session registration and memory injection:

```bash
curl -X POST http://127.0.0.1:8420/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "x-conversation-id: conv-001" \
     -H "x-task-id: task-abc" \
     -H "x-request-id: req-123" \
     -d '{"model":"gpt-4o","messages":[{"role":"user","content":"记忆中有什么信息？"}]}'

```

## Key Implementation Files

The following source files define the integration behavior:

- [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts): HTTP Gateway implementation exposing OpenAI-compatible endpoints (port 8420)
- [`MemoryCore/src/gateway/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/config.ts): Environment variable mapping and YAML configuration loading
- [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md): Header requirements and v1 plugin usage documentation
- [`agents/skills/setup-proxy/setup-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/skills/setup-proxy/setup-proxy.sh): Multi-agent header synchronization script
- [`README.deployment.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.deployment.md): Complete deployment guide covering lines 303-330 (plugin configuration) and lines 553-560 (end-to-end flow)

## Summary

- **TencentDB Agent Memory** exposes an OpenAI-compatible HTTP Gateway at `http://127.0.0.1:8420` via [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)
- **Header preselection** requires three custom headers: `x-conversation-id`, `x-task-id`, and `x-request-id`
- The **v1 plugin** implements automatic **prefetch** calls to retrieve relevant memories before each LLM request
- **Cross-session memory** persists when maintaining consistent `x-task-id` values across different `x-conversation-id` values
- **Memory Proxy** ([`setup-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/setup-proxy.sh)) manages header synchronization for multi-agent deployments

## Frequently Asked Questions

### What are the required headers for integrating TencentDB Agent Memory with Hermes Agent?

You must provide three headers: `x-conversation-id` (session identifier), `x-task-id` (business task identifier), and `x-request-id` (unique request identifier). These headers enable the **Header preselection** mechanism described in [`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md), allowing the Gateway to register sessions and inject relevant memories without interactive authentication.

### How does the v1 plugin handle memory retrieval?

The v1 plugin, implemented in the `memory_tencentdb` package, automatically calls the **prefetch** interface before forwarding requests to the LLM. This retrieves vector-similar memories from the L0-L3 hierarchy (Conversation, Atomic Memory, Scene Blocks, Persona) based on the current `x-conversation-id` and `x-task-id`, then injects them into the conversation context.

### Can I share memories across different conversation sessions?

Yes. By maintaining the same `x-task-id` and `x-request-id` while changing the `x-conversation-id`, the Memory Gateway treats the request as part of the same business task but a new session. The **prefetch** mechanism retrieves memories associated with the task ID, enabling cross-session continuity as documented in [`README.deployment.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.deployment.md) (lines 553-560).

### Where is the OpenAI-compatible endpoint defined in the source code?

The endpoint is defined in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts), which binds to port 8420 by default and implements the `/v1/chat/completions` route. The configuration mapping between environment variables and the server instance is handled in [`MemoryCore/src/gateway/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/config.ts).