# How Chat Memory is Structured in TencentDB Agent Memory: Architecture and Implementation

> Explore Chat Memory structure in TencentDB Agent Memory. Discover its architecture with deterministic IDs, multi-tiered storage, and Memory Bridge service for efficient retrieval.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: architecture
- Published: 2026-08-21

---

**Chat Memory in TencentDB Agent Memory is implemented as a first-class asset type tightly coupled to a team-agent pair, utilizing deterministic asset IDs, multi-tiered storage layers (L0-L3), and a Memory Bridge service for aggregated retrieval.**

TencentDB Agent Memory treats conversational context as durable, queryable assets rather than transient session data. In the [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) repository, Chat Memory is structured across five architectural layers that handle everything from ID generation to frontend visualization. Understanding how Chat Memory is structured reveals how the system maintains strict isolation between teams while enabling sophisticated retrieval across distributed storage tiers.

## Asset Identification and Isolation

### Deterministic Asset ID Generation

Every Chat Memory is uniquely identified by a deterministic asset ID generated from the team-agent pair. The `buildChatMemoryAssetId(teamId, agentId)` utility in [`MemoryCore/src/metadata/utils/chat-memory-asset.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/utils/chat-memory-asset.ts) constructs IDs following the pattern `chat_memory-{team_id}-{agent_id}`.

This deterministic approach ensures that the same team-agent pair always resolves to the same asset, preventing duplicate memory instances and enabling consistent retrieval across distributed services.

### Isolation Context in API Types

The SDK enforces strict isolation through `V3IsolationContext`, which carries `team_id`, `agent_id`, `user_id`, and optional `session_id` or `task_id` parameters. These types are defined in [`sdk/memory-core/typescript/src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/types.ts) (lines 141-167), specifically within `V3ChatMemoryClearRequest`, `V3ChatMemoryClearItem`, and `V3ChatMemoryClearData` interfaces.

```typescript
// From sdk/memory-core/typescript/src/v3/types.ts
interface V3ChatMemoryClearRequest {
  isolation: V3IsolationContext;
  memory_ids: string[];
}

```

## Storage Architecture and Retrieval

### Multi-Tiered Backend Storage

Chat Memory persists across four storage layers (L0-L3) using various backends including Cos (Cloud Object Storage), SQLite, filesystem, or in-memory stores. The **L0** and **L1** layers store raw conversation data and embeddings directly, while **L2** and **L3** represent higher-level abstractions generated by the offload pipeline.

Adapters in `MemoryCore/src/metadata/store/*-adapter.ts` handle the specific persistence logic for each backend type, ensuring consistent CRUD operations regardless of the underlying storage mechanism.

### Memory Bridge Aggregation

Retrieval operations flow through the **Memory Bridge** service located in [`MemoryProxy/src/memory/memory-bridge.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/memory/memory-bridge.ts). This component automatically aggregates the agent's **self** Chat Memory with up to two **imported** Chat Memories before executing vector searches.

As implemented in lines 311-318 of [`memory-bridge.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/memory-bridge.ts), this aggregation enables agents to reference conversational context from other agents while maintaining clear ownership boundaries.

## Operational Capabilities

### Capability Gating

Teams can disable Chat Memory entirely by setting `chat_memory: false` in their configuration. The capability check in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts) (lines 334-336) prevents the `TdaiClient` inference component from instantiating when this flag is disabled, effectively bypassing memory operations at the handler level.

### Asset-Level Operations

The system supports three primary operations on Chat Memory assets:

- **Clear**: Deletes all L0/L1 contents and profile records while preserving asset metadata
- **Search**: Queries across L0-L3 layers with vector similarity
- **Bind**: Imports other agents' Chat Memories for cross-agent context sharing

The `clearChatMemory` method is implemented 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) (lines 379-394) and exposed via the HTTP endpoint `POST /v3/chat-memory/clear`.

## Frontend Integration

