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

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, 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, 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 requires environment variables for your upstream LLM provider.

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.

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:

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

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

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

This script, located at 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:

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: HTTP Gateway implementation exposing OpenAI-compatible endpoints (port 8420)
• MemoryCore/src/gateway/config.ts: Environment variable mapping and YAML configuration loading
• agents/hermes/README.md: Header requirements and v1 plugin usage documentation
• agents/skills/setup-proxy/setup-proxy.sh: Multi-agent header synchronization script
• 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
• 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) 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, 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 (lines 553-560).

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

The endpoint is defined in 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.

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