feature_pitch: "HISTORICAL: ZeroEntropy zembed-1 embeddings + zerank-2 reranking (provider retired 2026-09-04)" required_action: no # purely opt-in

v0.35.0.0 migration notes

HISTORICAL — DO NOT FOLLOW. Do not execute any command in this file. ZeroEntropy's hosted API shuts down 2026-09-04; the opt-in config edits and commands below would strand a brain on a dead provider. To LEAVE ZeroEntropy, follow skills/migrations/v0.46.3.0.md.

ZeroEntropy support landed (historical record). No required user action. Reranker was on by default for tokenmax mode only; the embedding model was unchanged for everyone unless the user explicitly opted in via config file or env var.

What changed automatically

KNOBS_HASH_VERSION bumped 1 → 2 to fold reranker config into the query_cache.knobs_hash column. Expect a temporary cache hit-rate dip for ~1 hour (the default cache.ttl_seconds) as v=1 rows TTL out and v=2 rows backfill. Search still works during the dip; only cache hits are affected.
tokenmax mode now defaults search.reranker.enabled = true. If the user has ZEROENTROPY_API_KEY set AND uses tokenmax, reranker fires. Without the API key, the rerank attempt fails-open (audit-logged) and search returns the RRF order — same UX as before, just with an observable failure in gbrain doctor.
conservative and balanced modes default reranker = false. Nothing changes for those users without an explicit opt-in.

What the user could do at the time (historical — do not run any of this)

The zembed-1 opt-in (era recipe, now a strand-your-brain trap)

The era's opt-in was a config-file edit pointing embedding_model at zeroentropyai:zembed-1 (valid Matryoshka dims: 2560, 1280, 640, 320, 160, 80, 40), followed by a key export and a staged re-embed (gbrain models doctor, a small --stale smoke, then the full pass). Running that today points a brain at an API that dies 2026-09-04 — the maintained path is the off-ramp in skills/migrations/v0.46.3.0.md.

The zerank-2 opt-in on conservative/balanced (era recipe)

The era's opt-in was search.reranker.enabled true with a ZE key set, verified via gbrain models doctor. Enabling reranking TODAY should set the surviving model first: gbrain config set search.reranker.model voyage:rerank-2.5, then enable.

Opt out of reranker on tokenmax

If you're on tokenmax mode and don't want reranker spend:

gbrain config set search.reranker.enabled false

The override sticks above the mode bundle default.

Diagnostics

gbrain models doctor --json — probes embedding_config, reranker_config, and reranker reachability. Surfaces config issues with paste-ready fix hints.
gbrain doctor — runs reranker_health against the JSONL audit at ~/.gbrain/audit/rerank-failures-YYYY-Www.jsonl. Auth failures warn immediately; transient failures warn at >=5 in 7 days.
tail -100 ~/.gbrain/audit/rerank-failures-*.jsonl — raw failure log for direct inspection (privacy: query text is SHA-256 hashed; never raw).