TencentDB Agent Memory API Endpoints for Conversation Management: Complete v3 Reference

TencentDB Agent Memory exposes six primary API endpoints for managing conversation memory: five L0 Conversation endpoints (add, query, search, delete, count) under /v3/conversation/* and one Chat-Memory management endpoint (/v3/chat-memory/clear) for clearing layered memory assets while preserving metadata.

The TencentDB Agent Memory service implements a tiered memory architecture where conversation data is managed through a set of RESTful v3 APIs. Understanding these API endpoints for managing conversation memory in TencentDB Agent Memory is essential for building multi-turn dialogue systems that require persistent context across sessions.

L0 Conversation Memory API Endpoints

The L0 (raw dialogue) layer provides full CRUD operations over conversation records. All five endpoints share a common request envelope and require team_id, agent_id, and user_id for multi-tenant isolation.

Add Messages to Conversation

POST /v3/conversation/add writes new messages to a session.

This endpoint accepts 1–100 L0 messages per request. According to the source documentation in MemoryCore/v3-api-memorycore-doc.md (line 109), the request body must include a session_id and a messages array containing role and content objects.

// TypeScript SDK example
await client.addConversation({
  session_id: 'sess_123',
  messages: [{ role: 'user', content: 'What is the latency?' }],
});

The handler logic resides in MemoryCore/src/core/.../conversation-add/add-handler.ts, while the HTTP route is registered in MemoryCore/src/gateway/v2-router.ts under the path "/conversation/add".

Query Conversation Messages

POST /v3/conversation/query paginates L0 messages for a specific session.

This endpoint supports limit, offset, and time-range filtering parameters. As documented in MemoryCore/v3-api-memorycore-doc.md (line 144), it returns the conversation history for a given session_id with configurable pagination.

# Python SDK example

resp = client.query_conversation(session_id='sess_123')
print(resp['data']['accepted_messages'])

Search Conversation Memory

POST /v3/conversation/search performs full-text search over L0 messages.

The search endpoint accepts a query string of 1–2048 characters and returns matching messages with relevance scores. Referenced in MemoryCore/v3-api-memorycore-doc.md (line 152), this enables semantic retrieval across all sessions for a given tenant.

const search = await client.searchConversation({ query: 'latency' });
console.log(search.data.messages);

Delete Conversation Records

POST /v3/conversation/delete removes messages by ID or session.

This bulk deletion endpoint accepts either message_ids or session_ids (mutually exclusive). As noted in MemoryCore/v3-api-memorycore-doc.md (line 160), you must provide one of these fields to execute the deletion.

await client.deleteConversation({ message_ids: ['msg_a', 'msg_b'] });

Count Conversation Messages

POST /v3/conversation/count returns totals with optional filtering.

This aggregation endpoint calculates the total number of L0 messages, supporting filters by session or time range. The implementation details are documented in MemoryCore/v3-api-memorycore-doc.md (line 176).

cnt = client.count_conversation(team_id='t_1')
print(cnt['data']['total'])

Chat-Memory Management Endpoint

Clear Chat Memory Contents

POST /v3/chat-memory/clear empties layered memory while preserving metadata.

Unlike the L0 endpoints that operate on individual messages, this endpoint targets the entire memory asset. According to MemoryCore/v3-api-memorycore-doc.md (line 617), it clears all L0/L1/L2/L3 data belonging to one or more chat_memory-<team>-<agent> assets while retaining ownership, bindings, ACL, and visibility settings.

Important security note: This endpoint does not perform user-level Owner checks. The front-panel or UI layer must enforce "Owner-only" validation before proxying the request. The operation is idempotent; invoking it on an already-cleared memory returns cleared: true with zero deletions.

await client.clearChatMemory({ memory_ids: ['chat_memory-t_1-agt_1'] });

The handler implementation is located in MemoryCore/src/gateway/chat-memory-handlers.ts.

Authentication and Multi-Tenant Isolation

All v3 data-plane APIs require Bearer token authentication via the Authorization: Bearer <KERNEL_AUTH_TOKEN> header.

Isolation fields ensure strict multi-tenant separation. Every request must carry team_id, agent_id, and user_id either in the JSON body or via HTTP headers (x-tdai-team-id, x-tdai-agent-id, x-tdai-user-id). For data-plane calls, the trio team_id + agent_id + user_id is mandatory; missing values fall back to the default bucket.

The standard response envelope across all endpoints follows this structure:

{
  "code": 0,
  "message": "ok",
  "request_id": "...",
  "data": { }
}

SDK Implementation Examples

The official SDKs map 1:1 to the HTTP endpoints described above.

TypeScript SDK v3

The TypeScript client implementation in MemoryCore/sdk/memory-core/typescript/src/v3/client.ts exposes methods including addConversation, queryConversation, searchConversation, deleteConversation, countConversation, and clearChatMemory (around line 390).

import { MemoryClient } from '@tencentdb-agent-memory/memory-sdk-ts/v3';

const client = new MemoryClient({
  endpoint: 'https://memory.tencentyun.com',
  apiKey: '<YOUR_API_KEY>',
  serviceId: 'instance-1',
});

// Add messages
await client.addConversation({
  session_id: 'sess_123',
  messages: [{ role: 'user', content: 'What is the latency?' }],
});

// Query first 20 messages
const q = await client.queryConversation({ session_id: 'sess_123' });
console.log(q.data.accepted_messages);

// Search across sessions
const s = await client.searchConversation({ query: 'latency' });
console.log(s.data.messages);

// Delete by message IDs
await client.deleteConversation({ message_ids: ['msg_a', 'msg_b'] });

// Count total messages
const cnt = await client.countConversation({ team_id: 't_1' });
console.log('total L0 msgs:', cnt.data.total);

// Clear chat memory asset
await client.clearChatMemory({ memory_ids: ['chat_memory-t_1-agt_1'] });

Python SDK v3

The Python implementation in MemoryCore/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py provides equivalent convenience methods: add_conversation, query_conversation, search_conversation, delete_conversation, count_conversation, and clear_chat_memory.

from tencentdb_agent_memory.v3.client import V3MemoryClient

client = V3MemoryClient(
    endpoint='https://memory.tencentyun.com',
    api_key='<YOUR_API_KEY>',
    service_id='instance-1',
)

# Add messages

client.add_conversation(
    session_id='sess_123',
    messages=[{'role': 'user', 'content': 'How many instances?'}],
)

# Query conversation

resp = client.query_conversation(session_id='sess_123')
print(resp['data']['accepted_messages'])

# Full-text search

search = client.search_conversation(query='instances')
print(search['data']['messages'])

# Bulk delete

client.delete_conversation(message_ids=['msg_x'])

# Count messages

cnt = client.count_conversation(team_id='t_1')
print(cnt['data']['total'])

# Clear memory contents

client.clear_chat_memory(memory_ids=['chat_memory-t_1-agt_1'])

Key Source Files and Architecture

Understanding the following source files provides deeper insight into the endpoint implementations:

• MemoryCore/v3-api-memorycore-doc.md – Master documentation listing all /v3/* endpoints with complete request/response schemas.
• MemoryCore/src/gateway/v2-router.ts – HTTP routing registration mapping paths like "/conversation/add" to their respective handlers.
• MemoryCore/src/core/.../conversation-add/add-handler.ts – Core logic for the add operation and related conversation management.
• MemoryCore/src/gateway/chat-memory-handlers.ts – Implementation of the chat-memory clear operation.
• MemoryCore/sdk/memory-core/typescript/src/v3/client.ts – TypeScript SDK client exposing wrapper methods for all endpoints.
• MemoryCore/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py – Python SDK client providing equivalent functionality.

Summary

• Five L0 Conversation endpoints (/v3/conversation/add, /query, /search, /delete, /count) provide full lifecycle management for raw dialogue records.
• One Chat-Memory endpoint (/v3/chat-memory/clear) clears layered memory data while preserving asset metadata and permissions.
• Multi-tenant isolation requires team_id, agent_id, and user_id for all data-plane operations.
• SDK implementations in TypeScript and Python offer 1:1 method mappings to the REST endpoints for simplified integration.

Frequently Asked Questions

What is the maximum number of messages I can add in a single API call?

According to the MemoryCore/v3-api-memorycore-doc.md specification, the /v3/conversation/add endpoint accepts between 1 and 100 L0 messages per request. Exceeding this limit requires batching across multiple calls.

Does the clear chat-memory endpoint delete the memory asset itself?

No. The /v3/chat-memory/clear endpoint only empties the L0/L1/L2/L3 data contents. As implemented in MemoryCore/src/gateway/chat-memory-handlers.ts, it preserves the asset metadata including ownership, bindings, ACL settings, and visibility configurations.

How does the API enforce security between different teams?

The API requires the isolation fields team_id, agent_id, and user_id on every data-plane request, passed either in the JSON body or via x-tdai-* HTTP headers. The routing layer in MemoryCore/src/gateway/v2-router.ts validates these fields to ensure strict multi-tenant separation, routing requests to the appropriate isolated bucket.

What authentication method is required for these endpoints?

All v3-level conversation memory endpoints require Bearer token authentication using the header Authorization: Bearer <KERNEL_AUTH_TOKEN>. Additionally, the chat-memory clear endpoint expects the front-panel to perform Owner verification before proxying the request, as the endpoint itself does not enforce user-level ownership checks.

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