# How TencentDB Agent Memory Layers Work: From L0 Conversations to L3 Personas

> Discover how TencentDB Agent Memory layers memory from L0 conversations to L3 personas. Learn about the asynchronous transformation of data into facts, context blocks, and persona profiles for efficient knowledge retrieval.

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

---

**TencentDB Agent Memory implements a four-layer hierarchy (L0 through L3) that asynchronously transforms raw conversation logs into distilled facts, scenario-based context blocks, and long-term persona profiles, enabling agents to retrieve relevant knowledge with hierarchical fallback strategies.**

The TencentDB-Agent-Memory repository provides a production-grade memory system for AI agents that progressively refines unstructured chat data into structured, reusable assets. By understanding how data flows from timestamped messages (L0) through atomic extractions (L1) and scenario assemblies (L2) to persistent cognitive profiles (L3), developers can optimize retrieval performance and maintain context across complex, multi-session interactions.

## Understanding the Four Memory Layers (L0 to L3)

The architecture organizes memory into four distinct levels of abstraction, each serving specific retrieval patterns and latency requirements.

### L0 Conversation: The Raw Event Stream

**L0 stores the complete, timestamped chat messages** with full conversational context. This layer acts as the system of record, capturing every user message and assistant response exactly as transmitted. According to the source code in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts), L0 data persists to JSONL files, ensuring an auditable trail of all interactions. This layer is essential when precise wording or complete dialogue history is required for compliance or debugging.

### L1 Atom: Distilled Facts and Preferences

**L1 contains machine-readable atoms**—facts, preferences, constraints, and events extracted from L0 conversations via LLM-based background workers. As implemented in [`MemoryCore/src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/store/llm-binding-store.ts), these atoms represent discrete knowledge units such as `{type: "Fact", key: "caching", value: "LRU with 5 min TTL"}`. The extraction process runs asynchronously, parsing raw conversations into queryable data structures that support fast, precise recall without reprocessing entire chat histories.

### L2 Scenario: Contextual Groupings

**L2 aggregates related L1 atoms into scenario assets** centered around specific projects, tasks, or business domains. The [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts) service periodically groups atoms sharing a common `scenario_id`, producing bundled context blocks. These pre-assembled packages allow agents to bootstrap quickly with relevant domain knowledge—for example, loading all authentication-related atoms for a "mobile-auth rewrite" project—without runtime extraction overhead.

### L3 Persona: Long-Term Cognitive Profiles

**L3 synthesizes cross-scenario patterns into persistent persona profiles** that capture stable user habits, communication styles, and high-level goals. The synthesis logic in [`MemoryCore/src/utils/memory-cleaner.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/memory-cleaner.ts) merges long-term patterns across multiple L2 scenarios, creating comprehensive profiles that agents can inject directly into prompts. This layer enables instant personality alignment and goal-awareness, inheriting deep understanding of user preferences without repeated context buildup.

## The Asynchronous Data Pipeline

The system employs an **asynchronous refinement pipeline** that progressively elevates data from raw inputs to high-level knowledge.

Data flows through four stages:

1. **Ingestion (L0)** – Agents submit raw conversations via `POST /v3/conversation/add`, defined in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts), persisting messages with isolation context.

2. **Extraction (L1)** – Background workers read new L0 records and execute LLM-based extraction, storing results in [`MemoryCore/src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/store/llm-binding-store.ts).

3. **Assembly (L2)** – The pipeline worker in [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts) aggregates atoms by `scenario_id` into scenario assets.

4. **Synthesis (L3)** – Long-term patterns merge into persona profiles, with cleanup operations handled by the memory cleaner utility.

Retrieval follows the inverse hierarchy. Most queries target L2 scenarios or L3 personas for low-latency responses; if specific facts are missing, the system falls back to L1 atoms and L0 conversations using BM25 plus vector search with reranking.

## Isolation Context and Session Handling

Every memory operation binds to an **isolation context** tuple: `(team_id, agent_id, user_id, session_id, task_id)`. This structure, enforced throughout [`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), ensures strict multi-tenant separation.

- **L0/L1 operations** accept optional `session_id` parameters, enabling aggregation across sessions for team-wide analytics or user-level longitudinal analysis.
- **L2/L3 assets** enforce strict scoping—these belong to specific teams and maintain versioning per persona, preventing cross-contamination between organizational boundaries.

## Working with the TypeScript SDK

The [`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) package provides methods to interact with each memory layer.

### Writing Raw Conversations to L0

Persist conversation logs to trigger the downstream pipeline:

```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." },
  ],
});

```

*This creates an L0 record; background workers subsequently generate L1 atoms.*

### Querying L1 Atomic Facts

Retrieve extracted facts without parsing raw chat:

```typescript
const atoms = await client.searchAtomic({
  query: "caching strategy",
  limit: 5,
});
// Returns: [{type: "Fact", key: "caching", value: "LRU with 5 min TTL"}]

```

### Loading L2 Scenario Context

Fetch pre-bundled context for specific projects:

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

```

This provides a ready-made context block prepopulated with relevant L1 atoms, as aggregated by the pipeline worker in [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts).

### Fetching L3 Persona Profiles

Access long-term user models for prompt injection:

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

```

The returned profile includes stable preferences and decision patterns synthesized across multiple scenarios.

## Summary

- **TencentDB Agent Memory** organizes data in four layers: L0 (raw conversations), L1 (extracted atoms), L2 (scenario assemblies), and L3 (persona profiles).
- **Asynchronous processing** moves data upwards through the hierarchy via background workers defined in [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts).
- **Retrieval prioritizes speed** by checking L2/L3 first, falling back to L1/L0 only when necessary, utilizing BM25 and vector search.
- **Strict isolation** ensures team-scoped memory through the `(team_id, agent_id, user_id, session_id, task_id)` tuple implemented in the TypeScript SDK client.

## Frequently Asked Questions

### What distinguishes L1 atoms from L2 scenarios?

**L1 atoms are discrete, extracted facts** (e.g., "user prefers dark mode") stored individually in [`MemoryCore/src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/store/llm-binding-store.ts), while **L2 scenarios are aggregated collections** of related atoms grouped by project or task context in [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts). Atoms answer specific factual queries; scenarios provide broad contextual grounding for agent initialization.

### How does the retrieval system prioritize memory layers?

The retrieval engine **queries L2 scenarios and L3 personas first** for high-speed context loading, as these layers contain pre-synthesized knowledge blocks. If the required information is absent, the system **falls back to L1 atomic search and L0 conversation logs**, employing BM25 text matching combined with vector similarity search and reranking algorithms to locate specific details.

### Can applications query L0 conversations directly?

**Yes, L0 remains directly accessible** via the SDK and API endpoints, though retrieval typically relies on higher layers for efficiency. Direct L0 access is primarily used for audit trails, exact wording verification, or debugging extraction quality, while production agent queries leverage the hierarchical cache of L1-L3 to minimize latency and token costs.

### How does TencentDB Agent Memory maintain data isolation across teams?

The system enforces isolation through a **mandatory context tuple** `(team_id, agent_id, user_id, session_id, task_id)` passed with every operation 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). L2 and L3 assets are strictly bound to `team_id` with versioned persona profiles, preventing unauthorized cross-team access, while L0/L1 operations support optional session aggregation for authorized analytics without compromising security boundaries.