Operations Overview

CortexDB is a single Rust binary with roughly 100 environment variables, 10 CLI flags, and a TOML configuration file. That sounds like a lot. In practice, most operators touch fewer than ten knobs — the rest exist for cluster tuning, regulated-industry deployments, or A/B experiments.

This section is structured so you can stop reading at the level of detail you need:

The three places config lives

CortexDB reads configuration from three sources, applied in this order (each layer overrides the previous):

  Lowest      1. Compiled defaults        Hardcoded sane production values
   ↑          2. <data_dir>/cortex.toml   Persisted, version-controllable source of truth
   ↓          3. Environment variables    Per-process overrides (benchmarks, A/B, hotfixes)
  Highest     4. CLI flags                Cluster topology only — no overlap with the above

Things that should be the same across every restart go in cortex.toml (HNSW shape, WAL sync mode, retention policy, audit). Things that should change between runs go in env vars (model choice, recall weights, scheduler on/off). Topology is a CLI concern because it changes the binary's role, not its behavior.

What's actually tunable

Always touch

• An embedding provider — without one you're on mock embeddings and recall is nonsense. The server pins the embedding provider to the data dir on first boot, and GET /v1/admin/ready reports degraded: true while on mock. See Self-hosting defaults and Embeddings.
• cortex.toml's [storage] data_path — defaults to /data/cortex, which is wrong unless that's a real volume you mounted.

Touch on day one

• Embedding model — CORTEX_EMBEDDING_MODEL + CORTEX_EMBEDDING_DIMS.
• Answer model — CORTEX_ANSWER_PROVIDER + CORTEX_ANSWER_MODEL.
• Scheduler — [scheduler] in cortex.toml, or CORTEX_SCHEDULER_DISABLE=1. Background compaction & methylation are on by default; disable for benchmarks.

Touch only with a reason — recall weights and pool sizes (CORTEX_GRAPH_RETRIEVAL_TOP_K, CORTEX_SALIENCE_WEIGHT, CORTEX_MULTIHOP_*), HNSW shape ([engine] hnsw_m / hnsw_ef_construction / hnsw_ef_search; defaults M=16, ef_construction=200, ef_search=100).

Don't touch unless debugging the recall pipeline — the A/B feature flags (CORTEX_MS_COUNT_RELEVANCE_ENABLE, CORTEX_FACT_EVENT_PROMOTION_ENABLE, CORTEX_FACT_VALIDITY_FILTER, …). See Recall Tuning — several switches the v1 docs list are not read by the server.

A note on what's hard-coded

About 25 retrieval and ranking constants live in the coordinator as const declarations, not env vars — e.g. RRF_K = 60.0 (the reciprocal-rank-fusion smoothing constant), RETRIEVAL_TOP_K = 40 / RETRIEVAL_TOP_K_MS = 160, RERANK_POOL = 25. A handful that move the needle on real workloads have env-var overrides (CORTEX_GRAPH_RETRIEVAL_TOP_K, CORTEX_MULTIHOP_QUERY_COUNT, CORTEX_MULTIHOP_MAX_QUERY_FANOUT); the rest are intentionally constants.

Each page that follows takes one subsystem and walks every knob: name → default → type & range → what it controls → when to change it → example. For a 30-second answer, jump to Profiles & Presets.