Configuration

• Everything lives in one file: cymatix.toml, read once at process start by cymatix_context.config.load_config(). There is no second config source and no dotfile.
• The loader is soft-fail on every section. Malformed TOML, an unknown key, a bad value — each logs a WARNING and falls back to the typed dataclass default. The server never refuses to start over a config typo. The single hard failure is [abstain] mode = "per_classifier" without an [abstain.default] block.
• Defaults are the interesting part. Almost every expensive feature in this project ships off, and every default-off flip is attached to a receipt. This page gives the tour and the flip dates; the exhaustive per-key reference is docs/config-reference.md.
• Canonical names are shown first. [compressor] and [knowledge_store] are the software-lexicon spellings; [ribosome] and [genome] are the legacy spellings the file on disk still uses, and both resolve. See Lexicon.
• This page documents v0.9.1. Two new knobs (#409, #412), the wave-1 ranking defaults (#407), and the tagger v2 behavior change (#413) are marked where they appear.

Where a value comes from

Highest priority wins:

1. Per-call request fields — caller_model_class, include_cold, decoder_mode, ignore_delivered and friends on the /context body. These never mutate the loaded config.
2. Environment variables — the CYMATIX_* set below.
3. cymatix.toml — the path in CYMATIX_CONFIG, else cymatix.toml in the current working directory.
4. Dataclass defaults in cymatix_context/config.py, returned as-is when no file is found.

Two typo guards run at load, both warning-only:

• An unrecognized key inside a known section logs Unknown-key check output naming the section and key.
• An unrecognized top-level section logs Unknown top-level section [<name>] in cymatix.toml. New in 0.9.1 — it catches a mistyped [retreival] that would previously have been silently ignored while you wondered why the flip did nothing.

Canonical and legacy names

The 0.9.1 lexicon pass adds canonical software-term aliases across the config surface. They are additive: every legacy spelling keeps working, unchanged.

Collision rule: the legacy name wins, and a WARNING names both. If a config carries both [compressor] and [ribosome], the [ribosome] block is the one that binds and the alias is dropped with a log line. Same for the key pairs and for the two env vars. The rule is deliberately conservative — an operator who has both spellings in play gets the behavior their existing file already had, not a silent change.

(The CLI is the one exception: --max-docs and --max-genes share an argparse destination, so passing both is plain last-wins. See CLI.)

Every section

The synonym map earns its own warning. Retrieval matches query keywords against the tags assigned at ingest time. When a query returns "no relevant context", the most common cause by far is that your vocabulary and your corpus's tags never meet. Add a row under [synonyms] and restart before concluding that retrieval is broken.

Default-off, and when it flipped

Every one of these was flipped by a measurement, not a preference. The default retrieval path in 0.9.1 makes zero model calls as a result.

Two consequences worth internalizing. Turning a retrieval knob back on is not enough on its own — dense recall additionally needs the vectors to exist, so a store ingested with dense_embed_on_ingest = false returns nothing from the dense tier until scripts/backfill_bgem3_v2.py has run (same story for scripts/backfill_sema.py). And the dense-off default carries a disclosed p50 latency regression — dense's ANN gate was load-bearing as a candidate-list cap — ×2.5–2.6 at 100k fragments, shrinking to ×1.09–1.38 at the 829k operating point (#374); the mitigation has not landed.

New in 0.9.1

[budget] min_delivered_docs — the delivered-seat floor

[budget]
min_delivered_docs = 0    # default: off, byte-identical legacy behavior

• Guards both mechanisms that cost a document its seat. It lifts the classifier's per-rule assembly cap to at least N, and it makes the Stage-5 budget trimmer shrink the largest parts (tail-truncated, header-preserving, marked ...[budget-trimmed]) instead of evicting whole documents.
• The token budget still wins last: if every part is already at the truncation floor and the prompt still overflows, eviction resumes below the floor.
• Model-class caps (small_moe = 4) are a model-capability concern and stay untouched.
• Measured at floor 12 on the 829k bed: gold-document delivery 0.630 → 0.668, +18 / −0 needles — zero paired losses, and the map and final rank bases came back byte-identical per needle, so this is a pure delivery change (#409).
• The default flip was not taken. The benchmark measures delivery, not answer quality under a widened seat count — more documents in the window is not automatically a better answer. The receipts justify shipping the knob, not flipping it.

[ingestion] entity_autolink_hub_cutoff — bound the auto-link sweep

[ingestion]
entity_autolink_hub_cutoff = 0    # default: off, byte-identical legacy behavior

• Ingest-time entity auto-linking sweeps every entity_graph posting row of every probe entity before its per-insert GROUP BY. On hub-heavy corpora that is O(N²) per build: on a 289k-document EnronQA bed, auto_link_by_entity was 89.5% of writer wall time — 148.9 ms/insert, versus 7.4 ms without the two MIME-header hubs.
• Set above 0 and entities whose posting count exceeds the bound are dropped from the probe set before the GROUP BY. The count probe is LIMIT-bounded, so per-insert cost becomes O(n_entities × cutoff). PKI_NOISE_CUTOFF = 200 is the precedent value for a future flip (#411).
• Measured on a 500-document read-only replay at cutoff 200: 0.53% of distinct entities held 56.9% of all postings; the per-link call went 210.5 ms → 0.62 ms (~340×) (#412).
• Caveat, and the reason it ships off: the cutoff changes which relation=5 COVER edges form — 4,842 → 2,867 on that bed. A store built with the cutoff on is not edge-identical to one built without it. Those edges are default-inert at query time, but "inert" is not "absent".

Wave-1 ranking defaults (#407)

• [retrieval] rrf_k graduates 60 → 20, tightening the rank-position discount so a high-ranked candidate from any single signal survives fusion. Set 60 to restore the Cormack 2009 default.
• [retrieval] rerank_combinator_by_class extends from {multi_hop, default} to all five classifier classes, all mapped to eps_band. Pass an explicit {} to restore global-combinator behavior.
• Together, on the 829k bed at n=470: delivered gold 0.555 → 0.630, recall@12 0.651 → 0.681, paired +18 / −4, zero question-type regressions. The band also protects paraphrastic gold — the unbanded arm dropped semantic recall@12 0.32 → 0.16.
• Both halves ship as one commit, so the whole thing reverts with one git revert. Full context: Pipeline.

Tagger v2 (#413) — a behavior change, not a knob

• The CPU ingest tagger now rejects entities containing newlines or tabs, and no longer emits standard email/MIME header field names, x-* extension headers, or MIME transport artifacts as entities. It fixes the EnronQA entity-graph hub problem at the source.
• There is no config knob. The version is the module constant TAGGER_VERSION = 2 in cymatix_context/tagger.py.
• Comparability rule: the tagger determines document boundaries and tags, so beds built under different tagger versions are not cross-comparable. Every bed built before 2026-08-30 is tagger_version = 1. scripts/build_fixture_matrix.py records the value in each bed's manifest and docs/benchmarks/BASELINES.md requires matching versions for a cross-bed claim. See Benchmarks and Receipts.

Security knobs

A loopback bind is not authentication — any process on the same host can reach the port. Three knobs harden the surface; two are opt-in, one is now on by default.

[server]
admin_token = "your-secret"              # 401s /admin/*, /ingest, /consolidate without the bearer
swap_db_roots = ["F:/cymatix/genomes"]   # 403s /admin/swap-db targets outside these roots

[budget]
neutralize_control_tags = true           # default since 2026-08-19 (#351) — set false to opt out

• admin_token (default "" = no auth). When non-empty, every /admin/* route plus /ingest and /consolidate demands Authorization: Bearer <token> and returns 401 otherwise. Read-only routes (/stats, /health, /context, …) stay open.
• swap_db_roots (default [] = unrestricted). When non-empty, POST /admin/swap-db only opens .db paths that resolve under one of the listed roots; anything else is rejected 403 before a store is opened. A root on a different drive than the target never matches.
• neutralize_control_tags (default true since 2026-08-19, #351). The assembly loop escapes a content-sourced <cymatix: to <cymatix: so an ingested document cannot forge the genuine <cymatix:no_match/> / <cymatix:slate> control tags that downstream agents trust. The genuine no-match tag is emitted on a separate branch and is never escaped. The flip was receipt-gated: the escape runs strictly after retrieval, fusion, and rank publication, and the 141-needle 100k-carve A/B measured the delivered basis and 141/141 assembled windows byte-identical across arms. Set false and documents legitimately containing the literal <cymatix: string ship verbatim. Scope limit: this closes control-tag forgery only. General indirect prompt injection through document text is inherent to context injection and is not addressed.
• Startup warning. When [server] host is non-loopback (not 127.0.0.1 / localhost / ::1) while admin_token is empty, the app logs a prominent NETWORK-EXPOSED ADMIN SURFACE warning at startup. Warning only — the bind is honored unchanged.

Environment variables

All process-level overrides use the CYMATIX_ prefix and beat the TOML file.

The OTel rule is env-wins in both directions. CYMATIX_OTEL_ENABLED=0 silences a [telemetry] enabled = true, and the tray launcher's auto-export of CYMATIX_OTEL_ENABLED=1 beats a [telemetry] enabled = false once the observability stack's collector port is up. Resolution happens in otel.resolve_telemetry_settings(), not in the TOML loader. See Observability.

CYMATIX_STORE_PATH=genomes/dogfood/genome.db cymatix-server
CYMATIX_OTEL_ENABLED=1 CYMATIX_OTEL_ENDPOINT=localhost:4317 cymatix-server

When a change takes effect

• Restart required for most of the surface: [compressor], [hardware], [server], [knowledge_store], [ingestion], [cymatics], [classifier], [plr], [abstain], [mem_sync], [synonyms], [vault], [headroom], the [budget] token caps, and the [retrieval] weights and mode.
• Read per request: [budget] foveated_alpha / foveated_c_min / foveated_base_chars, [retrieval] ann_threshold_mode, and [retrieval] fusion_mode.
• POST /admin/refresh invalidates the retrieval-layer caches and the [know] calibration table. That route is one of the ones admin_token gates.
• When in doubt, restart. The hot-reload paths exist for the highest-churn knobs, not as a general contract.

A note on names in code blocks: the shipped cymatix.toml on disk still uses the legacy spellings ([ribosome], [genome], genome.db, max_genes_per_turn), and this page reproduces them verbatim where it quotes the file. Renaming the on-disk file and the SQL columns is a tracked Tier-3 change, deliberately not taken in 0.9.1 because it breaks every existing store and consumer. See Lexicon.

Go deeper

• docs/config-reference.md — the canonical per-key reference: type, default, and the rationale for every knob, plus loading order and hot-reload semantics
• cymatix.toml — the shipped file, with the flip receipts written inline as comments
• docs/benchmarks/2026-08-14-encoder-isolation-scale-curve.md — the four-scale receipts behind the dense and SPLADE flips
• CHANGELOG.md — every default flip with its receipt path and disclosure
• docs/operator-runbooks.md — backfill and calibration procedures with timings
• Next: Retrieval Dimensions · HTTP API · Benchmarks and Receipts · Observability