# How the Retrieval Strategy Combines Different Memory Layers in TencentDB Agent Memory

> Discover how TencentDB Agent Memory's retrieval strategy blends L3 persona L2 scenario data with L1 facts and L0 logs using BM25 and vector search then fuses results for optimal speed and precision.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-27

---

**The retrieval strategy combines different memory layers by first bootstrapping with high-level L3 persona and L2 scenario data, then falling back to BM25 keyword search and vector similarity on L1 atomic facts and L0 conversation logs, merging results with Reciprocal Rank Fusion to balance speed and precision.**

TencentDB Agent Memory implements a hierarchical, four-layer storage system that optimizes retrieval performance through tiered fallback logic. When processing a query, the system leverages a sophisticated retrieval strategy that progressively searches from coarse-grained persona data down to fine-grained conversation records. This layered approach ensures agents receive rapid contextual bootstrapping while maintaining access to precise factual details when needed.

## The Four-Layer Memory Architecture

The retrieval strategy operates across a hierarchical memory stack where each layer serves a distinct purpose in the recall pipeline:

- **L3 – Core/Persona**: Stores long-term profiles and stable behavioral patterns. This layer provides immediate grounding for user preferences and identity context.
- **L2 – Scenario**: Contains knowledge blocks grouped by specific projects or operational contexts. This enables quick "scenario" recall for the current task domain.
- **L1 – Atom**: Houses extracted facts, preferences, constraints, and discrete events. This layer supplies precise factual data retrieved via hybrid search methods.
- **L0 – Conversation**: Maintains raw chat logs with full contextual history. This serves as the source of truth for exact wording or timestamp-specific lookups.

According to the repository README, "Both generation and retrieval are layered: normally, L2/L3 provide a quick context bootstrap; when specific facts are needed, BM25 + vector retrieval + RRF fall back to L1/L0" (`/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/README.md#L55-L56`).

## The Tiered Retrieval Pipeline

The retrieval engine orchestrates a three-phase pipeline that dynamically selects memory layers based on query requirements.

### Bootstrap with L3/L2: Fast Context Injection

When a query enters the system, the `handleBeforeRecall` function in [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts) (lines 371-399) first attempts to satisfy the request using L3 and L2 layers. This bootstrap phase injects relevant persona or scenario data if the query matches stored keys, providing the LLM with immediate high-level grounding without computational overhead.

### Fallback to L1/L0: BM25 and Vector Search

If the query requires concrete facts not satisfied by the bootstrap phase, the system falls back to lower layers. The retrieval engine executes two parallel search strategies against the SQLite store in [`MemoryCore/src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/sqlite.ts) (lines 207-228):

1. **BM25 Full-Text Search (FTS)**: Performs keyword-based ranking on the L1 atomic and L0 conversation stores.
2. **Vector Similarity Search**: When an embedding provider is configured, computes semantic similarity using the TCVDB vector store backend.

### Result Fusion with Reciprocal Rank Fusion

The two result sets merge using **Reciprocal Rank Fusion (RRF)**, a ranking algorithm that assigns higher weight to items appearing high in both keyword and vector rankings. This fusion preserves result diversity while improving relevance, ensuring the final context window contains the most authoritative information from both lexical and semantic search perspectives.

The HTTP `/recall` endpoint defined in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) (lines 941-965) reports the chosen strategy (`keyword`, `vector`, or `none`) and the final memory layer utilized in the response metadata.

## Implementation Details

### Core Recall Orchestration

The central recall logic resides in [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts), where the `handleBeforeRecall` method manages the pre-recall step, executes the tiered search strategy, and attaches performance metadata to the response. This handler coordinates between the high-speed L3/L2 lookup and the computationally intensive L1/L0 search.

### Storage Backends and Search Implementation

The SQLite storage layer in [`MemoryCore/src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/sqlite.ts) implements both retrieval modalities:

- **BM25 Ranking**: Utilizes SQLite's built-in FTS5 engine for keyword relevance scoring.
- **Vector Operations**: Interfaces with Tencent Cloud Vector Database (TCVDB) for embedding-based similarity calculations.

### Configuration and Safety Limits

