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

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, 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.

// 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.

// 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.

// 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.

// 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
• 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, 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:

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	L0 client initialization and writeL0 flag handling
MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts	L2/L3 system prompt injection implementation
MemoryCore/v3-api-memorycore-doc.md	Definitive API reference for all four layers
README.md (repo root)	Visual architecture overview and flowchart
docs/tdai-v2-technical-ops.md	Pipeline documentation for L0→L1→L2→L3 transformation
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. 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.

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