---
feature_pitch: ZeroEntropy zembed-1 embeddings + zerank-2 cross-encoder reranking
required_action: no  # purely opt-in
---

# v0.35.0.0 migration notes

ZeroEntropy support landed. **No required user action.** Reranker is on by
default for `tokenmax` mode only; embedding model is unchanged for everyone
unless the user explicitly opts 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 can do (optional)

### Try zembed-1 embeddings

Switching embedding models invalidates the vector index — you'll need to
re-embed. Edit `~/.gbrain/config.json`:

```json
{
  "embedding_model": "zeroentropyai:zembed-1",
  "embedding_dimensions": 2560
}
```

Valid dims: 2560, 1280, 640, 320, 160, 80, 40 (Matryoshka-style; smaller
trades quality for storage). Then:

```bash
export ZEROENTROPY_API_KEY=...
gbrain models doctor                  # verify config
gbrain embed --stale --limit 50       # smoke a small re-embed
gbrain embed --stale                  # full re-embed
```

### Try zerank-2 on conservative/balanced

```bash
export ZEROENTROPY_API_KEY=...
gbrain config set search.reranker.enabled true
gbrain models doctor                  # verify reranker_config + reachability
gbrain query "some query that previously misranked"
```

To opt out:
```bash
gbrain config set search.reranker.enabled false
```

### Opt out of reranker on tokenmax

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

```bash
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).