---
name: v0.36.2.0
version: 0.36.2.0
headline: ZeroEntropy is the new default for embedding + reranker
---

# v0.36.2.0 Migration: ZeroEntropy as default

**TL;DR:** v0.36.2.0 makes ZeroEntropy (`zembed-1` at 1280d via Matryoshka, `zerank-2` cross-encoder reranker) the default retrieval stack. Real-corpus benchmark says: 2.2× faster than OpenAI, 2.6× cheaper at regular pricing, wins 11/20 head-to-head queries, reranker reshuffles 60% of top-1 results. New installs land on it automatically. Existing brains see a one-shot upgrade prompt with a cost estimate; default-on-Enter is "stay on current provider" so the safe path is the no-action path.

This migration is **opt-in for existing brains**. Running `gbrain upgrade` does not silently re-embed your data. The prompt is TTY-only; non-TTY upgrades (CI, cron, docker) print an informational stderr line and skip the switch.

## What the agent should do post-upgrade

When the user invokes any gbrain command immediately after `gbrain upgrade` to v0.36.2.0:

1. **Check whether the prompt has been surfaced yet.** `gbrain ze-switch --dry-run --json` shows the planner state including `ze_switch_offered`, `ze_switch_prompt_shown`, and the comparison numbers. If `ze_switch_offered` is true and `ze_switch_prompt_shown` is false, the user hasn't seen the prompt yet.

2. **Surface the comparison numbers.** Quote the benchmark from the prompt:
   - Wins 11/20 queries head-to-head (OpenAI 6, Voyage 4)
   - 442ms avg vs OpenAI 973ms (2.2× faster)
   - $0.05/M tokens vs OpenAI $0.13 (2.6× cheaper at regular pricing)
   - zerank-2 reshuffles 60% of top-1 results
   - Only 10-18% overlap between providers — pairing primary + reranker compounds

3. **Recommend switching** unless the user has stated a constraint that makes ZE unsuitable (no internet, regulatory concern with a specific provider, contractual commitment to another stack). When recommending, point them at:
   ```bash
   gbrain ze-switch              # interactive prompt
   gbrain ze-switch --dry-run    # see the plan without applying
   ```

4. **If the user already declined** (`ze_switch_already_declined` true) and they ask about it later, mention `gbrain ze-switch --force` re-opens the prompt. The 90-day decline window auto-resets after that, so a year-later contributor "we have better benchmarks now" data gets surfaced naturally.

5. **If the user switched and now regrets it**, mention `gbrain ze-switch --undo`. Restores their prior model + dim + reranker state with a symmetric cost-warning prompt (re-embedding back is also a real cost).

## The CLI surface in full

| Command | Effect |
|---|---|
| `gbrain ze-switch` | Interactive prompt (TTY only). Default-on-Enter = stay. |
| `gbrain ze-switch --dry-run` | Print plan as text. Change nothing. |
| `gbrain ze-switch --dry-run --json` | Machine-readable envelope: `{status, plan}`. |
| `gbrain ze-switch --non-interactive` | Switch without prompting. Errors if `ZEROENTROPY_API_KEY` missing. |
| `gbrain ze-switch --non-interactive --ignore-missing-key` | Same, but stage the schema change before the key is ready. Embeddings fail loud until key arrives. |
| `gbrain ze-switch --resume` | Complete a half-applied switch (crash recovery). |
| `gbrain ze-switch --force` | Bypass the prompt-shown gate (re-show after `n`). |
| `gbrain ze-switch --undo` | Reverse with cost-warning prompt. |
| `gbrain ze-switch --undo --non-interactive --confirm-reembed` | Scripted undo. The `--confirm-reembed` flag is required (un-doing also pays for re-embed). |

## Consolidation with the v0.32.7 chunker prompt

If a brain has BOTH a stale chunker version AND the ZE-switch offered, the `RetrievalUpgradePlanner` consolidates into ONE prompt + ONE re-embed pass. The user is not double-charged. This was a real bug class the original cutover plan had; codex outside-voice review caught it before implementation.

## Doctor checks added in v0.36.2.0

`gbrain doctor` now runs two new ZE-aware checks:

- **`ze_embedding_health`** — warns if `embedding_model` starts with `zeroentropyai:` but no key is configured (neither env nor `gbrain config set zeroentropy_api_key`). Fix hint points at the setup URL.
- **`embedding_width_consistency`** — asserts the configured `embedding_dimensions` matches the actual `vector(N)` width on `content_chunks.embedding`. Warns on drift. Fix hint suggests `gbrain ze-switch --resume` if drift came from a half-applied switch, or `gbrain config set embedding_dimensions <schema-dim>` to match the existing schema.

## What changed under the hood

- Default embedding model: `openai:text-embedding-3-large` (1536d) → `zeroentropyai:zembed-1` (1280d via Matryoshka).
- Default reranker: off in `balanced` mode bundle → on. (Still off in `conservative`, still on in `tokenmax`.)
- Reranker model: already `zeroentropyai:zerank-2` since v0.35.0.0; that doesn't change.
- Schema transition (when user accepts the switch): DROP indexes → ALTER `content_chunks.embedding` to `vector(1280)` → CREATE INDEX. Atomic inside one `engine.transaction()`. HNSW indexes recreated in the same transaction; no silent slow-search window.
- Three new config keys: `ze_switch_prompt_shown`, `ze_switch_requested`, `ze_switch_applied`. Plus `ze_switch_previous_snapshot` (JSON, captures prior config for `--undo`) and `ze_switch_declined_at` (ISO timestamp for the 90-day re-ask gate).

## What NOT to do

- Don't run `gbrain ze-switch --non-interactive --ignore-missing-key` for a user without explaining the consequence — every embed call will fail until they set `ZEROENTROPY_API_KEY`. Surface that loudly.
- Don't tell the user the sale price ($0.025/M) is the cost they'll pay long-term. It's a promotional rate. The CHANGELOG and prompt cite the regular $0.05/M as the cost anchor.
- Don't assume the user wants the switch because the comparison numbers favor it. The user owns the decision. The prompt's default-on-Enter is "stay" for exactly this reason.

## Why 1280d, not 1024d

The valid ZE Matryoshka dim steps are `2560, 1280, 640, 320, 160, 80, 40`. 1024 (Voyage's step) is NOT on ZE's list — see `src/core/ai/dims.ts:ZEROENTROPY_VALID_DIMS`. 1280 is the step closest to the prior OpenAI 1536d default and stays in the high-recall zone of the Matryoshka curve.

## Verifying the switch

```bash
gbrain doctor                          # both new checks should be green
gbrain ze-switch --dry-run             # status should be skipped_already_applied
gbrain models                          # confirm embedding + reranker defaults
gbrain search "test query" --limit 5   # confirm the reranker is firing
```
