Understanding the Layered Architecture of TencentDB Agent Memory

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

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

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.

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