Combine BM25 keyword search with vector similarity using Reciprocal Rank Fusion for accurate, recall-maximizing retrieval.

Why Hybrid Search

Vector search is great at finding semantically similar content, but it can miss results that match on exact terms. Keyword search finds exact matches but misses paraphrases. Hybrid search combines both to maximize recall and precision.

Cogitator's hybrid search pipeline:

Query ──┬── Vector Search (cosine similarity) ──┐
        │                                        ├── RRF Fusion ── Ranked Results
        └── Keyword Search (BM25) ──────────────┘

HybridSearch Class

The HybridSearch class orchestrates vector and keyword search, then fuses results using Reciprocal Rank Fusion (RRF).

import {
  HybridSearch,
  PostgresAdapter,
  OpenAIEmbeddingService,
  unwrap,
} from '@cogitator-ai/memory';

const embeddings = new OpenAIEmbeddingService({
  apiKey: process.env.OPENAI_API_KEY!,
});

const db = new PostgresAdapter({
  provider: 'postgres',
  connectionString: process.env.DATABASE_URL!,
});
db.setVectorDimensions(embeddings.dimensions);
unwrap(await db.connect());

const search = new HybridSearch({
  embeddingAdapter: db,
  embeddingService: embeddings,
  keywordAdapter: db,
  defaultWeights: { bm25: 0.4, vector: 0.6 },
});

const results = unwrap(
  await search.search({
    query: 'How do agents use tools?',
    strategy: 'hybrid',
    limit: 10,
    filter: { sourceType: 'document' },
  })
);

for (const result of results) {
  console.log(`[${result.score.toFixed(3)}] ${result.content}`);
  console.log(
    `  vector: ${result.vectorScore?.toFixed(3)}, keyword: ${result.keywordScore?.toFixed(3)}`
  );
}

search() returns a MemoryResult<SearchResult[]>. Each result has id, sourceId, sourceType, content, score, metadata and, depending on which searches found it, vectorScore / keywordScore.

Search Strategies

You can switch between strategies per query:

// vector only
const vectorResults = await search.search({
  query: 'agent memory architecture',
  strategy: 'vector',
  limit: 5,
});

// keyword only
const keywordResults = await search.search({
  query: 'agent memory architecture',
  strategy: 'keyword',
  limit: 5,
});

// hybrid (combines both)
const hybridResults = await search.search({
  query: 'agent memory architecture',
  strategy: 'hybrid',
  limit: 5,
  weights: { bm25: 0.5, vector: 0.5 },
});

Constructor Options

Option	Type	Default	Description
`embeddingAdapter`	`EmbeddingAdapter`	—	Backend for vector search
`embeddingService`	`EmbeddingService`	—	Converts query text to vectors
`keywordAdapter`	`KeywordSearchAdapter`	—	Backend for keyword search (optional)
`defaultWeights`	`HybridSearchWeights`	`{ bm25: 0.4, vector: 0.6 }`	Default fusion weights

Search option	Description
`query`	Text to search for; embedded with `embeddingService` for vector search
`strategy`	`'vector'`, `'keyword'` or `'hybrid'`
`limit`	Max results (default 10)
`weights`	Overrides `defaultWeights` for this query
`threshold`	Minimum vector similarity, passed to the embedding adapter (Postgres and in-memory default to 0.7)
`filter`	`sourceType`, `agentId`, `threadId`, `userId` — passed to both adapters

When no keywordAdapter is provided, HybridSearch falls back to a built-in local BM25 index that you populate yourself:

const added = unwrap(
  await db.addEmbedding({
    sourceId: 'doc-1',
    sourceType: 'document',
    vector: await embeddings.embed('Agent memory architecture overview'),
    content: 'Agent memory architecture overview',
  })
);

search.indexDocument(added.id, added.content);
console.log(search.indexSize); // 1

search.removeDocument(added.id);
search.clearIndex();

Fusion matches results by id, so index each document under the id of its stored embedding — otherwise a document found by both searches is counted as two results. The local index ignores filter (a warning is logged) and reports every hit as sourceType: 'document' with sourceId equal to its id. PostgresAdapter and InMemoryEmbeddingAdapter implement KeywordSearchAdapter, so passing one as keywordAdapter avoids all of this.

BM25 Index

The BM25Index class implements the Okapi BM25 ranking algorithm for full-text keyword search. It tokenizes documents, builds an inverted index, and scores queries using term frequency and inverse document frequency.

import { BM25Index } from '@cogitator-ai/memory';

const index = new BM25Index({ k1: 1.5, b: 0.75 });

index.addDocument({ id: 'doc-1', content: 'Cogitator is an AI agent runtime' });
index.addDocument({ id: 'doc-2', content: 'Agents can use tools for external actions' });
index.addDocument({ id: 'doc-3', content: 'Memory adapters persist conversation history' });

