# Understanding the Layered Architecture of TencentDB Agent Memory

> Explore the four-layer memory architecture of TencentDB Agent Memory. Discover how L0-L3 organizes user data and access through a Node.js Gateway API.

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

---

**The TencentDB Agent Memory system implements a four-layer memory architecture (L0–L3) that organizes user data into conversation history, atomic extractions, hierarchical scene blocks, and long-term persona profiles, all accessed through a local Node.js Gateway sidecar exposing a version-3 HTTP API with strict tenant isolation.**

The **layered architecture of TencentDB Agent Memory** provides a structured approach to managing AI agent context across different temporal and semantic scales. This open-source system separates transient dialog data from persistent user knowledge through distinct storage tiers, enabling efficient retrieval and maintenance of conversational state. Each layer serves a specific functional purpose within the broader Hermes framework, with the Python `MemoryTencentdbProvider` coordinating access via a supervised Gateway process.

## The Four-Layer Memory Hierarchy

The architecture organizes memory into four ascending levels of abstraction, from raw conversational data to synthesized user personas. Each layer operates independently but contributes to a unified context window during agent inference.

### L0 – Conversation Layer

The **Conversation Layer** stores raw dialog messages exchanged between users and assistants. This ephemeral tier captures the complete chat history without semantic processing, serving as the foundational record of interaction. 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), this layer is accessed through endpoints such as `conversation/add`, `conversation/search`, and `conversation/query`. The `sync_turn` method writes new exchanges to L0 after each LLM response, ensuring conversation continuity while respecting session isolation boundaries.

### L1 – Extraction Layer

The **Extraction Layer** contains atomic "memories" derived from conversation analysis, including discrete facts, user preferences, and explicit instructions. Unlike the raw L0 data, L1 stores structured, semantically meaningful units that support targeted retrieval. The provider invokes `atomic_search` during the prefetch phase to retrieve relevant memories via the `atomic/search` endpoint, enabling contextually appropriate responses without processing entire conversation histories.

### L2 – Scene Blocks Layer

**Scene Blocks** represent hierarchical context files stored in markdown format, describing operational environments, task plans, or domain-specific configurations. This layer supports complex multi-step workflows by maintaining structured scene descriptions that agents can reference during execution. The `scenario_ls` and `scenario/read` endpoints allow the system to list available contexts and retrieve specific scene definitions, which the provider accesses through `memory_tencentdb_read_scene` functionality.

### L3 – Persona Synthesis Layer

The **Persona Synthesis Layer** maintains long-term user profiles and core descriptions that persist across sessions. This tier captures stable user attributes, preferences, and relationship history that inform the agent's personality adaptation. During initialization and prefetch operations, the system calls `core_read` via the `core/read` endpoint to retrieve the `system_prompt_block`, injecting synthesized persona context directly into LLM prompts.

## Gateway Architecture and Sidecar Management

The layered memory system exposes functionality through a local **Node.js Gateway** sidecar that implements a version-3 (`/v3/*`) HTTP API. This architectural separation isolates the Python provider from direct database concerns while enabling cross-language compatibility.

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) manages the sidecar lifecycle with the following responsibilities:

