# How the L0-L3 Memory Layering System Works in TencentDB Agent Memory

> Discover how the L0-L3 memory layering system in TencentDB Agent Memory transforms raw data into user personas. Understand the four-stage hierarchy for efficient storage and retrieval.

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

---

**The L0-L3 memory layering system in TencentDB Agent Memory is a four-stage hierarchy that progressively distills raw conversational data into long-term user personas, with each layer serving distinct storage, retrieval, and injection purposes.**

The TencentDB Agent Memory repository implements a sophisticated data architecture that transforms ephemeral chat logs into persistent, reusable intelligence. Understanding how the **L0-L3 memory layering system** operates is essential for developers building agents that maintain context across sessions while optimizing token usage and retrieval latency.

## The Four Layers of the Memory Hierarchy

### L0 – Conversation (Raw Dialogue)

**L0 stores raw turn-by-turn chat logs** between users and LLMs. This layer captures the complete, unprocessed dialogue history directly after each message exchange.

- **Typical Size**: Hundreds of KB per session
- **API Methods**: `writeChat()` and `readChat()` (v2 API)
- **Scope**: Session-scoped; requires a `session_id` for all operations

According to the repository's core documentation, L0 serves as the immutable foundation from which all higher-level abstractions are derived.

### L1 – Atom (Extracted Facts)

**L1 contains small, self-contained facts or actions** automatically distilled from L0 data. These atomic units represent discrete pieces of information—such as user preferences, decisions, or specific actions—extracted through rule-based or model-driven parsers.

- **Typical Size**: Few KB per atom
- **API Methods**: `writeAtom()` and `readAtom()`
- **Creation**: Generated by automatic distillation pipelines processing L0 logs

### L2 – Scenario (Contextual Groups)

**L2 aggregates related atoms into higher-level contexts** representing projects, tasks, or domains. Scenarios group atoms that share common tags or purposes, creating mid-level semantic clusters.

- **Typical Size**: Tens of KB
- **API Methods**: `writeScenario()` and `readScenario()`
- **Usage**: Added as **tool-style references** in LLM prompts, enabling on-demand retrieval during sessions

### L3 – Persona (Core Memory)

**L3 maintains long-term user or team-level profiles** containing stable patterns and high-level cognition. This **core memory** is injected directly into LLM system prompts to bootstrap agent context without requiring tool calls.

- **Typical Size**: Few hundred KB (concise persona description)
- **API Methods**: `readCore()`, `writeCore()`, and `countCore()` 
- **Scope**: Team-agent scoped; **does not consume `session_id`**, allowing multiple agents to share personas across sessions

As documented in [`sdk/memory-core/typescript/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md), L3 profiles are generated once per agent or team after onboarding and remain stable across interactions.

## How the Layers Interact

### Distillation Pipeline (L0→L1→L2→L3)

When a conversation ends, the **pipeline manager** processes raw L0 logs through an idempotent transformation chain. In [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts), the system:

1. Extracts atoms (L1) from conversation logs using parsers
2. Groups atoms into scenarios (L2) by similarity and shared tags  
3. Builds personas (L3) from aggregated scenario data

The pipeline guarantees **idempotency**—the same hash always produces the same record, ensuring consistency across runs. This stateful processing is managed by [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts).

### Retrieval Strategies (Top-Down and Bottom-Up)

The system employs dual retrieval modes depending on query requirements:

- **Normal Generation**: Agents first read L2/L3 for high-level context, then fall back to L1/L0 using **BM25 + vector search + RRF** (Reciprocal Rank Fusion) for concrete facts
- **Fine-Grained Queries**: For precise historical data, the system retrieves directly from L1/L0 with strict **item-count, character-budget, and timeout limits** to prevent context overflow

The **Memory Hub** merges results from all layers and returns curated snippets to the LLM, as described in the root [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md).

### Prompt Injection Architecture

L3 personas are injected **directly into the system prompt** as static text because they are short, stable, and frequently accessed. This approach avoids the latency of tool calls for core identity information.

L2 scenario indices are injected as **tool-style references**, allowing the LLM to retrieve relevant context on-demand during active sessions. This hybrid approach balances immediate availability (L3) with flexible retrieval (L2), implemented in [`MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts).

### Scope and Ownership Isolation

The layering system enforces strict isolation boundaries:

- **L0–L1**: Session-scoped; every operation requires a valid `session_id`
- **L2–L3**: Team-agent scoped; no `session_id` required, enabling shared personas across multiple agents and sessions

