# How L2 Scenario Memory Is Stored and Organized in TencentDB Agent Memory

> Discover how L2 Scenario memory is stored and organized in TencentDB Agent Memory. Learn about Markdown files, JSON indexing, and storage backend for efficient retrieval.

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

---

**L2 Scenario memory in TencentDB Agent Memory persists as Markdown files in a `scene_blocks/` directory, abstracted by a storage backend interface, indexed via JSON for fast retrieval, and isolated per team-agent pair.**

TencentDB Agent Memory implements a four-layer hierarchy (L0→L1→L2→L3) to manage conversational context, with **L2 Scenario memory** serving as the project-level knowledge layer. According to the TencentDB/TencentDB-Agent-Memory source code, this layer stores work contexts, project descriptions, and logical scenes as structured Markdown documents rather than vector embeddings.

## Physical Storage Structure

Every L2 scenario is stored as a **Markdown file** (`*.md`) within the `scene_blocks/` directory. The canonical path is defined in [`MemoryCore/src/core/storage/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/storage/types.ts), where `StoragePaths.sceneBlocksDir` specifies the folder location and the helper `StoragePaths.sceneBlock(name)` resolves to `scene_blocks/<name>.md` (lines 54-55 and 72-74).

This file-based approach makes scenarios human-readable and version-control friendly, allowing direct editing of project knowledge without database migrations.

## Multi-Tenant Isolation

After the v3 migration, scenarios are strictly scoped to a specific **team and agent pair**. The storage path follows the convention `profiles/<team>|<agent>/scene_blocks/`, ensuring that different teams and agents cannot access each other's L2 data. This isolation mechanism is documented in [`MemoryCore/scripts/migrate-v2-to-v3/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/scripts/migrate-v2-to-v3/README.md) (line 58).

## Storage Backend Abstraction

