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 when a provider is available. The lightweight desktop uses BM25 without a model download. Development or archive builds can include the optional local embedding libraries. Bring your own key to add a hosted provider: Voyage, OpenAI, and OpenRouter, called directly from your machine. If no vector provider is available, Ask ranks on BM25 alone.
Want to improve a search now? Start in Ask the brain, then return here when you want to add vector ranking with a hosted provider.
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.
Choosing a hosted provider
- 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. - OpenRouter - use one OpenRouter key to route the request to
openai/text-embedding-3-large. RepoOps requests 1,536 dimensions and records returned usage for the query.
Getting an API key
- Voyage: docs.voyageai.com generate key. Format:
pa-.... - OpenAI: platform.openai.com/api-keys create. Format:
sk-.... - OpenRouter: openrouter.ai authentication, then create a key. Format:
sk-or-....
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”, or “OpenRouter”.
The key lives in the data-dir .env(%APPDATA%\repo-dashboard\.env on Windows, ~/.repo-dashboard/.env elsewhere). It survives upgrades. RepoOps sends it directly to the provider you selected to authenticate embedding requests; it is not sent to RepoOps hosted services.
Fail-soft contract
If the embeddings call errors, times out, or rate-limits, Ask returns the BM25 ranking without prompting. The Vector chip in the signal row stays unlit for that query; the upstream error goes to the server’s stdout, not the page. 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.
Read next: Ask the brain or Settings.