# Understanding the Layered Memory Architecture (L0-L3) in TencentDB Agent Memory

> Explore TencentDB Agent Memory's layered memory architecture (L0-L3) for faster retrieval. Learn how it optimizes context checking before accessing detailed conversation data.

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

---

**TencentDB Agent Memory implements a four-tier hierarchy (L0-L3) that optimizes retrieval speed by checking lightweight context bootstraps (L2/L3) before falling back to granular conversation data (L0/L1) using BM25 and vector search with RRF merging.**

The TencentDB-Agent-Memory repository provides a scalable memory system for AI agents that balances speed, relevance, and permanence through a layered storage approach. This architecture separates ephemeral conversation data from durable knowledge, enabling efficient retrieval across different time horizons and data types.

## The Four Layers of Memory (L0-L3)

The system organizes information into four distinct tiers, each optimized for specific access patterns and data lifecycles as defined in the core implementation.

### L0 – Conversation Layer

The **L0 layer** captures raw user-assistant dialogue as individual chat messages. This layer maintains the complete, unmodified transcript of interactions, making it the source of truth for exact historical queries. According to [`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), the `add_conversation()` method writes directly to this tier, storing messages with their original roles and content.

### L1 – Atomic Layer

The **L1 layer** stores structured "atomic" items extracted from L0 conversations, such as parsed facts, intents, or small JSON-like objects. While L0 holds raw text, L1 contains semantically processed information that enables precise fact retrieval without re-parsing entire conversations.

### L2 – Context Bootstrap Layer

The **L2 layer** provides lightweight, LLM-generated summaries of recent conversation history, serving as a **context bootstrap** for rapid response generation. As documented in [`docs/tdai-v2-technical-ops.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/docs/tdai-v2-technical-ops.md), this layer delivers a quick glimpse of relevant information without scanning the entire raw conversation history.

### L3 – Long-Term Knowledge Layer

The **L3 layer** holds durable, session-agnostic knowledge such as product documentation and policies. This tier utilizes **vector-indexed chunks** and **BM25-indexed text**, accessed via hybrid retrieval with **RRF (Reciprocal Rank Fusion)** when L0-L2 cannot satisfy a query.

## How Layered Retrieval Works

As stated in [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) at line 255, both generation and retrieval follow a cascading pattern that prioritizes speed before precision:

1. **Fast Path (L2/L3 Bootstrap)** – The system first attempts to bootstrap context using lightweight L2 summaries and L3 knowledge bases. These layers provide immediate relevant context without heavy computation or scanning full conversation histories.

2. **Fine-Grained Fallback (L1/L0)** – When specific facts are required beyond the bootstrap context, the engine falls back to **BM25 + vector retrieval** on the atomic (L1) and conversation (L0) layers. Results from both methods are merged using RRF to produce a ranked list for the LLM.

## Session Isolation and Scope

The architecture implements distinct scoping rules across layers to balance privacy with broad knowledge access.

- **L0 and L1** support **session isolation** via `session_id` parameters. When `session_id` is provided to methods like `query_conversation()` 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), the query filters to that specific session. When omitted, the API aggregates across all sessions belonging to the same `(team, agent, user)` triple.

- **L2 and L3** are **session-agnostic** global assets. These layers do not depend on specific conversation instances and remain accessible across all sessions for a given deployment, providing consistent long-term knowledge and context bootstraps.

## Implementation in Code

The Python SDK exposes these layers through the `MemoryClient` class defined 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).

### Writing to L0 (Conversation)

```python
from tencentdb_agent_memory.v3.client import MemoryClient

client = MemoryClient(team_id="team-abc", agent_id="assistant", user_id="user-xyz")
client.add_conversation(messages=[
    {"role": "user", "content": "How do I reset my password?"},
    {"role": "assistant", "content": "You can reset it via the Settings page."}
])

```

### Querying with Session Isolation

```python

# Retrieve recent messages from a specific session

result = client.withIsolation({"session_id": "sess-123"}).query_conversation(limit=20)
print(result.total)  # Total number of messages in that session

```

Omitting the `session_id` parameter aggregates results across all sessions for the user-agent pair.

### Performing Layered Retrieval

```python

# First, get a quick bootstrap from L2/L3

bootstrap = client.get_context_bootstrap(keywords=["password", "reset"])

# If more exact facts are needed, fall back to BM25 + vector retrieval

relevant = client.search_conversation(
    query="reset password steps",
    session_id=None,  # cross-session aggregation

    top_k=5
)

# Combine both sources before sending to the LLM

prompt = f"<relevant-memories>{relevant}</relevant-memories>\n{bootstrap}\nUser: ..."

```

## Summary

- **Four-tier hierarchy**: L0 (raw conversation), L1 (atomic facts), L2 (context bootstrap), and L3 (long-term knowledge) provide graduated storage optimization for different data types.
- **Speed-first retrieval**: The system queries lightweight L2/L3 layers first, falling back to granular L0/L1 only when necessary via BM25 and vector search with RRF merging.
- **Flexible isolation**: L0 and L1 support session-scoped queries through `withIsolation()`, while L2 and L3 remain globally accessible across all sessions.
- **Key source files**: Core implementation resides 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), architectural documentation appears in [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) (line 255), operational details are in [`docs/tdai-v2-technical-ops.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/docs/tdai-v2-technical-ops.md), and runtime configuration of layered lookup is managed in [`MemoryCore/src/utils/env-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/env-config.ts).

## Frequently Asked Questions

### What is the difference between L0 and L1 in TencentDB Agent Memory?

**L0 stores raw conversation transcripts** exactly as exchanged between users and assistants, while **L1 contains structured atomic items** such as parsed facts and intents extracted from those conversations. L0 serves as the immutable history, whereas L1 provides machine-readable data structures for precise querying without re-processing raw text.

### How does the retrieval system decide when to query L0/L1 versus L2/L3?

The system implements a **cascading retrieval strategy** defined in the memory core. It first attempts to satisfy queries using the lightweight **L2/L3 bootstrap** layers for speed. Only when the bootstrap context proves insufficient does it fall back to **BM25 and vector retrieval** against L0/L1, merging results using Reciprocal Rank Fusion (RRF) to ensure comprehensive coverage.

### Are the L2 and L3 layers shared across all user sessions?

**Yes**, L2 and L3 are **session-agnostic** global assets that do not depend on specific `session_id` values. While L0 and L1 can be isolated to individual sessions using the `withIsolation()` method, L2 and L3 remain accessible across all sessions for a given team-agent-user combination, providing consistent long-term knowledge and context bootstraps.

### What retrieval algorithms does the L3 layer utilize?

The L3 layer employs **hybrid retrieval** combining **BM25 text search** and **dense vector similarity search**, with results merged via **RRF (Reciprocal Rank Fusion)**. This approach balances keyword precision with semantic understanding, enabling effective retrieval of both exact terminology and conceptually related content from the durable knowledge base.