# TencentDB Agent Memory Four-Layer Model: Complete Guide to L0-L3 Architecture

> Master the TencentDB Agent Memory four-layer model L0-L3. Understand how raw dialogue evolves to long-term personas via isolated HTTP endpoints and TypeScript modules. Get the complete guide.

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

---

**The four-layer memory model in TencentDB Agent Memory organizes conversational data into a hierarchy ranging from raw dialogue (L0) to long-term personas (L3), with each layer exposed through isolated HTTP endpoints and implemented in specific TypeScript modules.**

TencentDB Agent Memory implements a hierarchical storage architecture that separates conversational data into four distinct abstraction layers. This design enables AI agents to retrieve context at varying granularities, from complete message history to distilled user profiles. The model is fully open-sourced in the TencentCloud/TencentDB-Agent-Memory repository and exposed via a unified HTTP gateway backed by SQLite.

## Overview of the Four-Layer Memory Architecture

The four-layer memory model structures data as a pyramid of increasing abstraction. Each layer serves a specific purpose in the agent's contextual understanding, from capturing raw interactions to maintaining persistent personas across sessions.

### L0 – Conversation Layer

The **L0 Conversation layer** stores the complete turn-by-turn dialogue between users and agents. This layer retains raw messages with full temporal fidelity, capturing every interaction exactly as it occurred. According to the source code in [`MemoryCore/src/core/conversation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation.ts), this layer handles the foundational data structure upon which all higher abstractions depend.

API access flows through `/v3/conversation/*` endpoints, allowing direct insertion and retrieval of dialogue turns.

### L1 – Atomic Memory Layer

The **L1 Atomic Memory layer** extracts small, reusable facts from conversations, such as names, dates, or specific settings. These discrete data points serve as short-term contextual anchors that agents can query without processing entire conversation histories. The implementation resides in [`MemoryCore/src/core/atomic.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/atomic.ts), providing granular storage for individual facts.

Access this layer via `/v3/atomic/*` endpoints to store and retrieve specific key-value pairs derived from ongoing dialogues.

### L2 – Scenario Layer

The **L2 Scenario layer** groups related atomic memories into structured "scene" objects. Unlike isolated facts, scenarios maintain contextual relationships, such as meeting contexts or project briefs that bind multiple atomic elements together. The [`MemoryCore/src/core/scenario.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/scenario.ts) module implements this structured grouping logic.

Query scenarios through `/v3/scenario/*` endpoints to retrieve cohesive context blocks rather than scattered individual facts.

### L3 – Profile Layer

The **L3 Profile layer** maintains long-term persona or role summaries that persist across many sessions. This top-level abstraction aggregates information from lower layers to build comprehensive user or agent models. The core logic lives in [`MemoryCore/src/core/profile.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/profile.ts), managing durable identity information.

Access profiles via `/v3/core/*` endpoints, specifically `/v3/core/profile`, to fetch persistent user characteristics and preferences.

## Storage Isolation and Multi-Tenancy Security

All four layers enforce strict **three-dimensional isolation** based on Team, Agent, and User identifiers. This architecture ensures complete data separation between tenants, preventing cross-contamination of conversational memory.

Every API request must include `team_id`, `agent_id`, and `user_id` either as JSON body parameters or `x-tdai-*` HTTP headers. The storage backend uses SQLite, as documented in [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md), with each tenant's data logically segregated within the database schema.

## Gateway Routing and API Structure

The unified HTTP gateway routes requests to layer-specific handlers based on URL path conventions. The [`MemoryCore/src/gateway/v3/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v3/router.ts) file maps incoming requests to the appropriate core modules:

- `/v3/conversation` routes to conversation handlers
- `/v3/atomic` routes to atomic memory handlers  
- `/v3/scenario` routes to scenario handlers
- `/v3/core/*` routes to profile and core memory handlers

This routing layer abstracts the underlying storage complexity, presenting a consistent interface regardless of which memory layer is being accessed.

## Practical Code Examples

### Writing to L0 Conversation Layer

Store raw dialogue turns using standard HTTP POST requests:

```bash
curl -X POST http://127.0.0.1:8420/v3/conversation \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-team-id: my-team" \
  -H "x-tdai-agent-id: my-agent" \
  -H "x-tdai-user-id: alice" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-123",
        "role": "user",
        "content": "I need a list of my upcoming meetings.",
        "timestamp": 1724832000
      }'

```

### Querying L1 Atomic Memory

Retrieve specific facts using GET requests with key parameters:

```bash
curl -G http://127.0.0.1:8420/v3/atomic \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-team-id: my-team" \
  -H "x-tdai-agent-id: my-agent" \
  -H "x-tdai-user-id: alice" \
  --data-urlencode "key=name" \
  --data-urlencode "session_id=sess-123"

```

### Accessing L2 Scenarios

Fetch grouped context objects by scenario identifier:

```bash
curl -G http://127.0.0.1:8420/v3/scenario \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-team-id: my-team" \
  -H "x-tdai-agent-id: my-agent" \
  -H "x-tdai-user-id: alice" \
  --data-urlencode "scenario_id=meeting-2024-09"

```

### Retrieving L3 Profiles

Access long-term user personas through the core profile endpoint:

```bash
curl -G http://127.0.0.1:8420/v3/core/profile \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-team-id: my-team" \
  -H "x-tdai-agent-id: my-agent" \
  -H "x-tdai-user-id: alice" \
  --data-urlencode "profile_id=user-alice"

```

### TypeScript SDK Implementation

For programmatic access, the `MemoryPromptClient` class abstracts the layer parameter:

```typescript
import { MemoryPromptClient } from '../sdk/memory-core/typescript/src/v3/memory-prompt-client.js';

const client = new MemoryPromptClient({
  baseUrl: 'http://127.0.0.1:8420',
  apiKey: process.env.TDAI_GATEWAY_API_KEY,
});

await client.layer({
  team_id: 'my-team',
  agent_id: 'my-agent',
  user_id: 'alice',
  layer: 'L0',
  block_id: 'sess-123',
  page: 0,
  pageSize: 10,
});

```

The SDK implementation in [`sdk/memory-core/typescript/src/v3/memory-prompt-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/memory-prompt-client.ts) automatically handles the layer specification and isolation headers.

## Summary

- The four-layer model separates conversational data into **L0 (Conversation)**, **L1 (Atomic Memory)**, **L2 (Scenario)**, and **L3 (Profile)** layers, each serving distinct abstraction needs.
- **Storage isolation** enforces Team/Agent/User boundaries across all layers, ensuring multi-tenant security in the SQLite backend.
- **HTTP endpoints** follow predictable patterns: `/v3/conversation`, `/v3/atomic`, `/v3/scenario`, and `/v3/core/*`, routed through [`MemoryCore/src/gateway/v3/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v3/router.ts).
- **Core implementations** reside in dedicated TypeScript modules: [`conversation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/conversation.ts), [`atomic.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/atomic.ts), [`scenario.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/scenario.ts), and [`profile.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/profile.ts) within the `MemoryCore/src/core/` directory.
- **SDK support** includes the `MemoryPromptClient` class for typed interactions with the layer-specific APIs.

## Frequently Asked Questions

### What is the purpose of separating memory into four layers?

The four-layer architecture allows AI agents to efficiently retrieve context at appropriate granularities. Raw conversation history (L0) provides complete fidelity for specific queries, while higher layers (L1-L3) offer progressively compressed, semantically rich representations that reduce token consumption and improve retrieval speed. This separation enables agents to access quick facts (L1), situational context (L2), or persistent user models (L3) without processing entire dialogue histories.

### How does TencentDB Agent Memory ensure data isolation between different teams?

The system implements **three-dimensional isolation** requiring `team_id`, `agent_id`, and `user_id` for every operation. These identifiers function as mandatory namespaces within the SQLite storage backend, physically and logically segregating all four memory layers. As implemented in the core storage modules, no cross-tenant data access is possible because every query filters by these three isolation dimensions enforced at the gateway level in [`MemoryCore/src/gateway/v3/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v3/router.ts).

### Which source files implement the four-layer memory model?

The concrete implementations reside in [`MemoryCore/src/core/conversation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation.ts#L0), [`MemoryCore/src/core/atomic.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/atomic.ts#L1), [`MemoryCore/src/core/scenario.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/scenario.ts#L2), and [`MemoryCore/src/core/profile.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/profile.ts#L3). The HTTP routing that exposes these layers publicly is defined in [`MemoryCore/src/gateway/v3/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v3/router.ts), while the high-level architectural documentation appears in [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md).

### Can I access multiple memory layers simultaneously using the SDK?

Yes, the `MemoryPromptClient` class supports accessing any layer by specifying the `layer` parameter as 'L0', 'L1', 'L2', or 'L3' in method calls. While each API endpoint targets a specific layer, client applications can orchestrate calls across multiple layers within a single session to composite rich contextual prompts. The SDK handles the necessary isolation headers and routing for each layer automatically.