What is native hybrid search in Weaviate?

Native hybrid search is Weaviate running keyword BM25 and vector similarity in one query path, then fusing the two ranked lists into a single answer set. You do not glue two clients together after the fact. The database owns both legs and the merge. That matters for agent memory because real questions mix paraphrase with exact tokens. This chapter explains how Weaviate’s hybrid operator works, what alpha and fusion change in the ranking, when to prefer hybrid over pure vector or pure BM25, and how Weaviate Engram exposes that native capability as HybridRetrieval for everyday memory recall.

What Makes Hybrid Search “Native” in Weaviate?

Hybrid is not a marketing label for “we have two indexes.” It is a first-class search operator. On each hybrid request Weaviate embeds the query for dense search, runs BM25 over the inverted index for sparse search, and merges the results with a chosen fusion method. Both searches see the same objects. Filters and tenancy rules apply inside the engine. Your application receives one ordered list with combined scores.

That design removes a common failure mode in hand-rolled stacks. Teams that fetch top-k vectors in one system and top-k keywords in another often disagree on ids, score scales, and filter semantics. Native hybrid keeps those decisions consistent. For agent memory, consistency means a preference note and a ticket id can compete fairly in the same ranking without custom merge code on every turn.

The next question is how the merge actually treats those two different score worlds.

How Do Alpha and Fusion Shape the Final Ranking?

Alpha sets the blend between vector and keyword influence. At zero, hybrid collapses to pure BM25. At one, it collapses to pure vector search. At one half, both sides weigh evenly. Weaviate’s common default sits near three quarters toward vectors when alpha is left at the server default, which favors semantic recall while still letting strong keyword hits contribute. Tune toward keywords when operators hunt codes and citations. Tune toward vectors when users speak vaguely.

Fusion decides how ranks become comparable. Ranked fusion scores objects by position in each list, then adds those rank-based scores. Relative score fusion normalizes each side so the best raw score becomes one and the worst becomes zero, then combines the scaled values. Relative score fusion is the modern default because it keeps magnitude information. A memory that crushed BM25 by a wide margin can outrank a cluster of near-tied vector neighbors. Ranked fusion throws that gap away and only keeps order.

Those knobs matter most when query shape matches how people actually ask agents for help.

Why Is Hybrid the Default Starting Point for Agent Memory?

Agent queries are messy. One turn says “the cold soak rule for vine row C4.” Another says “how long should we leave those Cabernet clusters wet after rain.” The first needs an exact row token. The second needs semantic reach. Hybrid boosts results that win on either path. That robustness is why Engram documents hybrid as the recommended retrieval type for most searches, with vector and BM25 available when the question is clearly one-sided.

Hybrid still costs two searches under the hood. For high-throughput paths that only ever match SKUs strings, BM25 alone can be cheaper and clearer. For similarity-only recommendations with no text query, vector search is the honest choice. For the mixed, typo-prone language of chat, start hybrid. Measure with a small gold set of memory questions before you chase exotic alpha values. A static middle blend often survives distribution shift better than a brittle optimum.

Weaviate Engram is how most products should consume that native hybrid path.

How Does Weaviate Engram Surface Hybrid Without Exposing Cluster Knobs?

Engram’s search API accepts a retrieval_config. Pass HybridRetrieval with a limit, or the string "hybrid". Engram routes into Weaviate-backed hybrid retrieval for that project. You keep scopes with user_id, groups, topics, and properties. You do not wire alpha in the chat loop unless you later operate raw Weaviate collections beside Engram. The product default stays simple: add memories asynchronously, wait when freshness matters, search with hybrid for ordinary turns.

Switch to BM25Retrieval when support staff paste exact error strings. Switch to VectorRetrieval when the user describes a feeling or a goal with no stable tokens. Keep hybrid for the unpredictable middle. That selection framework mirrors Weaviate’s own guidance for user-facing search, now applied to personal and procedural memory.

Here is a vineyard assistant storing a row note, then recalling it with Engram hybrid search so both the rain-soak idea and the exact row id can score.

import os
from engram import EngramClient
from engram.types import HybridRetrieval

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
user_id = "viticulturist-oma"
group = "vineyard_ops"

run = client.memories.add(
    "Vine row C4 (vine-row-c4): after heavy rain Oma waits 36 hours before "
    "leaf pulling on Cabernet so berry skins dry and mildew pressure drops. "
    "Do not irrigate C4 the same day as a canopy thin.",
    user_id=user_id,
    group=group,
    properties={"row_id": "vine-row-c4"},
)
client.runs.wait(run.run_id)

results = client.memories.search(
    query="How long after rain before leaf pulling on vine row C4?",
    user_id=user_id,
    group=group,
    properties={"row_id": "vine-row-c4"},
    retrieval_config=HybridRetrieval(limit=5),
)
for memory in results:
    print(memory.content)

The query pairs a natural-language timing question with a hard row identifier. Native hybrid lets BM25 lock the id while vectors connect “after rain” to the stored wait rule. Engram returns the fused list your prompt needs.

Operations still benefit from knowing what sits under that one config line.

What Should You Verify When Hybrid Results Feel Off?

If exact codes never surface, inspect whether the memory text actually contains those tokens, then try BM25 alone as a diagnostic. If paraphrases never surface, confirm the pipeline finished with runs.wait and try vector alone. If rankings feel random across near-duplicates, check whether you are comparing scores across different fusion eras or client defaults that unset alpha differently. Relative score fusion plus an explicit alpha on raw Weaviate queries removes that ambiguity when you operate the database directly.

Keep evaluation grounded. Build a tiny set of agent questions with expected memory ids. Run hybrid, vector, and BM25. Prefer the mode that hits the right memory most often under your real wording. Native hybrid usually wins that bake-off for chatty products. Weaviate Engram makes that win the default without forcing every agent author to become a search engineer.

Native hybrid search is Weaviate’s built-in merge of BM25 and vectors with alpha and fusion under explicit control. Weaviate Engram turns that into a one-line HybridRetrieval choice for agent memory. Our next chapter, How does multi-tenancy work as Weaviate’s isolation primitive?, shifts from ranking mechanics to how Weaviate isolates each tenant’s data so hybrid recall stays private at scale.