How TencentDB Agent Memory's Layered Architecture (L0-L3) Works

TencentDB Agent Memory organizes interaction data into a four-layer hierarchy that progressively refines raw conversations into reusable knowledge, allowing agents to retrieve high-level context instantly while maintaining access to granular historical details.

TencentDB Agent Memory implements a sophisticated storage system that transforms ephemeral chat messages into structured, long-term knowledge. This article examines the Layered Memory Architecture (L0-L3) as implemented in the TencentCloud/TencentDB-Agent-Memory repository, detailing how each layer serves distinct retrieval needs—from raw audit trails to synthesized user personas.

The Four Layers of Memory

L0 Conversation: The Raw Audit Trail

The foundation layer stores complete, timestamped chat messages with full context. According to src/core/conversation/l0-recorder.ts, L0 persists raw JSONL records that guarantee faithful reconstruction of exactly what was said. This layer serves audit requirements and precise wording retrieval when exact phrasing matters.

L1 Atom: Distilled Facts and Preferences

Background workers process L0 records to extract discrete facts, constraints, and preferences, storing them in src/store/llm-binding-store.ts. These atoms represent actionable information—such as "user prefers dark mode"—enabling fast, precise recall without parsing full conversation history.

L2 Scenario: Contextual Project Blocks

Atoms sharing a common scenario_id are aggregated into scenario assets, as implemented in src/services/pipeline-worker.ts. An L2 scenario bundles related atoms around specific projects or tasks (e.g., "mobile-auth rewrite"), providing ready-made context blocks that bootstrap agents for particular domains.

L3 Persona: Long-Term User Profiles

The highest layer synthesizes long-term patterns across scenarios into stable user or team profiles. The system merges behavioral patterns and high-level cognition in src/utils/memory-cleaner.ts, allowing agents to inherit deep understanding of user habits, goals, and communication styles instantly.

Data Flow and Asynchronous Processing

Ingestion Pipeline

When an agent completes a turn, the SDK posts raw messages via POST /v3/conversation/add. The TypeScript SDK method in sdk/memory-core/typescript/src/v3/client.ts (lines 191-199) handles this ingestion:

await client.addConversation({
  session_id: "sess-123",
  messages: [{ role: "user", content: "How do I enable dark mode?" }]
});

This creates the L0 record. Background workers then asynchronously extract L1 atoms, assemble L2 scenarios, and synthesize L3 personas without blocking the main agent loop.

Retrieval with Hierarchical Fallback

Retrieval follows the same hierarchy for performance optimization. Most queries target L2/L3 for speed; if specific facts are missing, the system falls back to L1/L0 using BM25 plus vector search with reranking, as documented in the Technical Implementation section of the README.

Isolation and Session Handling

Every operation binds to an IsolationContext tuple of (team_id, agent_id, user_id, session_id, task_id) defined in sdk/memory-core/typescript/src/v3/client.ts (lines 155-163). For L0/L1 operations, omitting session_id enables aggregation across sessions for team-wide analytics. L2/L3 operations enforce strict context boundaries, ensuring assets belong to specific teams with versioned persona profiles.

SDK Implementation Examples

Recording Raw Conversations (L0)

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." },
  ],
});

Querying Atomic Facts (L1)

const atoms = await client.searchAtomic({
  query: "caching strategy",
  limit: 5,
});

This returns extracted facts like {type:"Fact", key:"caching", value:"LRU with 5 min TTL"} from the atomic store.

Loading Scenario Context (L2)

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

This provides a pre-bundled context block that can be prepended to the prompt of a new agent run.

Fetching User Personas (L3)

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

This delivers the high-level persona profile (preferences, previous decisions, style) ready to be injected into the LLM prompt.

Summary

• TencentDB Agent Memory uses a four-layer hierarchy (L0-L3) that balances granular audit trails with high-performance retrieval.
• L0 Conversation stores raw messages in src/core/conversation/l0-recorder.ts for complete historical fidelity.
• L1 Atoms distill facts into src/store/llm-binding-store.ts for rapid fact retrieval.
• L2 Scenarios aggregate atoms via src/services/pipeline-worker.ts into domain-specific context blocks.
• L3 Personas synthesize long-term profiles in src/utils/memory-cleaner.ts for persistent user modeling.
• The asynchronous pipeline processes layers in the background while isolation contexts ensure proper data boundaries across teams and sessions.

Frequently Asked Questions

What distinguishes L2 Scenarios from L3 Personas?

L2 Scenarios group related atoms around specific projects or tasks, providing immediate context for particular domains. L3 Personas capture cross-scenario patterns and stable behavioral traits about users or teams, enabling agents to maintain consistent understanding across unrelated interactions.

How does the system handle missing information during retrieval?

The retrieval engine prioritizes L2/L3 assets for speed but implements automatic fallback to L1/L0 when specific details are absent. It combines BM25 text search with vector similarity and reranking to locate relevant historical data across all layers.

Can session data be aggregated across multiple conversations?

Yes. For L0 and L1 operations, omitting the session_id parameter in the IsolationContext allows aggregation across sessions, useful for team-wide statistics. However, L2 scenarios and L3 personas maintain strict context binding to specific teams and users regardless of session boundaries.

What storage formats back each memory layer?

L0 conversations persist as JSONL files in src/core/conversation/l0-recorder.ts. L1 atoms store in the LLM binding store at src/store/llm-binding-store.ts. L2 scenarios aggregate in SQLite via src/store/sqlite-store.ts, while L3 personas maintain versioned profiles processed through src/utils/memory-cleaner.ts.

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