Understanding the Layered Architecture of TencentDB Agent Memory

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

1. Service Discovery: Auto-discovers the Gateway start command from 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, 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. The Python client in 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:

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 – Core provider with circuit breaker and prefetch logic
• MemoryCore/hermes-plugin/memory/memory_tencentdb/supervisor.py – Gateway lifecycle management
• 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 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. 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.

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