# How Conversation Data (L0) Is Stored in TencentDB Agent Memory: Schema and Operations

> Learn how TencentDB Agent Memory stores raw L0 conversation data in a MongoDB-style document store. Explore the six core HTTP operations for managing this immutable data.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-28

---

**TencentDB Agent Memory persists raw dialogue as immutable L0 Conversation records in a MongoDB-style document store, exposing six core HTTP operations—add, query, search, delete, count, and force-archive—wrapped by TypeScript and Python SDKs.**

TencentDB Agent Memory implements a hierarchical memory architecture where L0 represents the immutable foundation of raw conversation data. According to the TencentCloud/TencentDB-Agent-Memory repository, these records serve as the source of truth for downstream L1 Atom extraction and higher-level memory abstractions. This article examines the storage schema, automatic archival triggers, and the six core API operations that manipulate L0 data.

## L0 Conversation Storage Schema

L0 Conversation is the lowest-level memory layer that preserves every dialogue turn exactly as it occurred. When a client calls the `POST /v3/conversation/add` endpoint, the Memory Core creates an immutable JSON document containing the following fields:

- `session_id`: A stable identifier for the conversation, often composed of the user ID and session ID
- `user_id`: The originating user identifier
- `team_id`: The organizational team the conversation belongs to  
- `agent_id`: The specific agent that generated the turn
- `messages`: An array of message objects containing `role`, `content`, and optional `metadata`
- `timestamp`: Server-side time when the turn was received
- `archived`: Boolean flag indicating archival status (false during active turns, true after archiving)
- `space_id` (optional): Logical partition for multi-tenant isolation
- `reason` and `task_id` (optional): Context fields used during manual archiving

These records are stored in the **Memory Core** database as immutable JSON documents. As documented in the [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) **Technical Implementation** section, the raw L0 data later feeds an asynchronous pipeline that extracts L1 Atoms, L2 Scenarios, and L3 Personas, while the original conversation remains preserved for verification and replay.

## Key Operations for L0 Conversation Data

The Memory Core v3 API exposes six primary HTTP endpoints for manipulating L0 records. According to [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md), these operations support the full lifecycle of conversation storage and retrieval.

### Add Conversation

The `POST /v3/conversation/add` endpoint inserts new L0 turns into the database. The request body requires `session_id`, `user_id`, `team_id`, `agent_id`, and `messages`.

Automatic archiving triggers when any of three conditions are met:

- Tool-call count reaches 10 or greater
- Payload size exceeds 10 KB  
- The `space_id` field is present in the record

### Query and Search Operations

**Query Conversation** (`POST /v3/conversation/query`): Retrieves recent turns for a specific session using `session_id` or `message_ids`, with an optional `limit` parameter to control result volume. Results preserve chronological order.

**Search Conversation** (`POST /v3/conversation/search`): Executes BM25 and vector-based full-text search across L0 content. Requires a `query` string and accepts optional filters, returning matching turns with relevance scores.

### Archive and Delete Operations

**Force Archive** (`POST /v3/conversation/force-archive`): Manually marks a conversation as archived, bypassing automatic triggers. Requires `session_id`, `user_id`, `team_id`, `agent_id`, `space_id`, `reason`, and `task_id` parameters.

**Delete Conversation** (`POST /v3/conversation/delete`): Performs hard deletion of L0 entries in bulk using either `message_ids` or `session_ids` arrays.

**Count Conversation** (`POST /v3/conversation/count`): Returns aggregate counts of L0 turns matching optional filter criteria.

## SDK Implementation Examples

