How TencentDB Agent Memory Layers Work: From L0 Conversations to L3 Personas

TencentDB Agent Memory implements a four-layer hierarchy (L0 through L3) that asynchronously transforms raw conversation logs into distilled facts, scenario-based context blocks, and long-term persona profiles, enabling agents to retrieve relevant knowledge with hierarchical fallback strategies.

The TencentDB-Agent-Memory repository provides a production-grade memory system for AI agents that progressively refines unstructured chat data into structured, reusable assets. By understanding how data flows from timestamped messages (L0) through atomic extractions (L1) and scenario assemblies (L2) to persistent cognitive profiles (L3), developers can optimize retrieval performance and maintain context across complex, multi-session interactions.

Understanding the Four Memory Layers (L0 to L3)

The architecture organizes memory into four distinct levels of abstraction, each serving specific retrieval patterns and latency requirements.

L0 Conversation: The Raw Event Stream

L0 stores the complete, timestamped chat messages with full conversational context. This layer acts as the system of record, capturing every user message and assistant response exactly as transmitted. According to the source code in MemoryCore/src/core/conversation/l0-recorder.ts, L0 data persists to JSONL files, ensuring an auditable trail of all interactions. This layer is essential when precise wording or complete dialogue history is required for compliance or debugging.

L1 Atom: Distilled Facts and Preferences

L1 contains machine-readable atoms—facts, preferences, constraints, and events extracted from L0 conversations via LLM-based background workers. As implemented in MemoryCore/src/store/llm-binding-store.ts, these atoms represent discrete knowledge units such as {type: "Fact", key: "caching", value: "LRU with 5 min TTL"}. The extraction process runs asynchronously, parsing raw conversations into queryable data structures that support fast, precise recall without reprocessing entire chat histories.

L2 Scenario: Contextual Groupings

L2 aggregates related L1 atoms into scenario assets centered around specific projects, tasks, or business domains. The MemoryCore/src/services/pipeline-worker.ts service periodically groups atoms sharing a common scenario_id, producing bundled context blocks. These pre-assembled packages allow agents to bootstrap quickly with relevant domain knowledge—for example, loading all authentication-related atoms for a "mobile-auth rewrite" project—without runtime extraction overhead.

L3 Persona: Long-Term Cognitive Profiles

L3 synthesizes cross-scenario patterns into persistent persona profiles that capture stable user habits, communication styles, and high-level goals. The synthesis logic in MemoryCore/src/utils/memory-cleaner.ts merges long-term patterns across multiple L2 scenarios, creating comprehensive profiles that agents can inject directly into prompts. This layer enables instant personality alignment and goal-awareness, inheriting deep understanding of user preferences without repeated context buildup.

The Asynchronous Data Pipeline

The system employs an asynchronous refinement pipeline that progressively elevates data from raw inputs to high-level knowledge.

Data flows through four stages:

1. Ingestion (L0) – Agents submit raw conversations via POST /v3/conversation/add, defined in MemoryCore/src/core/conversation/l0-recorder.ts, persisting messages with isolation context.

2. Extraction (L1) – Background workers read new L0 records and execute LLM-based extraction, storing results in MemoryCore/src/store/llm-binding-store.ts.

3. Assembly (L2) – The pipeline worker in MemoryCore/src/services/pipeline-worker.ts aggregates atoms by scenario_id into scenario assets.

4. Synthesis (L3) – Long-term patterns merge into persona profiles, with cleanup operations handled by the memory cleaner utility.

Retrieval follows the inverse hierarchy. Most queries target L2 scenarios or L3 personas for low-latency responses; if specific facts are missing, the system falls back to L1 atoms and L0 conversations using BM25 plus vector search with reranking.

Isolation Context and Session Handling

Every memory operation binds to an isolation context tuple: (team_id, agent_id, user_id, session_id, task_id). This structure, enforced throughout sdk/memory-core/typescript/src/v3/client.ts, ensures strict multi-tenant separation.

