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

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

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:

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:

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:

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:

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 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.
• Core implementations reside in dedicated TypeScript modules: conversation.ts, atomic.ts, scenario.ts, and 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.

Which source files implement the four-layer memory model?

The concrete implementations reside in MemoryCore/src/core/conversation.ts, MemoryCore/src/core/atomic.ts, MemoryCore/src/core/scenario.ts, and MemoryCore/src/core/profile.ts. The HTTP routing that exposes these layers publicly is defined in MemoryCore/src/gateway/v3/router.ts, while the high-level architectural documentation appears in 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.

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