# How L1 (Atom) Memory Is Recalled and Used in TencentDB Agent Memory

> Discover how L1 Atom memory is recalled and used in TencentDB Agent Memory. Explore the two-stage retrieval pipeline, token budgets, and Memory Hub API integration.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: internals
- Published: 2026-09-01

---

**L1 (Atom) memory in TencentDB Agent Memory is recalled via a two-stage retrieval pipeline that performs BM25 vector search on atomic entries in [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts), enforces strict token budgets, and injects the retrieved facts into the model’s system prompt through the Memory Hub API.**

TencentDB Agent Memory organizes experience into four layers—L0 (Conversation), L1 (Atom), L2 (Scenario), and L3 (Core/Persona). The **L1 Atom** layer stores distilled, granular facts extracted from raw conversation logs. When an agent needs to ground its reasoning in long-term knowledge, it recalls these atomic units through a dedicated retrieval pipeline and injects them into the LLM context.

## The L1 Memory Retrieval Pipeline

The recall process begins in [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts), which implements a stateful, budget-aware retrieval system optimized for low-latency access to L1 Atom entries.

### Two-Stage Search and Fallback

For any given query, the pipeline executes a **fast BM25 vector search** against the L1 Atom index to surface the most relevant atomic facts. If the initial retrieval proves insufficient, the system performs a fallback search against the raw **L0 Conversation** logs to ensure no critical detail is missed. This hybrid approach balances speed with comprehensiveness, allowing the agent to access both distilled knowledge (L1) and verbatim history (L0) when necessary.

### Budget Enforcement and Truncation

To prevent context window overflow, the pipeline enforces hard limits on retrieval size. Results are capped by **token budget**, **character count**, and **timeout** thresholds before being packaged for the model. The [`MemoryCore/src/utils/text-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/text-utils.ts) module provides helper functions for truncation, merging, and formatting these L1 memory snippets into coherent context blocks.

## From L1 Atoms to Model Context

Once retrieved, L1 Atom entries are transformed into structured **Memory Asset payloads** and delivered to the agent via the Memory Hub API.

### Asset Discovery via Memory Hub

The agent first calls the **`/v3/tools/list`** endpoint (documented in [`MemoryProxy/v3-api-memoryproxy-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/v3-api-memoryproxy-doc.md)) to discover accessible memory assets. This request respects team, user, and ACL bindings, ensuring only authorized L1-derived assets (Chat Memory, Skills, Wiki, CodeGraph) are returned.

### Asset Extraction and Payload Generation

Using the **`/v3/tools/call`** endpoint (see [`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md)), the agent retrieves the specific Memory Asset payload containing the L1 Atom content. This JSON block may include aggregated atomic facts formatted as L2 Scenario summaries or L3 Persona profiles, depending on the asset type requested.

### Prompt Injection

The retrieved L1 memory content is prepended to the model’s **system prompt** (or injected as a dedicated memory-only system message). Because L1 Atoms represent pre-distilled facts rather than raw conversation history, the model can immediately ground its generation on authoritative knowledge without processing redundant dialogue.

## API Integration Example

The following TypeScript demonstrates the complete flow: discovering available assets, retrieving L1-derived memory content, and injecting it into the LLM request.

```typescript
// 1️⃣ List assets the agent can access (respects ACL)
const assets = await fetch(
  'http://localhost:8125/v3/tools/list',
  { method: 'GET', headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());

// 2️⃣ Select the L1-derived asset (e.g., Chat Memory or Persona)
const memoryAssetId = assets.find(a => a.type === 'chat_memory').id;

// 3️⃣ Retrieve the L1 Atom content packaged as a Memory Asset
const l1Memory = await fetch(
  `http://localhost:8125/v3/tools/call/${memoryAssetId}`,
  { method: 'GET', headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());

// 4️⃣ Inject L1 memory into the model's system prompt
const response = await fetch('http://localhost:8125/v3/agent/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: l1Memory.content },   // <-- L1 memory context
      { role: 'user',   content: userPrompt }
    ],
    max_tokens: 1024
  })
}).then(r => r.json());

```

## Summary

- **L1 Atom retrieval** relies on BM25 vector search implemented in [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts), with fallback to L0 Conversation logs for completeness.
- **Budget controls** (token, character, timeout caps) ensure retrieved L1 content fits within model context windows, managed via [`text-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/text-utils.ts).
- **Memory Hub API** endpoints (`/v3/tools/list` and `/v3/tools/call`) handle asset discovery and extraction, respecting ACL bindings defined in [`MemoryProxy/v3-api-memoryproxy-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/v3-api-memoryproxy-doc.md).
- **Prompt injection** places L1 memory into the system message, allowing the model to reason over distilled facts without reprocessing raw history.

## Frequently Asked Questions

### What is the difference between L0 and L1 memory in TencentDB Agent Memory?

**L0 Conversation** stores the raw, unprocessed dialogue history between users and agents. **L1 Atom** memory consists of distilled, semantic facts extracted from those conversations—individual pieces of knowledge like user preferences, decisions, or constraints. The retrieval pipeline searches L1 first for efficiency and falls back to L0 only when necessary.

### How does the stateful pipeline manager prevent context window overflow?

The [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts) implementation enforces three simultaneous constraints: a **token budget**, a **character count limit**, and a **timeout threshold**. Results from the L1 Atom search are truncated and merged using utilities in [`text-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/text-utils.ts) until all constraints are satisfied, ensuring the final payload never exceeds the model's capacity.

### Can agents access L1 memory from other teams or users?

No. The **`/v3/tools/list`** endpoint filters assets based on team, user, and ACL (Access Control List) bindings. Agents receive only the L1-derived assets they are explicitly authorized to access, as enforced by the Memory Hub's permission layer documented in the Memory Proxy API.

### Why use BM25 search for L1 Atoms instead of pure vector similarity?

BM25 provides **fast, exact-match retrieval** on discrete atomic facts, which is ideal for the granular, keyword-rich nature of L1 entries. The pipeline uses this as the first stage for speed, reserving deeper semantic search or raw log scanning (L0 fallback) for cases where the BM25 results are insufficient.