• L0/L1 operations accept optional session_id parameters, enabling aggregation across sessions for team-wide analytics or user-level longitudinal analysis.
• L2/L3 assets enforce strict scoping—these belong to specific teams and maintain versioning per persona, preventing cross-contamination between organizational boundaries.

Working with the TypeScript SDK

The sdk/memory-core/typescript/src/v3/client.ts package provides methods to interact with each memory layer.

Writing Raw Conversations to L0

Persist conversation logs to trigger the downstream pipeline:

import { MemoryClient } from "@tencentdb-agent-memory/memory-core";

const client = new MemoryClient({
  endpoint: "https://memory.example.com",
  apiKey: "your-api-key",
  teamId: "team-001",
  agentId: "agent-scout",
  userId: "user-alice",
});

await client.addConversation({
  session_id: "sess-20230819",
  messages: [
    { role: "user", content: "Explain the caching strategy." },
    { role: "assistant", content: "We use LRU with a 5 min TTL." },
  ],
});

This creates an L0 record; background workers subsequently generate L1 atoms.

Querying L1 Atomic Facts

Retrieve extracted facts without parsing raw chat:

const atoms = await client.searchAtomic({
  query: "caching strategy",
  limit: 5,
});
// Returns: [{type: "Fact", key: "caching", value: "LRU with 5 min TTL"}]

Loading L2 Scenario Context

Fetch pre-bundled context for specific projects:

const scenario = await client.getScenario({
  scenario_id: "proj-payment-gateway",
});

This provides a ready-made context block prepopulated with relevant L1 atoms, as aggregated by the pipeline worker in MemoryCore/src/services/pipeline-worker.ts.

Fetching L3 Persona Profiles

Access long-term user models for prompt injection:

const persona = await client.getPersona({
  user_id: "user-alice",
});

The returned profile includes stable preferences and decision patterns synthesized across multiple scenarios.

Summary

• TencentDB Agent Memory organizes data in four layers: L0 (raw conversations), L1 (extracted atoms), L2 (scenario assemblies), and L3 (persona profiles).
• Asynchronous processing moves data upwards through the hierarchy via background workers defined in MemoryCore/src/services/pipeline-worker.ts.
• Retrieval prioritizes speed by checking L2/L3 first, falling back to L1/L0 only when necessary, utilizing BM25 and vector search.
• Strict isolation ensures team-scoped memory through the (team_id, agent_id, user_id, session_id, task_id) tuple implemented in the TypeScript SDK client.

Frequently Asked Questions

What distinguishes L1 atoms from L2 scenarios?

L1 atoms are discrete, extracted facts (e.g., "user prefers dark mode") stored individually in MemoryCore/src/store/llm-binding-store.ts, while L2 scenarios are aggregated collections of related atoms grouped by project or task context in MemoryCore/src/services/pipeline-worker.ts. Atoms answer specific factual queries; scenarios provide broad contextual grounding for agent initialization.

How does the retrieval system prioritize memory layers?

The retrieval engine queries L2 scenarios and L3 personas first for high-speed context loading, as these layers contain pre-synthesized knowledge blocks. If the required information is absent, the system falls back to L1 atomic search and L0 conversation logs, employing BM25 text matching combined with vector similarity search and reranking algorithms to locate specific details.

Can applications query L0 conversations directly?

Yes, L0 remains directly accessible via the SDK and API endpoints, though retrieval typically relies on higher layers for efficiency. Direct L0 access is primarily used for audit trails, exact wording verification, or debugging extraction quality, while production agent queries leverage the hierarchical cache of L1-L3 to minimize latency and token costs.

How does TencentDB Agent Memory maintain data isolation across teams?

The system enforces isolation through a mandatory context tuple (team_id, agent_id, user_id, session_id, task_id) passed with every operation in sdk/memory-core/typescript/src/v3/client.ts. L2 and L3 assets are strictly bound to team_id with versioned persona profiles, preventing unauthorized cross-team access, while L0/L1 operations support optional session aggregation for authorized analytics without compromising security boundaries.

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