# How to Create and Manage Chat Memory for an Agent in TencentDB Agent Memory

> Learn how to create and manage chat memory for your TencentDB Agent Memory. Discover how it stores conversational context and uses panel-level APIs and kernel SDK methods for efficient management.

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

---

**Chat Memory in TencentDB Agent Memory is a memory asset that stores conversational context across L0-L3 layers, vectors, and files, managed through panel-level APIs for ACL enforcement and kernel SDK methods for data operations.**

TencentDB Agent Memory provides a structured system for persisting and retrieving an agent's conversation history. This guide explains how to create, bind, import, and manage Chat Memory assets using the official panel HTTP routes and TypeScript SDK, with direct references to the source code implementation.

## Architecture Overview: Panel, Meta Kernel, and Data Kernel

The Chat Memory system operates across three distinct layers, each with specific responsibilities:

| Layer | Responsibility | Primary Interface |
|-------|---------------|-------------------|
| **Panel** | Asset-level CRUD, ACL checks, ownership validation | `POST /api/v1/chat-memory/*` routes in [[`chat-memory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/chat-memory.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryPanel/src/panel/http/routes/chat-memory.ts) |
| **Meta Kernel** | Asset metadata storage (`asset/create`, `asset/update`, `asset/get`) | `deps.metaKernel.invoke` calls from panel routes |
| **Data Kernel** | Actual chat messages (L0-L3) and vector indexes | `/v3/conversation/*` and `/v3/chat-memory/*` endpoints |

The **panel routes enforce all user-level permissions**, while the kernel APIs operate without ACL checks. Always route authenticated operations through the panel to ensure proper ownership validation.

## Creating a Chat Memory Asset

To create a new Chat Memory, issue a `POST` request to the panel's `/api/v1/chat-memory/create` endpoint.

The panel validates the caller via `X-Tdai-User-Key`, generates a unique asset ID with the `mem-xxx` prefix, and invokes `meta/kernel` `asset/create` with `asset_type: "chat_memory"`.

```typescript
import { post } from '@/lib/api'; // wrapper around fetch with proper headers

async function createChatMemory(
  teamId: string,
  title: string,
  scope: 'team' | 'private'
) {
  const resp = await post('/api/v1/chat-memory/create', {
    team_id: teamId,
    title,
    scope,
  });
  if (resp.code !== 0) throw new Error(`Create failed: ${resp.message}`);
  return resp.data; // { id, title, scope, owner_user_id, ... }
}

```

The returned asset ID serves as the canonical reference for all subsequent operations.

## Binding Chat Memory to an Agent

Before an agent can use a memory asset, you must **allocate** (bind) it to that agent. This creates a durable association in the metadata layer.

The allocation endpoint enforces two critical constraints:
- The caller must own the target agent
- The memory asset must belong to the same team
- The agent may borrow **at most 2 assets**

```typescript
async function allocateMemory(memoryId: string, agentId: string) {
  const resp = await post('/api/v1/chat-memory/allocate', {
    memory_id: memoryId,
    agent_id: agentId,
  });
  if (resp.code !== 0) throw new Error(`Allocate failed: ${resp.message}`);
}

```

Internally, this calls `meta/kernel` `asset/allocate` to persist the binding.

## Importing Historical Conversations (L0 Layer)

To seed a Chat Memory with existing conversation data, use the `/api/v1/chat-memory/import` endpoint. This populates the **L0 layer**—raw message history—before any vectorization or summarization occurs.

The panel validates agent ownership, normalizes message format (role, content, optional timestamp), and forwards to `/v3/conversation/add` with the agent's `owner_user_id` as `user_id`.

```typescript
interface ChatMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
  ts?: string; // ISO 8601 timestamp
}

async function importConversation(
  teamId: string,
  agentId: string,
  messages: ChatMessage[]
) {
  const resp = await post('/api/v1/chat-memory/import', {
    team_id: teamId,
    agent_id: agentId,
    messages,
  });
  if (resp.code !== 0) throw new Error(`Import failed: ${resp.message}`);
  return resp.data; // { imported: true, block_id, session_id, accepted_count }
}

```

The `block_id` and `session_id` in the response identify the imported segment for future reference.

## Clearing Chat Memory

There are two ways to clear memory, depending on your execution context:

### Via the TypeScript SDK (Agent-Side)

The SDK provides [`clearChatMemory`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts) in [[`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts):

```typescript
import { MemoryClient } from '@tencentdb/memory-core';

const client = new MemoryClient({ 
  baseUrl: 'https://kernel.example.com' 
});

await client.clearChatMemory({ 
  memory_ids: ['mem-abc123', 'mem-def456'] 
});

```

This issues `POST /v3/chat-memory/clear` directly against the data kernel.

### Via Panel API (Owner-Authenticated)

For operations requiring ownership verification, use the panel endpoint:

```typescript
async function clearMemoryPanel(memoryId: string) {
  const resp = await post('/api/v1/chat-memory/clear', {
    memory_id: memoryId,
  });
  return resp.data;
}

```

The panel adds **Owner-only ACL enforcement** before delegating to the kernel.

## Changing Visibility Scope

To modify whether a Chat Memory is **private** (owner-only) or **team-shared**, call the patch-scope endpoint:

```typescript
async function updateScope(memoryId: string, visibility: 'team' | 'private') {
  const resp = await post('/api/v1/chat-memory/patch-scope', {
    memory_id: memoryId,
    visibility,
  });
  if (resp.code !== 0) throw new Error(`Update failed: ${resp.message}`);
  return resp.data;
}

```

This validates the asset type is `chat_memory`, then invokes `meta/kernel` `asset/update` with the new visibility value.

Team-shared assets (`visibility: "team"`) are readable by any team member but remain modifiable only by the owner.

## Permission Model and Security Considerations

- **Asset Owner** (`owner_user_id`): Full CRUD operations, binding, importing, clearing
- **Team Members** (`visibility: "team"`): Read-only access to shared memories
- **Panel Enforcement**: All user-level ACL checks happen in [[`chat-memory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/chat-memory.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryPanel/src/panel/http/routes/chat-memory.ts) routes
- **Kernel Trust**: Meta and data kernels assume callers are already authorized; never expose kernel endpoints directly to untrusted clients

The **"≤ 2 borrowed assets" rule** prevents agent memory bloat and is enforced at allocation time.

## Key Source Files Reference

| Purpose | File Path |
|---------|-----------|
| Panel HTTP routes (create, allocate, import, clear, patch-scope) | [[`MemoryPanel/src/panel/http/routes/chat-memory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/src/panel/http/routes/chat-memory.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryPanel/src/panel/http/routes/chat-memory.ts) |
| TypeScript SDK client with `clearChatMemory` | [[`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) |
| Frontend API wrapper for Memory Panel UI | [[`MemoryPanel/web/src/lib/api/chat-memory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/lib/api/chat-memory.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryPanel/web/src/lib/api/chat-memory.ts) |
| Core kernel handlers for chat-memory operations | [[`MemoryCore/src/gateway/chat-memory-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/chat-memory-handlers.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/gateway/chat-memory-handlers.ts) |

## Summary

- **Create** Chat Memory assets via `POST /api/v1/chat-memory/create` with panel authentication
- **Bind** memories to agents using `POST /api/v1/chat-memory/allocate`, respecting the 2-asset limit
- **Import** historical conversations to L0 via `POST /api/v1/chat-memory/import` with normalized message arrays
- **Clear** memories using the SDK's `clearChatMemory` for direct kernel access, or panel `/clear` for owner verification
- **Adjust visibility** with `POST /api/v1/chat-memory/patch-scope` to toggle between private and team-shared access
- **Always route authenticated operations through the panel** to ensure proper ACL enforcement; the kernel layer performs no user-level authorization

## Frequently Asked Questions

### What is the difference between panel endpoints and kernel SDK methods for Chat Memory management?

Panel endpoints (`/api/v1/chat-memory/*`) enforce ownership, team membership, and asset limits before executing operations. The kernel SDK methods (like `clearChatMemory`) operate directly on data without user-level ACL checks. Use panel endpoints for multi-user scenarios and SDK methods only in trusted, agent-side contexts where authentication was already validated.

### Why does my agent allocation request fail with a borrowing limit error?

TencentDB Agent Memory enforces a maximum of **2 borrowed assets per agent**. This prevents memory bloat and ensures predictable retrieval performance. To resolve, either unbind an existing memory from the agent using the deallocate endpoint, or consolidate conversation history into fewer memory assets.

### How does Chat Memory store conversation data across the L0-L3 layers?

The **L0 layer** stores raw imported messages via `/v3/conversation/add`. Higher layers (L1-L3) contain progressively processed representations—chunked segments, vector embeddings, and summarized extracts—that the kernel generates asynchronously. The panel routes handle L0 ingestion; the data kernel in [[`chat-memory-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/chat-memory-handlers.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/gateway/chat-memory-handlers.ts) manages the full layer stack.