CortexDB Production Configuration

Server: CortexProd (ssh CortexProd) Binary: /root/cortex/target/release/cortexdb Service: systemctl restart cortexdb.service Service file: /etc/systemd/system/cortexdb.service Env file: /root/cortex/.env Runtime overrides: /etc/systemd/system/cortexdb.service.d/cohere.conf Data dir: /root/cortex/cortexdb_data/ Log file: /var/log/cortexdb.log Mode: Single-node (no CLI args) Listen: 0.0.0.0:3142 (behind nginx on :443 → api.cortexdb.ai / api-v1.cortexdb.ai; port 3141 is intentionally free — an orphan process squatted it until 2026-07-09) Also on this box: cortexdb-limechat.service (enterprise pilot, second checkout at /root/cortex-enterprise, binds 3143, env /root/limechat/.env, enrichment pinned in the unit file)

Production Checklist — what a deployment must set

Five decisions. Everything not listed here has a benchmarked default — leave it alone unless you have a measured reason.

Variable	Setting	Why
`OPENAI_API_KEY` (or `CORTEX_EMBEDDING_` / `CORTEX_LLM_` for another provider)	required	Powers embeddings + extraction. Without it recall silently degrades to keyword-only (mock embeddings).
`CORTEX_ANSWER_API_KEY`	required if `/v1/answer` is used	Anthropic key; the endpoint 503s without it.
`CORTEX_ENRICHMENT_DELAY_SECONDS`	must be a conscious choice	Unset = enrichment OFF: no facts/beliefs, and background concept reflection is gated off too (see `CORTEX_V1_LAYERS_AUTO` below) — zero background LLM spend. Episodes still build (deterministic, from raw events). `N >= 0` = WAL-cursor scanner every N seconds (`0` clamps to the 5 s floor ≈ near-realtime; `86400` daily). Restart-safe in every mode. Legacy `CORTEX_ENRICHMENT_DELAY_MINUTES` still honored x60.
`CORTEX_V1_LAYERS_AUTO`	leave unset unless you know why	The synthesis scheduler (episodes/beliefs/concept reflection — the last is an LLM call). Unset → runs, but concept reflection follows the enrichment switch above (enrichment off ⇒ no reflection LLM calls). `1` forces concept reflection even with enrichment off (reflects over raw events — conscious spend). `0` disables the scheduler entirely. `/v1/admin/layers/stats` → `health.concepts_gated_by` shows the live verdict.
`CORTEX_EVICT_VECTORS_ON_ENRICH`	`1` — always set it	Demotes chunk vectors to cold storage once enrichment commits: flat memory at any corpus size, recall verified at parity. No-op while enrichment is off, so it is always safe to set — leaving it unset just means RAM grows linearly with corpus size once enrichment is enabled.
`CORTEX_API_KEY`	required when the port is reachable beyond localhost	Bearer auth for the data API.
`CORTEX_DEPLOYMENT_PRESET`	`on_prem_enterprise` / `cloud_shared_saas` / `cloud_private`	Valid names only — an unknown preset prevents the v1 surface from starting. Default `dev_local` allows unsigned actors — never leave it default in production.

Set only if it applies: CORTEX_RERANKER_{PROVIDER,MODEL} (recall quality; recommended when budget allows), CORTEX_ENRICHMENT_{MODEL,URL,API_KEY} (cheaper/different enrichment model), CORTEX_BLOB_* (S3/GCS/Azure instead of local disk), CORTEX_TELEMETRY=0 (policy opt-out), CORTEX_ANSWER_DEFAULT_INSTRUCTIONS (v0.8.6: deployment-wide answer-style policy, e.g. "always include entity identifiers"), CORTEX_RECENCY_TAIL_EVENTS (v0.8.6: default evidence size for order: "recency" timeline-tail recall, default 100; the mode and its question-shape inference ship on — kill-switches CORTEX_RECENCY_ORDER=0, CORTEX_RECENCY_INFERENCE=0).

