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

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 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, 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 enforce the request structures.

TypeScript SDK

Located in sdk/memory-core/typescript/src/v3/client.ts, the SkillClient class provides methods like conversationAdd(), queryConversation(), and conversationForceArchive().

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 offers identical functionality with Pythonic naming conventions.

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.

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, which specifies structures like conversationAddRequestSchema. Both the TypeScript client (sdk/memory-core/typescript/src/v3/client.ts) and Python client (sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py) implement these schema requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}