As shown in [`sdk/memory-core/python/tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py), this design eliminates re-authentication overhead for core profile access.

## Working with the L3 Core API

The following TypeScript example demonstrates interacting with the L3 layer using the official SDK. Note that L3 operations require `team_id` and `agent_id` but **no `session_id`**:

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

// Initialize client for team-agent scope (no session_id required)
const client = new MemoryClient({
  endpoint: 'https://memory.tencentyun.com',
  teamId: 'team-123',
  agentId: 'agent-xyz',
});

// Write a persona (L3)
await client.writeCore({
  memory_id: 'persona-2024',
  content: `User prefers concise answers, works in fintech, and values data privacy.
            Recent projects: risk-assessment engine, KPI dashboard.`,
  meta: { visibility: 'team' },
});

// Read the persona
const persona = await client.readCore({ memory_id: 'persona-2024' });
console.log('Loaded persona:', persona?.content);

// Count persona records
const count = await client.countCore({ filter: { type: 'persona' } });
console.log('Number of personas:', count);

```

The Python SDK provides equivalent functionality with snake_case method names:

```python
from tencentdb_agent_memory.v3 import MemoryClient

client = MemoryClient(
    endpoint='https://memory.tencentyun.com',
    team_id='team-123',
    agent_id='agent-xyz'
)

# Write core memory

client.write_core(
    memory_id='persona-2024',
    content='User prefers concise answers, works in fintech...'
)

# Retrieve and count

persona = client.read_core(memory_id='persona-2024')
count = client.count_core(filter={'type': 'persona'})

```

These calls target the `/v3/core/*` endpoints via the low-level HTTP client implemented in [`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts).

## Key Implementation Files

| File Path | Purpose |
|-----------|---------|
| [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) | High-level overview of the L0→L1→L2→L3 pipeline and layer purposes |
| [`sdk/memory-core/typescript/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md) | L3 API documentation (`readCore`, `writeCore`, `countCore`) and scope clarification |
| [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts) | Distillation pipeline implementation converting chat logs to atoms, scenarios, and personas |
| [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts) | Stateful processing ensuring idempotent L1-L3 record creation |
| [`MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts) | L3 persona injection into LLM system prompts without tool calls |
| [`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts) | Low-level HTTP client for `/v3/core/*` endpoints |
| [`sdk/memory-core/python/tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py) | Python SDK implementation showing team-agent scoped L3 access |

## Summary

- **L0-L3 represents a progressive abstraction ladder**: Raw conversations (L0) → atomic facts (L1) → scenario groups (L2) → stable personas (L3)
- **Distillation is automatic and idempotent**: The pipeline manager in [`pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-manager.ts) processes L0 data through L3 without manual intervention
- **Retrieval is bidirectional**: Agents consume L2/L3 for immediate context and L0/L1 for detailed historical lookup using hybrid search (BM25 + vector + RRF)
- **L3 requires no session context**: Core memory operates at the team-agent level, enabling efficient multi-session persistence via `writeCore()` and `readCore()`
- **Injection strategy varies by layer**: L3 embeds directly into system prompts while L2 exposes tool-style indices for dynamic retrieval

## Frequently Asked Questions

### What is the difference between L2 Scenarios and L3 Personas?

**L2 Scenarios** are mid-level contextual groups that organize related atomic facts (L1) by project or domain, typically tens of KB in size. **L3 Personas** are concise, stable profiles (few hundred KB) representing long-term user or team cognition. While L2 functions as a dynamic retrieval index accessed via tools, L3 is embedded directly into the system prompt as static context.

### Why does L3 Core Memory not require a session_id?

L3 operates at the **team-agent scope** rather than the session scope, as implemented in the Python SDK's [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py). This design allows multiple agents belonging to the same team to share persistent user profiles without re-authenticating or reloading context for every new conversation session, reducing latency and improving cross-session consistency.

### How does the system prevent duplicate memories during distillation?

The distillation pipeline implemented in [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts) and [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts) is **idempotent**. It generates consistent hashes for input data, ensuring that processing the same L0 conversation multiple times produces identical L1-L3 records without duplication.

### Which search algorithms does TencentDB Agent Memory use for retrieval?

For L0 and L1 retrieval, the system employs a hybrid approach combining **BM25 keyword search**, **vector similarity search**, and **RRF (Reciprocal Rank Fusion)** to merge results. This multi-strategy retrieval, referenced in the root documentation, balances semantic relevance with keyword precision while respecting strict character and token budgets.