The system uses the **`IStorageBackend`** interface (lines 85-98 in [`MemoryCore/src/core/storage/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/storage/types.ts)) to abstract all file operations. This abstraction supports multiple backends:

- **Local filesystem** for development environments
- **COS (Tencent Cloud Object Storage)** for production deployments

Both implementations expose identical `read_file` and `write_file` APIs, making L2 operations backend-agnostic regardless of the deployment target.

## Indexing and Fast Lookup

To avoid expensive filesystem scans during runtime, the system maintains a **scene index** at [`.metadata/scene_index.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/.metadata/scene_index.json). At startup, [`MemoryCore/src/core/scene/scene-index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/scene/scene-index.ts) (lines 108-119) scans every `.md` file in `scene_blocks/` and rebuilds this index, caching filenames, titles, and optional summaries. This enables O(1) lookup times for `listScenarios` operations without touching the storage backend.

## Backup and Versioning

During extraction pipeline runs, the system creates atomic backups before writing changes. When `scene_blocks/` is modified, copies are stored under `.backup/scene_blocks/<index>/` (e.g., `.backup/scene_blocks/0/<name>.md`) as implemented in [`MemoryCore/src/core/scene/scene-extractor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/scene/scene-extractor.ts) (lines 175-185). This versioning strategy allows automatic rollback if generation steps fail or produce corrupted output.

## Programmatic Access via SDK

Both Python and TypeScript SDKs expose identical CRUD operations for L2 scenarios: `listScenarios`, `readScenario`, `writeScenario`, `rmScenario`, and `countScenario`. These methods internally delegate to the storage backend's `read_file` and `write_file` primitives.

**Python SDK example:**

```python
from tencentdb_agent_memory.v2 import MemoryClient

# Initialise the client (API key / endpoint omitted for brevity)

with MemoryClient(endpoint="https://api.tdai.tencent.com", api_key="YOUR_KEY") as client:
    # 1️⃣ List all scenario files

    scenarios = client.list_scenarios()
    print("Available scenarios:", [s["filename"] for s in scenarios])

    # 2️⃣ Read a specific scenario

    content = client.read_scenario("scene_blocks/project-overview.md")
    print("--- Scenario content ---")
    print(content)

    # 3️⃣ Write (update) a scenario – file must already exist

    new_md = "# Project Overview\n\nUpdated description ..."

    client.write_scenario("scene_blocks/project-overview.md", new_md)

    # 4️⃣ Remove a scenario

    client.rm_scenario("scene_blocks/old-prototype.md")

```

**TypeScript SDK example:**

```typescript
import { MemoryClient } from "memory-core";

const client = new MemoryClient({
  endpoint: "https://api.tdai.tencent.com",
  apiKey: "YOUR_KEY",
});

async function demoL2() {
  // List scenarios
  const list = await client.listScenarios();
  console.log("Scenarios:", list.map(s => s.filename));

  // Read a scenario
  const md = await client.readScenario("scene_blocks/project-overview.md");
  console.log(md);

  // Write (update) a scenario
  await client.writeScenario("scene_blocks/project-overview.md", "# Updated\n\n…");

  // Delete a scenario
  await client.rmScenario("scene_blocks/obsolete.md");
}
demoL2();

```

## LLM Prompt Injection

When forwarding requests to the LLM, the **MemoryProxy** can inject L2 content directly into system prompts. The `injectL2L3` flag in [`MemoryProxy/src/tdai/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/types.ts) (lines 14-15) controls whether scenario knowledge is prepended to the context. This gives the model immediate access to project background without requiring explicit retrieval calls during inference.

## Directory Layout Overview

A complete memory instance follows this structure, as defined in [`MemoryCore/src/utils/pipeline-factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-factory.ts) (lines 174-182):

```

<instance-root>/
├─ conversations/          # L0 raw dialogues

├─ records/                # L1 atomic memories (vectorized)

├─ scene_blocks/           # L2 markdown scenario files

├─ persona.md              # L3 persona / long-term profile

├─ .metadata/              # scene_index.json, checkpoint.json

└─ .backup/                # backups for persona & scene_blocks

```

## Summary

- L2 Scenario memory uses **Markdown files** stored in `scene_blocks/` for human-readable project context.
- Files are **isolated per team-agent pair** under `profiles/<team>|<agent>/` in v3 architecture.
- The **`IStorageBackend`** abstraction enables seamless switching between local filesystem and COS storage.
- **[`.metadata/scene_index.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/.metadata/scene_index.json)** provides fast indexing of scenarios without filesystem scanning.
- **Automatic backups** to `.backup/scene_blocks/` protect against pipeline failures.
- **SDK methods** (`listScenarios`, `readScenario`, etc.) provide unified CRUD access across Python and TypeScript.
- **MemoryProxy** can inject L2 content directly into LLM prompts via the `injectL2L3` configuration.

## Frequently Asked Questions

### How is L2 Scenario memory physically stored in TencentDB Agent Memory?

L2 Scenario memory is stored as individual **Markdown files** (`*.md`) within a dedicated `scene_blocks/` directory. Each scenario is a separate document containing project descriptions or work context, located via `StoragePaths.sceneBlock(name)` which resolves to `scene_blocks/<name>.md` according to [`MemoryCore/src/core/storage/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/storage/types.ts).

### What storage backends support L2 Scenario files?

The system supports any backend implementing the **`IStorageBackend`** interface. Production deployments typically use **COS (Tencent Cloud Object Storage)**, while development environments use the **local filesystem backend**. Both implement the same read/write API, ensuring backend-agnostic operation as defined in [`MemoryCore/src/core/storage/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/storage/types.ts).

### How does the system handle backup and recovery for L2 scenarios?

During extraction pipeline execution, the system creates versioned backups under `.backup/scene_blocks/<index>/` before writing changes. If a generation step fails, the system can restore from these backups. This mechanism is implemented in [`MemoryCore/src/core/scene/scene-extractor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/scene/scene-extractor.ts).

### Can L2 Scenario content be injected into LLM prompts automatically?

Yes. When the `injectL2L3` flag is enabled in [`MemoryProxy/src/tdai/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/types.ts), the **MemoryProxy** automatically prepends L2 scenario content to the system prompt. This gives the LLM immediate project context without requiring explicit retrieval calls during inference.