# How L2 Memory Layers Are Organized in TencentDB Agent Memory

> Discover how TencentDB Agent Memory organizes L2 memory layers using team-agent scoped scenario blocks accessed via /v3/scenario/* API endpoints without session identifiers.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```python
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.