Skip to main content

​
ZeroEntropy — zembed-1 + zerank-2

ZeroEntropy ships two specialized small models for retrieval pipelines:
  • zembed-1 — multilingual embedding distilled from zerank-2. Flexible Matryoshka dims (2560/1280/640/320/160/80/40), 32K context, asymmetric input_type: query|document encoding. 0.025/1Mtokens(sale)/0.025/1M tokens (sale) / 0.05 regular.
  • zerank-2 — SOTA multilingual cross-encoder reranker. $0.025/1M tokens (~50% cheaper than Cohere/Voyage rerankers). Plus zerank-1 and zerank-1-small for legacy / open-source needs.
Both land in modusbrain v0.35.0.0 behind the openai-compatible recipe path, alongside OpenAI and Voyage.

​
Setup

  1. Get an API key at dashboard.zeroentropy.dev.
  2. Export it:

​
Embedding switch — zembed-1

Important: modusbrain config set embedding_model … is NOT a live gateway switch. embedding_model and embedding_dimensions size the schema and must be stable across engine connects, so they only resolve from the file plane (~/.modusbrain/config.json) and the env plane (MODUSBRAIN_EMBEDDING_MODEL / MODUSBRAIN_EMBEDDING_DIMENSIONS). The DB plane is intentionally ignored for these two keys (same posture as today’s Voyage setup). Edit ~/.modusbrain/config.json:
Valid dims: 2560 (default), 1280, 640, 320, 160, 80, 40. Matryoshka-style — smaller trades quality for storage monotonically. Pick the largest that fits your column width.

​
Option B — env plane (CI / Docker)

​
Re-embed

Switching embedding models invalidates the vector index. Re-embed:

​
Verify

Expected: status: "ok". Invalid dims (e.g. 1024, 1536, 3072) surface as status: "config" with a paste-ready modusbrain config set embedding_dimensions <one of 2560|1280|640|320|160|80|40> fix hint.

​
Reranker switch — zerank-2

The reranker is the bigger story: modusbrain had no cross-encoder reranker stage before v0.35.0.0. It slots between RRF dedup and token-budget enforcement in hybrid search.

​
Default-on with tokenmax mode

tokenmax mode now defaults search.reranker.enabled = true with zerank-2. If you already use tokenmax AND have ZEROENTROPY_API_KEY set, reranker fires automatically. Without the key, every rerank call fails-open (audit-logged) and search returns RRF order — same UX as before, just with an observable failure surfaced via modusbrain doctor.

​
Opt-in on conservative or balanced mode

The override sits above the mode-bundle default; opt-out is one flip.

​
Cost anchor

At 30 candidates × ~400 tokens/chunk × 0.025/1M=∗∗ 0.025/1M = **~0.0003/query**. Rounding error against the tokenmax + Opus pairing’s ~$700/mo at single-user volume per the CLAUDE.md cost matrix.

​
Verify

Two probes run for reranker:
  • reranker_config (zero-network) — validates the model resolves through the recipe registry and is in the touchpoint’s allowlist.
  • A reachability probe sends a minimal {query: "probe", documents: ["probe"]} rerank to verify auth + URL.

​
Knobs reference

​
Failure observability

Reranker is fail-open by construction: every error class (auth, rate-limit, network, timeout, payload-too-large, unknown) returns the original RRF order unchanged. Failures log to ~/.modusbrain/audit/rerank-failures-YYYY-Www.jsonl (ISO-week rotation). modusbrain doctor reads the audit and surfaces:
  • auth failures — any single one warns (config-time problem doctor’s own probe should have caught)
  • payload-too-large — any single one warns (workload-mismatch signal)
  • transient (network/timeout/rate_limit) — warns at >=5 in 7 days
Query text is SHA-256 hashed in the audit; never logged raw.

​
Asymmetric input_type

ZE zembed-1 (and Voyage v3+) use asymmetric query/document encoding for better retrieval. The gateway’s embedQuery(text) companion threads input_type: 'query'; standard embed(texts) defaults to 'document'. Hybrid search’s two query-side embed sites use embedQuery() automatically; all ingest paths use embed(). Symmetric providers (OpenAI text-embedding-3, fixed-dim Voyage models) ignore the field — no behavior change.

​
Cache key versioning

v0.35.0.0 bumped KNOBS_HASH_VERSION 1 → 2 to fold reranker config into the query_cache.knobs_hash column. During a rolling deploy:
  • Expect a temporary cache hit-rate dip (~1 hour at default cache.ttl_seconds = 3600s)
  • Hot queries may briefly double their cache row count (one row per version)
Both clear naturally; no operator action required.

​
Troubleshooting