How to Integrate TencentDB Agent Memory with OpenClaw: Complete Setup Guide

Integrate TencentDB Agent Memory with OpenClaw by deploying the memory proxy and configuring four mandatory headers (x-team-id, x-agent-id, x-task-id, x-conversation-id) in your OpenClaw client configuration.

TencentDB Agent Memory (TD Agent Memory) provides a centralized memory hub that enables persistent context across AI agent conversations. When integrated with OpenClaw, this system intercepts chat requests through a local proxy, automatically injects relevant memory assets into system prompts, and records interactions for future retrieval. This guide covers the complete TencentDB Agent Memory OpenClaw integration based on the source code in the TencentCloud/TencentDB-Agent-Memory repository.

Architecture Overview

The integration operates through three distinct layers that work together to provide seamless memory augmentation.

Memory Proxy Layer

The MemoryProxy acts as a thin HTTP gateway that forwards OpenAI-style requests to upstream LLMs while injecting memory assets. According to MemoryProxy/v3-api-memoryproxy-doc.md, the proxy reads the headers x-team-id, x-agent-id, x-task-id, and x-conversation-id to augment the system prompt with relevant Chat Memory, Skills, Wiki, and CodeGraph assets.

Memory Core Layer

Located in MemoryCore/src/core/tdai-core.ts, the core service stores all assets in a SQLite database and runs extraction pipelines. These pipelines transform raw conversations (L0) into atoms (L1), scenes (L2), and personas (L3). The core exposes /v3 APIs used by the proxy for real-time memory retrieval.

OpenClaw Client Layer

A standard OpenClaw installation communicates with the proxy as if it were an OpenAI provider. As documented in agents/openclaw/README.md, the client sends the four mandatory headers, and the proxy registers the session automatically without requiring interactive forms.

Prerequisites and Deployment

Before configuring the integration, you must deploy the full service stack.

Deploy the three-service stack (memory-core, memory-hub, proxy) using the all-in-one script:

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
./start-all.sh

This interactive script creates the necessary .env file and generates an admin key. Once running, the Memory Hub UI becomes available at http://localhost:8125, where you must create a Team, Agent, and optional Task to obtain the numeric IDs required for the headers.

Configuration Steps

1. Configure the OpenClaw Provider

Edit ~/.openclaw/openclaw.json to add the memory proxy as a provider. The baseUrl points to the proxy's OpenClaw endpoint at http://<proxy-host>:8096/openclaw/<spaceId>:

{
  "models": {
    "mode": "merge",
    "providers": {
      "memory-proxy": {
        "baseUrl": "http://127.0.0.1:8096/openclaw/default",
        "apiKey": "<business user sk-mem-...>",
        "api": "openai-completions",
        "headers": {
          "x-team-id": "42",
          "x-agent-id": "7",
          "x-task-id": "3",
          "x-conversation-id": "session-001"
        },
        "request": {
          "allowPrivateNetwork": true
        },
        "models": [
          {
            "id": "gpt-5.5",
            "name": "GPT-5.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 32000,
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
          }
        ]
      }
    }
  }
}

2. Set Required Headers

The four headers in the headers object drive the entire integration:

• x-team-id: Identifies the team context from the Memory Hub
• x-agent-id: Specifies which agent configuration to load
• x-task-id: Required by the proxy for OpenClaw sessions (see known limitations in INSTALL.md)
• x-conversation-id: Identifies the specific conversation thread

3. Optional: Disable Task Requirement

If you prefer not to create a task for every session, edit the proxy's generated config.yaml to add a default task ID:

sessionInit:
  defaultTaskId: "no-task"

This configuration bypasses the requirement to specify unique task IDs for each conversation while maintaining full memory functionality.

Understanding the Header-Driven Integration

When all four headers are present and valid, the proxy executes a specific workflow defined in MemoryCore/src/core/tdai-core.ts:

1. Immediate Session Registration: The proxy registers the session automatically using the header values—no interactive form step is required
2. Memory Injection: The proxy queries the Memory Core for relevant assets and injects them into the first system message
3. Conversation Recording: The interaction is stored in the SQLite database for future L0-L3 extraction pipelines

If any header is missing, the request bypasses the injection logic and is simply forwarded to the upstream LLM (the "session bypass" path).

Verifying the Integration

Test that requests are being properly injected using a direct curl command to the proxy endpoint:

curl -X POST http://127.0.0.1:8096/openclaw/default/v1/chat/completions \
  -H "Authorization: Bearer <sk-mem-...>" \
  -H "x-team-id: 42" \
  -H "x-agent-id: 7" \
  -H "x-task-id: 3" \
  -H "x-conversation-id: session-001" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"What is the project name?"}]}'

A successful integration returns responses augmented with memory context from previous conversations stored in the team's memory hub.

Key Source File References

Understanding these core files helps troubleshoot integration issues:

• MemoryProxy/v3-api-memoryproxy-doc.md: Documents the API specification and header-auto-select logic
• MemoryCore/src/core/tdai-core.ts: Core entry point used by both OpenClaw (in-process) and the proxy (out-of-process)
• MemoryCore/src/utils/openclaw-state-dir.ts: Resolves the OpenClaw state directory when running as a plugin
• agents/openclaw/README.md: Contains specific OpenClaw client configuration requirements
• INSTALL.md: Details the known limitation regarding x-task-id and the optional sessionInit.defaultTaskId configuration

Summary

The TencentDB Agent Memory OpenClaw integration creates a persistent memory layer for AI agents through a proxy-based architecture. Key takeaways include:

• Deploy the full stack using start-all.sh before attempting client configuration
• Configure four mandatory headers (x-team-id, x-agent-id, x-task-id, x-conversation-id) in ~/.openclaw/openclaw.json
• Set sessionInit.defaultTaskId in the proxy config to make task IDs optional
• The proxy automatically registers sessions and injects memory assets without interactive forms
• Missing headers trigger a bypass mode where requests forward directly to the LLM without memory augmentation

Frequently Asked Questions

What happens if I don't provide all four required headers?

If any of the headers (x-team-id, x-agent-id, x-task-id, x-conversation-id) are missing, the proxy enters a "session bypass" path. The request forwards directly to the upstream LLM without memory injection or recording. As implemented in MemoryCore/src/core/tdai-core.ts, the proxy requires all identifiers to locate and inject the correct memory assets.

How do I rotate conversation IDs for fresh sessions?

OpenClaw does not automatically rotate the x-conversation-id value. You must manually change this header in your ~/.openclaw/openclaw.json configuration when you want to start a fresh session. According to agents/openclaw/README.md, maintaining the same conversation ID continues the existing memory context, while changing it creates a new isolated session.

Can I use TencentDB Agent Memory with OpenClaw without creating tasks?

Yes. While the proxy normally requires an x-task-id header, you can disable this requirement by editing the proxy's config.yaml. Add the sessionInit.defaultTaskId setting with a constant value (such as "no-task"), as documented in the "Known limitation: x-task-id" section of INSTALL.md. This allows the integration to function without explicit task creation in the Memory Hub UI.

Where does the proxy store the conversation data?

The Memory Core stores all conversation data in a SQLite database, as referenced in MemoryCore/src/core/tdai-core.ts. The proxy itself is stateless and acts only as a gateway. The core service handles the extraction pipelines that transform raw conversations (L0) into structured atoms (L1), scenes (L2), and personas (L3) for future retrieval.

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