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

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

Writing to L0 (Conversation)

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

# 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

# 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, architectural documentation appears in README.md (line 255), operational details are in docs/tdai-v2-technical-ops.md, and runtime configuration of layered lookup is managed in 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.

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