# Understanding the Layered Architecture of TencentDB Agent Memory

> Explore the layered architecture of TencentDB Agent Memory, featuring a four-layer system (L0-L3) managed by a Node.js Gateway. Understand how conversations, facts, contexts, and profiles are isolated and accessed.

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

---

**TencentDB Agent Memory implements a four-layer memory system (L0-L3) that isolates raw conversations, extracted facts, scene contexts, and persona profiles behind a local Node.js Gateway sidecar exposing version-3 HTTP endpoints.**

The layered architecture of TencentDB Agent Memory organizes conversational AI state into distinct storage tiers optimized for different access patterns and retention requirements. This open-source system, available at `TencentCloud/TencentDB-Agent-Memory`, structures data across four hierarchical layers accessed through a unified Gateway that enforces strict tenancy isolation. Each layer operates independently, allowing the system to balance real-time performance with long-term memory synthesis.

## The Four Memory Layers (L0-L3)

The architecture divides memory into four specialized layers, each with dedicated API endpoints and storage characteristics.

### L0 – Conversation Layer

The **Conversation Layer** stores raw dialog messages between users and assistants. This layer captures the complete, unprocessed interaction history through endpoints such as `conversation/add`, `conversation/search`, and `conversation/query`. According to the source code in [`MemoryCore/hermes-plugin/memory/memory_tencentdb/__init__.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/hermes-plugin/memory/memory_tencentdb/__init__.py), the `sync_turn` method writes new exchanges to this layer immediately after each turn, ensuring the system retains the canonical record of all interactions.

### L1 – Extraction Layer

The **Extraction Layer** contains atomic "memories" distilled from L0 conversations, including discrete facts, user instructions, and preference statements. Accessed via `atomic/search`, `atomic/update`, and `atomic/delete` endpoints, this layer powers structured recall through the `memory_tencentdb_memory_search` tool. The Python client in [`sdk/memory-core/python/tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py) exposes these operations as `atomic_search`, enabling the provider to retrieve relevant context without processing full conversation logs.

### L2 – Scene Blocks

The **Scene Blocks Layer** maintains hierarchical markdown files describing operational contexts, plans, and structured scenarios. Endpoints `scenario/ls` and `scenario/read` (accessed via `memory_tencentdb_read_scene`) allow agents to navigate complex, multi-step workflows. This layer stores contextual metadata that guides agent behavior across extended sessions, distinct from the atomic facts stored in L1.

### L3 – Persona Synthesis

The **Persona Synthesis Layer** houses the long-term user profile and core identity descriptors. Through `core/read` and `core/write` endpoints, the system maintains persistent user models that survive individual sessions. As implemented in the provider, this data populates the `system_prompt_block` injected into LLM prompts, ensuring consistent personality-aware responses.

## Gateway Architecture and Sidecar Management

All memory layers route through a local Node.js **Gateway** sidecar that exposes the `/v3/*` HTTP API. The `MemoryTencentdbProvider` initializes this connection through the `GatewaySupervisor` class defined in [`MemoryCore/hermes-plugin/memory/memory_tencentdb/supervisor.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/hermes-plugin/memory/memory_tencentdb/supervisor.py).

The supervisor performs three critical functions:

1. **Service Discovery**: Resolves connection parameters from environment variables `MEMORY_TENCENTDB_GATEWAY_HOST` and `MEMORY_TENCENTDB_GATEWAY_PORT`, auto-discovering the Gateway start command from [`src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/server.ts).
2. **Health Monitoring**: Maintains a background watchdog thread that monitors Gateway process health.
3. **Automatic Recovery**: Implements **circuit breaker** logic using `_BREAKER_THRESHOLD` and `_BREAKER_COOLDOWN_SECS` constants, alongside a recover throttle (`_RECOVER_COOLDOWN_SECS`) that prevents restart loops.

The provider records success and failure states via `_record_success` and `_record_failure` methods, triggering recovery only after the cooldown period expires.

## Data Flow: Prefetch and Sync Operations

The architecture separates read and write operations into distinct phases optimized for latency and consistency.

### Parallel Prefetch Operations

During the `prefetch` phase (executed before each LLM inference), the provider initiates three concurrent calls:

- **L1 retrieval** via `atomic_search` to fetch relevant memories.
- **L3 retrieval** via `core_read` to load the user persona.
- **L2 retrieval** via `scenario_ls` to list available scene contexts.

