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

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 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/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 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/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: 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/feat/server_team/MemoryKnowledge/v3-api-memoryknowledge-doc.md#L65-L70).

# 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/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/feat/server_team/MemoryCore/README.md), [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/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.

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