Docs · BYOK embeddings
Bring your own embeddings key
RepoOps’ Ask the brain ranker uses a two-layer ladder: a fast BM25 lexical pass against your local brain markdown, then a cosine re-rank using embedding vectors. The vector half runs by default on a keyless on-device model (Xenova/all-MiniLM-L6-v2, fetched once on first use, then offline). Bring your own key to swap it for a hosted provider: Voyage, OpenAI, and OpenRouter, called directly from your machine. If neither is available, Ask ranks on BM25 alone.
Why two layers
BM25 is fast, deterministic, and works without any API call - which means it works on the airplane, on a fresh checkout, and when your provider is down. Vector cosine catches the semantic matches BM25 misses (“deploy” ↔ “ship”, “auth” ↔ “login”). When both layers agree the row floats to the top. When the embeddings call fails we fail soft - Ask still returns the BM25 ranking, with a small chip on the sidebar noting the fallback.
When to pick Voyage vs OpenAI
- Voyage - an embeddings-only vendor, generally stronger on technical content. RepoOps calls
voyage-3. Check the current rate and free-tier terms on Voyage’s pricing page before you commit. - OpenAI - you probably already have a key, and
text-embedding-3-smallis good enough for the re-rank. Pick this if you don’t want another vendor account. Rates are on OpenAI’s pricing page.
Getting an API key
- Voyage: docs.voyageai.com generate key. Format:
pa-.... - OpenAI: platform.openai.com/api-keys create. Format:
sk-....
Setting the key in RepoOps
- Open the localhost dashboard at
http://localhost:4000/. - Manage Settings Embeddings.
- Pick a provider; paste the key; click Test connection.
- Done. The chip on Ask the brain’s sidebar flips from “BM25 only” to “Voyage” / “OpenAI”.
The key lives in the data-dir .env(%APPDATA%\repo-dashboard\.env on Windows, ~/.repo-dashboard/.env elsewhere). It survives upgrades. It never leaves your machine.
Fail-soft contract
If the embeddings call errors, times out, or rate-limits, Ask returns the BM25 ranking without prompting. The sidebar chip shows the fallback (“BM25 only”) plus the upstream error. Re-running the query retries the embeddings layer; nothing is cached as broken.
Disk cache
Embedding vectors are cached on disk per repo mirror in <mirrorDir>/.brain-embedding-cache.json, keyed on the corpus SHA plus the provider and model. A provider or model swap invalidates cleanly without a manual purge. Cache TTL is unlimited - embeddings of the same brain text are stable for the same model.
Remove a key
Settings Embeddings Remove. Or hand-edit the data-dir .env. The process unsets immediately without a restart.