# What Is Stored in the L2 Scenario Layer in TencentDB-Agent-Memory

> Discover what the L2 Scenario layer in TencentDB-Agent-Memory stores. Learn how organized knowledge blocks like JSON and Markdown files enable instant context restoration for AI agents.

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

---

**The L2 Scenario layer stores organized knowledge blocks—typically JSON or Markdown files describing projects, architectures, or recurring tasks—that enable agents to restore working context instantly without reprocessing raw conversation history.**

The TencentDB-Agent-Memory repository implements a hierarchical memory system designed to optimize agent performance through structured context management. The **L2 Scenario layer** serves as the intermediate tier between granular facts and high-level profiles, specifically engineered to provide quick-boot capabilities for specialized work contexts. According to the repository’s architecture documentation, this layer contains distilled information organized around specific projects or operational scenarios rather than isolated data points.

## L2 Scenario Layer Architecture and Purpose

The L2 Scenario layer functions as a contextual bridge within the three-tier memory architecture implemented in `TencentDB-Agent-Memory`.

### Position in the Memory Hierarchy

The memory system organizes information across three distinct granularity levels:

- **L1 Atom**: Stores fine-grained, individual facts and raw conversation snippets
- **L2 Scenario**: Contains organized knowledge blocks representing complete work contexts
- **L3 Core/Persona**: Maintains long-term agent profiles and persistent behavioral patterns

As defined in the repository's [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md), the L2 layer specifically addresses the need for knowledge blocks organized around projects or work scenarios. This positioning allows agents to bypass expensive reprocessing of L1 atomic data when resuming familiar contexts.

### File Formats and Storage Structure

Scenario files within the L2 layer utilize standard document formats that balance human readability with programmatic access:

- **JSON files**: Structured data representations for configuration sets and metadata
- **Markdown files**: Narrative documentation describing architectures, deployment pipelines, or task procedures

These files reside in the directory specified by `StoragePaths.sceneBlocksDir`, managed through the Memory Core gateway rather than direct filesystem access.

## How the L2 Scenario Layer Stores Context

Unlike flat memory records, the L2 layer implements a project-centric organization that mirrors real-world work structures.

### Knowledge Block Organization

Each scenario represents a **knowledge block**—a self-contained unit of context sufficient to restore an agent's understanding of a specific operational domain. Examples include microservice architecture documentation, CI/CD pipeline specifications, recurring maintenance task procedures, and project-specific terminology glossaries.

The storage model emphasizes distilled information over raw conversation logs, enabling sub-second context restoration even after extended periods of inactivity.

### Storage Path and Directory Structure

The physical storage location is abstracted through the `StoragePaths.sceneBlocksDir` constant, referenced by handlers in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts). This abstraction ensures consistent path resolution across different deployment environments while preventing directory traversal vulnerabilities through schema validation in [`v2-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-schemas.ts).

## Managing Scenario Files via the Memory Core API

The L2 Scenario layer exposes a RESTful interface through the Memory Core gateway, providing CRUD operations via the `/v3/scenario` endpoint namespace.

### Listing and Reading Scenarios

Retrieve existing scenarios using the `ls` and `read` handlers implemented in `handleScenarioLs` and `handleScenarioRead` within [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts):

```typescript
// List all scenario files under a project prefix
await fetch('/v3/scenario/ls', {
  method: 'POST',
  body: JSON.stringify({ path_prefix: 'my-project/' })
});

// Read a specific architecture document
await fetch('/v3/scenario/read', {
  method: 'POST',
  body: JSON.stringify({ path: 'my-project/architecture.md' })
});

```

These operations validate paths against the scenario schema before accessing `StoragePaths.sceneBlocksDir`, ensuring secure namespace isolation.

### Writing and Removing Scenario Files

Create, update, or delete scenario blocks using the write and remove handlers:

```typescript
// Write or update a scenario file
await fetch('/v3/scenario/write', {
  method: 'POST',
  body: JSON.stringify({
    path: 'my-project/architecture.md',
    content: '# Architecture\n- Service A\n- Service B'

  })
});

// Remove a scenario file
await fetch('/v3/scenario/rm', {
  method: 'POST',
  body: JSON.stringify({ path: 'my-project/deprecated-config.json' })
});

```

The `handleScenarioWrite` and `handleScenarioRm` functions enforce schema validation through [`MemoryCore/src/gateway/v2-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-schemas.ts) before persisting changes to disk.

## Key Implementation Files

The L2 Scenario layer implementation spans three critical files:

- **[`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts)**: Implements the four core handlers (`handleScenarioLs`, `handleScenarioRead`, `handleScenarioWrite`, `handleScenarioRm`) that process API requests and coordinate storage operations.

- **[`MemoryCore/src/gateway/v2-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-schemas.ts)**: Defines TypeScript interfaces and validation schemas for scenario path parameters, ensuring safe filename handling and preventing directory traversal attacks.

- **[`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md)** (root): Documents the three-layer memory architecture concept, specifically describing how L2 scenarios provide quick-boot context for agents through organized knowledge blocks.

## Summary

- The **L2 Scenario layer** stores organized knowledge blocks—JSON and Markdown files representing projects, architectures, or recurring tasks—in the `StoragePaths.sceneBlocksDir` directory.
- It occupies the intermediate tier between **L1 Atom** (individual facts) and **L3 Core/Persona** (long-term profiles), optimized for rapid context restoration.
- Four dedicated handlers in [`v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-router.ts) manage scenario lifecycle: `handleScenarioLs`, `handleScenarioRead`, `handleScenarioWrite`, and `handleScenarioRm`.
- All operations adhere to strict schemas defined in [`v2-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-schemas.ts) to ensure secure path handling and data integrity.

## Frequently Asked Questions

### What file formats does the L2 Scenario layer use?

The L2 Scenario layer primarily utilizes **JSON** for structured configuration data and **Markdown** for narrative documentation describing architectures, deployment pipelines, or task procedures. These formats enable both human editing and programmatic parsing by the agent system.

### How does the L2 Scenario layer differ from L1 Atom and L3 Core layers?

The **L1 Atom** layer stores granular, isolated facts extracted from conversations, while the **L3 Core/Persona** layer maintains long-term behavioral profiles and persistent agent characteristics. The **L2 Scenario** layer bridges these extremes by organizing related knowledge into project-centric blocks that provide immediate operational context without requiring atomic-level reconstruction.

### Can I directly access the scenario files on disk?

While scenario files reside in `StoragePaths.sceneBlocksDir`, the architecture encourages access exclusively through the **Memory Core API** (`/v3/scenario/*` endpoints). This ensures path validation, security isolation, and schema compliance enforced by the handlers in [`v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-router.ts) and validation logic in [`v2-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-schemas.ts).

### What operations are supported for managing scenario files?

The L2 Scenario layer supports standard CRUD operations exposed through four dedicated handlers: **`handleScenarioLs`** (list), **`handleScenarioRead`** (retrieve), **`handleScenarioWrite`** (create/update), and **`handleScenarioRm`** (delete). These map to the `ls`, `read`, `write`, and `rm` API endpoints respectively, operating within the secure storage abstraction provided by `StoragePaths.sceneBlocksDir`.