TencentDB Agent Memory Retrieval Techniques: BM25, Vector Search, and Hybrid Fusion Explained

TencentDB Agent Memory combines BM25 full-text search, dense vector embeddings, Reciprocal Rank Fusion (RRF), and graph traversal to retrieve the most relevant context for LLM agents across layered memory stores.

The TencentCloud/TencentDB-Agent-Memory repository implements a sophisticated retrieval stack that balances out-of-the-box usability with optional high-precision semantic search. Understanding these retrieval techniques is essential for optimizing agent performance, whether you need fast keyword matching or deep semantic understanding across documentation wikis.

BM25 Full-Text Search (Sparse Retrieval)

At the foundation of TencentDB Agent Memory lies BM25 full-text search, which provides robust keyword retrieval without external dependencies.

Implementation in SQLite Store

The system leverages SQLite's FTS5 virtual table to power BM25 ranking. In MemoryCore/src/core/store/sqlite.ts, the store encodes queries and documents using local BM25 logic, enabling instant full-text matching across atomic memories. This approach requires zero configuration and works offline, making it the default retrieval mode when provider: "none" is set in tdai-gateway.standalone.yaml.

The BM25 encoder lives in MemoryCore/src/core/store/bm25-local.ts, where it handles tokenization and scoring entirely within the local process. This ensures low-latency retrieval for L2/L3 bootstrap layers where speed matters more than semantic nuance.

Vector (Dense) Embedding Search

For semantic similarity matching, the system supports optional dense vector embeddings powered by Tencent Cloud VectorDB.

Tencent Cloud VectorDB Integration

When embeddingEnabled: true is configured, MemoryCore/src/core/store/tcvdb.ts transforms text queries into dense vectors and forwards them to Tencent Cloud VectorDB. The store receives similarity scores for candidate documents, enabling retrieval of conceptually related content even when keyword overlap is minimal.

This mode is particularly effective for L1/L0 fallback layers where agents need specific facts expressed in different terminology than the original query.

Hybrid Retrieval with Reciprocal Rank Fusion (RRF)

The most powerful retrieval mode combines both sparse and dense signals through hybrid search with RRF.

Combining Sparse and Dense Signals

In MemoryCore/src/core/store/tcvdb.ts, the hybridSearch method executes BM25 and vector searches in parallel, then merges results using Reciprocal Rank Fusion (RRF). This algorithm favors items that rank highly in either list, balancing BM25's exact matching precision with embeddings' semantic coverage.

The RRF implementation calculates fused scores based on reciprocal ranks, ensuring that a document appearing third in BM25 and fifth in vector search outranks documents appearing tenth in both lists.

Graph-Expanded Wiki Search

For knowledge base retrieval, TencentDB Agent Memory implements graph-expanded search that treats wiki pages as nodes in a semantic network.

Traversing Wikilink Relationships

Located in MemoryKnowledge/src/engines/wiki/graph-search.ts, this engine performs an initial BM25 seed retrieval, then walks [[wikilink]] edges up to a configurable hop count (default 2). This expansion pulls related documentation pages that may not contain the original keywords but are topically adjacent, enabling "semantic drill-down" through technical documentation.

After expansion, the system re-ranks the combined set of seed and neighbor pages before returning results to the agent.

Layered Memory Architecture

Retrieval operates across a layered hierarchy as described in the repository's README.md. L2 and L3 serve as fast bootstrap layers using lightweight BM25 scans, while L1 and L0 provide deeper factual recall using the full hybrid retrieval stack. When a concrete fact is required, the system automatically falls back from abstract summaries (L2/L3) to detailed atomic memories (L1/L0) using the techniques above.

Configuration and Usage Examples

BM25-Only Retrieval

By default, the gateway runs in BM25-only mode. Use the TypeScript SDK to search atomic memories:

import { createMemoryClient } from '../sdk/memory-core/typescript';

const client = createMemoryClient({
  endpoint: 'http://127.0.0.1:8420',
  apiKey: process.env.TDAI_GATEWAY_API_KEY,
});

const results = await client.atomic.search({
  query: 'user prefers dark theme',
  topK: 10,
  teamId: 'team-123',
  agentId: 'agent-foo',
});

console.log(results);

Hybrid Vector Search

Enable embeddings in your gateway configuration, then invoke hybrid search:

import { createMemoryClient } from '../sdk/memory-core/typescript';

const client = createMemoryClient({ endpoint: 'http://127.0.0.1:8420', apiKey: '…' });

const hybrid = await client.atomic.search({
  query: 'how to reset password',
  topK: 20,
  useEmbedding: true,          // Forces hybridSearch (BM25 + vector + RRF)
  teamId: 'team-123',
});

console.log(hybrid);

Wiki Graph Search

For documentation exploration with link expansion:

import fetch from 'node-fetch';

const base = 'http://127.0.0.1:8420';
const token = process.env.TDAI_GATEWAY_API_KEY;

async function wikiSearch(query: string, hop = 2) {
  const resp = await fetch(`${base}/v3/tools/call`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      tool: 'wikiSearch',
      args: { query, hop },   // hop = 0 means pure BM25
    }),
  });
  return resp.json();
}

wikiSearch('authentication flow', 2).then(console.log);

Summary

• BM25 via FTS5 provides fast, local keyword search in MemoryCore/src/core/store/sqlite.ts without external services.
• Dense vector search leverages Tencent Cloud VectorDB through MemoryCore/src/core/store/tcvdb.ts when embeddingEnabled: true.
• Hybrid RRF merges sparse and dense rankings in tcvdb.ts using Reciprocal Rank Fusion for optimal relevance.
• Graph expansion traverses wiki links in MemoryKnowledge/src/engines/wiki/graph-search.ts to surface related documentation.
• Layered retrieval uses L2/L3 for fast bootstrapping and L1/L0 for deep factual recall, configurable via tdai-gateway.*.yaml files.

Frequently Asked Questions

What is the default retrieval mode in TencentDB Agent Memory?

The default configuration disables remote embeddings and uses BM25 full-text search exclusively. In tdai-gateway.standalone.yaml, the provider is set to "none", causing the system to rely on the local BM25 encoder in MemoryCore/src/core/store/bm25-local.ts and SQLite FTS5 tables.

How does Reciprocal Rank Fusion (RRF) improve search results?

RRF combines result lists from different retrieval methods by scoring documents based on their reciprocal ranks across lists. According to the implementation in MemoryCore/src/core/store/tcvdb.ts, this technique ensures that documents ranking highly in either BM25 or vector search receive priority, producing more robust results than either method alone.

When should I enable graph-expanded wiki search?

Use graph expansion when querying technical documentation where related concepts are linked via [[wikilink]] syntax. Setting hop to 1 or 2 in the wikiSearch tool call (as implemented in MemoryKnowledge/src/engines/wiki/graph-search.ts) retrieves not just keyword matches but conceptually adjacent pages, improving coverage of interconnected knowledge bases.

Can I use vector search without Tencent Cloud VectorDB?

No. The dense embedding path in MemoryCore/src/core/store/tcvdb.ts specifically integrates with Tencent Cloud VectorDB. There is no local embedding option; the system defaults to BM25 when external vector services are unavailable or embeddingEnabled remains false.

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