# What Is the Purpose of Each Memory Layer (L0-L3) in TencentDB Agent Memory?

> Understand the purpose of each memory layer L0-L3 in TencentDB Agent Memory. Discover how transient and persistent data are organized for efficient knowledge management.

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

---

**TencentDB Agent Memory organizes data into four hierarchical layers—L0, L1, L2, and L3—where lower layers store transient conversational data and higher layers persist abstract, long-term knowledge.**

The **TencentDB-Agent-Memory** repository implements a pyramid-style memory architecture that lets AI agents store, retrieve, and manipulate information at different granularities. According to the source code in [`sdk/memory-core/typescript/README_CN.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README_CN.md), this design separates raw dialogue history from structured facts, contextual scenarios, and stable user personas, offering flexible isolation through the optional `sessionId` parameter.

## The Four Memory Layers Explained

### L0: Raw Conversational Dialogue

**L0** stores the complete transcript of user-agent interactions—the literal conversation turns. This layer captures the *conversation* itself in its rawest form, preserving the exact sequence of messages exchanged between user and assistant.

Key operations exposed 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) include:
- `addConversation()` – appends new messages to a session
- `queryConversation()` – retrieves a session’s message history  
- `searchConversation()` – performs full-text search across messages
- `deleteConversation()` – removes specific messages

When implemented as shown in the repository’s TypeScript SDK, this layer acts as the agent’s short-term working memory for the current interaction thread.

### L1: Structured Atomic Notes

**L1** contains structured atomic memories—key-value pairs or semantic facts extracted from conversations. Unlike the raw text of L0, L1 stores *meaning* such as user preferences, decisions, or extracted entities in a queryable format.

The primary operations are:
- `updateAtomic()` – creates or modifies a fact
- `queryAtomic()` – retrieves specific atomic memories
- `searchAtomic()` – semantic search across stored facts
- `deleteAtomic()` – removes obsolete entries

According to the API specification in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md), L1 serves as the agent’s semantic memory, enabling it to recall "the user prefers Paris" rather than searching through entire chat transcripts.

### L2: Scenario Files

**L2** manages scenario files—markdown documents or other assets that describe a *scene*, *context*, or *standard operating procedure*. This layer supplies *contextual knowledge* that prompts can reference, such as policies, manuals, or situational guidelines.

Core operations include:
- `listScenarios()` – enumerates available context files
- `readScenario()` – loads a specific document
- `writeScenario()` – creates or updates scene descriptions
- `rmScenario()` – deletes scenario files

As noted in the source documentation, L2 operates at the **team level** and does not consume `sessionId`, meaning these resources are shared globally across all sessions for a given team-agent combination.

### L3: Core User Profile

**L3** maintains the core user profile—a high-level persona containing long-term traits, stable preferences, and demographic information that persists indefinitely. This layer supplies a *stable persona* that survives across sessions and even different agents within the same team.

Available operations are:
- `readCore()` – retrieves the user’s persistent profile
- `writeCore()` – updates core attributes
- `countCore()` – returns profile statistics

Implemented in [`MemoryCore/openclaw-plugin/src/hooks/recall.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/openclaw-plugin/src/hooks/recall.ts), L3 represents the apex of the memory pyramid, holding the most abstract and durable knowledge about the user.

## Session Isolation vs. Global Aggregation

The four layers behave differently regarding session scope based on the `sessionId` parameter:

- **With `sessionId` provided** → L0 and L1 operations are *session-scoped*, affecting only the specified conversation thread
- **With `sessionId: null`** → L0 and L1 operations *aggregate* across all sessions sharing the same `(team, agent, user)` tuple
- **L2 and L3** are inherently team-level; they ignore `sessionId` and apply globally to the agent within the team

This isolation model enables developers to choose between ephemeral session memories and persistent cross-session knowledge on a per-operation basis.

## Practical Implementation with the TypeScript SDK

The `MemoryClient` class 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) exposes methods that automatically target the appropriate layer. Here is a complete workflow demonstrating all four layers:

```typescript
import { MemoryClient } from "@tencentdb-agent-memory/memory-sdk-ts/v3";

const client = new MemoryClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "your-gateway-api-key",
  serviceId: "mem-instance-1",
  teamId: "team-123",
  agentId: "agent-xyz",
  userId: "user-abc",
  sessionId: "sess-001",           // L0/L1 scoped to this session
});

// L0: Capture raw conversation
await client.addConversation({
  messages: [{ role: "user", content: "Hi, I need a travel plan." }],
});
const conv = await client.queryConversation({ limit: 10 });

// L1: Store structured facts
await client.updateAtomic({ key: "preferred_city", value: "Paris" });
const facts = await client.searchAtomic({ query: "city", limit: 5 });

// L2: Manage contextual knowledge
await client.writeScenario({ path: "travel.md", content: "# Travel Guide\n..." });

const guide = await client.readScenario({ path: "travel.md" });

// L3: Access persistent profile
const profile = await client.readCore();

```

All SDK calls abstract the underlying HTTP endpoints (`/v3/...`), routing requests to the correct memory layer automatically.

## Summary

- **L0** stores raw conversational turns for immediate dialogue context
- **L1** holds structured key-value facts for semantic recall
- **L2** manages team-level scenario files and contextual documents  
- **L3** preserves long-term user personas across all sessions
- **Session scope** applies selectively: L0/L1 respect `sessionId` while L2/L3 are team-global
- **Implementation** uses `MemoryClient` methods that map directly to each layer’s CRUD operations

## Frequently Asked Questions

### What is the difference between L0 and L1 memory in TencentDB Agent Memory?

**L0 stores raw conversation transcripts**—the literal text of user and assistant messages—while **L1 stores extracted semantic facts** as structured key-value pairs. Use L0 when you need the full conversational context, and L1 when you need to query specific facts like "preferred_city=Paris" without parsing conversation history.

### How does session isolation work across the four memory layers?

**L0 and L1 support optional session isolation** through the `sessionId` parameter; when provided, operations affect only that session, but when omitted, they aggregate across all user sessions. **L2 and L3 are always team-scoped** and do not accept `sessionId`, meaning they are shared globally across all sessions for a given agent-team combination.

### When should an agent use L2 scenario files instead of L1 atomic memories?

**Use L2** when you need to store rich contextual documents such as standard operating procedures, markdown guides, or complex scene descriptions that exceed simple key-value storage. **Use L1** for discrete, queryable facts about the user. L2 files are typically read into prompts as context, while L1 entries are searched or retrieved as specific data points.

### Can different agents within the same team access a user’s L3 core profile?

**Yes**, the L3 core profile is shared at the team level across all agents. Since L3 operations do not require a `sessionId` and are keyed to the `(team, user)` tuple, any agent within the same team can read and write the persistent user persona, enabling consistent personality modeling across different agent instances.