# How the Layered Memory Architecture (L0–L3) Works in TencentDB Agent Memory

> Understand TencentDB Agent Memory's layered architecture (L0-L3). Discover how raw data becomes atomic facts, structured scenarios, and persona profiles for efficient prompt injection.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: architecture
- Published: 2026-09-02

---

**TencentDB Agent Memory uses a four-tier hierarchy where raw conversation (L0) is progressively distilled into atomic facts (L1), structured scenarios (L2), and long-term persona profiles (L3), with L0/L1 scoped to sessions and L2/L3 shared across agents for efficient prompt injection.**

The **TencentDB Agent Memory** system implements a sophisticated layered memory architecture that balances granular conversation tracking with efficient context retrieval. This design separates ephemeral dialogue data from durable knowledge representations, enabling both precise session recall and fast agent bootstrapping. Understanding how the **L0–L3 memory layers** interact is essential for building applications that leverage the full capabilities of the Tencent Cloud memory service.

## Overview of the Four Memory Layers

The architecture defines four distinct abstraction levels, each with specific data types, isolation boundaries, and API endpoints:

| Layer | Content | Isolation | Primary API |
|-------|---------|-----------|-------------|
| **L0** | Raw conversation turns (messages) | **Session-level** — requires `session_id` | `POST /v3/conversation/add`, `GET /v3/conversation/query` |
| **L1** | Atomic memories (atoms) — episodic facts, hints, instructions | **Session-level** — bound to session | `POST /v3/atomic/add`, `GET /v3/atomic/query` |
| **L2** | Scenario files — structured scene or task documents | **Team/Agent-level** — no `session_id` | `POST /v3/scenario/write`, `GET /v3/scenario/read` |
| **L3** | Core persona / long-term profile | **Team/Agent-level** — global to agent | `POST /v3/core/write`, `GET /v3/core/read` |

This progression mirrors cognitive science models: **L0–L1** capture working memory, while **L2–L3** form semantic long-term storage.

## Data Flow: From Raw Conversation to Persona Profile

The **layered memory architecture** implements a pipeline that transforms transient dialogue into persistent, reusable knowledge.

### Layer 0: Conversation Capture

Every user interaction begins at **L0**. In [`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts), the proxy records turns via the **tdai** client when `config.tdai.memory.writeL0` is enabled. The `writeL0` function posts raw messages to the kernel endpoint `/v3/conversation/add`.

```typescript
// L0 write via TypeScript SDK
await client.tdai.conversation.add({
  memory_id: "chat_memory-001",
  messages: [{ role: "user", content: "How do I reset my password?" }],
});

```

### Layer 1: Atomic Extraction

A background Gateway worker reads **L0 entries** and extracts **L1 atoms** — discrete facts like "user asked about password reset" or "agent provided steps A, B, C." These atoms are stored via the atomic API and remain **session-bound** for contextual retrieval.

```typescript
// L1 query — fetch atomic memories for current session
const l1Atoms = await client.tdai.atomic.query({
  memory_id: "chat_memory-001",
  session_id: "sess-42",
  limit: 10,
});

```

### Layer 2: Scenario Synthesis

The pipeline aggregates related atoms into **L2 scenarios** — structured documents describing task contexts or operational scenes. Unlike L0/L1, scenarios are **session-agnostic** and shared across the team or agent.

```typescript
// L2 write — create reusable scenario file
await client.tdai.scenario.write({
  memory_id: "scene_memory-001",
  path: "scenarios/onboarding.md",
  content: "# Onboarding Scenario\nUser wants to set up a new account...",

});

```

### Layer 3: Persona Consolidation

Finally, the system synthesizes a **L3 core persona** — a high-level profile capturing long-term preferences, behavioral patterns, and cognitive models. This **global agent state** persists across all sessions.

```typescript
// L3 read — retrieve consolidated persona
const persona = await client.tdai.core.read({
  memory_id: "core_memory-001",
});

```

## Isolation and Access Patterns

The **layered memory architecture** implements a critical split in how layers are accessed during inference.

### Session-Scoped Layers (L0/L1)

- **Require `session_id`** — strictly tied to specific dialogues
- **Not injected automatically** — preserved as **read-only tools** (`conversation/search`, `atomic/query`)
- **On-demand retrieval** — the LLM invokes these tools explicitly, preserving upstream KV-cache efficiency

### Agent-Global Layers (L2/L3)

- **Session-agnostic** — no `session_id` required
- **Direct system prompt injection** — implemented in [`MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts)
- **Fast bootstrapping** — loaded once per request without repeated retrieval overhead

