How L2 Memory Layers Are Organized in TencentDB Agent Memory

The TencentDB Agent Memory system implements L2 memory as team-agent scoped scenario blocks stored as files, accessible via the /v3/scenario/* API endpoints without requiring session identifiers.

The TencentDB Agent Memory platform organizes persistent context into a four-layer hierarchy, with L2 memory layers serving as the scenario storage tier shared across sessions. Unlike conversation-specific layers, L2 operates at the team-agent level, enabling reusable "scene blocks" that persist independent of individual chat sessions. This article examines the organizational structure, storage model, and API implementation of L2 memory based on the TencentCloud/TencentDB-Agent-Memory source code.

Understanding the Four-Layer Memory Hierarchy

To grasp how L2 memory layers function, you must first understand their position within the broader architecture. According to the provider documentation in MemoryCore/hermes-plugin/memory/memory_tencentdb/__init__.py, the system implements:

• L0: Conversation logs at the asset level (chat-memory)
• L1: Extraction and atomic memories at the asset level
• L2: Scene blocks (scenarios) at the team + agent level without session requirements
• L3: Persona synthesis and core memory at the team + agent level

The L2 layer specifically stores reusable scenario objects that represent contextual "scene blocks" shared across all sessions for a given team-agent pair.

Organizational Structure of L2 Memory Layers

The L2 layer organizes data through three core mechanisms: tenancy isolation, file-based persistence, and dedicated API endpoints.

Tenancy and Scope Isolation

L2 memory operates exclusively at the team-agent granularity. Each record lives under the tenant tuple (team_id, agent_id), and the API explicitly omits session_id parameters for these operations.

As noted in sdk/memory-core/python/tencentdb_agent_memory/v3/client.py at lines 60-71, the L2 implementation is described as "team+agent 级，不需要 session_id" (team+agent level, no session_id required). This design ensures that scenarios remain accessible across any conversation session belonging to that specific team-agent combination.

The client automatically embeds tenancy information through an IsolationHeader containing team_id, agent_id, and user_id. While session_id is optional and influences only L0-L1 calls, L2 operations ignore it entirely, providing a consistent cross-session view.

File-Based Storage Model

Scenarios persist as files within the gateway's storage directory, typically using Markdown format. When migrating from v2 to v3, the system explicitly handles these as file objects. The migration script MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py at lines 11-15 references "L2/L3 文件迁移" (L2/L3 file migration), copying these files into the new v3 profiles directory.

This file-based approach means each scenario has a distinct path (e.g., games/chess.md) that serves as its unique identifier within the storage system.

API Endpoint Architecture

All L2 operations utilize the /v3/scenario/* endpoint family, implemented in the v3 client. The available methods include:

• list_scenarios(): via POST /v3/scenario/ls
• read_scenario(path): via POST /v3/scenario/read
• write_scenario(path, content, ...): via POST /v3/scenario/write
• rm_scenario(path): via POST /v3/scenario/rm

These endpoints automatically apply tenancy isolation through the client's isolation headers while accepting file paths as primary identifiers.

Working with L2 Scenarios in Practice

The following example demonstrates accessing L2 memory layers using the Python SDK. Notice that no session_id is passed, reflecting the team-agent scope:

from tencentdb_agent_memory.v3 import MemoryClient

# Initialize client with tenancy identifiers

client = MemoryClient(
    endpoint="https://memory.tencentyun.com",
    api_key="YOUR_API_KEY",
    team_id="my-team",
    agent_id="my-agent",
    user_id="my-user",
)

# List scenarios under a specific prefix

scenarios = client.list_scenarios(path_prefix="games/")
print("Available scenarios:", scenarios["items"])

# Read a specific scenario file

scenario = client.read_scenario(path="games/chess.md")
print("Content:", scenario["content"])

# Write or update a scenario

client.write_scenario(
    path="games/chess.md",
    content="# Chess Opening\nUse the Sicilian Defense...",

    summary="Chess opening guide"
)

# Remove a scenario

client.rm_scenario(path="games/old-game.md")

The MemoryClient automatically injects team_id and agent_id into the isolation headers, while the absence of session_id confirms the cross-session nature of L2 storage.

Summary

• L2 memory layers store reusable scenario blocks at the team-agent level, independent of individual conversation sessions.
• Tenancy isolation relies on (team_id, agent_id) tuples without requiring session_id, as implemented in tencentdb_agent_memory/v3/client.py.
• File-based storage persists scenarios as Markdown files within gateway storage directories, referenced by unique paths.
• API operations use the /v3/scenario/* family including list_scenarios(), read_scenario(), write_scenario(), and rm_scenario().
• Migration support explicitly handles L2 files as distinct objects when upgrading from v2 to v3, copying them to the profiles directory.

Frequently Asked Questions

What is the scope of L2 memory in TencentDB Agent Memory?

L2 memory operates at the team + agent level, meaning data is shared across all sessions belonging to a specific team-agent pair. Unlike L0 and L1 layers, which bind to individual conversation sessions, L2 scenarios remain accessible regardless of which specific chat session initiates the request.

How does L2 differ from L0 and L1 memory layers?

While L0 stores conversation logs and L1 maintains atomic extractions—both scoped to specific chat sessions with session_id requirements—L2 organizes reusable scene blocks that persist across sessions. This architectural distinction enables consistent contextual scenarios without duplicating data for every new conversation.

What API endpoints manage L2 scenario blocks?

L2 operations utilize the /v3/scenario/* API family: POST /v3/scenario/ls for listing, POST /v3/scenario/read for retrieval, POST /v3/scenario/write for updates, and POST /v3/scenario/rm for deletion. These map to the SDK methods list_scenarios(), read_scenario(), write_scenario(), and rm_scenario() respectively.

Is session_id required when accessing L2 memory?

No. The L2 layer explicitly does not require session_id parameters. According to the client implementation in sdk/memory-core/python/tencentdb_agent_memory/v3/client.py, L2 is designed as "team+agent 级" (team+agent level) and functions without session identifiers, providing cross-session data persistence.

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