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

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

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.

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.

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

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:

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.

Key Implementation Files

File Path	Purpose
README.md	High-level overview of the L0→L1→L2→L3 pipeline and layer purposes
sdk/memory-core/typescript/README.md	L3 API documentation (readCore, writeCore, countCore) and scope clarification
MemoryCore/src/utils/pipeline-manager.ts	Distillation pipeline implementation converting chat logs to atoms, scenarios, and personas
MemoryCore/src/utils/stateful-pipeline-manager.ts	Stateful processing ensuring idempotent L1-L3 record creation
MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts	L3 persona injection into LLM system prompts without tool calls
MemoryProxy/src/tdai/client.ts	Low-level HTTP client for /v3/core/* endpoints
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 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. 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 and 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.

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