# Required Headers for Data-Plane and Meta-Plane Requests in TencentDB Agent Memory

> Discover essential HTTP headers for TencentDB Agent Memory data-plane and meta-plane requests. Learn the required keys for agent and user identification. Master your data integration.

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

---

**TencentDB Agent Memory requires specific HTTP headers for data-plane requests (`x-tdai-user-key`, `x-tdai-team-id`, `x-tdai-agent-id`) and meta-plane requests (`x-team-id`, `x-agent-id`, `x-task-id`, `x-conversation-id`), with additional headers like `x-tdai-service-id` for Knowledge API calls.**

TencentDB Agent Memory separates traffic into two logical planes—**Data-Plane** (Memory Core) and **Meta-Plane** (Memory Proxy)—each with distinct authentication and routing requirements. Sending the correct headers ensures proper session registration, asset injection, and access control. This guide covers the exact header specifications as implemented in the [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) repository.

## Data-Plane Headers: Memory Core Required Headers

Data-plane requests target the Memory Core endpoints (`/v3/memory/...`, `/v3/knowledge/...`). These three headers are **mandatory** for every request.

### Required Data-Plane Headers

| Header | Purpose | Example |
|--------|---------|---------|
| `x-tdai-user-key` | API key identifying the user | `ak-1234567890abcdef` |
| `x-tdai-team-id` | Team the request belongs to | `team-prod-001` |
| `x-tdai-agent-id` | Agent that will act on the request | `agent-chatbot-v2` |

