# What Is the L0 Conversation Layer in TencentDB Agent Memory Architecture?

> Discover the L0 Conversation layer, the immutable foundation of TencentDB Agent Memory. It captures raw dialogue in JSON-L for agent retrieval and memory extraction.

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

---

**The L0 Conversation layer serves as the immutable foundation of the TencentDB Agent Memory architecture, capturing raw turn-by-turn dialogue in append-only JSON-L format to provide the single source of truth for downstream memory extraction and agent retrieval.**

The TencentDB Agent Memory system organizes conversational data through a hierarchical four-layer architecture (L0 → L1 → L2 → L3). At the base sits the **Conversation (L0)** layer, an append-only ledger implemented in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts) that persists every exchange between users and agents exactly as spoken, enabling verification, incremental processing, and accurate historical analysis.

## The Four-Layer Memory Hierarchy

The memory service processes conversational data through distinct abstraction levels. **L0 Conversation** stores the raw, unmodified dialogue, while L1 Atoms extract semantic facts, L2 Scenarios group contextual situations, and L3 Personas build long-term user profiles. This design ensures that higher-level memories remain traceable to their original source material, with L0 acting as the irreproachable audit log for the entire system.

## Core Responsibilities of the L0 Conversation Layer

### Capture Immutable Conversation History

The primary function of L0 is to record dialogue exactly as it occurs. Each turn is stored as a single JSON-L line containing a unique message ID, the role (`user` or `assistant`), a precise timestamp, and the session key or ID that scopes the conversation. According to [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts), this append-only structure prevents data loss and ensures that every interaction remains searchable by its original timing and content.

### Incremental Recording with Noise Filtering

Rather than rewriting entire conversation files, the L0 recorder writes only new messages after the previous capture point using a position slice or timestamp cursor. Before persisting, the content undergoes sanitization to remove injected tags, code blocks, and image data that could bloat storage or leak implementation details. This incremental approach minimizes I/O overhead while maintaining a clean, queryable history.

### Foundation for Higher-Level Memories

L0 operates as the substrate for the entire memory pipeline. L1 Atoms are extracted from these raw messages through an asynchronous processing pipeline that parses the JSON-L lines into structured facts. Simultaneously, L0 remains directly accessible when precise wording or exact timestamps are required, providing a fallback for verification that higher-level abstractions cannot distort.

### Read-Only Tool Interface for Agents

The `MemoryProxy` exposes L0 data through a read-only endpoint (`/v3/memory/addConversation`) that agents can query on-demand. This design avoids KV-cache invalidation and leaves the upstream request flow unchanged, allowing models to retrieve specific conversation turns without modifying the storage layer. The proxy surface implemented in [`MemoryProxy/src/tdai/recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/recorder.ts) validates requests before forwarding them to the core client, ensuring that agents can only append or read, never delete or alter historical records.

## Working with L0 Conversation Data

### Writing Conversation Turns

Clients interact with L0 through the TypeScript memory client, which handles the JSON-L serialization and session management automatically. The `session_key` identifies the conversation stream, while `session_id` scopes it to a single session instance.

```typescript
// Using the TypeScript memory client (v3 API)
import { MemoryClient } from '@tencentdb-agent-memory/memory-core';

// `sessionKey` identifies the conversation; `sessionId` scopes it to a single session.
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` …' }
  ]
});

```

### Reading Raw L0 Messages

For incremental processing or direct retrieval, the `readConversationMessages` function streams messages from the JSON-L file based on timestamp cursors. This supports asynchronous pipelines that extract L1 Atoms without reloading the entire conversation history.

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

// Return all user/assistant messages after a given timestamp (e.g. for incremental processing)
const msgs = await readConversationMessages(
  'team‑xyz‑agent‑abc',          // sessionKey
  '/home/user/.openclaw/memory-tdai', // baseDir (default location)
  0,                            // afterTimestamp – 0 = first capture
  console                        // optional logger
);
console.log(msg);

```

## Key Implementation Files

- **[`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts)**: Implements the JSON-L writer, incremental filtering, content sanitization, and read APIs that define the L0 persistence layer.
- **[`MemoryProxy/src/tdai/recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/recorder.ts)**: Demonstrates how the proxy extracts the latest user query and bridges the L0 write operations to the core client.
- **[`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts)**: Documents the L0-related request flow and the `addConversation` interface exposed as a read-only tool for agents.
- **[`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md)** (Technical Implementation section): Provides the high-level overview of the L0 → L1 → L2 → L3 layering and the architectural role of raw conversation storage.

## Summary

- **L0 Conversation** is the append-only foundation of the TencentDB Agent Memory four-layer architecture, storing raw dialogue as JSON-L lines.
- Each message receives immutable metadata including unique IDs, timestamps, roles, and session identifiers.
- The layer implements incremental writes with position-based cursors and sanitizes content by stripping injected tags and binary data.
- L0 serves as the upstream source for L1 Atom extraction while remaining directly searchable for precise retrieval.
- A read-only proxy interface (`/v3/memory/addConversation`) allows agents to query history without invalidating caches or modifying stored data.

## Frequently Asked Questions

### What file format does the L0 Conversation layer use for storage?

The L0 Conversation layer persists dialogue as **JSON-L** (JSON Lines), where each line represents a single message object containing fields for the message ID, role (`user` or `assistant`), timestamp, session key, and sanitized content. This format enables efficient append-only writes and streaming reads without parsing entire files into memory.

### How does L0 Conversation prevent duplicate or redundant data writes?

The recorder uses an **incremental position slice** or **timestamp cursor** to track the last written message. When new messages arrive, the system only appends entries occurring after the previous capture point, avoiding full file rewrites. This mechanism is implemented in [`MemoryCore/src/core/conversation/l0-recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/conversation/l0-recorder.ts) to optimize I/O performance during high-frequency agent interactions.

### Why is L0 considered the "single source of truth" in the memory architecture?

Because **L0 stores the raw, unmodified text** of every user and assistant exchange before any abstraction or summarization occurs. Higher layers (L1 Atoms, L2 Scenarios, L3 Personas) derive their data from these records through asynchronous pipelines, making L0 the authoritative reference for verifying historical accuracy and retrieving exact phrasing when semantic abstractions prove insufficient.

### How do agents access L0 data without disrupting the KV cache?

The `MemoryProxy` exposes L0 through a **read-only endpoint** (`/v3/memory/addConversation`) that agents query on-demand. This design deliberately avoids KV-cache invalidation by treating the memory store as an external reference rather than a mutable state container, ensuring that upstream request flows and conversational contexts remain unchanged during memory retrieval.