# What Is the Purpose of Scenarios (L2) in TencentDB Agent Memory Layering?

> Discover how Scenarios L2 in TencentDB Agent Memory act as project-level containers for shared knowledge, enabling rapid context bootstrapping and team collaboration without replaying raw conversations.

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

---

**Scenarios (L2) serve as project-level memory containers that group related knowledge to enable fast context bootstrapping and team-wide memory sharing without replaying raw conversations.**

The TencentCloud/TencentDB-Agent-Memory repository implements a four-tier memory hierarchy (L0 → L1 → L2 → L3) designed to optimize how AI agents retain and retrieve context. The **L2 Scenario** layer sits between atomic facts (L1) and core personas (L3), functioning as the primary organizational unit for project-specific knowledge.

## Understanding the Memory Layer Architecture

The memory system organizes information into distinct layers to balance granularity with retrieval speed:

- **L0:** Raw conversation logs
- **L1:** Atomic facts and knowledge fragments
- **L2:** **Scenarios** – logical containers for related project knowledge
- **L3:** Core personas and long-term agent identity

As defined in the project documentation at [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) (lines 52–54), Scenarios bridge the gap between low-level facts and high-level agent configuration, providing a mid-tier abstraction that captures complete working contexts.

## Core Purpose of Scenarios (L2)

Scenarios solve the cold-start problem for agents resuming work on specific projects or workflows. Rather than forcing an agent to process entire conversation histories (L0) or search through disconnected atomic facts (L1), the L2 layer delivers a **compact, high-level snapshot** of relevant context.

### Project-Level Knowledge Containers

A Scenario acts as a logical bucket that associates **atoms (L1 facts)** and **core assets (L3 personas)** with a specific use-case. According to the type definitions in [`sdk/memory-core/typescript/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/types.ts) (lines 63–94), each Scenario stores:

- A unique `path` (e.g., [`projectX/design.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/projectX/design.md))
- Optional `summary` metadata
- `created_at` and `updated_at` timestamps
- Full markdown-style `content`

This structure allows agents to treat entire projects, deployment pipelines, or troubleshooting workflows as single retrievable units.

### Fast Context Bootstrapping

When an Agent initializes a task, it can retrieve the complete Scenario through a single API call. The client 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 326–345) exposes methods like `readScenario()` that return both the content and metadata instantly.

This **fast bootstrapping** capability means the Agent receives sufficient context to act immediately, triggering deeper L1/L0 retrieval only when fine-grained facts are required.

### Team-Wide Memory Sharing

Scenarios operate as **team-level assets** that do not require a `session_id`. This design, reflected in the SDK's permission model, enables multiple agents within the same team to read, write, and count Scenarios. Experience accumulated by one Agent becomes instantly reusable by others, creating a persistent "team memory" that survives individual sessions.

## How Scenarios Work Under the Hood

The TypeScript SDK defines Scenario operations through a strict interface. The [`types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/types.ts) file specifies that Scenario responses include entries with `path`, `summary`, and timestamp fields, while the v3 client in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) implements the full CRUD surface:

- `listScenarios()` – Enumerate available Scenarios
- `readScenario()` – Retrieve specific Scenario content
- `writeScenario()` – Create or update Scenarios
- `rmScenario()` – Delete obsolete contexts
- `countScenario()` – Query Scenario quantities by path prefix

The Python SDK mirrors this functionality 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) (lines 460–470), ensuring consistent behavior across language implementations.

## Working with Scenarios Programmatically

You can interact with the L2 layer using either the TypeScript or Python SDK.

### TypeScript Implementation

```typescript
import { MemoryClient } from '@tencentdb-agent-memory/memory-tencentdb';

const client = new MemoryClient();

// Retrieve all Scenarios for the current team
const list = await client.listScenarios();
console.log('Available scenarios:', list.entries.map(e => e.path));

// Load a specific project context
const scenario = await client.readScenario({ path: 'projectX/design.md' });
console.log('Scenario content:\n', scenario.content);

// Persist new project knowledge
await client.writeScenario({
  path: 'projectX/design.md',
  content: '# Project X Design\n\n- Goal: Implement caching layer\n- Architecture: Redis cluster',

  summary: 'High-level design for Project X',
});

// Clean up obsolete Scenarios
await client.rmScenario({ path: 'old-project/notes.md' });

// Count Scenarios under a specific prefix
const cnt = await client.countScenario({ path_prefix: 'projectX/' });
console.log(`Project X has ${cnt.total} scenarios`);

```

### Python Implementation

```python
from tencentdb_agent_memory.v3.client import MemoryClient

client = MemoryClient()

# List all Scenarios

list_data = client.listScenarios()
print("Scenarios:", [e["path"] for e in list_data["entries"]])

# Read existing context

scenario = client.readScenario({"path": "projectX/design.md"})
print("Content:", scenario["content"])

# Write project documentation

client.writeScenario({
    "path": "projectX/design.md",
    "content": "# Project X Design\n\nArchitecture details...",

    "summary": "Design doc for Project X"
})

# Remove outdated entries

client.rmScenario({"path": "old-project/notes.md"})

# Query Scenario counts

count = client.countScenario({"path_prefix": "projectX/"})
print(f"Project X has {count['total']} scenarios")

```

## Summary

- **Scenarios (L2)** are project-level containers in the TencentDB Agent Memory hierarchy that sit between atomic facts (L1) and personas (L3).
- They enable **fast context bootstrapping** by delivering complete working snapshots through single API calls, eliminating the need to replay raw conversations.
- Scenarios function as **team-level assets** without session restrictions, allowing persistent knowledge sharing across multiple agents.
- The SDK provides full CRUD operations including `listScenarios`, `readScenario`, `writeScenario`, `rmScenario`, and `countScenario` in both TypeScript and Python implementations.
- Each Scenario tracks versioning through `created_at` and `updated_at` timestamps while supporting markdown content and optional summaries.

## Frequently Asked Questions

### What is the difference between L2 Scenarios and L1 Atoms?

**L1 Atoms** store discrete facts and knowledge fragments, while **L2 Scenarios** aggregate multiple atoms into coherent project contexts. When an agent needs specific data points, it queries L1; when it needs to understand the broader project state, it retrieves the L2 Scenario.

### Can multiple agents access the same Scenario simultaneously?

Yes. Scenarios are designed as **team-level assets** that do not require a `session_id`. Any agent belonging to the same team can read from or write to Scenarios, enabling collaborative memory persistence across distributed agent workflows.

### How does version tracking work for Scenarios?

Each Scenario object includes `created_at` and `updated_at` timestamps managed by the server. When you call `writeScenario()` with an existing path, the system updates the content and refreshes the `updated_at` field, creating an implicit version history that teams can track through the API.

### When should I use L2 Scenarios versus L3 Personas?

Use **L2 Scenarios** for project-specific knowledge that changes frequently, such as feature specifications, deployment configurations, or troubleshooting guides. Use **L3 Personas** for stable, long-term agent characteristics like personality traits, expertise domains, and persistent behavioral instructions that transcend individual projects.