Effective Runtime Configuration

Secrets (stored in `/root/cortex/.env`, redacted here)

OPENAI_API_KEY=<redacted>
COHERE_API_KEY=<redacted>
CORTEX_API_KEY=<redacted>
CORTEX_SUPERKEY=<redacted>
TURSO_DATABASE_URL=<redacted>
TURSO_AUTH_TOKEN=<redacted>

Embedding Service

CORTEX_EMBEDDING_PROVIDER=cohere
CORTEX_EMBEDDING_MODEL=embed-english-v3.0
CORTEX_EMBEDDING_DIMS=1024

LLM (entity extraction, query classification)

CORTEX_LLM_URL=https://api.openai.com/v1
CORTEX_LLM_MODEL=gpt-4o-mini

Enrichment (fact augmentation)

CORTEX_ENRICHMENT_CONCURRENCY=16   # default 16; each job = 1-2 LLM calls. Lower only on rate-limited keys.

CORTEX_ENRICHMENT_MODEL=gpt-4o
CORTEX_ENRICHMENT_URL=https://api.openai.com/v1

Reranker (cross-encoder confidence scoring)

CORTEX_RERANKER_PROVIDER=cohere
CORTEX_RERANKER_MODEL=rerank-v3.5
CORTEX_RERANKER_MODEL_PATH=

Authentication

CORTEX_API_KEY=<redacted>
CORTEX_SUPERKEY=<redacted>

CORTEX_API_KEY — Bootstrap key for the "default" tenant. Used when Turso auth is not available.
CORTEX_SUPERKEY — Bypasses all rate limits and tier gates. Used for benchmarks and admin.

Turso (customer API key database)

TURSO_DATABASE_URL=<redacted>
TURSO_AUTH_TOKEN=<redacted>

When TURSO_DATABASE_URL is set, the server uses Turso for API key auth.
This is the same DB the website (cortexdb.ai) writes keys to on user signup.
Without it, the server falls back to in-memory bootstrap key (CORTEX_API_KEY only).

v1 Token Minter (PASETO)

