# Understanding the L0 Conversation Layer in TencentDB Agent Memory

> Discover the L0 Conversation layer in TencentDB Agent Memory. It captures raw dialogue as JSON-L records for accurate retrieval and structured memory extraction. Learn its foundational role.

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

---

**The L0 Conversation layer serves as the immutable foundation of the TencentDB Agent Memory system, capturing raw turn-by-turn dialogue as JSON-L records to enable accurate retrieval and downstream structured memory extraction.**

The TencentDB Agent Memory implements a hierarchical four-layer architecture (L0 → L1 → L2 → L3) designed to transform unstructured dialogue into structured, queryable knowledge. At the base of this hierarchy sits the **L0 Conversation layer**, which functions as the single source of truth for every exchange between users and agents.

## Core Responsibilities of the L0 Conversation Layer

### Immutable Dialogue Capture

Each interaction is stored as a discrete JSON-L line containing a unique message identifier, role designation (`user` or `assistant`), precise timestamp, and session metadata. In [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts), the recorder persists these turns atomically, ensuring that historical dialogue remains unchanged and auditable.

### Incremental and Sanitized Recording

The layer implements intelligent filtering to avoid redundant writes. Using a **position slice** or **timestamp cursor**, the system only appends new messages following the previous capture point. Before persistence, content undergoes sanitization to strip injected tags, code blocks, and image data, reducing noise in downstream processing.

### Foundation for Higher-Level Memory Extraction

While L0 maintains the raw dialogue, it serves as the upstream source for **L1 Atoms**—structured memory units extracted via asynchronous pipelines. The raw records remain directly searchable when precise wording or temporal boundaries are required for agent responses, as documented in the Technical Implementation section of [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md).

### Read-Only Tool Interface

To prevent KV-cache invalidation and maintain upstream request flow integrity, the layer exposes a read-only endpoint at `/v3/memory/addConversation` through the MemoryProxy. This interface, implemented in [`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts), allows agents to query conversation history on-demand without modifying the underlying storage.

## Technical Implementation in l0-recorder.ts

The core logic resides in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts), which handles three critical functions:

- **Write Operations**: Appending JSON-L lines with unique message IDs and session keys
- **Incremental Reads**: Supporting cursor-based retrieval using timestamp parameters
- **Content Sanitization**: Filtering malicious or noisy content before persistence

When the proxy layer receives a new conversation turn, [`MemoryProxy/src/tdai/recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/recorder.ts) extracts the latest user query and forwards the write operation to this core recorder, maintaining separation between network-facing components and storage logic.

## Working with L0 Conversation Data

### Recording Conversation Turns

Client applications interact with the L0 layer through the TypeScript memory client using the v3 API:

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

await client.addConversation({
  session_key: 'team-xyz-agent-abc',
  session_id: 'sess-001',
  messages: [
    { role: 'user', content: 'How do I deploy the new service?' },
    { role: 'assistant', content: 'You can run `./deploy.sh` …' }
  ]
});

```

### Retrieving Raw Messages

For downstream processing or verification, applications can read conversation history incrementally:

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

const msgs = await readConversationMessages(
  'team-xyz-agent-abc',
  '/home/user/.openclaw/memory-tdai',
  0,  // afterTimestamp - 0 returns all messages
  console
);

```

The `afterTimestamp` parameter enables efficient incremental processing, allowing L1 extraction pipelines to resume from specific points without reprocessing entire conversation histories.

## Summary

- The **L0 Conversation layer** acts as the immutable foundation of the four-tier TencentDB Agent Memory architecture
- It stores raw dialogue as **JSON-L records** with unique IDs, timestamps, and session metadata in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts)
- **Incremental recording** with cursor-based positioning and content sanitization ensures efficient, clean data capture
- The layer exposes **read-only endpoints** through MemoryProxy to serve agent queries without invalidating caches
- All **L1 Atom extraction** derives from this raw L0 data, making it the authoritative source for higher-level memory structures

## Frequently Asked Questions

### How does the L0 Conversation layer differ from L1 Atoms in TencentDB Agent Memory?

While L0 stores raw, turn-by-turn dialogue as JSON-L records, L1 Atoms represent structured, semantic units extracted from these conversations through asynchronous processing pipelines. L0 maintains the exact wording and temporal sequence, whereas L1 organizes information into queryable knowledge chunks.

### What sanitization does the L0 recorder apply to conversation data?

According to the implementation in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts), the recorder removes injected tags, code blocks, and image data before persisting messages. This noise filtering ensures that downstream memory extraction processes focus on semantic content rather than formatting artifacts.

### Can agents modify conversation history stored in the L0 layer?

No, the L0 Conversation layer is designed as an immutable log. The MemoryProxy exposes only read-only endpoints such as `/v3/memory/addConversation` for agent queries. This architectural constraint prevents KV-cache invalidation and maintains data integrity across the memory hierarchy.

### How does incremental recording work in the L0 layer?

The system uses a position slice or timestamp cursor to track the last captured message. When recording new turns, `readConversationMessages` accepts an `afterTimestamp` parameter that returns only messages occurring after the specified time, enabling efficient batch processing without reloading entire conversation histories.