# TencentDB Agent Memory Layers Explained: L0, L1, L2, and L3 Architecture

> Understand the TencentDB Agent Memory L0, L1, L2, and L3 architecture. Learn how these layers manage transient, team, and long-term knowledge for efficient agent context retrieval and durable storage.

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

---

**The four-layer pyramid in TencentDB Agent Memory organizes knowledge from transient conversation history (L0/L1) to persistent team scenarios (L2) and long-term agent personas (L3), enabling agents to balance immediate context retrieval with durable knowledge storage.**

The TencentDB-Agent-Memory repository implements a hierarchical memory architecture that mimics human cognitive retention. Understanding these **TencentDB Agent Memory layers** is essential for building agents that maintain context across sessions while efficiently retrieving relevant knowledge. This system categorizes information based on granularity, lifetime, and access patterns across four distinct tiers.

## The Four-Layer Memory Pyramid

The memory architecture follows a pyramid structure where each ascending layer represents broader scope and longer persistence. According to the [Memory Pyramid documentation](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/README.md#memory-pyramid) in [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md), the layers are organized as follows:

### L0: Conversation Layer

**L0** stores raw turn-by-turn dialogue between users and agents. This layer captures the complete ephemeral interaction history within a single session.

- **Scope**: One-off user-agent interactions
- **Storage**: Vector store (e.g., TCVDB)
- **Session Requirement**: **Required** — every call requires a `session_id`
- **Content**: Raw dialogue transcripts
- **Lifetime**: Transient; cleared when the session ends

### L1: Atom Layer

**L1** contains fine-grained facts extracted from L0 conversations. These are short, discrete knowledge snippets indexed for rapid retrieval.

- **Scope**: Fine-grained facts and decisions
- **Storage**: Vector store plus SQLite rows
- **Session Requirement**: **Required** — atoms inherit the `session_id` from their source conversation
- **Content**: Short snippets, facts, code fragments, and extracted decisions
- **Use Case**: Sharing specific facts across sessions of the same agent

### L2: Scenario Layer

**L2** represents team-level, project-oriented context stored as curated markdown files. Unlike L0/L1, scenarios persist across all sessions for a given agent.

- **Scope**: Project-level context and workflows
- **Storage**: File system (`scene_blocks/`) with optional vector indexing for full-text search
- **Session Requirement**: **Not required** — APIs do not consume `session_id`
- **Content**: Markdown files describing scenarios (e.g., "customer-onboarding flow", "deployment checklist")
- **Isolation**: Uses team-triplet (`serviceId/agentId`) only

### L3: Persona Layer

**L3** maintains long-term profiles of agents or users, capturing personality traits and persistent preferences.

- **Scope**: Agent identity and user profiles
- **Storage**: File system (`persona/`) with optional vector indexing
- **Session Requirement**: **Not required**
- **Content**: Persona documents describing personality, communication style, and role-specific knowledge
- **Lifetime**: Persistent across all interactions

## Core Architectural Differences

### Granularity and Lifetime

**L0/L1** are **transient** layers tied to specific conversation sessions. Data in these layers is cleared when sessions end or ages out based on retention policies. **L2/L3** are **persistent** layers that survive across sessions, representing reusable knowledge blocks for entire teams or specific agent identities.

### Isolation Model

The isolation mechanisms differ fundamentally between layers:

- **L0/L1**: Use the **session-triplet** (`serviceId/agentId/sessionId`) to strictly isolate data within single conversations
- **L2/L3**: Use the **team-triplet** (`serviceId/agentId`) only, enabling tri-tuple isolation without session components

This architectural distinction explains why the SDK documentation notes that L2/L3 "do not consume `session_id`" while L0/L1 require it.

### Access Patterns

Retrieval strategies vary by layer characteristics:

- **L0/L1**: Driven by **vector similarity** (BM25 + embeddings) due to short, highly contextual content
- **L2/L3**: Typically **keyword-based** or direct file lookups, as data is already curated into coherent knowledge blocks

### Performance Impact

The layers exhibit different resource consumption profiles:

- **L0/L1**: Consume significant vector-store bandwidth; implementations often paginate or cap results to maintain context window limits
- **L2/L3**: Loaded once per request or cached, acting as **bootstrap context** that reduces deep retrieval needs from L0/L1

## Working with L2 and L3 APIs

The TypeScript SDK in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts) provides direct methods for managing Scenario (L2) and Persona (L3) files. Unlike L0/L1 operations, these methods do not require a `sessionId` parameter.

### L2 Scenario Operations

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

// Construct client without sessionId for L2/L3 operations
const client = new MemoryClient({
  serviceId: 'my-service',
  agentId: 'workbuddy',
  // sessionId is intentionally omitted
});

