# How to Use the TypeScript SDK to Manage Chat Memory Layers in TencentDB Agent Memory

> Master Chat Memory management in TencentDB Agent Memory using the TypeScript SDK. Learn to clear all memory layers with V3Client.clearChatMemory and manage data with MemoryPromptClient.

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

---

**The TencentDB Agent Memory TypeScript SDK exposes the `V3Client.clearChatMemory` method to atomically purge all four logical layers (L0‑L3) while preserving asset metadata, alongside layer-specific read/write utilities via `MemoryPromptClient` and generic core APIs.**

The **TencentDB-Agent-Memory** repository provides a TypeScript SDK that enables developers to programmatically manipulate **chat memory** assets through a layered storage architecture. By using the TypeScript SDK to manage Chat Memory layers, you can build stateful agent workflows that efficiently handle conversation context across raw utterances, indexed records, vector embeddings, and consolidated prompt files.

## Understanding the Four Chat Memory Layers

Chat memory in the TencentDB ecosystem is divided into four logical tiers that represent different stages of data refinement:

- **L0** – Raw chat utterances stored as plain text.
- **L1** – Token‑level index records for fast lookup.
- **L2** – Vector embeddings and profile metadata for semantic search.
- **L3** – Consolidated prompt‑ready files consumed directly by agents.

Each layer serves a distinct purpose in the retrieval‑augmented generation pipeline, and the SDK allows you to target them individually or clear them collectively.

## Clearing Chat Memory Assets with V3Client

The only chat‑memory‑specific operation that the SDK currently ships is **clearing** an entire memory asset while preserving its configuration metadata (owner, ACL, and name). This operation is implemented in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts) within the `V3Client` class.

### The clearChatMemory Method

The `V3Client.clearChatMemory` method sends a `POST /v3/chat-memory/clear` request that atomically wipes **all four layers** for each supplied `memory_id`. The operation is **idempotent**—calling it again on an already‑cleared memory returns success with zero deletions.

```typescript
import { V3Client } from './src/v3/client';
import { V3ChatMemoryClearRequest } from './src/v3/types';

// Clear specific memory assets
async function clearMemories(memoryIds: string[]) {
  const req: V3ChatMemoryClearRequest = { memory_ids: memoryIds };
  const resp = await client.clearChatMemory(req);
  return resp.data;
}

```

The method signature and validation logic are located at [V3Client.clearChatMemory](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts#L88-L95) in the source tree.

### Request Validation and Limits

Before transmitting the request, the SDK validates that the `memory_ids` array meets strict criteria:

1. Must contain between 1 and 100 unique identifiers.
2. Each string must be non‑empty.
3. All IDs must belong to the `chat_memory` asset type.

If any ID is missing or belongs to a different asset type, the **entire batch is rejected** and the service returns a failure for the complete request rather than partial success.

### Handling Batch Responses and Errors

The response type `V3ChatMemoryClearData` (defined in [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts)) contains per‑asset status codes that indicate success or specific failure reasons:

```typescript
function reportClearResult(data: V3ChatMemoryClearData) {
  data.items.forEach(item => {
    console.log(`Memory ${item.memory_id}: cleared=${item.cleared}`);
    if (!item.cleared) {
      console.warn(`  Reason: ${item.reason}`);
      if (item.retryable) console.info('  Will retry later');
    }
  });
  console.log('All cleared?', data.all_cleared);
}

```

Each item includes fields for `cleared`, `reason`, `retryable`, and `attempts`, allowing you to implement robust retry logic for transient failures.

## Reading and Writing Individual Layers

While clearing targets the entire asset, reading and writing operations typically target specific layers. The SDK provides both generic core APIs and specialized helpers for this purpose.

### Using MemoryPromptClient for L3 Operations

To interact with the **L3** layer (consolidated prompts), use the `MemoryPromptClient` defined in [`src/v3/memory-prompt-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/memory-prompt-client.ts). This helper accepts the `MemoryPromptLayer` enumeration from [`src/v3/memory-prompt-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/memory-prompt-types.ts) to specify the target tier:

```typescript
import { MemoryPromptLayer } from './src/v3/memory-prompt-types';
import { MemoryPromptClient } from './src/v3/memory-prompt-client';

const promptClient = new MemoryPromptClient(client);

// Write a prompt file to the L3 layer
await promptClient.writePrompt({
  memory_id: 'mem-12345',
  layer: MemoryPromptLayer.L3,
  content: 'You are a helpful assistant...',
});

// Read the same prompt back
const prompt = await promptClient.readPrompt({
  memory_id: 'mem-12345',
  layer: MemoryPromptLayer.L3,
});
console.log('Prompt content:', prompt.content);

```

The `MemoryPromptLayer` enum maps directly to L0 through L3, enabling type‑safe layer selection for downstream operations.

### Accessing L0, L1, and L2 via Core APIs

For layers other than L3, or for custom data access patterns, the `V3Client` exposes `readCore` and `writeCore` methods (implemented in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts)). These generic entry points accept layer identifiers and handle the underlying transport to the V3 gateway, allowing you to manipulate raw utterances (L0), index records (L1), and vector profiles (L2) programmatically.

