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

> Learn how to integrate TencentDB Agent Memory with OpenClaw. Deploy the memory proxy and configure essential headers for seamless integration. Get started now.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```bash
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>`:

```json
{
  "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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.yaml) to add a default task ID:

```yaml
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/v3-api-memoryproxy-doc.md)**: Documents the API specification and header-auto-select logic
- **[`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/openclaw-state-dir.ts)**: Resolves the OpenClaw state directory when running as a plugin
- **[`agents/openclaw/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/openclaw/README.md)**: Contains specific OpenClaw client configuration requirements
- **[`INSTALL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.