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

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 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 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 (lines 141-167), specifically within V3ChatMemoryClearRequest, V3ChatMemoryClearItem, and V3ChatMemoryClearData interfaces.

// 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. 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, 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 (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 (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. 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

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

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

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

Searching Across Memory Layers

// 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
• 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
• 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)
• Operations include clearing (preserving metadata), vector search, and cross-agent binding capabilities exposed through 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

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

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