notelight

Private semantic search over your own files, for you and your AI agents. A Rust retrieval engine with a Python interface, a CLI, and an MCP server, with retrieval quality you can measure. How it works walks through the design end to end in a few minutes. Try it in your browser: the same Rust core as WebAssembly. Index a folder of your own notes (Markdown, text and PDF) or search this repository’s docs, entirely on your machine: files never leave the browser, and the only download is the 127 MiB model, once.

Status: 0.2.0, alpha. You can index a folder of notes, search it from the command line or from Claude, Cursor and other AI agents over MCP or in your browser, include PDF and DOCX files, and measure retrieval quality on public benchmarks (results). See the roadmap and the changelog.

Why

Tools that let you “chat with your files” usually need a server, an account, or an upload. notelight keeps everything on your machine:

• Hybrid retrieval. BM25 plus quantized embeddings, fused with Reciprocal Rank Fusion, so both exact names and paraphrased questions work. Quote a phrase ("lock file") to put exact matches first.
• Agent-ready. An MCP server lets Claude, Copilot or Cursor search your notes and cite path:line.
• Measured. notelight eval reports recall@10, nDCG@10 and MRR@10 on BEIR datasets and on a labelled benchmark of note-style queries, for every quantization setting, not just anecdotes.
• Private. No telemetry, and no network after a one-time model download.

Usage

Install it from PyPI (Python 3.10+), ideally into a virtual environment or with pipx install notelight:

pip install notelight

There are prebuilt wheels for Linux (x86_64 and aarch64, glibc 2.28+), Windows (x64) and macOS (Apple silicon and Intel), so you do not need Rust. Two limits come from ONNX Runtime, which runs the embedding model: on Intel Macs use Python 3.10 to 3.13, and Alpine and other musl-based Linux