const results = index.search('agent tools', 10);
for (const r of results) {
  console.log(`${r.id}: ${r.score.toFixed(3)} — ${r.content}`);
}

BM25 Parameters

Parameter	Type	Default	Description
`k1`	number	1.5	Term frequency saturation. Higher = more weight to repeated terms
`b`	number	0.75	Document length normalization. 0 = no normalization, 1 = full normalization
`tokenizer`	`TokenizerConfig`	—	Tokenizer options used for documents and queries

search(query, limit = 10) returns { id, content, score }[], best first. Terms are matched exactly after tokenization (no stemming), so agent does not match agents.

Document Management

index.addDocuments([
  { id: 'a', content: 'First doc' },
  { id: 'b', content: 'Second doc' },
]);

index.removeDocument('a');
index.getDocument('b'); // { id: 'b', content: 'Second doc' }
index.clear(); // removes all documents
console.log(index.size); // 0

Tokenizer

The BM25 index uses a configurable tokenizer that normalizes text before indexing and searching.

import { tokenize, getTermFrequency } from '@cogitator-ai/memory';

const tokens = tokenize('The quick brown fox jumps over the lazy dog', {
  lowercase: true,
  removeStopwords: true,
  minLength: 2,
});
// ['quick', 'brown', 'fox', 'jumps', 'over', 'lazy', 'dog']

const freq = getTermFrequency(tokens);
// Map { 'quick' => 1, 'brown' => 1, 'fox' => 1, ... }

Option	Type	Default	Description
`lowercase`	boolean	true	Convert text to lowercase
`removeStopwords`	boolean	true	Remove common English stop words
`minLength`	number	2	Minimum token length to keep

Reciprocal Rank Fusion

RRF merges ranked lists from different search methods into a single ranking. Each result's score is based on its rank position rather than raw score, which normalizes across different scoring scales.

The formula for each result:

RRF_score = weight * (1 / (k + rank + 1))

Where rank is the 0-based position in each list and k is a constant (default: 60) that dampens the contribution of lower-ranked results. A result's fused score is the sum over the lists it appears in.

import { reciprocalRankFusion, fuseSearchResults, type SearchResult } from '@cogitator-ai/memory';

const doc = (id: string, score: number): SearchResult => ({
  id,
  sourceId: id,
  sourceType: 'document',
  content: `Document ${id}`,
  score,
});

const vectorResults = [doc('a', 0.95), doc('b', 0.82)];
const keywordResults = [doc('b', 4.2), doc('c', 3.1)];

const fused = fuseSearchResults(vectorResults, keywordResults, { bm25: 0.4, vector: 0.6 });
// 'b' ranks high in both lists, so it gets the top combined score

The fuseSearchResults function preserves both individual scores on each result:

for (const result of fused) {
  console.log(result.id);
  console.log(`  combined: ${result.score}`);
  console.log(`  vector:   ${result.vectorScore}`);
  console.log(`  keyword:  ${result.keywordScore}`);
}

Low-Level RRF

For custom fusion scenarios, use reciprocalRankFusion directly. It takes any number of ranked lists (position in the array is the rank; only id is read), one weight per list (default 1), and returns a map of fused scores. Duplicate ids within one list count once:

const scores = reciprocalRankFusion(
  [
    [{ id: 'a' }, { id: 'b' }],
    [{ id: 'b' }, { id: 'c' }],
  ],
  [0.6, 0.4],
  { k: 60 }
);
// Map { 'a' => 0.00984, 'b' => 0.01623, 'c' => 0.00645 }

Tuning Weights

The balance between BM25 and vector search depends on your data:

Scenario	Recommended Weights
General knowledge retrieval	`{ bm25: 0.4, vector: 0.6 }`
Technical docs with exact terms	`{ bm25: 0.6, vector: 0.4 }`
Conversational / paraphrase-heavy	`{ bm25: 0.2, vector: 0.8 }`
Code search	`{ bm25: 0.7, vector: 0.3 }`

The HybridSearch class oversamples by 3x (fetches limit * 3 from each backend) before fusion, ensuring good candidate coverage for the final ranking.

Hybrid Search

Why Hybrid SearchCopy Anchor Link

HybridSearch ClassCopy Anchor Link

Search StrategiesCopy Anchor Link

Constructor OptionsCopy Anchor Link

BM25 IndexCopy Anchor Link

BM25 ParametersCopy Anchor Link

Document ManagementCopy Anchor Link

TokenizerCopy Anchor Link

Reciprocal Rank FusionCopy Anchor Link

Low-Level RRFCopy Anchor Link

Tuning WeightsCopy Anchor Link

On this page