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

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 and 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 (lines 28-50) and 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 (lines 28-32), the listScenarios method accepts an optional path prefix and returns the matching entries:

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 (lines 62-67) via the list_scenarios method:

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 (lines 33-35), the readScenario method fetches the file data:

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

Python Implementation

The read_scenario method in client.py (lines 69-74) performs the equivalent operation:

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 (lines 36-42) constructs the payload with these fields:

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

  summary: 'System architecture v2',
});

Python Implementation

Correspondingly, client.py (lines 76-92) provides the write_scenario method:

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 (lines 45-50) handles file removal:

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

Python Implementation

In client.py (lines 94-99), the rm_scenario method executes the deletion:

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 (lines 28-50) and 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) 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 and sdk/memory-core/python/tencentdb_agent_memory/v3/client.py.

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