vault-search

Hybrid search MCP server for Obsidian vaults. Combines BM25 keyword matching, fuzzy title search, and vector semantic search with Reciprocal Rank Fusion (RRF) into a single ranked result set. Embeddings run locally in-process via ONNX (no API key needed) or via any OpenAI-compatible API. Features layered config (~/.vault-search/config.json, VS_ env vars, CLI flags), rate-limited embeddings, full CLI, dual MCP transport (stdio for Claude Desktop/Cursor, HTTP/SSE for Docker), and smart chunking strategies.

---

• Hybrid search with RRF fusion — BM25 + fuzzy title + vector semantic search merged via Reciprocal Rank Fusion
• ONNX embeddings by default — runs nomic-ai/modernbert-embed-base in-process via ONNX Runtime; no API key needed
• API embedding support — works with any OpenAI-compatible API: Ollama, LiteLLM, OpenAI, OpenRouter
• Layered config system — ~/.vault-search/config.json, VS_* env vars, and CLI flags with full precedence control
• Generic frontmatter filter — --filter key=value filters by any indexed frontmatter field (configured via VS_FILTER_FIELDS)
• Rate-limited embeddings — token bucket rate limiter with adaptive backoff; never hammers the embedding API
• Multi-model embedding support — switch models at any time; per-model vector tables in a single SQLite DB
• Container-native — Dockerfile with multi-stage build, Docker health endpoint (/healthz), and JSON status endpoint (/status)
• Full CLI — search, read, reindex, status, embedding management, config inspection
• Dual MCP transport — stdio for local clients (Claude Desktop, Cursor), HTTP/SSE for remote/Docker deployments
• Smart chunking — auto mode selects whole-doc or heading-based chunking per note; sliding window fallback
• Frontmatter injection — configurable frontmatter fields prepended to each chunk for richer embeddings
• Query embedding cache — repeated queries skip the embedding API entire