The Core validates `x-tdai-user-key` through meta-authentication middleware. Successful validation extracts `team_id`, `agent_id`, and optional `task_id` from corresponding headers or request body, as documented in [[`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/README.md#L186-L190).

### Optional Data-Plane Headers

- **`x-tdai-task-id`** — Narrows the request to a specific task context
- **`x-tdai-session-id`** — Enables per-session isolation for fine-grained scoping

```typescript
// TypeScript SDK: Data-Plane request to Memory Core
import { MemoryCoreClient } from '@tencentdb-agent-memory/memory-core';

const client = new MemoryCoreClient({
  baseUrl: 'http://localhost:8125',
  headers: {
    'x-tdai-user-key': process.env.TDAI_USER_KEY!,
    'x-tdai-team-id': process.env.TDAI_TEAM_ID!,
    'x-tdai-agent-id': process.env.TDAI_AGENT_ID!,
    'x-tdai-task-id': process.env.TDAI_TASK_ID,      // optional
    'x-tdai-session-id': 'session-1234',              // optional
  },
});

await client.memory.addConversation({ /* payload */ });

```

## Meta-Plane Headers: Memory Proxy Required Headers

Meta-plane requests target Proxy endpoints (`/meta/auth/verify`, `/meta/instances`). These headers enable **header auto-selection**—immediate session registration without interactive forms.

### Required Meta-Plane Headers

| Header | Purpose | Required For |
|--------|---------|--------------|
| `x-team-id` | Team identifier | All meta-plane requests |
| `x-agent-id` | Agent identifier | All meta-plane requests |
| `x-task-id` | Task identifier | Header-pre-select agents (Hermes/OpenClaw) |
| `x-conversation-id` | Per-Pi session identifier | Session registration and asset injection |

According to [[`INSTALL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/INSTALL.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/INSTALL.md#L287-L292), when `x-team-id`, `x-agent-id`, **and** `x-task-id` are all present and valid, the Proxy registers the session immediately and injects memory assets. Missing headers trigger fallback to interactive session initialization.

### Additional Meta-Plane Headers

- **`x-tdai-user-key`** — Required for any request passing authentication middleware (same key used in Data-Plane)
- **`x-tdai-service-id`** — Required by Knowledge API when querying wiki resources

```python

# Python: Meta-Plane request to Memory Proxy

import requests
import os

url = 'http://localhost:8125/meta/auth/verify'
headers = {
    'x-tdai-user-key': os.getenv('TDAI_USER_KEY'),
    'x-team-id': os.getenv('TDAI_TEAM_ID'),
    'x-agent-id': os.getenv('TDAI_AGENT_ID'),
    'x-task-id': os.getenv('TDAI_TASK_ID'),      # required for header-pre-select

    'x-conversation-id': 'conv-5678',
}
resp = requests.post(url, json={}, headers=headers)
print(resp.json())

```

## Knowledge API: Special Header Requirements

Calls to `/v3/knowledge/...` endpoints require `x-tdai-service-id` to identify the target wiki or knowledge graph, per [[`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryKnowledge/v3-api-memoryknowledge-doc.md#L65-L70).

```bash

# Curl: Knowledge query with service identification

curl -X POST https://api.example.com/v3/knowledge/query \
  -H "x-tdai-user-key: $TDAI_USER_KEY" \
  -H "x-tdai-team-id: $TDAI_TEAM_ID" \
  -H "x-tdai-agent-id: $TDAI_AGENT_ID" \
  -H "x-tdai-service-id: wiki-42" \
  -d '{"query":"How does the caching layer work?"}'

```

## Header Auto-Select Mechanism Explained

The Proxy's header auto-select behavior is governed by three conditions:

1. **All three headers present** (`x-team-id`, `x-agent-id`, `x-task-id`) → Immediate session registration with memory asset injection
2. **Any header missing** → Fallback to interactive "session init" form flow
3. **Invalid header values** → Authentication failure with 401/403 response

This mechanism is specifically implemented for **header-pre-select agents** like Hermes and OpenClaw, documented in [[`agents/hermes/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/hermes/README.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/agents/hermes/README.md).

## Header Comparison: Data-Plane vs Meta-Plane

| Aspect | Data-Plane (Memory Core) | Meta-Plane (Memory Proxy) |
|--------|--------------------------|---------------------------|
| **Prefix** | `x-tdai-*` | `x-*` (short form) |
| **User identity** | `x-tdai-user-key` (required) | `x-tdai-user-key` (auth middleware) |
| **Team** | `x-tdai-team-id` | `x-team-id` |
| **Agent** | `x-tdai-agent-id` | `x-agent-id` |
| **Task** | `x-tdai-task-id` (optional) | `x-task-id` (required for pre-select) |
| **Session** | `x-tdai-session-id` (optional) | `x-conversation-id` (required) |

## Summary

- **Data-plane requests** require `x-tdai-user-key`, `x-tdai-team-id`, and `x-tdai-agent-id` for Memory Core access
- **Meta-plane requests** use short-form headers (`x-team-id`, `x-agent-id`, `x-task-id`, `x-conversation-id`) for Proxy session management
- **Header auto-select** triggers immediate registration when all three Proxy headers are valid
- **Knowledge queries** need `x-tdai-service-id` to specify the target wiki or graph
- Source documentation is located in [[`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/README.md), [[`MemoryProxy/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/README.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryProxy/README.md), and [[`INSTALL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/INSTALL.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/INSTALL.md)

## Frequently Asked Questions

### What happens if I omit `x-task-id` in a meta-plane request?

The Proxy falls back to interactive session initialization. Without `x-task-id`, header auto-select cannot complete, forcing users through a manual form flow to establish session context.

### Is `x-tdai-user-key` required for both planes?

Yes. While the Data-Plane requires it as the primary identity header, the Meta-Plane also needs `x-tdai-user-key` for any request passing through authentication middleware—even though the short-form headers handle routing.

### Can I use the same agent ID across multiple teams?

Yes. The `agent_id` is scoped by `team_id`, so identical agent identifiers in different teams reference distinct agent instances with separate memory stores.

### Why do Knowledge endpoints need `x-tdai-service-id` separately?

TencentDB Agent Memory supports multiple knowledge sources (wikis, graphs) per team. The `service_id` disambiguates which repository to query, enabling multi-tenant knowledge management without URL path changes.