vector-hybrid-search

name	vector-hybrid-search
skill_type	skill
description	Retrieve knowledge from a vector-store collection via the vector-mcp MCP server's vector_search tool — semantic (ANN) search, lexical BM25 search, or a hybrid of the two fused with Reciprocal Rank Fusion. Use when the agent must answer a question from an indexed corpus, pull top-k relevant chunks for RAG context, or tune the semantic-vs-lexical balance of retrieval. Do NOT use for creating collections or ingesting documents (use vector-collection-management) or for backend connection setup (vector-backend-operations).
license	MIT
tags	["vector","rag","search","semantic","bm25","hybrid","mcp"]
metadata	{"author":"Genius","version":"0.1.0"}

Vector Hybrid Search

Retrieval over vector-store collections through the vector-mcp MCP server. One condensed tool exposes three retrieval strategies: dense semantic search, sparse lexical BM25 search, and a hybrid that fuses both rankings.

When to use

• Answer a natural-language question from an indexed corpus (grab RAG context).
• Fetch the top-k most relevant chunks for a query.
• Do keyword/term-exact retrieval where BM25 beats embeddings (codes, IDs, rare tokens).
• Balance recall (semantic) against precision on exact terms (lexical) via hybrid fusion.

When NOT to use

• Creating / populating / deleting collections → vector-collection-management.
• Selecting or configuring the backend engine → vector-backend-operations.
• General web search or KG queries — this only searches the named collection.

Prerequisites & environment

Connect via the mcp-client skill against the vector-mcp MCP server. The collection must already exist and be populated (see vector-collection-management). Connection params (db_type, db_path, host/port, db_name, username, password, collection_name) are passed inline, matching the collection you want to query.

Tools & actions

Condensed tool	Actions
vector_search	semantic_search, lexical_search, search (hybrid)

Key parameters

• question — the query text (required for every action).
• number_results — top-k to return.
• semantic_weight / bm25_weight — leg weights for the hybrid search action.
• rrf_k — the Reciprocal Rank Fusion constant that merges the two rankings.

Recipes

Semantic (vector) search:

{"action":"semantic_search","db_type":"chromadb","db_path":"./chroma","collection_name":"handbook","question":"how do I connect to the VPN?","number_results":5}

Lexical BM25 search (term-exact):

{"action":"lexical_search","db_type":"chromadb","db_path":"./chroma","collection_name":"handbook","question":"gw-hq","number_results":5}

Hybrid search, semantic-leaning fusion:

{"action":"search","db_type":"chromadb","db_path":"./chroma","collection_name":"handbook","question":"vpn gateway hostname","number_results":8,"semantic_weight":0.7,"bm25_weight":0.3,"rrf_k":60}

Gotchas

• question is required; an empty/missing question returns nothing useful.
• Results carry a score whose meaning depends on the action — semantic returns a distance (lower = closer), BM25 a relevance score (higher = better), hybrid a fused RRF score; don't compare scores across actions.
• Hybrid weights are only honored by the search action; they're ignored by the pure semantic_search / lexical_search actions.
• A typical rrf_k is 60; smaller rrf_k sharpens toward top ranks, larger flattens the fusion.
• Retrieval only covers the specified collection_name on the specified backend — point the connection params at the collection you actually populated.

Related

• vector-collection-management — build and load the collections you search here.
• vector-backend-operations — backend/engine selection and connection tuning.