# Chat Memory Layers (L0-L3) in TencentDB Agent Memory: Architecture and Implementation

> Explore Chat Memory layers L0-L3 in TencentDB Agent Memory. Discover how this architecture moves from raw dialogue to knowledge graphs for short-term context and long-term learning.

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

---

**TencentDB Agent Memory implements a four-tier Chat Memory hierarchy (L0-L3) that progresses from raw dialogue storage to persistent knowledge graphs, enabling both short-term context retention and long-term cross-session learning.**

The TencentCloud/TencentDB-Agent-Memory repository provides a hierarchical memory system for conversational AI agents. This architecture separates immediate conversation history from distilled knowledge using four distinct Chat Memory layers (L0-L3) that optimize for retrieval speed, storage efficiency, and knowledge reuse.

## The Four Layers of Chat Memory

The architecture divides memory into four logical tiers, each with distinct storage characteristics and retention policies.

### L0 – Raw Turns

**L0** stores every user-assistant message pair exactly as it arrives. This layer guarantees a faithful replay of the original dialogue by maintaining an immutable log of the conversation. Raw turns are kept for the entire session lifetime and are pruned only when the session terminates. In the source code, this queue logic resides in [`MemoryCore/src/utils/serial-queue.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/serial-queue.ts).

### L1 – Turn-Level Embeddings

**L1** contains vector embeddings of each turn, produced by the underlying LLM. These embeddings enable fast similarity search to retrieve the most relevant prior turns based on semantic meaning. This layer uses an in-memory vector store with a configurable time-to-live (TTL), typically expiring after 24 hours. The embedding generation and vector storage are also managed within [`MemoryCore/src/utils/serial-queue.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/serial-queue.ts).

### L2 – Session Summaries

**L2** maintains aggregated, concise summaries of the conversation generated periodically by the LLM. This layer provides a compact long-term view of the session that preserves continuity without loading the full turn history from L0. Summaries are updated every *N* turns (default approximately 20) and are retained for the lifetime of the session. The summarization pipeline is implemented in [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts).

### L3 – Global Knowledge Graph

**L3** represents structured knowledge extracted from many sessions, including entities, relations, and facts stored in a shared graph database. This layer allows cross-session reuse of learned facts, enabling the agent to "remember" information across distinct users or sessions. Data persists indefinitely and is backed by SQLite or TS-based stores. The graph service logic is found in [`MemoryKnowledge/src/store/code-graph-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/code-graph-service.ts).

## How the Layers Interact

When a new turn arrives, the system processes it through the hierarchy in a specific pipeline:

1. **Ingestion**: The raw message pair appends to **L0** immediately.
2. **Vectorization**: The turn embeds and indexes into **L1** for similarity-based retrieval.
3. **Summarization**: After a configurable threshold, the system synthesizes an **L2** summary that compresses older L0 data, keeping short-term memory lightweight.
4. **Knowledge Extraction**: Periodically or via explicit calls, salient facts promote from **L2** into the **L3** knowledge graph, making them available to future sessions.

This flow is documented in the repository diagram `assets/images/chat_memory.png` and detailed in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md).

## Source Code Implementation

The implementation maps directly to specific source files within the repository:

| Layer | Source File | Purpose |
|-------|-------------|---------|
| L0 / L1 | [`MemoryCore/src/utils/serial-queue.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/serial-queue.ts) | Implements the turn-level queue and in-memory vector store |
| L2 | [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts) | Handles periodic session summarization |
| L3 | [`MemoryKnowledge/src/store/code-graph-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/code-graph-service.ts) | Manages the persistent knowledge graph |
| API | [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) | Documents the public API for layer manipulation |

## Working with Chat Memory: Practical Example

The following TypeScript example demonstrates how to interact with each layer using the `MemoryCore` API:

```typescript
import { MemoryCore } from '@tencentdb/memory-core';

// 1️⃣ Store a new turn (writes to L0 and L1)
await MemoryCore.appendTurn({
  sessionId: 'sess-123',
  role: 'user',
  content: 'What is the capital of France?',
});

// 2️⃣ Retrieve relevant prior turns (queries L1)
const similar = await MemoryCore.searchTurns({
  sessionId: 'sess-123',
  query: 'France capital',
  topK: 5,
});

// 3️⃣ Get current session summary (reads L2)
const summary = await MemoryCore.getSessionSummary('sess-123');

// 4️⃣ Query global knowledge graph (accesses L3)
const facts = await MemoryCore.queryKnowledgeGraph({
  entity: 'France',
  predicate: 'capital',
});

```

All four methods operate as thin wrappers around the underlying layered stores described in the source files.

## Summary

- **L0** provides immutable raw turn storage for session fidelity.
- **L1** enables fast semantic retrieval through vector embeddings.
- **L2** compresses history into summaries for efficient long-context windows.
- **L3** persists structured knowledge across sessions in a graph database.
- The architecture balances immediate context needs (L0-L2) with long-term learning (L3) through explicit promotion workflows implemented in `MemoryCore` and `MemoryKnowledge` modules.

## Frequently Asked Questions

### How does data flow from L0 to L3?

Data flows sequentially through the layers as conversation volume increases. New turns enter L0 and generate L1 embeddings immediately. After a configurable number of turns (default ~20), the system creates or updates an L2 summary. Finally, explicit extraction calls or periodic background jobs promote salient facts from L2 into the permanent L3 knowledge graph.

### What storage backends support each layer?

L0 and L1 utilize in-memory storage with TTL-based expiration for performance. L2 summaries persist in session-scoped storage for the duration of the conversation. L3 uses durable SQLite or TS-based stores according to the implementation in [`MemoryKnowledge/src/store/code-graph-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/code-graph-service.ts), ensuring cross-session durability.

### Can I configure the summarization threshold for L2?

Yes. The summarization trigger is configurable via the parameters exposed in [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts). The default processes approximately every 20 turns, but this value adjusts based on token limits, conversation density, or explicit API configuration passed to the stateful pipeline manager.

### When should I query L3 instead of searching L1?

Query **L3** when seeking established facts, entities, or relationships that may have originated in previous sessions or earlier in the current session. Query **L1** when retrieving specific verbatim dialogue turns or recent context that requires semantic similarity matching rather than structured knowledge lookup.