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

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, 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 (line 58).

Storage Backend Abstraction

The system uses the IStorageBackend interface (lines 85-98 in 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. At startup, 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 (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:

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:

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 (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 (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 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.

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.

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.

Can L2 Scenario content be injected into LLM prompts automatically?

Yes. When the injectL2L3 flag is enabled in 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.

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