## Practical Implementation Patterns

Combining the clear operation with layer‑specific writes enables common agent memory workflows.

### The Memory Recycling Workflow

A typical pattern involves clearing existing state and immediately seeding new L3 content without destroying the asset identity:

```typescript
async function recycleMemory(memoryId: string, newPrompt: string) {
  // Clear all layers atomically
  await client.clearChatMemory({ memory_ids: [memoryId] });
  
  // Write new prompt to L3
  await promptClient.writePrompt({
    memory_id: memoryId,
    layer: MemoryPromptLayer.L3,
    content: newPrompt,
  });
}

```

This workflow preserves the `memory_id` and its access controls while resetting conversational context.

### Inspecting Operation Results

When debugging batch clear operations, iterate over the `items` array in the response to identify specific failures. Check the `all_cleared` boolean for quick validation that the entire batch succeeded before proceeding with subsequent write operations.

## Summary

- **Four logical layers** (L0‑L3) store progressively refined chat data, from raw utterances to prompt‑ready files.
- **`V3Client.clearChatMemory`** in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts) provides the only chat‑specific SDK operation, atomically clearing all layers while preserving asset metadata.
- **Batch constraints** limit requests to 1‑100 unique `memory_ids`, with strict validation that rejects the entire batch if any ID is invalid.
- **`MemoryPromptClient`** and the `MemoryPromptLayer` enum in [`src/v3/memory-prompt-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/memory-prompt-types.ts) offer type‑safe access to layer L3 for prompt management.
- **Generic core APIs** (`readCore`/`writeCore`) enable direct manipulation of L0, L1, and L2 storage tiers when specialized helpers are insufficient.

## Frequently Asked Questions

### What is the difference between clearing and deleting a chat memory asset?

Clearing via `V3Client.clearChatMemory` wipes the data in all four layers (L0‑L3) but preserves the asset's metadata, including its ID, owner, and ACL configuration. Deleting an asset would remove the configuration entirely, requiring you to recreate access controls. Clearing is the preferred method for recycling a `memory_id` between conversation sessions.

### How do I target a specific layer when reading chat memory?

Use the `MemoryPromptClient` helper class for L3 (prompt layer) operations, passing the `MemoryPromptLayer.L3` enum value. For other layers (L0‑L2), use the generic `readCore` method available on `V3Client`, specifying the appropriate layer identifier in the request parameters.

### Is the clearChatMemory operation safe to retry?

Yes. The `clearChatMemory` operation is **idempotent** according to the implementation in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts). If you retry a request after a network timeout, the second call will return success and report zero deletions if the first attempt already cleared the data, ensuring your application can safely implement automatic retry logic.

### What happens if one memory ID in a batch does not exist?

The entire batch fails. The SDK validates that all `memory_ids` exist and belong to the `chat_memory` asset type before executing the clear operation. If any single ID is missing or invalid, the service returns an error response for the complete request, and no layers are cleared for any ID in the batch. You must correct the invalid ID and resubmit the complete list.