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 an optional cosine re-rank using embedding vectors. The embeddings layer is BYOK - your provider, your key, called directly from your machine. Voyage and OpenAI are the two supported providers at launch.
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 - purpose-built embeddings vendor; higher quality on technical content; cheaper per token at the relevant scale (~$0.02 per 1M tokens for
voyage-3). Sign-up is fast and doesn’t require a payment method for the free tier. - OpenAI - you probably already have a key; quality is fine; price is higher (
text-embedding-3-smallat ~$0.13 per 1M tokens). Pick this if you don’t want another vendor account.
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 under .claude/brain/.vector-cache/ keyed by (provider, model, sha256(text)). A provider/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.