# How TencentDB Agent Memory's Layered Architecture (L0-L3) Works

> Understand TencentDB Agent Memory's L0-L3 layered architecture. Learn how it refines conversations into reusable knowledge for instant high-level context and granular historical recall.

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

---

**TencentDB Agent Memory organizes interaction data into a four-layer hierarchy that progressively refines raw conversations into reusable knowledge, allowing agents to retrieve high-level context instantly while maintaining access to granular historical details.**

TencentDB Agent Memory implements a sophisticated storage system that transforms ephemeral chat messages into structured, long-term knowledge. This article examines the **Layered Memory Architecture (L0-L3)** as implemented in the `TencentCloud/TencentDB-Agent-Memory` repository, detailing how each layer serves distinct retrieval needs—from raw audit trails to synthesized user personas.

## The Four Layers of Memory

### L0 Conversation: The Raw Audit Trail

The foundation layer stores complete, timestamped chat messages with full context. According to [`src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/core/conversation/l0-recorder.ts), L0 persists raw JSONL records that guarantee faithful reconstruction of exactly what was said. This layer serves audit requirements and precise wording retrieval when exact phrasing matters.

### L1 Atom: Distilled Facts and Preferences

Background workers process L0 records to extract discrete facts, constraints, and preferences, storing them in [`src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/store/llm-binding-store.ts). These **atoms** represent actionable information—such as "user prefers dark mode"—enabling fast, precise recall without parsing full conversation history.

### L2 Scenario: Contextual Project Blocks

Atoms sharing a common `scenario_id` are aggregated into scenario assets, as implemented in [`src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/services/pipeline-worker.ts). An **L2 scenario** bundles related atoms around specific projects or tasks (e.g., "mobile-auth rewrite"), providing ready-made context blocks that bootstrap agents for particular domains.

### L3 Persona: Long-Term User Profiles

The highest layer synthesizes long-term patterns across scenarios into stable user or team profiles. The system merges behavioral patterns and high-level cognition in [`src/utils/memory-cleaner.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/utils/memory-cleaner.ts), allowing agents to inherit deep understanding of user habits, goals, and communication styles instantly.

## Data Flow and Asynchronous Processing

### Ingestion Pipeline

When an agent completes a turn, the SDK posts raw messages via `POST /v3/conversation/add`. The TypeScript SDK method 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 191-199) handles this ingestion:

```typescript
await client.addConversation({
  session_id: "sess-123",
  messages: [{ role: "user", content: "How do I enable dark mode?" }]
});

```

This creates the L0 record. Background workers then asynchronously extract L1 atoms, assemble L2 scenarios, and synthesize L3 personas without blocking the main agent loop.

### Retrieval with Hierarchical Fallback

Retrieval follows the same hierarchy for performance optimization. Most queries target L2/L3 for speed; if specific facts are missing, the system falls back to L1/L0 using **BM25 plus vector search with reranking**, as documented in the Technical Implementation section of the README.

## Isolation and Session Handling

Every operation binds to an `IsolationContext` tuple of `(team_id, agent_id, user_id, session_id, task_id)` defined 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 155-163). For L0/L1 operations, omitting `session_id` enables aggregation across sessions for team-wide analytics. L2/L3 operations enforce strict context boundaries, ensuring assets belong to specific teams with versioned persona profiles.

## SDK Implementation Examples

### Recording Raw Conversations (L0)

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

const client = new MemoryClient({
  endpoint: "https://memory.example.com",
  apiKey: "your-api-key",
  teamId: "team-001",
  agentId: "agent-scout",
  userId: "user-alice",
});

await client.addConversation({
  session_id: "sess-20230819",
  messages: [
    { role: "user", content: "Explain the caching strategy." },
    { role: "assistant", content: "We use LRU with a 5 min TTL." },
  ],
});

```

### Querying Atomic Facts (L1)

```typescript
const atoms = await client.searchAtomic({
  query: "caching strategy",
  limit: 5,
});

```

This returns extracted facts like `{type:"Fact", key:"caching", value:"LRU with 5 min TTL"}` from the atomic store.

### Loading Scenario Context (L2)

```typescript
const scenario = await client.getScenario({
  scenario_id: "proj-payment-gateway",
});

```

This provides a pre-bundled context block that can be prepended to the prompt of a new agent run.

### Fetching User Personas (L3)

```typescript
const persona = await client.getPersona({
  user_id: "user-alice",
});

```

This delivers the high-level persona profile (preferences, previous decisions, style) ready to be injected into the LLM prompt.

## Summary

- TencentDB Agent Memory uses a **four-layer hierarchy** (L0-L3) that balances granular audit trails with high-performance retrieval.
- **L0 Conversation** stores raw messages in [`src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/core/conversation/l0-recorder.ts) for complete historical fidelity.
- **L1 Atoms** distill facts into [`src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/store/llm-binding-store.ts) for rapid fact retrieval.
- **L2 Scenarios** aggregate atoms via [`src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/services/pipeline-worker.ts) into domain-specific context blocks.
- **L3 Personas** synthesize long-term profiles in [`src/utils/memory-cleaner.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/utils/memory-cleaner.ts) for persistent user modeling.
- The **asynchronous pipeline** processes layers in the background while **isolation contexts** ensure proper data boundaries across teams and sessions.

## Frequently Asked Questions

### What distinguishes L2 Scenarios from L3 Personas?

L2 Scenarios group related atoms around specific projects or tasks, providing immediate context for particular domains. L3 Personas capture cross-scenario patterns and stable behavioral traits about users or teams, enabling agents to maintain consistent understanding across unrelated interactions.

### How does the system handle missing information during retrieval?

The retrieval engine prioritizes L2/L3 assets for speed but implements automatic fallback to L1/L0 when specific details are absent. It combines BM25 text search with vector similarity and reranking to locate relevant historical data across all layers.

### Can session data be aggregated across multiple conversations?

Yes. For L0 and L1 operations, omitting the `session_id` parameter in the `IsolationContext` allows aggregation across sessions, useful for team-wide statistics. However, L2 scenarios and L3 personas maintain strict context binding to specific teams and users regardless of session boundaries.

### What storage formats back each memory layer?

L0 conversations persist as JSONL files in [`src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/core/conversation/l0-recorder.ts). L1 atoms store in the LLM binding store at [`src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/store/llm-binding-store.ts). L2 scenarios aggregate in SQLite via [`src/store/sqlite-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/store/sqlite-store.ts), while L3 personas maintain versioned profiles processed through [`src/utils/memory-cleaner.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/utils/memory-cleaner.ts).