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

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 in 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 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

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

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.

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

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