Profiles & Presets

Seven copy-paste configurations — Benchmark / Max-Recall / Voice / Batch / Cost / Enterprise / Quickstart — for the most common CortexDB deployment shapes.

Each profile below is a complete config you can copy into your environment. Every one is marked as either:

Benchmark-validated — we ran this exact configuration on a public benchmark and reproduced the published result.
Principled — derived from the recall pipeline source and internal tuning, but not validated on a published benchmark. Likely good; not proven.

When in doubt, start with Self-host quickstart, then move toward whichever profile matches your workload.

HNSW quantization tokens

The engine's quantization default is tq2 (unset = TQ2); opt out with sq8 or fp32. The accepted hnsw_quantization values are tq2 / sq8 / fp32 — not ScalarU8 / None. This is corrected in the profiles below.

1. Benchmark-validated (LongMemEval-S, 93.8%)

Use this to reproduce the published numbers or run a head-to-head against another memory layer.

Status: Benchmark-validated — the exact configuration that scored 469/500 on LongMemEval-S in the benchmark paper.

# <data_dir>/cortex.toml
[cluster]
node_id = 1

[storage]
[engine]
[network]
[llm]
[governance]

[scheduler]
enabled = false

export OPENAI_API_KEY=sk-...                       # embeddings + extraction
export ANTHROPIC_API_KEY=sk-ant-...                # answer generation
export CORTEX_EMBEDDING_MODEL=text-embedding-3-small
export CORTEX_EMBEDDING_DIMS=1536
export CORTEX_ANSWER_PROVIDER=anthropic
export CORTEX_ANSWER_MODEL=claude-opus-4-6

What's intentional: scheduler.enabled = false (background compaction emits summary entries that pollute top-K over long runs); text-embedding-3-small (the larger model adds ~0.4pp at ~3× cost); claude-opus-4-6 (strongest on the multi-session reasoning that dominates total error). Cost per 150-question run: ~$6.

The five layers are always materialized

There is no opt-in flag for "all five memory layers" — Events, Episodes, Facts, Beliefs, Understanding are always materialized. What's opt-in is the depth of each stage (bigger embedding model, reranker, async KG enrichment, verifier, wider HNSW, more HyDE/multihop) — that's the Max-Recall profile.

2. Max-Recall (every opt-in feature on)

Highest possible recall accuracy; money and latency are not constraints.

Status: Principled — per-component ablation deltas exist, but the full stack has not been run on a public benchmark. Plausible gain over 93.8%: +1 to +3 pp.

# <data_dir>/cortex.toml
[cluster]
node_id = 1

[storage]
data_path = "/data/cortex"
wal_sync = true

[engine]
vector_dimensions = 3072            # match text-embedding-3-large
hnsw_m = 32                         # default 16 — wider graph
hnsw_ef_construction = 500          # default 200 — better-built index
hnsw_ef_search = 200                # default 100 — bigger query candidate pool
hnsw_quantization = "fp32"          # default TQ2 — keep f32, no quantization loss
block_cache_bytes = 34359738368     # 32 GB — keep more index pages hot

[network]
[llm]
[governance]

[scheduler]
enabled = false                     # preserve index stability

# Auth
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export COHERE_API_KEY=...                          # reranker

# Bigger embedding model
# NOTE: embedding provider/model/dims are pinned to the data dir on first boot —
# changing them on an EXISTING data dir is startup-fatal unless you set
# CORTEX_EMBEDDING_ALLOW_REPIN=1 for one restart and re-index. Use a fresh data dir.
export CORTEX_EMBEDDING_MODEL=text-embedding-3-large
export CORTEX_EMBEDDING_DIMS=3072

# Strongest answer model + verifier on every question type
export CORTEX_ANSWER_PROVIDER=anthropic
export CORTEX_ANSWER_MODEL=claude-opus-4-6
export CORTEX_VERIFIER_MODEL=gpt-4.1
export CORTEX_VERIFIER_MAX_TOKENS=16384

# Reranker on (Cohere rerank-v3.5)
export CORTEX_RERANKER_PROVIDER=cohere
export CORTEX_RERANKER_MODEL=rerank-v3.5