1. **Service Discovery**: Auto-discovers the Gateway start command from [`src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/server.ts) and resolves connection parameters via environment variables (`MEMORY_TENCENTDB_GATEWAY_HOST`, `MEMORY_TENCENTDB_GATEWAY_PORT`).
2. **Health Monitoring**: Maintains a background watchdog thread that continuously verifies Gateway availability.
3. **Automatic Recovery**: Implements resurrection logic to restart the Gateway process following failures.

All Gateway interactions require explicit tenant identification 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), mandating `team_id`, `agent_id`, and `user_id` parameters for every request.

## Fault Tolerance and Circuit Breaking

The provider implements robust error handling through a **circuit breaker pattern** to prevent cascading failures during Gateway outages. The `MemoryTencentdbProvider` tracks operation outcomes via `_record_success` and `_record_failure` methods, respecting configurable thresholds (`_BREAKER_THRESHOLD`, `_BREAKER_COOLDOWN_SECS`) and recovery throttles (`_RECOVER_COOLDOWN_SECS`). When the circuit opens due to consecutive failures, the system enters a cooldown period before attempting automatic recovery, ensuring stability under load.

## Data Flow During Agent Turns

Each conversational turn follows a structured lifecycle that coordinates reads across L1–L3 and writes to L0.

### The Prefetch Phase

Before generating a response, the `prefetch` method executes three parallel API calls to assemble context:

- **L1 Retrieval**: `atomic_search` retrieves relevant atomic memories matching the current query.
- **L3 Retrieval**: `core_read` fetches the user's persistent persona profile.
- **L2 Retrieval**: `scenario_ls` lists available scene contexts for the current operational domain.

These results merge into a structured prompt containing `<relevant-memories>`, `<user-core>`, and `<scene-navigation>` blocks, which the LLM receives as part of its system context.

### The Synchronization Phase

Following LLM response generation, the `sync_turn` method persists the exchange to L0 via `conversation_add`. This operation respects the same isolation context (`team_id`, `agent_id`, `user_id`) and implements concurrency control to throttle simultaneous sync threads, preventing resource exhaustion during high-volume interactions.

## Strict Tenant Isolation

Version 3 of the API introduces **mandatory tenancy isolation** that prevents memory leakage between organizations, agents, or users. Every request to any layer must include the three-part identifier context 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). 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) enforces these constraints during initialization, ensuring that memories remain strictly scoped to their respective tenants throughout the data lifecycle.

## Implementation Example

The following demonstrates initializing the provider and executing the standard prefetch-sync workflow within a Hermes-based agent:

```python
from memory.memory_tencentdb import MemoryTencentdbProvider

# Initialize with strict tenant isolation

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

# Prefetch: Retrieve L1 memories, L3 persona, and L2 scenes

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

# Returns structured blocks: <relevant-memories>, <user-core>, <scene-navigation>

# Sync: Store the turn in L0 conversation history

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",
)

```

Key implementation files include:
- [`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) – Core provider with circuit breaker and prefetch logic
- [`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) – Gateway lifecycle management
- [`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) – Python v3 client for L0-L3 operations
- [`sdk/memory-core/python/tencentdb_agent_memory/v3/memory_prompt.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/memory_prompt.py)  Memory prompt construction utilities

## Summary

- **TencentDB Agent Memory** organizes data into four distinct layers: L0 (raw conversation), L1 (atomic extractions), L2 (scene blocks), and L3 (persona synthesis).
- The **Node.js Gateway sidecar** exposes layer-specific endpoints under `/v3/*`, managed by the `GatewaySupervisor` with automatic health monitoring and recovery.
- **Strict tenant isolation** requires `team_id`, `agent_id`, and `user_id` for every operation, preventing cross-contamination between users or agents.
- The **`prefetch` method** parallelizes reads across L1, L2, and L3 to assemble comprehensive context, while **`sync_turn`** writes to L0 with concurrency throttling.
- **Circuit breaker logic** (`_BREAKER_THRESHOLD`, `_BREAKER_COOLDOWN_SECS`) protects the system from Gateway failures through automatic failure detection and recovery throttling.

## Frequently Asked Questions

### How does the four-layer architecture improve AI agent performance?

The separation of concerns across L0–L3 enables optimized retrieval strategies for different data types. Raw conversations (L0) provide complete historical records, while atomic memories (L1) allow semantic search without processing entire chat logs. Scene blocks (L2) enable complex task planning, and persona data (L3) ensures consistent user modeling. This hierarchy reduces token consumption by retrieving only relevant structured data rather than full conversation histories.

### What happens when the Gateway sidecar becomes unavailable?

The `GatewaySupervisor` implements a circuit breaker pattern that tracks failure thresholds. When consecutive failures exceed `_BREAKER_THRESHOLD`, the circuit opens for `_BREAKER_COOLDOWN_SECS`, during which requests fail fast without attempting connections. A background watchdog thread monitors the Gateway process and automatically restarts it after the recovery cooldown period expires, ensuring high availability without manual intervention.

### How does tenant isolation prevent data leakage in multi-user environments?

Every API request in the v3 protocol must include `team_id`, `agent_id`, and `user_id` parameters as 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). The Gateway enforces these boundaries at the storage layer, ensuring that queries from one tenant cannot access memories belonging to another. This design supports SaaS deployments where multiple organizations share infrastructure while maintaining strict data separation.

### What is the difference between `prefetch` and `sync_turn` operations?

The `prefetch` method performs read-only operations across L1, L2, and L3 layers to assemble context before LLM inference, executing `atomic_search`, `core_read`, and `scenario_ls` in parallel. Conversely, `sync_turn` writes to L0 via `conversation_add` after the LLM generates a response, persisting the exchange to conversation history. This read-before-write pattern ensures agents respond with appropriate context while maintaining accurate historical records.