# TencentDB Agent Memory API Endpoints for Conversation Management: Complete v3 Reference > Explore TencentDB Agent Memory API endpoints for conversation management. Master add, query, search, delete, count, and clear chat memory actions with our v3 reference. - Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) - Tags: api-reference - Published: 2026-08-28 --- **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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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 // 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/.../conversation-add/add-handler.ts), while the HTTP route is registered in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (line 144), it returns the conversation history for a given `session_id` with configurable pagination. ```python # 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (line 152), this enables semantic retrieval across all sessions for a given tenant. ```typescript 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (line 160), you must provide one of these fields to execute the deletion. ```typescript 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (line 176). ```python 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (line 617), it clears all L0/L1/L2/L3 data belonging to one or more `chat_memory--` 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. ```typescript await client.clearChatMemory({ memory_ids: ['chat_memory-t_1-agt_1'] }); ``` The handler implementation is located in [`MemoryCore/src/gateway/chat-memory-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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 ` 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: ```json { "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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/sdk/memory-core/typescript/src/v3/client.ts) exposes methods including `addConversation`, `queryConversation`, `searchConversation`, `deleteConversation`, `countConversation`, and `clearChatMemory` (around line 390). ```typescript import { MemoryClient } from '@tencentdb-agent-memory/memory-sdk-ts/v3'; const client = new MemoryClient({ endpoint: 'https://memory.tencentyun.com', apiKey: '', 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`. ```python from tencentdb_agent_memory.v3.client import V3MemoryClient client = V3MemoryClient( endpoint='https://memory.tencentyun.com', 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md)** – Master documentation listing all `/v3/*` endpoints with complete request/response schemas. - **[`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/chat-memory-handlers.ts)** – Implementation of the chat-memory clear operation. - **[`MemoryCore/sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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 `. 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.