# Async KG enrichment on (deeper cross-session entity resolution)
export CORTEX_ENRICHMENT_MODEL=gpt-4o
export CORTEX_ENRICHMENT_URL=https://api.openai.com/v1

# Stronger entity extractor on the write path
export CORTEX_LLM_MODEL=gpt-4o                     # default gpt-4o-mini

# More HyDE passages + wider multihop
export CORTEX_HYDE_PASSAGES_MS=3                   # default 1
export CORTEX_HYDE_MULTIQUERY_DISABLED_TYPES=      # empty = HyDE on for every type
export CORTEX_MULTIHOP_QUERY_COUNT=6               # default 4
export CORTEX_MULTIHOP_MAX_QUERY_FANOUT=8          # default 5
export CORTEX_MULTIHOP_QUERY_PLANNER_TYPES=single-session-user,single-session-assistant,multi-session,open-domain

# Larger graph retrieval pool + extra channels
export CORTEX_GRAPH_RETRIEVAL_TOP_K=80             # default 40 single / 120 MS
export CORTEX_ENTITY_VECTOR_SEED_ENABLE=1
export CORTEX_FACT_EVENT_PROMOTION_ENABLE=1
export CORTEX_FACT_VALIDITY_FILTER=1
export CORTEX_SALIENCE_WEIGHT=0.15                 # default 0.10

# Keep detail during long evals
export CORTEX_METHYLATION_INACTIVITY_HOURS=720     # 30 days (default 7)
export CORTEX_CONSOLIDATION_MIN_AGE_HOURS=168      # 7 days (default 1)

Enrichment is a heavy add-on

CORTEX_ENRICHMENT_MODEL turns on the async KG enrichment LLM — it is off by default and is the main driver of write-side LLM cost (~10×). It is also what populates the Facts/Beliefs/Understanding layers on a self-host. See Self-hosting defaults.

Per-component deltas (ablated individually against the Benchmark baseline) are roughly: large embeddings ~+0.4pp; Cohere reranker ~+1.5–2pp; verifier ~+0.3–0.8pp; async enrichment ~+0.5–1pp; HyDE 3 passages ~+0.3–0.6pp; multihop 6/8 ~+0.5–1.2pp; HNSW M=32/ef200/fp32 ~+0.5pp. They don't add cleanly. Cost per 150-question run: ~$35–60 vs ~$6 for Benchmark.

Use it for leaderboard runs, high-value-per-query workloads (legal/medical), or measuring your instance's ceiling. Not for realtime/voice, cost-sensitive deployments, or reproducing the published 93.8% (use the Benchmark profile for that).

3. Voice / Realtime (sub-100ms recall p50)

Voice agents, coding assistants doing many recalls per turn — anywhere every millisecond is user-perceived.

Status: Principled.

# <data_dir>/cortex.toml
[cluster]
node_id = 1

[storage]
data_path = "/var/lib/cortexdb"
wal_sync = false                # accept WAL durability gap for write latency

[engine]
hnsw_ef_search = 60             # default 100 — smaller = faster, ~0.5pp recall loss
block_cache_bytes = 17179869184 # 16 GB

[network]
request_timeout_ms = 3000       # default 10000 — fail fast

[scheduler]
enabled = true
enrichment_drain_interval_secs = 5  # consume async results aggressively

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export CORTEX_EMBEDDING_MODEL=text-embedding-3-small
export CORTEX_EMBEDDING_DIMS=1536

# Skip the reranker, HyDE, and multihop on hot paths
export CORTEX_RERANKER_PROVIDER=                   # empty = disable
export CORTEX_HYDE_MULTIQUERY_DISABLED_TYPES=single-session-user,single-session-assistant,multi-session,open-domain
export CORTEX_MULTIHOP_QUERY_PLANNER_TYPES=        # empty = disable for all
export CORTEX_GRAPH_RETRIEVAL_TOP_K=20

# Keep all extraction async — nothing synchronous on the write path
export CORTEX_SYNC_FACT_EXTRACT_DISABLE=1
export CORTEX_SYNC_GRAPH_SEED_DISABLE=1