// List all scenario files
const scenarios = await client.listScenarios();
console.log('Available scenarios:', scenarios.map(s => s.path));

// Read specific scenario content
const content = await client.readScenario('projectX/arch-overview.md');

// Update scenario file
await client.writeScenario('projectX/arch-overview.md', '# Architecture Overview\n...');

// Remove obsolete scenarios
await client.rmScenario('projectX/old-notes.md');

```

### L3 Persona Operations

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

const client = new MemoryClient({
  serviceId: 'my-service',
  agentId: 'workbuddy',
});

// List available personas
const personas = await client.listPersonas();
console.log('Personas:', personas.map(p => p.path));

// Read agent persona
const persona = await client.readPersona('workbuddy/persona.md');

// Update long-term preferences
await client.writePersona(
  'workbuddy/persona.md', 
  '# WorkBuddy Persona\nLikes concise answers...'

);

```

The SDK automatically routes these calls to the file-system backend (or COS in production environments), as documented in the [MemoryCore README](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/README.md).

## When to Use Each Layer

Selecting the appropriate layer depends on the information's scope and longevity:

- **Quickly re-entering known projects**: Use **L2 (Scenario)**. Scenario markdown files contain high-level overviews and recent decisions, providing immediate context without searching conversation history.

- **Maintaining consistent agent identity**: Use **L3 (Persona)**. Persona documents capture long-term style preferences and role-specific constraints that must persist across every session.

- **Answering factual questions about recent dialogue**: Use **L0/L1**. The raw conversation (L0) or extracted atoms (L1) contain the freshest information from the current interaction.

- **Reusing specific facts across sessions**: Use **L1 (Atom)**. Atoms are indexed for fast vector retrieval and can be shared by all sessions of the same agent.

- **Cold-starting new agents**: Combine **L2 + L3**. Load relevant scenarios and personas first, then fall back to L1/L0 if deeper detail is required.

- **Performing long-term audits**: Query **L2** scenario logs or **L3** persona-level change history. These layers maintain persisted documentation searchable without digging through transient conversation history.

### Generation Pipeline Workflow

In production implementations, the retrieval pipeline follows this cascade:

1. **Bootstrap** context with appropriate **L2/L3** files (fast, deterministic loading)
2. **Fallback** to **BM25 + vector retrieval** on **L1** (and **L0** if needed) for concrete facts
3. **Cap retrieved items** by count, character budget, and timeout to maintain model context limits

## Summary

- **L0 (Conversation)**: Transient raw dialogue requiring `session_id`; stored in vector databases
- **L1 (Atom)**: Transient extracted facts requiring `session_id`; hybrid vector and SQLite storage
- **L2 (Scenario)**: Persistent project documentation; filesystem-based (`scene_blocks/`); no `session_id` required
- **L3 (Persona)**: Persistent agent profiles; filesystem-based (`persona/`); no `session_id` required
- **Isolation**: L0/L1 use session-triplets; L2/L3 use team-triplets (`serviceId/agentId`)
- **Implementation**: TypeScript SDK methods in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts) handle L2/L3 file operations without session parameters

## Frequently Asked Questions

### What distinguishes L0 from L1 in TencentDB Agent Memory?

**L0 stores complete conversation transcripts** while **L1 stores extracted atomic facts**. L0 maintains the full dialogue context for a specific session, whereas L1 breaks down that dialogue into discrete, searchable knowledge snippets (atoms) that can be retrieved independently. Both require a `session_id`, but L1 content is pre-processed for vector similarity search.

### Why do L2 and L3 layers not require a session_id?

L2 (Scenario) and L3 (Persona) represent **persistent knowledge** that exists above the session level. According to the architecture implemented in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts), these layers use team-triplet isolation (`serviceId/agentId`) rather than session-triplets. This design enables scenarios and personas to persist across all conversations for an agent, making them available during cold starts without requiring a specific session context.

### How does the SDK handle storage for Scenarios and Personas?

The SDK routes L2/L3 operations to **filesystem storage** (`scene_blocks/` for scenarios, `persona/` for personas) or to **COS (Cloud Object Storage)** in production environments. This differs from L0/L1, which use vector databases like TCVDB. The `MemoryClient` class automatically handles the backend routing based on the environment configuration.

### When should I use L2 Scenarios versus L3 Personas?

Use **L2 Scenarios** for project-specific context such as deployment checklists, architecture overviews, or team workflows that multiple agents might share. Use **L3 Personas** for agent-specific attributes like communication style, personality traits, or user preference profiles that define how an individual agent behaves across all projects.