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

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

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.

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