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

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/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".

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

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.

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 in [client.ts](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts):

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:

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:

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/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/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/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/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/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/feat/server_team/MemoryCore/src/gateway/chat-memory-handlers.ts) manages the full layer stack.

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