What Is Stored in the L2 Scenario Layer in TencentDB-Agent-Memory

The L2 Scenario layer stores organized knowledge blocks—typically JSON or Markdown files describing projects, architectures, or recurring tasks—that enable agents to restore working context instantly without reprocessing raw conversation history.

The TencentDB-Agent-Memory repository implements a hierarchical memory system designed to optimize agent performance through structured context management. The L2 Scenario layer serves as the intermediate tier between granular facts and high-level profiles, specifically engineered to provide quick-boot capabilities for specialized work contexts. According to the repository’s architecture documentation, this layer contains distilled information organized around specific projects or operational scenarios rather than isolated data points.

L2 Scenario Layer Architecture and Purpose

The L2 Scenario layer functions as a contextual bridge within the three-tier memory architecture implemented in TencentDB-Agent-Memory.

Position in the Memory Hierarchy

The memory system organizes information across three distinct granularity levels:

• L1 Atom: Stores fine-grained, individual facts and raw conversation snippets
• L2 Scenario: Contains organized knowledge blocks representing complete work contexts
• L3 Core/Persona: Maintains long-term agent profiles and persistent behavioral patterns

As defined in the repository's README.md, the L2 layer specifically addresses the need for knowledge blocks organized around projects or work scenarios. This positioning allows agents to bypass expensive reprocessing of L1 atomic data when resuming familiar contexts.

File Formats and Storage Structure

Scenario files within the L2 layer utilize standard document formats that balance human readability with programmatic access:

• JSON files: Structured data representations for configuration sets and metadata
• Markdown files: Narrative documentation describing architectures, deployment pipelines, or task procedures

These files reside in the directory specified by StoragePaths.sceneBlocksDir, managed through the Memory Core gateway rather than direct filesystem access.

How the L2 Scenario Layer Stores Context

Unlike flat memory records, the L2 layer implements a project-centric organization that mirrors real-world work structures.

Knowledge Block Organization

Each scenario represents a knowledge block—a self-contained unit of context sufficient to restore an agent's understanding of a specific operational domain. Examples include microservice architecture documentation, CI/CD pipeline specifications, recurring maintenance task procedures, and project-specific terminology glossaries.

The storage model emphasizes distilled information over raw conversation logs, enabling sub-second context restoration even after extended periods of inactivity.

Storage Path and Directory Structure

The physical storage location is abstracted through the StoragePaths.sceneBlocksDir constant, referenced by handlers in MemoryCore/src/gateway/v2-router.ts. This abstraction ensures consistent path resolution across different deployment environments while preventing directory traversal vulnerabilities through schema validation in v2-schemas.ts.

Managing Scenario Files via the Memory Core API

The L2 Scenario layer exposes a RESTful interface through the Memory Core gateway, providing CRUD operations via the /v3/scenario endpoint namespace.

Listing and Reading Scenarios

Retrieve existing scenarios using the ls and read handlers implemented in handleScenarioLs and handleScenarioRead within MemoryCore/src/gateway/v2-router.ts:

// List all scenario files under a project prefix
await fetch('/v3/scenario/ls', {
  method: 'POST',
  body: JSON.stringify({ path_prefix: 'my-project/' })
});

// Read a specific architecture document
await fetch('/v3/scenario/read', {
  method: 'POST',
  body: JSON.stringify({ path: 'my-project/architecture.md' })
});

These operations validate paths against the scenario schema before accessing StoragePaths.sceneBlocksDir, ensuring secure namespace isolation.

Writing and Removing Scenario Files

Create, update, or delete scenario blocks using the write and remove handlers:

// Write or update a scenario file
await fetch('/v3/scenario/write', {
  method: 'POST',
  body: JSON.stringify({
    path: 'my-project/architecture.md',
    content: '# Architecture\n- Service A\n- Service B'

  })
});

// Remove a scenario file
await fetch('/v3/scenario/rm', {
  method: 'POST',
  body: JSON.stringify({ path: 'my-project/deprecated-config.json' })
});

The handleScenarioWrite and handleScenarioRm functions enforce schema validation through MemoryCore/src/gateway/v2-schemas.ts before persisting changes to disk.

Key Implementation Files

The L2 Scenario layer implementation spans three critical files:

• MemoryCore/src/gateway/v2-router.ts: Implements the four core handlers (handleScenarioLs, handleScenarioRead, handleScenarioWrite, handleScenarioRm) that process API requests and coordinate storage operations.

• MemoryCore/src/gateway/v2-schemas.ts: Defines TypeScript interfaces and validation schemas for scenario path parameters, ensuring safe filename handling and preventing directory traversal attacks.

• README.md (root): Documents the three-layer memory architecture concept, specifically describing how L2 scenarios provide quick-boot context for agents through organized knowledge blocks.

Summary

• The L2 Scenario layer stores organized knowledge blocks—JSON and Markdown files representing projects, architectures, or recurring tasks—in the StoragePaths.sceneBlocksDir directory.
• It occupies the intermediate tier between L1 Atom (individual facts) and L3 Core/Persona (long-term profiles), optimized for rapid context restoration.
• Four dedicated handlers in v2-router.ts manage scenario lifecycle: handleScenarioLs, handleScenarioRead, handleScenarioWrite, and handleScenarioRm.
• All operations adhere to strict schemas defined in v2-schemas.ts to ensure secure path handling and data integrity.

Frequently Asked Questions

What file formats does the L2 Scenario layer use?

The L2 Scenario layer primarily utilizes JSON for structured configuration data and Markdown for narrative documentation describing architectures, deployment pipelines, or task procedures. These formats enable both human editing and programmatic parsing by the agent system.

How does the L2 Scenario layer differ from L1 Atom and L3 Core layers?

The L1 Atom layer stores granular, isolated facts extracted from conversations, while the L3 Core/Persona layer maintains long-term behavioral profiles and persistent agent characteristics. The L2 Scenario layer bridges these extremes by organizing related knowledge into project-centric blocks that provide immediate operational context without requiring atomic-level reconstruction.

Can I directly access the scenario files on disk?

While scenario files reside in StoragePaths.sceneBlocksDir, the architecture encourages access exclusively through the Memory Core API (/v3/scenario/* endpoints). This ensures path validation, security isolation, and schema compliance enforced by the handlers in v2-router.ts and validation logic in v2-schemas.ts.

What operations are supported for managing scenario files?

The L2 Scenario layer supports standard CRUD operations exposed through four dedicated handlers: handleScenarioLs (list), handleScenarioRead (retrieve), handleScenarioWrite (create/update), and handleScenarioRm (delete). These map to the ls, read, write, and rm API endpoints respectively, operating within the secure storage abstraction provided by StoragePaths.sceneBlocksDir.

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