Search

The search tool is the core of vibe-hnindex. It lets AI assistants find code using keyword matching, semantic understanding, or both combined.

Search Modes

Basic Usage

search(
  query: "authentication middleware",
  project_name: "my-app",
  mode: "hybrid",
  limit: 10
)

Keyword Mode

Uses SQLite FTS5 full-text search with BM25 scoring. Best for exact symbols, function names, and identifiers.

search(
  query: "UserService",
  project_name: "my-app",
  mode: "keyword"
)

Semantic Mode

Uses Qdrant vector search with Ollama embeddings. Best for natural language queries where you don't know the exact function name.

search(
  query: "how does the app handle user login",
  project_name: "my-app",
  mode: "semantic"
)

Hybrid Mode

Combines keyword and semantic search using Reciprocal Rank Fusion (RRF):

score(chunk) = 1/(60 + rank_keyword) + 1/(60 + rank_semantic)

Chunks appearing in both lists get higher combined scores.

Auto Mode

Let the server pick the best mode based on query shape. Short path-like queries lean keyword; longer question-like queries lean hybrid.

search(
  query: "authentication middleware",
  project_name: "my-app",
  mode: "auto"
)

Enable auto-routing by default: set SEARCH_AUTO_ROUTE=true in your MCP env.

Regex Search (v0.8.0+)

Search using JavaScript regex patterns with /pattern/flags syntax:

// Find all useState calls
search(query: "/useState\\(.*\\)/", project_name: "my-app", mode: "regex")

// Find TODOs, FIXMEs, HACKs
search(query: "/TODO|FIXME|HACK/g", project_name: "my-app", mode: "regex")

• Pattern wrapped in /pattern/flags — flags are optional (default i)
• Supports all standard JS regex flags: g, i, m, s, u, y
• Auto-detection: when mode is auto and query looks like /.../, regex mode is selected
• Matches are highlighted with **text** in output
• Results sorted by match count descending

Symbol Filters (v0.8.0+)

Filter results to files containing specific symbol types:

search(query: "authentication", project_name: "my-app", symbol_kind: "class")
search(query: "handler", project_name: "my-app", symbol_kind: "function")
search(query: "UserData", project_name: "my-app", mode: "symbol", symbol_kind: "interface")

Search Tips

• Narrow file_pattern and limit on the first pass
• Use keyword when you know exact symbols
• Set dedupe_by_file: false only when you need multiple chunks from the same file
• Use explain: true for a per-result score breakdown (path multiplier, RRF ranks)

Fuzzy Search (v0.8.1+)

Boost results using Levenshtein distance for approximate string matching — useful for misspelled queries or finding similar identifiers.

search(query: "authentication midleware", project_name: "my-app", fuzzy: true)
search(query: "fucntion handleReq", project_name: "my-app", fuzzy: true)

Enable globally: SEARCH_FUZZY_ENABLED=true.

Streaming Search (v0.9.0+)

Runs keyword + semantic in parallel for ~1.5-2× faster hybrid search:

search(query: "authentication", project_name: "my-app", stream: true)

Enable globally: SEARCH_STREAM_ENABLED=true. Provides 4-phase progress notifications and early result preview via MCP logging.

Search Cache (v0.8.0+)

Results are cached with LRU eviction and 5-minute TTL. Cache key includes project name, query, mode, limit, and filters. Automatically invalidated on re-index. Not used for regex mode.

Rerank

After retrieval, results can be reordered. Without RERANK_URL, Qdrant semantic scores are used. With RERANK_URL, results are sent to your custom HTTP endpoint. See Configuration → Optional Rerank.