# TencentDB Agent Memory: Understanding the Four Progressive Memory Layers (L0-L3)

> Explore the four progressive memory layers L0-L3 in TencentDB Agent Memory. Understand how raw dialogue transforms into abstract, reusable knowledge for enhanced AI capabilities.

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

---

**The four distinct memory layers in TencentDB Agent Memory are L0 (Conversation), L1 (Atom), L2 (Scenario), and L3 (Core/Persona), forming a hierarchical pyramid that moves raw dialogue upward into increasingly abstract, reusable knowledge.**

TencentDB Agent Memory implements a sophisticated hierarchical storage system that enables AI agents to retain context across sessions. According to the TencentCloud/TencentDB-Agent-Memory repository, this architecture stores information in a progressive fashion where each layer represents different granularity and semantic purpose, allowing efficient retrieval while preventing low-level memories from overwhelming prompts.

## The Progressive Memory Pyramid Architecture

The system organizes memory as a **progressive memory pyramid** that transforms raw interaction data into structured knowledge. During both generation and retrieval operations, the system prioritizes higher-level layers (L2/L3) for quick context assembly, falling back to lower layers (L1/L0) only when detailed facts are required via BM25, vector search, and reciprocal rank fusion (RRF).

This design ensures agents maintain immediate access to high-level user understanding while preserving the ability to verify specific details against original source material.

## Breaking Down the Four Memory Layers (L0-L3)

### L0 Conversation Layer

**L0 Conversation** stores the raw dialogue and full context of a session. This layer maintains an immutable record containing original utterances, timestamps, and sources.

The primary purpose is **verification fidelity**. When an agent needs to confirm exactly what was said or audit the source of information, it references this foundational layer. All higher layers (L1-L3) are distilled from this raw data through asynchronous processing pipelines.

### L1 Atom Layer

**L1 Atom** contains facts, preferences, constraints, and events extracted from L0 dialogue. These represent the minimal actionable pieces of information.

This layer enables **precise recall** of specific data points without reprocessing entire conversation histories. When the system needs a particular constraint or user preference, it queries L1 atoms rather than parsing raw transcripts. According to the implementation in [`MemoryPanel/web/src/pages/ChatMemoryPage/constants/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/ChatMemoryPage/constants/types.ts), the layer is strictly typed as `'L0' | 'L1' | 'L2' | 'L3'`.

### L2 Scenario Layer

**L2 Scenario** organizes knowledge blocks around specific projects or work contexts. Unlike atomic facts, this layer reconstructs entire situational contexts.

The purpose is **rapid context recreation**. When resuming work on a specific project, the agent can load the L2 scenario to immediately understand the current state, active tasks, and relevant background without processing raw dialogue history. This significantly reduces latency when switching between different work modes or projects.

### L3 Core / Persona Layer

**L3 Core** (also referred to as Persona) stores long-term user or team profiles, stable behavioral patterns, and high-level cognition. This represents the most abstract and stable memory tier.

This layer provides **immediate high-level understanding** of user preferences, communication styles, and organizational context. According to the repository's documentation in [`README_CN.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README_CN.md), L3 memories give agents an instant grasp of the user's overall context before any specific interaction begins, enabling personalized responses from the first prompt.

## Retrieval Strategy and Layer Priority

The retrieval system implements a **cascade strategy** that optimizes for both speed and accuracy:

1. **First attempt**: Query L2 (Scenario) and L3 (Core) layers for quick context assembly
2. **Fallback**: When detailed verification is needed, search L1 (Atom) and L0 (Conversation) using hybrid retrieval methods

This approach prevents low-context, high-volume data from overwhelming the prompt while maintaining **fidelity** through the ability to reference original sources when necessary. The quota management system tracks usage across these layers, as evidenced in [`MemoryCore/src/core/quota/quota-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/quota/quota-manager.ts) where layer information is reported as `level: "L0" | "L1" | "L2" | "L3"`.

## Working with Memory Layers in Code

### Type Definition

The layer enumeration is strictly defined in the frontend codebase to ensure type safety across the application:

```typescript
// MemoryPanel/web/src/pages/ChatMemoryPage/constants/types.ts
export type MemoryLayer = 'L0' | 'L1' | 'L2' | 'L3';

```

### Retrieving Specific Layers via API

To fetch memories from a specific layer, use the `/v3/chat-memory/layer` endpoint implemented in [`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):

```typescript
import { post } from '@/lib/api';

async function fetchL1Atoms(agentId: string, page = 1, pageSize = 20) {
  const resp = await post('/v3/chat-memory/layer', {
    agent_id: agentId,
    layer: 'L1',          // specify the target layer
    page,
    page_size: pageSize,
  });
  return resp.items;      // returns array of atomic memories
}

```

### Importing Raw Conversations

When importing new dialogue, the system automatically handles distillation into higher layers:

```typescript
import { post } from '@/lib/api';

async function importConversation(agentId: string, messages: Array<any>) {
  await post('/v3/chat-memory/import', {
    agent_id: agentId,
    layer: 'L0',
    messages,               // raw JSON message array
  });
  // Backend asynchronously creates L1/L2/L3 entries
}

```

### Utilities and Helper Functions

Layer-specific pagination and utilities are managed in [`MemoryPanel/web/src/pages/ChatMemoryPage/utils/memory-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/ChatMemoryPage/utils/memory-utils.ts), which provides helper functions for mapping pagination parameters and page sizes appropriate to each layer's data volume characteristics.

## Summary

- **L0 Conversation** provides immutable raw dialogue storage for verification and audit trails
- **L1 Atom** extracts minimal facts and preferences for precise, efficient recall
- **L2 Scenario** assembles project-specific knowledge blocks for rapid context switching
- **L3 Core** maintains long-term personas and stable user patterns for immediate personalization
- The **cascade retrieval strategy** prioritizes high-level layers (L2/L3) before falling back to detailed layers (L1/L0) via BM25 and vector search
- **Type safety** is enforced through the `MemoryLayer` type definition across the TypeScript frontend implementation

## Frequently Asked Questions

### How does TencentDB Agent Memory prevent prompt overload from too many memories?

The system uses a **hierarchical retrieval cascade** that queries higher-abstraction layers (L2 Scenario and L3 Core) first during generation. Only when specific factual verification is required does it fall back to L1 Atoms and L0 Conversation data. This prevents low-level, high-volume raw data from overwhelming the context window while maintaining access to detailed sources when necessary.

### What triggers the promotion of memories from L0 to higher layers?

According to the architecture documentation, the backend **asynchronously distills** L0 conversation data into L1 atoms, L2 scenarios, and L3 core memories after ingestion. When you import raw messages via `/v3/chat-memory/import` to the L0 layer, background processes automatically extract facts, organize scenarios, and update persona models without requiring manual intervention.

### Can I query multiple memory layers simultaneously?

While the API endpoint `/v3/chat-memory/layer` requires specifying a single layer parameter (`'L0' | 'L1' | 'L2' | 'L3'`), the retrieval system internally implements **reciprocal rank fusion (RRF)** that combines results from vector search and BM25 across layers when the application logic requires cross-layer context. Client code typically orchestrates calls to different layers sequentially based on priority.

### Where is the memory layer type defined in the source code?

The primary type definition is located in [`MemoryPanel/web/src/pages/ChatMemoryPage/constants/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/ChatMemoryPage/constants/types.ts), which exports `MemoryLayer` as a union type of the four string literals. Additional references to layer levels appear in [`MemoryCore/src/core/quota/quota-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/quota/quota-manager.ts) for usage tracking and in the API client implementations within [`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).