How Layered Memory (L0-L3) Works in TencentDB Agent Memory: A Technical Deep Dive

TencentDB Agent Memory organizes information into four hierarchical layers—L0 (Conversation), L1 (Atom), L2 (Scenario), and L3 (Core/Persona)—that automatically distill raw interactions into structured knowledge through an async pipeline while maintaining strict isolation between sessions and agents.

The TencentCloud/TencentDB-Agent-Memory repository implements a sophisticated layered memory architecture designed to balance detailed recall with efficient context management. This system enables AI agents to retain everything from raw chat logs to high-level personas, using a bottom-up fallback strategy that keeps prompts concise while preserving access to granular details.

The Four-Layer Memory Hierarchy

TencentDB Agent Memory stores information across four distinct tiers, each optimized for different retrieval patterns and data lifecycles.

L0: Conversation Layer

The L0 layer serves as the raw event log, storing unprocessed chat messages with timestamps, speaker roles, and metadata. According to the source code in sdk/memory-core/typescript/src/v3/client.ts, this layer captures exact transcripts of what was said, when, and by whom. The addConversation method (lines 93-99) writes to this layer and immediately triggers the L1 extraction pipeline via notifyPipeline.

L1: Atom Layer

L1 atoms represent structured facts, preferences, constraints, and events extracted from L0 content. When the pipeline processes a conversation like "请帮我把今天的部署记录保存下来" (please help me save today's deployment records), it distills this into atomic facts such as "用户请求保存部署记录" (user requested saving deployment records). These atoms power BM25 and vector retrieval when higher layers cannot answer specific factual queries.

L2: Scenario Layer

The L2 layer contains project-oriented knowledge blocks stored as versioned files—design documents, runbooks, and configuration files. Unlike L0/L1, L2 assets are team-agent-wide and ignore session boundaries. The readScenario method in the TypeScript SDK retrieves these files to provide quick context bootstrapping for specific workflows.

L3: Core/Persona Layer

L3 stores long-term profiles and stable behavioral patterns in files like persona.md. This layer gives agents persistent personalities and organization-wide context, allowing them to start tasks without re-learning basic preferences. L3 content is versioned and managed through writeCore and related endpoints.

How Data Flows Through the Layers

The repository implements distinct write and read pathways that automatically promote data up the hierarchy while allowing targeted fallback retrieval.

Write Path: L0 to L1 Extraction

When an agent interaction completes, the SDK calls MemoryClient.addConversation, which POSTs to /v3/conversation/add with strict isolation parameters (team_id, agent_id, user_id, and required session_id). As implemented in src/v3/client.ts, this operation:

1. Persists the raw message to L0
2. Enqueues the content for the async L1 extraction pipeline (notifyPipeline)
3. Triggers background workers that may generate L2 scenario files or update L3 personas if the content warrants higher-level assets

Read Path: Bottom-Up Fallback

Retrieval follows a fallback hierarchy designed to minimize token usage while maximizing accuracy. The system first attempts to answer using L2/L3 prompts for concise context. If specific facts are required, it falls back to L1 using BM25 and vector retrieval with RRF (Reciprocal Rank Fusion), and finally to L0 for exact message content when necessary. This approach is documented in the README: "Both generation and retrieval are layered … when specific facts are needed, BM25 + vector retrieval + RRF fall back to L1/L0."

Isolation and Session Management

The architecture enforces strict isolation through scope distinctions between layers. L0 and L1 are session-scoped, requiring a non-empty session_id for all write operations, while L2 and L3 are team-agent-wide and persist across sessions.

The SDK enforces these rules in IsolationContext.resolveSessionForWrite (lines 80-95 of client.ts). Every write operation includes team_id, agent_id, and user_id to guarantee memory assets never leak across unrelated agents or users.

Versioned Assets and Privacy Controls

L2 scenario files and L3 persona content use versioned storage (V3ScenarioWriteRequest, V3CoreWriteRequest). Deleting or overwriting creates new versions rather than erasing history, supporting auditability and rollback.

For privacy-preserving resets, the clearChatMemory endpoint (documented in MemoryCore/v3-api-memorycore-doc.md section 15.1) wipes the content of L0-L3 while preserving asset metadata, ownership, and ACLs:

await client.clearChatMemory({
  memory_ids: ['chat_memory-team_1-agent_chat'],
});

Working with Layered Memory in Code

Adding Conversation Data (L0) with Automatic L1 Extraction

The TypeScript SDK requires strict isolation context. The sessionId parameter is mandatory for L0 writes, triggering the extraction pipeline automatically:

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

const client = new MemoryClient({
  endpoint: 'http://localhost:8420',
  teamId: 'team_1',
  agentId: 'agent_chat',
  userId: 'user_42',
  sessionId: 'sess_001',   // Required for L0/L1 writes
});

await client.addConversation({
  session_id: 'sess_001',
  messages: [
    { role: 'user', content: '请帮我把今天的部署记录保存下来' },
    { role: 'assistant', content: '好的，我已经记录了！' },
  ],
});

Retrieving Session-Scoped History

Query L0 content with optional session aggregation. Omitting session_id aggregates across all sessions for the specified user:

const { messages, total } = await client.queryConversation({
  limit: 5,
});

console.log('Recent L0:', messages.map(m => m.content));

Accessing Scenario Files (L2)

Read project-specific knowledge without session constraints:

const { data } = await client.readScenario({
  path: '/projectX/architecture.md',
});
console.log('Scenario content:', data?.content);

Updating Core Personas (L3)

Write persistent behavioral templates that apply across all sessions:

await client.writeCore({
  content: `

# Persona: DevOps Engineer

- Expert in CI/CD pipelines
- Prefers reproducible builds
- Uses Tencent Cloud services
`,
});

Summary

• L0 (Conversation) stores raw chat logs with full metadata, while L1 (Atom) extracts structured facts via an async pipeline managed in MemoryCore/src/utils/pipeline-manager.ts.
• L2 (Scenario) and L3 (Core) provide project-wide and persona-level context, using versioned storage to preserve history during updates.
• The read-path implements a bottom-up fallback: L2/L3 → L1 (BM25+vector) → L0, optimizing for both conciseness and detail.
• Strict isolation requires session_id for L0/L1 operations, while L2/L3 operate at the team-agent level, enforced by IsolationContext.resolveSessionForWrite in sdk/memory-core/typescript/src/v3/client.ts.
• Asset-level operations like clearChatMemory enable privacy resets without destroying metadata bindings or ownership records.

Frequently Asked Questions

What triggers the L1 atom extraction from L0 conversations?

The addConversation method in sdk/memory-core/typescript/src/v3/client.ts automatically calls notifyPipeline after persisting L0 data, which enqueues the content for background processing. The pipeline parses raw text and generates structured L1 atoms without requiring manual intervention.

Why does querying L2 and L3 not require a session ID?

L2 (Scenario) and L3 (Core) layers are designed as team-agent-wide assets that persist across sessions, providing stable project context and persona definitions. The SDK enforces this in IsolationContext.resolveSessionForWrite, which validates that L0/L1 writes include session_id while allowing L2/L3 operations to omit it.

How does the retrieval fallback hierarchy improve performance?

By attempting retrieval first at L2/L3 (concise context), then falling back to L1 (BM25 + vector search with RRF), and finally L0 (exact messages), the system minimizes token usage in prompts. This layered approach ensures agents get high-level guidance when possible, while retaining access to granular facts only when necessary.

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