hybrid-search-implementation

★ 37,559

by wshobson · part of wshobson/agents

Combine vector and keyword search for improved retrieval. Use when implementing RAG systems, building search engines, or when neither approach alone provides sufficient recall.

🧩 One of 7 skills in the wshobson/agents package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Hybrid Search Implementation

Patterns for combining vector similarity and keyword-based search.

When to Use This Skill

Building RAG systems with improved recall
Combining semantic understanding with exact matching
Handling queries with specific terms (names, codes)
Improving search for domain-specific vocabulary
When pure vector search misses keyword matches

Core Concepts

1. Hybrid Search Architecture

Query → ┬─► Vector Search ──► Candidates ─┐
        │                                  │
        └─► Keyword Search ─► Candidates ─┴─► Fusion ─► Results

2. Fusion Methods

Method	Description	Best For
RRF	Reciprocal Rank Fusion	General purpose
Linear	Weighted sum of scores	Tunable balance
Cross-encoder	Rerank with neural model	Highest quality
Cascade	Filter then rerank	Efficiency

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Tune weights empirically - Test on your data
Use RRF for simplicity - Works well without tuning
Add reranking - Significant quality improvement
Log both scores - Helps with debugging
A/B test - Measure real user impact

Don'ts

Don't assume one size fits all - Different queries need different weights
Don't skip keyword search - Handles exact matches better
Don't over-fetch - Balance recall vs latency
Don't ignore edge cases - Empty results, single word queries