v3 /v3/conversation/* Endpoints: Add, Query, Search, Delete, and Count Operations Explained

The Memory Core service exposes five ops-only HTTP endpoints under /v3/conversation/—add, query, search, delete, and count—that manage L0 conversation messages with a unified response envelope.

The TencentDB-Agent-Memory repository provides a complete v3 API surface for managing L0 (conversation-level) message storage. These /v3/conversation/* endpoints form the foundation of the memory layer, enabling agents to persist dialogue history, retrieve paginated records, perform full-text search, prune obsolete data, and obtain usage statistics. All five operations share a consistent contract: they accept JSON request bodies, return envelopes with code, message, and data fields, and treat code: 0 as success.

---

Endpoint Overview

Operation	HTTP Method	Path	Purpose
Add	POST	/v3/conversation/add	Append one or multiple L0 messages to a session
Query	POST	/v3/conversation/query	Paginated retrieval with filtering by session, time range, etc.
Search	POST	/v3/conversation/search	Keyword-based full-text search across messages
Delete	POST	/v3/conversation/delete	Batch removal of messages or entire sessions
Count	POST	/v3/conversation/count	Return total matching messages with optional filters

The authoritative specification lives in [MemoryCore/v3-api-memorycore-doc.md](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/v3-api-memorycore-doc.md) at lines 9–76.

---

POST /v3/conversation/add: Writing L0 Messages

The add endpoint persists conversation turns and triggers asynchronous L1 extraction pipelines for downstream memory layers.

Request Body Schema

{
  "session_id": "string",
  "messages": [
    {
      "role": "user|assistant",
      "content": "string (1-8192 chars)",
      "timestamp": "ISO-8601? (optional)",
      "recorded_at": "ISO-8601? (optional)"
    }
  ],
  "team_id": "string?",
  "agent_id": "string?",
  "user_id": "string?",
  "task_id": "string?"
}

• session_id (required): Business session identifier
• messages: Array of 1–100 message objects
• Isolation fields: v3 enforces team_id + agent_id + user_id for multi-tenant boundaries

Response Data Fields

Field	Type	Description
accepted_ids	string[]	Storage identifiers for accepted messages
accepted_versions	string[]	Version tags (currently always "v1")
total_count	number	Count of messages successfully stored

cURL Example

curl -X POST http://localhost:8420/v3/conversation/add \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_1","messages":[{"role":"user","content":"帮我看看这个 bug"}]}'

---

POST /v3/conversation/query: Paginated Retrieval

The query endpoint lists stored messages with cursor-style pagination and temporal filtering.

Request Parameters (All Optional)

Field	Type	Default / Limits
session_id	string	—
limit	number	20 (max 100)
offset	number	—
time_start / time_end	string (ISO-8601)	—
team_id, agent_id, user_id	string	Tenant isolation

Response Structure

{
  "messages": [
    {
      "id": "string",
      "version": "string",
      "role": "user|assistant",
      "content": "string",
      "timestamp": "string?",
      "recorded_at": "string?",
      "session_id": "string?",
      "team_id": "string?",
      "user_id": "string?",
      "agent_id": "string?"
    }
  ],
  "total": "number"
}

cURL Example

curl -X POST http://localhost:8420/v3/conversation/query \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_1","limit":10}'

---

POST /v3/conversation/search: Full-Text Search

The search endpoint performs relevance-scored keyword matching across message contents.

Request Body

Field	Type	Required
query	string (1-2048 chars)	Yes
limit	number (default 5, max 100)	No
session_id	string	No
time_start / time_end	string (ISO-8601)	No
Isolation fields	string	No

Response with Relevance Scores

{
  "messages": [
    {
      "id": "string",
      "role": "user|assistant",
      "content": "string",
      "score": "number"
    }
  ]
}

The score field indicates textual relevance for ranking results.

cURL Example

curl -X POST http://localhost:8420/v3/conversation/search \
  -H "Content-Type: application/json" \
  -d '{"query":"bug","limit":5}'

---

POST /v3/conversation/delete: Batch Removal

The delete endpoint supports two mutually exclusive bulk deletion modes.

Deletion Modes (Supply Exactly One)

Field	Type	Constraint
message_ids	string[]	≤ 5,000 IDs
session_ids	string[]	≤ 100 IDs
session_id	string	Deprecated—use session_ids

Response

{
  "deleted_count": "number"
}

cURL Example

curl -X POST http://localhost:8420/v3/conversation/delete \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["msg_1","msg_2"]}'

---

POST /v3/conversation/count: Usage Statistics

The count endpoint returns aggregated totals for capacity planning and UI pagination.

Request Filters (All Optional)

Field	Type
session_id	string
time_start / time_end	string (ISO-8601)
Isolation fields	string

Response

{
  "total": "number"
}

cURL Example

curl -X POST http://localhost:8420/v3/conversation/count \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_1"}'

---

TypeScript SDK Usage

The [sdk/memory-core/typescript/README.md](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/README.md) provides typed client methods that mirror these five endpoints exactly.

import { MemoryCoreClient } from '@tencentdb/memory-core';

const client = new MemoryCoreClient({ baseURL: 'http://localhost:8420' });

async function workflow() {
  // Add messages
  await client.addConversation({
    session_id: 'sess_1',
    messages: [{ role: 'user', content: '帮我看看这个 bug' }]
  });

  // Query with pagination
  const query = await client.queryConversation({
    session_id: 'sess_1',
    limit: 5
  });

  // Search by keyword
  const search = await client.searchConversation({ query: 'bug' });

  // Delete by IDs from query results
  const ids = query.data.messages.map(m => m.id);
  await client.deleteConversation({ message_ids: ids });

  // Verify count
  const count = await client.countConversation({ session_id: 'sess_1' });
  console.log('Remaining messages:', count.data.total);
}

Python equivalents are documented in [sdk/memory-core/python/README.md](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/python/README.md).

---

Summary

• /v3/conversation/add persists 1–100 messages per call and triggers async L1 extraction
• /v3/conversation/query retrieves paginated message histories with optional time bounding
• /v3/conversation/search executes relevance-scored full-text search across content fields
• /v3/conversation/delete removes batches of messages (≤ 5,000) or sessions (≤ 100)
• /v3/conversation/count returns filtered totals for all matching L0 records
• All endpoints use POST, return unified envelopes, and respect team_id/agent_id/user_id isolation in v3

---

Frequently Asked Questions

What is the maximum number of messages per add request?

The /v3/conversation/add endpoint accepts 1–100 messages in a single messages array. Requests exceeding this limit are rejected before processing.

How do I delete an entire session instead of individual messages?

Pass the session_ids array (max 100 IDs) rather than message_ids. The deprecated session_id string parameter should be avoided in favor of the plural form.

Does the search endpoint support filtering by time range?

Yes. Supply optional time_start and time_end ISO-8601 strings alongside the required query parameter to constrain results temporally.

Where are the official API contracts documented?

The Memory Core v3 API documentation at [MemoryCore/v3-api-memorycore-doc.md](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/v3-api-memorycore-doc.md) provides complete request/response schemas, with line references to each endpoint's specification.

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