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

> Explore TencentDB Agent Memory's layered memory L0-L3 architecture. Understand how it transforms raw interactions into structured knowledge with async processing and session isolation. Learn more.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) section 15.1) wipes the content of L0-L3 while preserving asset metadata, ownership, and ACLs:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.