vault-index

Local hybrid search for markdown vaults and codebases, served as an MCP server. Keyword search (SQLite FTS5) and vector search (sqlite-vec, bge-small-en-v1.5 on CPU) are merged with reciprocal rank fusion, then a small cross-encoder (ms-marco-MiniLM-L-6-v2) reorders the top 10. Everything lives in one SQLite file on your machine; no cloud services.

Part of claude-second-brain, where every search change is measured against golden question sets and compared with naive grep and basic-memory (see its README for the numbers).

Use with Claude Code

claude mcp add vault-index -- uvx --python 3.12 vault-index

Then ask Claude to index a folder, for example: "index_paths ~/notes". After that, search_notes finds paraphrased answers with file path and heading. The first run downloads the two models (about 65 MB and 80 MB).

From a terminal

uvx --python 3.12 vault-index index ~/notes      # index a folder (progress on stderr); no paths re-syncs all
uvx --python 3.12 vault-index search "why did the probe fail"
uvx --python 3.12 vault-index --help

With no command it serves MCP over stdio. Indexing a large vault from the terminal first keeps the first tool call short.

Tools

• index_paths(paths, reindex=False): add folders or files as sources and sync them. With no paths, re-syncs every source (new, changed and deleted files).
• search_notes(query, limit=8, path_prefix=None): hybrid search; returns chunks with file path and heading path.
• get_note(path): full text of an indexed file.
• list_sources(), remove_source(path).

Markdown is chunked by heading. A .indexignore in a source folder lists relative paths to skip.

Settings

Python 3.10 to 3.13 (--python 3.12 keeps uvx off newer Pythons that onnxruntime does not support yet). MIT license.