fsearch

Natural-language file search, powered locally by Google's embeddinggemma-300m embedding model. Indexes file contents (and falls back to filename/path for binaries) into a local vector store, then lets you search with plain English.

Setup

embeddinggemma-300m is a gated model on Hugging Face — you must accept the license once and authenticate locally before first use:

1. Accept the license at https://huggingface.co/google/embeddinggemma-300m

2. Authenticate: huggingface-cli login (or set HF_TOKEN in your environment)

3. Install:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .

The model weights (~1.2GB) are not bundled with this repo — fsearch downloads and caches them automatically from Hugging Face the first time it needs the model. If you haven't completed steps 1–2, that first run fails with a clear error telling you what to do.

Usage

# Index your home directory (default), or scope to specific roots
fsearch index
fsearch index --root ~/Documents --root ~/Projects

# Re-index everything from scratch, ignoring the unchanged-file cache
fsearch index --full

# Search file contents (semantic, uses the embedding model)
fsearch search "budget spreadsheet from last quarter"
fsearch search "that PDF about tax deductions" --limit 5

# Search file names/paths only — plain substring match, no embedding model
fsearch search "indexer" --name

# View or edit config (indexed roots, excludes, max file size)
fsearch config show
fsearch config edit

All state lives under ~/.fsearch/ (config, SQLite metadata, Chroma vector store). Re-running fsearch index is incremental — only changed files are re-embedded.

Indexing a full home directory on a 300M-parameter model can take a while, especially on CPU. It's recommended to scope your first run with --root to a smaller directory.

Content search only returns matches with cosine similarity >= 0.4 — low- confidence noise is dropped rather than shown as a top hit. Empty queries are rejected.