Saved: reranker (~80–200ms), HyDE (~150–400ms), multihop (~200–600ms × N), sync fact extraction (~100–300ms on write). Lost: ~1–3pp recall. wal_sync = false risks ~10ms of writes on a hard crash — fine for voice, not for financial/compliance.

4. Batch / High Throughput

Bulk-ingesting historical data, CRM dumps, nightly ETL of transcripts.

Status: Principled. Optimizes writes-per-second over per-request latency.

# <data_dir>/cortex.toml
[storage]
data_path = "/var/lib/cortexdb"
wal_sync = true

[engine]
block_cache_bytes = 34359738368 # 32 GB

[scheduler]
enabled = true
compaction_interval_secs = 1800           # 30 min (default 5 min)
methylation_interval_secs = 3600          # 1 hour (default 10 min)
enrichment_drain_interval_secs = 60       # 1 min (default 30 s)
cognitive_persist_interval_secs = 600     # 10 min (default 1 min)
feedback_weight_interval_secs = 1800      # 30 min (default 2 min)

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# Large embedding batches
export CORTEX_EMBEDDING_MAX_BATCH_ITEMS=4096       # default 2048
export CORTEX_EMBEDDING_RETRY_ATTEMPTS=3
export CORTEX_EMBEDDING_RETRY_BASE_DELAY_MS=1000

# Defer write-path stages; use the cheap extractor
export CORTEX_SYNC_FACT_EXTRACT_DISABLE=1
export CORTEX_SYNC_GRAPH_SEED_DISABLE=1
export CORTEX_LLM_MODEL=gpt-4o-mini

# Use POST /v1/experience/bulk (up to 100 events/request)

Recall on freshly-ingested data is degraded until the async pipeline catches up. MAX_BATCH_ITEMS=4096 can hit OpenAI's per-batch token limit (the client splits automatically; tune down if logs fill with 413s).

5. Cost-Optimized (free-tier and prototypes)

Status: Principled.

# <data_dir>/cortex.toml
[storage]
data_path = "./cortexdb_data"

[engine]
block_cache_bytes = 2147483648  # 2 GB

[scheduler]
enabled = true

export OPENAI_API_KEY=sk-...
export CORTEX_EMBEDDING_MODEL=text-embedding-3-small
export CORTEX_EMBEDDING_DIMS=1536

# Cheap GPT model everywhere
export CORTEX_LLM_MODEL=gpt-4o-mini
export CORTEX_ANSWER_PROVIDER=openai
export CORTEX_ANSWER_MODEL=gpt-4o-mini

# Disable optional stages
export CORTEX_ENRICHMENT_MODEL=                       # empty = disabled
export CORTEX_RERANKER_PROVIDER=
export CORTEX_HYDE_PASSAGES_MS=1
export CORTEX_MULTIHOP_QUERY_COUNT=2                  # default 4
export CORTEX_VERIFIER_URL=                           # empty = verifier lane unconfigured

For a hobby project (~100K memories, 1K recalls/day): ~$6/month. To go truly free, swap embeddings to a local Ollama (nomic-embed-text, 768 d — set engine.vector_dimensions = 768 to match); expect ~5pp recall loss vs OpenAI embeddings.

6. Enterprise / Compliance

Regulated environments — HIPAA, SOC 2, GDPR, PCI.

Status: Principled — the security/compliance schema lights up the controls auditors look for; not formally certified against any regime.

# <data_dir>/cortex.toml
[storage]
data_path = "/data/cortex"
wal_sync = true

[engine]
hnsw_quantization = "sq8"       # save memory; encrypt-at-rest handles the rest

[network]
api_port = 3141
gossip_port = 7000
grpc_port = 9042

[governance]
default_retention_ttl_secs = 2592000    # 30 days — stored, NOT auto-enforced;
                                        # drive deletion via scheduled /v1/forget or /v1/erasures
max_retention_secs = 220752000          # 7 years
pii_detection = true
pii_handling = "Block"
audit_logging = true

[security]
[security.encryption]
enabled = true
key_file = "/etc/cortexdb/keys/master.key"
key_rotation_interval_secs = 7776000    # 90 days
blob_store_sse_kms = true