The Web UI renders Chat Memory management through the `useChatMemory` hook in [`MemoryPanel/web/src/pages/memory/ChatMemoryPage/components/useChatMemory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/memory/ChatMemoryPage/components/useChatMemory.ts). This component enforces business rules such as preventing users from unbinding their "self" memory while allowing management of imported memories.

## Code Examples

### Generating Chat Memory Asset IDs

```typescript
import { buildChatMemoryAssetId } from '@/MemoryCore/src/metadata/utils/chat-memory-asset';

const teamId = 'team-abc';
const agentId = 'agent-xyz';
const chatMemoryId = buildChatMemoryAssetId(teamId, agentId);
// Result: "chat_memory-team-abc-agent-xyz"

```

### Clearing Multiple Chat Memories

```typescript
import { MemoryClient } from '@tencentdb-agent-memory/memory-sdk-ts-v2/v3';

const client = new MemoryClient({
  baseURL: 'https://memory.tencentyun.com',
  teamId: 'team-abc',
  agentId: 'agent-xyz',
  userId: 'user-123',
});

await client.clearChatMemory({
  memory_ids: [
    'chat_memory-team-abc-agent-xyz',
    'chat_memory-team-abc-agent-other',
  ],
});

```

### Adding Conversation Data to L0/L1

```typescript
await client.addConversation({
  session_id: 'sess-001',
  messages: [
    { role: 'user', content: 'Hello' },
    { role: 'assistant', content: 'Hi there!' },
  ],
});

```

### Searching Across Memory Layers

```typescript
// Inside useChatMemory hook
const hits = await chatMemoryApi.search({
  team_id: activeTeamId,
  query: 'what is the weather tomorrow',
  layer: 'L2',
});

```

## Summary

- **Chat Memory** is a first-class asset identified by deterministic team-agent based IDs generated by `buildChatMemoryAssetId` in [`MemoryCore/src/metadata/utils/chat-memory-asset.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/utils/chat-memory-asset.ts)
- **Isolation** is enforced through `V3IsolationContext` carrying team, agent, and user identifiers in every API request defined in [`sdk/memory-core/typescript/src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/types.ts)
- **Storage** spans L0-L3 tiers using Cos, SQLite, or filesystem adapters in `MemoryCore/src/metadata/store/`
- **Retrieval** aggregates self and imported memories via the Memory Bridge service ([`MemoryProxy/src/memory/memory-bridge.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/memory/memory-bridge.ts))
- **Operations** include clearing (preserving metadata), vector search, and cross-agent binding capabilities exposed through [`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)
- **Gating** allows teams to completely disable Chat Memory through configuration flags checked in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts)

## Frequently Asked Questions

### What is the format of a Chat Memory asset ID?

Chat Memory asset IDs follow the pattern `chat_memory-{team_id}-{agent_id}`, generated deterministically by the `buildChatMemoryAssetId` function in [`MemoryCore/src/metadata/utils/chat-memory-asset.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/utils/chat-memory-asset.ts). This ensures consistent addressing for the same team-agent pair across all operations.

### How does the system handle multiple Chat Memories during search?

The Memory Bridge service in [`MemoryProxy/src/memory/memory-bridge.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/memory/memory-bridge.ts) automatically aggregates the agent's self Chat Memory with up to two imported Chat Memories before executing vector searches. This allows agents to query across their own history and referenced agent contexts simultaneously.

### Can Chat Memory be completely disabled for specific agents?

Yes. When `chat_memory: false` is configured, the capability check in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts) prevents the `TdaiClient` from instantiating, effectively disabling all Chat Memory operations for that team-agent pair without affecting other system functionality.

### What happens when Chat Memory is cleared?

The `clearChatMemory` operation deletes all L0/L1 layer contents and profile records while preserving the asset metadata structure. This allows the memory to remain addressable and bound to the agent while removing all conversational history and embeddings, as implemented 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).