This design optimizes the latency-critical path: **L2/L3** provide immediate context, while **L0/L1** remain available for deep recall when needed.

## Memory Operations and Lifecycle

### Clearing Memory

The `clearChatMemory()` operation (documented in SDK references) wipes **all four layers** atomically while preserving the memory asset itself, including bindings, ACLs, and visibility configurations.

### Editable Layers

Per [`ROADMAP.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/ROADMAP.md), the panel UI supports direct editing of **L1–L3**. L0 remains append-only by design, ensuring conversation audit trails stay immutable.

## Python SDK Implementation

The same **layered memory architecture** is accessible via Python:

```python
from tencentdb_agent_memory import MemoryClient

client = MemoryClient(
    endpoint="https://memory.example.com",
    api_key="YOUR_TOKEN",
    service_id="instance-1"
)

# L0: Record conversation turn

client.tdai.conversation.add(
    memory_id="chat_memory-001",
    messages=[{"role": "user", "content": "What is my quota?"}]
)

# L1: Query atomic memories

atoms = client.tdai.atomic.query(
    memory_id="chat_memory-001",
    session_id="sess-42",
    limit=5
)

# L2: Define reusable scenario

client.tdai.scenario.write(
    memory_id="scene_memory-001",
    path="scenarios/billing.md",
    content="# Billing Scenario\nDetails…"

)

# L3: Access core persona

persona = client.tdai.core.read(memory_id="core_memory-001")
print(persona)

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts) | L0 client initialization and `writeL0` flag handling |
| [`MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts) | L2/L3 system prompt injection implementation |
| [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) | Definitive API reference for all four layers |
| [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) (repo root) | Visual architecture overview and flowchart |
| [`docs/tdai-v2-technical-ops.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/docs/tdai-v2-technical-ops.md) | Pipeline documentation for L0→L1→L2→L3 transformation |
| [`MemoryPanel/panel-api-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/panel-api-doc.md) | Layer-wise CRUD endpoints for management UI |

## Summary

- **TencentDB Agent Memory** organizes knowledge into four progressive layers: **L0** (raw conversation), **L1** (atomic facts), **L2** (scenarios), and **L3** (persona core).
- **Isolation boundaries** split layers by scope: L0/L1 are **session-local**; L2/L3 are **agent-global**.
- **Access patterns differ**: L2/L3 are **injected into system prompts** for fast retrieval; L0/L1 are **exposed as tools** for on-demand query.
- **Data flows upward** through a background pipeline that distills conversation into increasingly abstract representations.
- **All layers** are manageable via unified TypeScript/Python SDKs with clear endpoint mappings.

## Frequently Asked Questions

### What is the difference between L1 atomic memories and L2 scenarios?

**L1 atoms** are granular, session-bound facts extracted from conversation turns — discrete pieces like "user prefers email notifications." **L2 scenarios** are structured documents aggregating multiple atoms into reusable task or scene descriptions, shared across all sessions for an agent. Atoms support precise recall; scenarios enable efficient context bootstrapping.

### Why are L0 and L1 not automatically injected into prompts?

**Automatic injection** would bloat the system prompt with repetitive, low-signal content and destroy KV-cache efficiency. Instead, L0/L1 remain accessible via **read-only tools** (`conversation/search`, `atomic/query`) that the LLM invokes explicitly when needed. This preserves inference latency while keeping detailed history available.

### Can I edit memory layers directly?

**L1–L3** support direct editing through the panel UI and API endpoints per [`ROADMAP.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/ROADMAP.md). **L0 is append-only** by design to maintain immutable conversation audit trails. Use `clearChatMemory()` to reset all layers while preserving asset metadata.

### How does session isolation work across the layered memory architecture?

**Session-level isolation** applies to L0/L1: every query requires a valid `session_id` and returns only data scoped to that dialogue. **L2/L3 bypass session scope entirely** — they belong to the team or agent entity, enabling persistent knowledge across unrelated conversations without session ID management.