The TypeScript and Python SDKs wrap these HTTP operations in type-safe client methods. The validation schemas defined in [`MemoryCore/src/api-helpers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/api-helpers.ts) enforce the request structures.

### TypeScript SDK

Located 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), the `SkillClient` class provides methods like `conversationAdd()`, `queryConversation()`, and `conversationForceArchive()`.

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

const client = new SkillClient({ baseUrl: 'https://localhost:8000' });

// Store a new conversation turn
await client.conversationAdd({
  session_id: 'sess-1234',
  user_id: 'u-alice',
  team_id: 'team-alpha',
  agent_id: 'agent-builder',
  messages: [
    { role: 'user', content: 'How do I configure the DB?' },
    { role: 'assistant', content: 'You need to set `max_connections`…' },
  ],
});

// Retrieve recent history
const recent = await client.queryConversation({
  session_id: 'sess-1234',
  limit: 5,
});

// Manual archival
await client.conversationForceArchive({
  session_id: 'sess-1234',
  user_id: 'u-alice',
  team_id: 'team-alpha',
  agent_id: 'agent-builder',
  space_id: 'default',
  reason: 'session finished',
  task_id: 'task-9876',
});

```

### Python SDK

The `SkillClient` in [`sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py) offers identical functionality with Pythonic naming conventions.

```python
from tencentdb_agent_memory.v3.skill_client import SkillClient

client = SkillClient(base_url="https://localhost:8000")

# Add conversation turn

client.conversation_add(
    session_id="sess-1234",
    user_id="u-alice",
    team_id="team-alpha",
    agent_id="agent-builder",
    messages=[
        {"role": "user", "content": "How do I configure the DB?"},
        {"role": "assistant", "content": "Set `max_connections`..."},
    ],
)

# Query recent turns

recent = client.query_conversation(session_id="sess-1234", limit=5)

# Force archive

client.conversation_force_archive(
    session_id="sess-1234",
    user_id="u-alice",
    team_id="team-alpha",
    agent_id="agent-builder",
    space_id="default",
    reason="session finished",
    task_id="task-9876",
)

```

## Summary

- L0 Conversation records store raw, immutable dialogue data as JSON documents in the Memory Core database, preserving every turn exactly as received.
- The storage schema includes mandatory fields (`session_id`, `user_id`, `team_id`, `agent_id`, `messages`) and optional archival metadata (`space_id`, `reason`, `task_id`).
- Six core HTTP operations manage L0 data: `add`, `query`, `search`, `delete`, `count`, and `force-archive`.
- Automatic archiving triggers when conversations exceed 10 tool calls, 10 KB payload size, or contain a `space_id` partition identifier.
- Both TypeScript and Python SDKs provide ergonomic wrappers around the `POST /v3/conversation/*` endpoints, with request validation defined in [`MemoryCore/src/api-helpers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/api-helpers.ts).

## Frequently Asked Questions

### What is the difference between L0, L1, L2, and L3 memory layers in TencentDB Agent Memory?

L0 represents raw conversation data stored as immutable JSON documents. L1 Atoms are extracted facts from L0, L2 Scenarios represent contextual situations, and L3 Personas capture long-term agent behavior patterns. The system processes L0 data through an asynchronous pipeline to derive these higher abstractions while keeping the original L0 records intact for verification.

### When does automatic archiving occur for L0 conversations?

Automatic archiving triggers when any of three conditions are met: the conversation contains 10 or more tool calls, the payload size reaches 10 KB, or the record includes a `space_id` field for multi-tenant partitioning. Archived records maintain their `archived` boolean flag as true but remain queryable in the database.

### How do I retrieve specific conversation turns using the SDK?

Use the `query_conversation` method in Python or `queryConversation` in TypeScript, passing the `session_id` and an optional `limit` parameter. For full-text search across message content, use `search_conversation` (Python) or `searchConversation` (TypeScript) which performs BM25 and vector search with relevance scoring.

### Where are the L0 conversation validation schemas defined?

Request validation schemas for conversation operations are defined in [`MemoryCore/src/api-helpers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/api-helpers.ts), which specifies structures like `conversationAddRequestSchema`. Both the TypeScript client ([`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)) and Python client ([`sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py)) implement these schema requirements.