# How to Manage L2 Scenario Files in TencentDB Agent Memory: List, Read, Write, and Delete

> Learn to manage L2 scenario files in TencentDB Agent Memory. Use SDK methods to list, read, write, and delete these persistent knowledge blocks for your team and agent namespace.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Use the SDK methods `listScenarios`, `readScenario`, `writeScenario`, and `rmScenario` (TypeScript) or their Python equivalents `list_scenarios`, `read_scenario`, `write_scenario`, and `rm_scenario` to perform CRUD operations on L2 scenario files, which are persistent knowledge blocks scoped to a team and agent namespace.**

L2 scenario files function as second-level knowledge blocks within the TencentDB-Agent-Memory platform, providing long-term storage that persists across sessions under a **team and agent** isolation context. Unlike transient conversation memory, these files maintain structured context such as design documents and reference material that agents can retrieve across multiple interactions. This guide demonstrates how to manage L2 scenario files using the official TypeScript and Python SDKs, referencing the specific implementations in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) and [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py).

## Understanding L2 Scenario Architecture

L2 scenario files operate through a three-tier architecture that enforces team and agent isolation while exposing REST-style endpoints. The **API gateway** receives `POST /v3/scenario/*` requests, validates the caller's team and agent credentials, and forwards the call to the **MemoryCore** service. The **SDKs** provide type-safe wrappers located in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) (lines 28-50) and [`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) (lines 60-100) that construct request payloads containing the isolation fields (`team_id`, `agent_id`) plus operation-specific parameters such as `path`, `content`, or `path_prefix`.

All endpoints share the `/v3` base prefix and return a standardized response schema (`{ success: true, data: ... }`). Invalid requests, such as missing required paths, return HTTP 400 errors that the SDK surfaces as native exceptions.

## Listing L2 Scenario Files

To retrieve a directory of scenario files, invoke the listing methods which map to `POST /v3/scenario/ls`. You can filter results by providing a `path_prefix` to simulate directory listing.

### TypeScript Implementation

In [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) (lines 28-32), the `listScenarios` method accepts an optional path prefix and returns the matching entries:

```typescript
import { MemoryCoreClient } from '@tencentdb/memory-core';

const client = new MemoryCoreClient(/* team/agent config */);
const list = await client.listScenarios({ path_prefix: 'projectA/' });
console.log('Scenarios:', list.entries);

```

### Python Implementation

The Python SDK implements identical functionality in [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py) (lines 62-67) via the `list_scenarios` method:

```python
from tencentdb_agent_memory.v3 import client as mem_client

c = mem_client.MemoryCoreClient()
lst = c.list_scenarios(path_prefix='projectA/')
print('Scenarios:', lst['entries'])

```

## Reading L2 Scenario Files

Reading retrieves the full content and metadata of a specific file via `POST /v3/scenario/read`. This operation requires the exact file path and returns the stored content plus any summary metadata.

### TypeScript Implementation

As defined in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) (lines 33-35), the `readScenario` method fetches the file data:

```typescript
const file = await client.readScenario({ path: 'projectA/design.md' });
console.log('Content:', file.content);

```

### Python Implementation

The `read_scenario` method in [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py) (lines 69-74) performs the equivalent operation:

```python
file = c.read_scenario('projectA/design.md')
print('Content:', file['content'])

```

## Writing L2 Scenario Files

Writing creates or updates scenario files using an upsert pattern via `POST /v3/scenario/write`. The operation requires the target `path`, the `content` to store, and an optional `summary` for indexing or display purposes.

### TypeScript Implementation

The `writeScenario` method in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) (lines 36-42) constructs the payload with these fields:

```typescript
await client.writeScenario({
  path: 'projectA/design.md',
  content: '# Design Document\n\nTechnical specifications...',

  summary: 'System architecture v2',
});

```

### Python Implementation

Correspondingly, [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py) (lines 76-92) provides the `write_scenario` method:

```python
c.write_scenario(
    path='projectA/design.md',
    content='# Design Document\n\nTechnical specifications...',

    summary='System architecture v2',
)

```

If the specified path already exists, the operation atomically overwrites the previous content and summary.

## Deleting L2 Scenario Files

Deletion permanently removes scenario files via `POST /v3/scenario/rm`. This irreversible operation requires only the target path.

### TypeScript Implementation

The `rmScenario` method in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) (lines 45-50) handles file removal:

```typescript
await client.rmScenario({ path: 'projectA/deprecated-spec.md' });
console.log('Scenario deleted');

```

### Python Implementation

In [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py) (lines 94-99), the `rm_scenario` method executes the deletion:

```python
c.rm_scenario('projectA/deprecated-spec.md')
print('Scenario deleted')

```

## Summary

- **L2 scenario files** persist under a **team and agent namespace** without session dependencies, enabling long-term knowledge storage that survives individual conversations.
- **CRUD operations** map to four REST endpoints (`/v3/scenario/ls`, `/read`, `/write`, `/rm`) wrapped by SDK methods in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) (lines 28-50) and [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py) (lines 60-100).
- **Listing** supports `path_prefix` filtering for hierarchical organization using forward-slash delimiters (e.g., `projectA/`).
- **Writing** operates as an atomic upsert, creating new files or overwriting existing content and summaries at the specified path.
- **Error handling** returns HTTP 400 for invalid parameters (missing paths, invalid isolation context) that the SDK surfaces as typed exceptions.

## Frequently Asked Questions

### What namespace do L2 scenario files use?

L2 scenario files exist within a **team and agent namespace** and do not depend on a session ID. According to the TencentDB-Agent-Memory source code, this design allows agents to access persistent knowledge blocks across multiple user sessions and conversations without binding data to transient session state.

### Can I organize scenario files into folders?

Yes. Use forward-slash delimiters in the `path` parameter (e.g., [`projectA/design.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/projectA/design.md)) and the `path_prefix` parameter in listing operations (e.g., `path_prefix='projectA/'`) to create virtual directory structures. The MemoryCore service treats these as hierarchical paths during storage and retrieval.

### What happens when I write to an existing scenario path?

The `writeScenario` operation performs an **atomic upsert**. If a file exists at the specified path, the method overwrites both the `content` and `summary` fields with the new values. If no file exists, it creates a new scenario entry without raising an error.

### How do the SDK methods map to the REST API endpoints?

The TypeScript methods `listScenarios`, `readScenario`, `writeScenario`, and `rmScenario` map directly to `POST /v3/scenario/ls`, `POST /v3/scenario/read`, `POST /v3/scenario/write`, and `POST /v3/scenario/rm` respectively. The Python SDK methods follow identical mappings, as implemented in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) and [`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).