These parallel requests minimize latency while assembling the structured prompt containing `<relevant-memories>`, `<user-core>`, and `<scene-navigation>` blocks that inform the model's response generation.

### Synchronous Turn Capture

After the LLM generates a response, the `sync_turn` method persists the exchange to L0 through `conversation_add`. This operation respects the same isolation context (`team_id`, `agent_id`, `user_id`) and implements throttling to prevent goroutine exhaustion during high-volume concurrent sync operations.

## Strict Tenancy Isolation

Version 3 of the API enforces **strict tenancy isolation** through the `V3MemoryClientConfig` interface defined in [`sdk/memory-core/typescript/src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/types.ts). Every request must include three mandatory identifiers:

- `team_id`: The organizational tenant.
- `agent_id`: The specific agent instance.
- `user_id`: The end-user context.

This schema guarantees that memories remain scoped per tenant and cannot bleed across agents or users, preventing cross-contamination in multi-tenant deployments.

## Implementation Example

Developers integrate this architecture through the `MemoryTencentdbProvider` class. The following pattern demonstrates initialization, prefetch, and turn synchronization:

```python
from tencentdb_agent_memory import MemoryTencentdbProvider

# Initialize with strict tenancy context

provider = MemoryTencentdbProvider()
provider.initialize(
    session_id="sess-123",
    team_id="my-team",
    agent_id="my-agent",
    user_id="user-42",
)

# Prefetch L1, L2, and L3 data for prompt construction

prompt = provider.prefetch(query="what did the user say about travel plans?")

# prompt contains structured memory blocks for the LLM

# After LLM response, persist the turn to L0

provider.sync_turn(
    user_content="I want to visit Tokyo next spring.",
    assistant_content="Sure, let me draft a travel plan for you.",
    session_id="sess-123",
)

```

The provider handles all Gateway communication, circuit breaker logic, and background supervision automatically, presenting a synchronous interface to the Hermes framework while managing asynchronous sidecar operations internally.

## Summary

- **Four distinct layers** (L0-L3) separate raw conversation logs, extracted atomic facts, scene hierarchies, and persona profiles.
- **Node.js Gateway sidecar** exposes version-3 HTTP endpoints (`/v3/*`) and manages local data access.
- **GatewaySupervisor** implements circuit breaker patterns and automatic recovery to ensure fault tolerance.
- **Parallel prefetch** retrieves L1, L2, and L3 data simultaneously to minimize inference latency.
- **Strict tenancy isolation** via `team_id`, `agent_id`, and `user_id` prevents cross-tenant data leakage.

## Frequently Asked Questions

### What are the four layers in TencentDB Agent Memory's architecture?

The architecture consists of **L0 (Conversation)** storing raw dialog, **L1 (Extraction)** holding atomic facts and memories, **L2 (Scene Blocks)** containing hierarchical markdown context files, and **L3 (Persona Synthesis)** maintaining long-term user profiles. Each layer has dedicated API endpoints and distinct retention characteristics optimized for specific retrieval patterns.

### How does the Gateway sidecar ensure fault tolerance?

The `GatewaySupervisor` class implements a circuit breaker pattern with configurable thresholds (`_BREAKER_THRESHOLD`) and cooldown periods (`_BREAKER_COOLDOWN_SECS`, `_RECOVER_COOLDOWN_SECS`). A background watchdog monitors process health and automatically restarts the Gateway if it becomes unresponsive, while throttling mechanisms prevent resource exhaustion during recovery attempts.

### What is the purpose of the prefetch operation?

The `prefetch` method executes three parallel API calls—`atomic_search` (L1), `core_read` (L3), and `scenario_ls` (L2)—to assemble contextual information before LLM inference. This approach minimizes latency by retrieving memories, persona data, and scene contexts simultaneously, then merging them into structured prompt blocks that guide the model's response generation.

### How is tenant isolation enforced across memory layers?

All v3 API endpoints require `team_id`, `agent_id`, and `user_id` parameters defined in `V3MemoryClientConfig`. The Gateway validates these identifiers on every request to `conversation/add`, `atomic/search`, `scenario/read`, and `core/read`, ensuring complete data isolation between tenants and preventing memory leakage across different agents or users.