Retrieval constraints are governed by settings in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts) (lines 84-92). The system enforces configurable caps to prevent context window overflow:

- **`recallTimeoutMs`**: Maximum milliseconds allocated to the retrieval operation.
- **Item Count Limits**: Hard caps on the number of memories returned per layer.
- **Character Budgets**: Maximum token allowances for the final context assembly.

These safeguards ensure the retrieval strategy remains performant even under high query loads or extensive memory stores.

## Practical Example: Invoking the Retrieval Pipeline

The following TypeScript SDK example demonstrates how the layered retrieval strategy exposes the selected search method through the API response:

```typescript
// Example: Invoke recall via the MemoryCore SDK
import { MemoryCoreClient } from '@tencentdb/memory-core';

// Initialise the client (endpoint URL may differ in your deployment)
const client = new MemoryCoreClient({ baseURL: 'http://localhost:8000/v3' });

async function demoRecall(query: string, sessionId: string) {
  // POST /recall – triggers the layered retrieval pipeline
  const resp = await client.recall({ query, session_id: sessionId });

  console.log('Recall strategy:', resp.recallStrategy); // "keyword", "vector", or "skipped"
  console.log('Returned memories (L1/L0):', resp.recalledL1Memories);
  // Each entry contains { content, score, type }
}

demoRecall('What is the current project deadline?', 'session-42');

```

The API response reveals the internal strategy selection:

```json
{
  "recalledL1Memories": [
    { "content": "Project X deadline is 2026‑12‑31.", "score": 0.93, "type": "conversation" },
    { "content": "Milestone Y due next week.", "score": 0.88, "type": "atom" }
  ],
  "recallStrategy": "keyword",
  "recallLatencyMs": 42,
  "hasError": false
}

```

The SDK transparently handles the layered approach: it first requests any available L3/L2 context (returned in `recalledL3Persona` when present), then executes the BM25 and vector fallback sequence as implemented in the core recall handler.

## Summary

- **Hierarchical Retrieval**: The system prioritizes L3 persona and L2 scenario data for immediate context bootstrapping before falling back to L1 atomic facts and L0 conversations.
- **Hybrid Search**: L1/L0 retrieval combines BM25 keyword search with vector similarity to capture both lexical matches and semantic relevance.
- **RRF Merging**: Reciprocal Rank Fusion unifies keyword and vector results, optimizing for both precision and diversity in the final context window.
- **Configurable Limits**: Timeouts, item counts, and character budgets in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts) prevent retrieval operations from exceeding resource constraints.
- **Transparent Strategy**: The `/recall` endpoint and TypeScript SDK expose the selected strategy (`keyword`, `vector`, or `none`) and performance metrics for observability.

## Frequently Asked Questions

### What is the order of memory layers during retrieval?

The retrieval strategy follows a top-down approach: L3 (Core/Persona) and L2 (Scenario) are queried first for rapid context establishment. If these layers lack sufficient information, the system falls back to L1 (Atom) and L0 (Conversation) using BM25 and vector search. This ordering prioritizes speed for high-level context while reserving computationally expensive search for specific factual details.

### How does Reciprocal Rank Fusion improve retrieval results?

Reciprocal Rank Fusion (RRF) merges the ranked lists from BM25 keyword search and vector similarity search by assigning scores based on inverse rank positions. Documents appearing in both high-ranking positions receive boosted scores, while unique items from either list maintain competitive rankings. This method improves relevance by leveraging the strengths of both lexical and semantic matching without requiring training data or parameter tuning.

### What happens if both BM25 and vector search return results?

When both search modalities return candidate memories, the system passes both ranked lists through the RRF algorithm to produce a unified, reranked result set. The final list truncates according to the configured item count and character budget limits defined in [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts). If only one modality returns results, those results proceed directly to the truncation phase without fusion penalties.

### How do I configure retrieval timeouts and limits?

Retrieval constraints are controlled through the configuration file at [`MemoryCore/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts) (lines 84-92). Key parameters include `recallTimeoutMs` for operation timeouts, maximum item counts per memory layer, and total character budgets for the assembled context. These settings ensure the retrieval strategy respects LLM token limits and maintains low-latency response times regardless of memory store size.