[security.tls]
api_tls_enabled = true
cert_path = "/etc/cortexdb/tls/cert.pem"
key_path = "/etc/cortexdb/tls/key.pem"
ca_cert_path = "/etc/cortexdb/tls/ca.pem"
mtls_enabled = true
min_tls_version = "1.3"

[security.rbac]
enabled = true
default_role = "reader"
oidc_issuer = "https://login.acme.com/"
oidc_audience = "cortexdb"
require_mfa = true

[security.rate_limit]
enabled = true
default_rpm = 600                       # headers only — quotas NOT enforced;
default_rpd = 50000                     # enforce hard limits at your LB
burst = 20

[security.breach_detection]
enabled = true
max_failed_auth = 5
auth_window_secs = 300
lockout_duration_secs = 3600

[blob_store]
provider = "s3"
bucket = "acme-cortex-blobs"
region = "us-east-1"
s3_encryption_type = "aws:kms"
s3_kms_key_id = "arn:aws:kms:us-east-1:123:key/abc"
s3_bucket_key_enabled = true

[compliance]
[compliance.data_residency]
enabled = true
allowed_regions = ["us-east-1", "us-west-2"]

[compliance.consent]
require_consent = true
default_purposes = ["customer_support"]

[compliance.classification]
auto_classify = true
default_sensitivity = "internal"
auto_redact_above = "confidential"

[compliance.dsar]
enabled = true                          # /v1/erasures honored

[compliance.siem]
enabled = true
format = "cef"
webhook_urls = ["https://siem.acme.com/ingest"]
batch_size = 100
flush_interval_secs = 30

export CORTEX_DEPLOYMENT_PRESET=on_prem_enterprise
export CORTEX_API_KEY=<generate-a-strong-secret>   # the value itself is the credential
export CORTEX_EMBEDDING_API_KEY=...                # separate from OPENAI_API_KEY
export CORTEX_ANSWER_API_KEY=...
export CORTEX_VERIFIER_API_KEY=...
export CORTEX_VERIFIER_MODEL=gpt-4.1
export CORTEX_LOG_FORMAT=json

Two enforcement caveats in the current release

Retention TTLs are stored but not auto-enforced — schedule /v1/forget / /v1/erasures jobs to actually delete. Rate-limit quotas emit headers but do not reject over-limit requests — enforce hard limits at your load balancer. See Security & Compliance.

7. Self-host quickstart (5-min Docker)

Status: Validated — what docker run cortexdb/cortexdb:latest gives you out of the box.

docker run -d \
  --name cortexdb \
  -p 127.0.0.1:3141:3141 \
  -v cortexdb-data:/data \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  cortexdb/cortexdb:latest

The container ships with zero cortex.toml overrides — every field at its compiled default: single-node, v1 API on :3141, data on the volume; auth on by default — add -e CORTEX_INSECURE_NO_AUTH=1 for a no-token local run (served as user:local), or -e CORTEX_API_KEY=<secret> to require bearer auth (a keyless network bind auto-generates a key); OpenAI text-embedding-3-small + gpt-4o-mini extraction; Anthropic claude-opus-4-6 answers; scheduler on; encryption/TLS/RBAC off (evaluation only).

curl http://localhost:3141/v1/admin/ready   # confirm it's serving, not degraded on mock embeddings

To deploy for real, layer on: CORTEX_API_KEY set to a strong secret; a real volume mount; TLS termination in front; a verified cold backup on a schedule; and the Enterprise profile block if you have compliance obligations.

Picking between profiles

Reproducing the published 93.8%? → Benchmark (1).
Absolute highest recall, cost no object? → Max-Recall (2).
Regulated industry? → Enterprise (6), layer tuning later.
Latency per request? → Voice/Realtime (3). Bulk ingest? → Batch (4). API cost? → Cost-Optimized (5). Just evaluating? → Quickstart (7).

Most production deployments end up as Enterprise + selective Voice/Realtime tuning on the recall hot path.

Next steps

Configuration Foundations — precedence rules and reload semantics
Recall Tuning — the recall-side knobs in detail
Benchmarking — full reproduction steps

On this page