Batch Delete Limits and `normalizeDeleteIds` Deduplication in TencentDB Agent Memory SDK

The TencentDB Agent Memory SDK enforces strict batch delete limits (100-5,000 items) through a client-side normalizeDeleteIds helper that validates, trims, deduplicates, and bounds-checks ID arrays before sending requests to the server.

The TencentDB Agent Memory SDK provides a TypeScript client for managing conversation history, knowledge bases, and memory entries in TencentDB. A critical safety mechanism in this SDK is the batch delete validation system, which prevents accidental mass deletions and malformed payloads. At the heart of this system lies the normalizeDeleteIds utility function implemented in client.ts.

What normalizeDeleteIds Does

The normalizeDeleteIds function (lines 33-45 in [sdk/memory-core/typescript/src/v3/client.ts](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts)) is a six-step pipeline that processes ID arrays before any API call is made:

• Step 1 — Input check: Returns undefined when the caller omits the field entirely, signaling "not supplied" to the API.
• Step 2 — Type validation: Throws ParamError if the value is not an array.
• Step 3 — Content validation: Rejects any element that isn't a non-empty string; whitespace-only strings fail validation.
• Step 4 — Normalization and deduplication: Trims whitespace, creates a Set to eliminate duplicates, then spreads back to a clean array.
• Step 5 — Upper-bound enforcement: Compares the deduplicated length against a caller-provided max limit.
• Step 6 — Return: Returns the validated, deduplicated array.

Because this logic runs before the HTTP request is sent, the SDK catches malformed or oversized payloads locally—saving a network round-trip that would otherwise result in a 400 error from the server.

Batch Delete Limits by API Endpoint

SDK Method	Field Name	Maximum Items	Source Reference
deleteConversation	message_ids	5,000	normalizeDeleteIds(..., 5000)
deleteConversation	session_ids	100	normalizeDeleteIds(..., 100)
metadataClient.deleteKnowledge	knowledge_ids	100	normalizeDeleteIds(..., 100)
deleteMemory	memory_ids	100	normalizeDeleteIds(..., 100)

The appropriate limit is hardcoded at each call site in client.ts. When you invoke deleteConversation with message_ids, the SDK internally calls normalizeDeleteIds(rawIds, 5000). For session_ids in the same method, it passes 100 instead.

How Deduplication Works

Duplicate IDs are automatically collapsed during Step 4. The implementation uses a concise pattern:

const deduped = [...new Set(raw.map((id) => id.trim()))];

This guarantees that the final request contains each ID exactly once, even if your input array includes repeated values or inconsistent whitespace. The deduplication happens after trimming but before the bounds check, so duplicates cannot be used to bypass the maximum limit.

Practical Code Examples

Delete up to 5,000 conversation messages

import { MemoryClient } from '@tencentcloud/memory-core';

const client = new MemoryClient({ /* your config */ });

await client.deleteConversation({
  message_ids: [
    'msg-001', 'msg-002', 'msg-001',  // duplicate automatically removed
    '  msg-003  ',                    // whitespace trimmed
    // ... up to 5,000 total
  ],
  session_ids: ['sess-A', 'sess-B'],  // optional, max 100
});

Delete knowledge assets (max 100)

import { MetadataClient } from '@tencentcloud/memory-core';

const meta = new MetadataClient({ /* your config */ });

await meta.deleteKnowledge(['doc-1', 'doc-2', 'doc-1'], 'team-123');
// Throws ParamError if >100 unique IDs or any blank string present

Delete memory entries (max 100)

await client.deleteMemory({
  memory_ids: ['mem-100', 'mem-101'],
});

Error handling for invalid input

try {
  await client.deleteConversation({ message_ids: [] });
} catch (e) {
  console.error(e.message);
  // "message_ids must be an array of non-empty strings"
}

Key Source Files

File	Purpose
client.ts	Core client with normalizeDeleteIds implementation (source)
metadata-client.ts	Knowledge API wrapper that delegates to normalizeDeleteIds (source)
knowledge-handlers.ts	Server-side handler receiving cleaned ID lists (source)
tcvdb.ts	Persistence layer implementing DB-level batch deletes (source)

Summary

• Batch delete limits are enforced client-side before any network request: 5,000 for message/atomic deletions, 100 for sessions, knowledge, and memory.
• normalizeDeleteIds validates type, content, duplicates, and bounds in a single pipeline.
• Deduplication uses Set construction after whitespace trimming, ensuring clean payloads.
• Early failure via ParamError prevents wasted round-trips and server load from invalid requests.

Frequently Asked Questions

What happens if I exceed the batch delete limit?

The SDK throws a ParamError immediately with a descriptive message. No HTTP request is sent to the server. You must split your IDs into multiple calls or reduce the batch size.

Does whitespace affect ID deduplication?

Yes. The normalizeDeleteIds function trims all strings before deduplication, so " id-1 " and "id-1" are treated as identical and collapsed to a single entry.

Can I bypass limits by including duplicate IDs?

No. Deduplication occurs before the bounds check. A list of 150 unique session IDs with 50 duplicates still counts as 150 items and will trigger the limit error for the 100-item threshold.

Why are conversation message_ids allowed 5,000 items while session_ids are limited to 100?

Message deletions are common cleanup operations that may involve large historical batches. Session deletions are more destructive (removing entire conversation contexts), so the stricter limit prevents accidental broad deletions.

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