The v1 API surface (/v1/*) authenticates with PASETO v4 public tokens. POST /v1/auth/tokens mints them; the dashboard (app.cortexdb.ai) and SDK examples are the main consumers.

CORTEX_V1_API_ADDR=0.0.0.0:3142
CORTEX_V1_AUDIENCE=cortexdb:tenant:<your-tenant>
CORTEX_V1_MINTER_ENABLE=1
CORTEX_V1_MINTER_KEY_DIR=/root/cortex/minter_keys
CORTEX_V1_MINTER_ISSUER=https://api-v1.cortexdb.ai/issuer

CORTEX_V1_API_ADDR — bind addr for the v1 surface. Without this set, the v1 router is not mounted. The legacy :3141 surface is independent.
CORTEX_V1_AUDIENCE — must match cortexdb:tenant:<tenant_id>. Used as the aud claim and verified on every request.
CORTEX_V1_MINTER_ENABLE — 1 turns on POST /v1/auth/tokens. Default is on for the dev_local preset and off everywhere else.
CORTEX_V1_MINTER_KEY_DIR — directory containing secret.key (64 raw bytes) and public.key (32 raw bytes). Without this, the minter falls back to an ephemeral keypair (tokens become invalid on restart — dev only). Production must point at a real on-disk pair.
CORTEX_V1_MINTER_ISSUER — issuer string used in the iss claim. Must be on the deployment's issuer allowlist for the verifier to accept the resulting tokens.

Generate a production keypair:

./build.sh cargo build --release -p cortex-auth --bin gen_minter_keys
./target/release/gen_minter_keys /root/cortex/minter_keys
chmod 600 /root/cortex/minter_keys/secret.key

The generator refuses to overwrite existing files — if you need to rotate, move the old pair aside first and revoke outstanding jtis via POST /v1/auth/revoke.

Capability gate. The mint endpoint requires auth.mint. Pass an optional scope in the request body to make the check scope-aware (caller must hold auth.mint on that scope). Omit scope for a deployment-wide check — used by operators minting service tokens.

Benchmark note

The best LoCoMo runs also depend on benchmark-harness choices such as --mode session, superkey usage, answer-prompt selection, and judge configuration. Those are not production server env settings and are documented separately from the runtime config above.

Implicit Defaults (no CLI args = single-node mode)

Setting	Value	Source
Mode	Single-node	No `--node-id` / `--rpc-addr` / `--gossip-addr`
Port	`3141`	Default in `parse_config()`
Listen address	`0.0.0.0:3141`	Hardcoded
Data directory	`cortexdb_data`	Default in `parse_config()`
Node ID	`1`	Default
Replication factor	`3`	Default (unused in single-node)
Log format	Text	No `CORTEX_LOG_FORMAT=json`
Log level	`info`	Default `RUST_LOG` filter

CLI Args (cluster mode — not used in prod today)

cortexdb --node-id=1 \
         --rpc-addr=0.0.0.0:3142 \
         --gossip-addr=0.0.0.0:3143 \
         --seed-nodes=10.0.0.2:3143,10.0.0.3:3143 \
         --rf=3 \
         --port=3141 \
         --data-dir=cortexdb_data_1

Data Directory (`cortexdb_data/`)

Path	Purpose
`wal/`	Write-ahead log (RocksDB) — source of truth
`content/`	Content store (RocksDB)
`fulltext/`	Tantivy fulltext index
`vector/`	HNSW vector index
`graph/`	Knowledge graph (RocksDB)
`temporal/`	Temporal index (RocksDB)
`resolver/`	Entity resolution store
`api_metrics.json`	Persisted API request metrics
`tenant_usage.json`	Persisted per-tenant usage counters

Systemd Service

[Unit]
Description=CortexDB Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/cortex
EnvironmentFile=/root/cortex/.env
ExecStart=/root/cortex/target/release/cortexdb
Restart=always
RestartSec=3
StandardOutput=append:/var/log/cortexdb.log
StandardError=append:/var/log/cortexdb.log

[Install]
WantedBy=multi-user.target

Telemetry

The community binary sends an anonymous usage beacon (on by default) so we can see how the free distribution is adopted. It carries aggregate counts and pseudonymous IDs only — never request/response bodies, query text, stored memory content, end-user IPs, or scope strings.

Opt out: set CORTEX_TELEMETRY=0 (or off/false/no) or DO_NOT_TRACK=1. The server logs usage telemetry disabled at startup and sends nothing.
Identity: an anonymous install UUID persisted at <data_dir>/.cortex_telemetry.json (delete to reset). An optional CORTEX_INSTALL_KEY=ck_… ties the install to a customer email on the backend only — the binary never sees the email.
Knobs: CORTEX_TELEMETRY_ENDPOINT, CORTEX_TELEMETRY_FLUSH_SECS (default 3600), CORTEX_CHANNEL (docker set by the image), and CORTEX_TELEMETRY_DEBUG=1 to log each beacon as JSON.

Full data dictionary, wire schema, and the cloud ingest contract are in TELEMETRY.md.

Useful Commands

# Restart server
systemctl restart cortexdb.service

# Check status
systemctl status cortexdb.service

# Tail logs
tail -f /var/log/cortexdb.log

# Rebuild and deploy
cd /root/cortex && git pull origin main && source ~/.cargo/env && cargo build --release -p cortexdb && systemctl restart cortexdb.service

# Health check
curl https://api-v1.cortexdb.ai/v1/admin/health

# Test with superkey
curl -H "<TOKEN redacted>" https://api-v1.cortexdb.ai/v1/admin/usage

PyPI (cortexdb-mcp)

Package: cortexdb-mcp Account: cortexdbai

# Publish new version
cd mcp-server
# bump version in pyproject.toml
python3 -m build
TWINE_USERNAME=__token__ "<PYPI_TOKEN redacted>" python3 -m twine upload dist/*