Retrieval modes
Knowledge Hub is an Early Access release. Refer to the Early Access disclaimer for details.
Knowledge Hub supports three retrieval modes: Semantic, Lexical, and Hybrid. The mode controls how Knowledge Hub searches the index when an agent submits a query. You set the default mode at the Knowledge Base level, and agents can override it per query.
Semantic mode
Semantic mode converts the query into a vector and finds the chunks in the index whose embeddings are closest by mathematical distance. It matches on meaning rather than exact wording.
Use Semantic mode when:
- Queries are natural-language questions (for example, "What is the return policy for enterprise contracts?")
- The query and the relevant content may use different vocabulary
- You want tolerance for paraphrasing, synonyms, and different phrasing of the same concept
Limitations:
- Semantic mode can return results that are topically related but not directly relevant if the indexed content is sparse or poorly chunked.
- It performs less well on exact identifiers such as product codes, error codes, and part numbers, because these have low semantic similarity to natural-language queries.
Lexical mode
Lexical mode performs a keyword search. It matches chunks that contain the exact terms in the query and ranks them by term frequency and relevance.
Use Lexical mode when:
- Queries contain specific identifiers: error codes, product names, version numbers, SKUs (stock keeping units)
- Exact wording matters and approximate meaning-based matches would be misleading
- The indexed content is highly structured with known terminology
Limitations:
- Lexical mode returns empty results if the query terms do not appear in the index, even if semantically equivalent content exists.
- It does not handle synonyms, acronym expansion, or natural-language variation well.
Hybrid mode
Hybrid mode runs both Semantic and Lexical searches in parallel and merges the results using a weighted scoring algorithm. It is the recommended default for most Knowledge Bases.
Use Hybrid mode when:
- You are unsure which mode is better for your content and query patterns
- Queries mix natural-language questions with specific identifiers
- You want both Semantic tolerance for varied phrasing and Lexical precision for exact terms
How merging works: Knowledge Hub scores each chunk from both the semantic and lexical passes, then combines the scores using a reciprocal rank fusion algorithm. The merged ranking reflects both meaning-based and keyword-based relevance.
Choosing a mode
The following table summarises when to use each mode:
| Scenario | Recommended mode |
|---|---|
| Conversational or natural-language queries | Semantic |
| Technical queries with exact codes or identifiers | Lexical |
| General-purpose Knowledge Base serving varied queries | Hybrid |
| Agent is getting too many off-topic results and lacks precision | Lexical |
| Agent is getting empty results for natural-language questions | Semantic or Hybrid |
Changing the retrieval mode
The default retrieval mode is set on the Knowledge Base. To update the retrieval settings, refer to Configuring retrieval settings. Changes to the default mode apply to all subsequent queries that do not specify an override.
Agents that call the Knowledge Hub retrieval API can pass a mode parameter to override the Knowledge Base default for a specific query. This lets a single Knowledge Base serve different query types from different agents without changing the configuration.
