🦦 ferret

Local-only multimodal file search. Point it at your directories and search text, images, PDFs, spreadsheets, presentations, and code with natural language. Everything runs on-device.

• Hybrid retrieval: BM25 keyword search fused with semantic vector search via RRF
• Multimodal: text embedder (bge-small, 384-d) + image embedder (MobileCLIP-S2, 512-d)
• Fast indexing: parallel extraction, batched GPU inference, SQLite WAL batching
• Web UI: Raycast-style command palette with live preview and highlighted matches
• Incremental: content-hash change detection; re-indexes only what changed
• OCR: PaddleOCR fallback for image files without machine-readable text

---

Install

Requires Python 3.12+. A CUDA-capable GPU is strongly recommended; CPU works but is slow.

pip install ferret-search           # CPU
pip install ferret-search[gpu]      # GPU (requires CUDA 12)

Usage

ferret index ~/Documents ~/Pictures ~/dev   # index paths
ferret search "notes on quantum computing"  # search from terminal
ferret serve                                # launch web UI at http://localhost:8765
ferret watch                                # watch for changes + keep models warm

Run ferret watch in the background to eliminate model load time from ferret search. The daemon holds the ONNX sessions in memory and serves queries over a Unix socket; without it, each search cold-loads the models (~1-3 s overhead).

Configuration

Config file at ~/.config/ferret/ferret.toml (respects $XDG_CONFIG_HOME):

roots = ["~/Documents", "~/Pictures", "~/dev"]

batch_size       = 256   # text chunks per GPU batch
image_batch_size = 32    # images per GPU batch
top_k            = 10
rrf_k            = 60    # RRF rank-fusion constant

Data is stored under standard XDG directories:

Development

git clone https://github.com/burntcarrot/ferret && cd ferret
uv sync
cd src/ferret/frontend && pnpm install && pnpm build && cd ../../..
uv run ferret index ~/Documents
uv run ferret serve
uv run pytest

See the internals docs for pipeline, retrieval design, and data model details.

License

MIT