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

> Understand TencentDB Agent Memory SDK batch delete limits (100-5000 items). Learn how normalizeDeleteIds deduplicates and validates ID arrays before server requests.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```typescript
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

```typescript
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)

```typescript
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)

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

```

### Error handling for invalid input

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) | Core client with `normalizeDeleteIds` implementation ([source](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts)) |
| [`metadata-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-client.ts) | Knowledge API wrapper that delegates to `normalizeDeleteIds` ([source](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/metadata-client.ts)) |
| [`knowledge-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/knowledge-handlers.ts) | Server-side handler receiving cleaned ID lists ([source](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/gateway/knowledge-handlers.ts)) |
| [`tcvdb.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tcvdb.ts) | Persistence layer implementing DB-level batch deletes ([source](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/tcvdb.ts)) |

## 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.