Storage & Cluster

CortexDB stores everything on one canonical write path: an append-only WAL backed by RocksDB. Every searchable index — HNSW vectors, Tantivy fulltext, the KG, materialized views — is a derivative of that WAL. Restore the WAL and you can rebuild every index.

Storage paths and durability

[storage]
data_path = "/data/cortex"          # default
wal_sync = true                     # default
max_disk_usage_percent = 95         # default

The default /data/cortex suits the Docker/k8s shape (mount a real volume there); bare-metal usually overrides to /var/lib/cortexdb. The config file lives at <data_path>/cortex.toml, so changing data_path also moves the config. wal_sync = false (or CORTEX_WAL_SYNC=0) is the explicit faster/weaker opt-out — fine for voice/realtime, not for financial/medical/compliance workloads. max_disk_usage_percent is a soft floor (RocksDB itself doesn't refuse writes) — keep ~10% headroom on the actual disk.

The extraction cache

Alongside the stores, the data directory holds an extraction cache that lets repeated extraction work skip the model call. It is on by default and lives at <data_dir>/extraction_cache (verified present on a fresh v0.9.9 boot). Four environment variables control it:

Because expiry is lazy, the directory can hold entries past their TTL until they are next read — size the volume for the cache as well as the stores.

Engine: HNSW and cache

[engine]
max_memory_bytes = 25769803776            # 24 GB (default)
vector_dimensions = 3072                  # default; MUST match embedding output
hnsw_m = 16                               # default
hnsw_ef_construction = 200                # default
hnsw_ef_search = 100                      # default; runtime-tunable
hnsw_quantization = "tq2"                 # default TQ2; opt out with sq8 / fp32
hnsw_tombstone_rebuild_threshold = 0.15   # default; 15% deleted → rebuild
block_cache_bytes = 8589934592            # 8 GB (default)

HNSW recipes

The Max-Recall config buys ~+0.5–1 pp at ~3× memory, ~2× build, ~2× query — rarely worth it in production.

Vector index persistence and memory

The HNSW index is snapshotted to the data directory so a restart warms from disk instead of rebuilding. These are environment variables, not cortex.toml fields; every default below is the value config_lint reports on v0.9.9.

Network and ports

[network]
api_port = 8443                # cortex.toml default
gossip_port = 7000             # default
grpc_port = 9042               # default
request_timeout_ms = 10000     # default (10 s)
gossip_interval_ms = 1000      # default (1 s)

Scheduler

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

CORTEX_SCHEDULER_DISABLE=1 disables the whole scheduler at startup (always set for benchmarks). Schema validation enforces the minimum intervals — compaction_interval_secs = 10 fails startup.

Cluster topology (experimental — not operational)

cortexdb \
  --node-id=1 \
  --rpc-addr=10.0.0.1:7100 \
  --gossip-addr=10.0.0.1:7000 \
  --seed-nodes=10.0.0.1:7000,10.0.0.2:7000,10.0.0.3:7000 \
  --rf=3 \
  --port=3141 \
  --data-dir=/data/cortex/node1

[cluster]
node_id = 1                                   # must match --node-id
seed_nodes = ["10.0.0.1:7000", "10.0.0.2:7000"]
replication_factor = 3
vnodes_per_node = 256
consistency_default = "Quorum"                # "One" | "Quorum" | "All"

These fields describe the intended design; none of the replication or consistency settings provide fault tolerance in the current release.

Blob storage

Binary content (images, audio, video, documents) is stored in a blob backend with a content-addressed reference in the WAL.

[blob_store]
provider = "local"                  # "local" | "s3" | "gcs" | "azure"

# Local mode
data_dir = "/data/cortex/blobs"

# S3 mode
bucket = "acme-cortex-blobs"
region = "us-east-1"
endpoint = ""                       # optional — S3-compatible (R2, MinIO, B2)
access_key_id = ""                  # falls back to AWS_ACCESS_KEY_ID env
secret_access_key = ""              # falls back to AWS_SECRET_ACCESS_KEY env
allow_http = false                  # true ONLY for MinIO over LAN
virtual_hosted_style_request = true # false for path-style URLs

# S3 encryption
s3_encryption_type = "aws:kms"      # "AES256" | "aws:kms" | "" (none)
s3_kms_key_id = "arn:aws:kms:..."   # required if s3_encryption_type = aws:kms
s3_bucket_key_enabled = true        # KMS bucket key — saves KMS API costs

Every TOML field has an env-var form (e.g. CORTEX_BLOB_BUCKET, CORTEX_BLOB_S3_KMS_KEY_ID); the env var wins if both are set. GCS uses gcs_bucket + gcs_application_credentials; Azure uses azure_account + azure_container + azure_access_key (falls back to AZURE_STORAGE_KEY); MinIO is S3 with endpoint + allow_http = true + virtual_hosted_style_request = false.

Blobs are referenced from /v1/experience payloads by content hash and served via /v1/blobs/{id}. The server reads/writes the backend transparently — co-locate CortexDB and the blob backend in the same region/VPC.

Content modality processors

Each modality has its own extraction integration; all are optional — if unconfigured, ingest silently skips extraction for that modality.

# Image (GPT-4o vision)
export CORTEX_IMAGE_PROVIDER=openai
export CORTEX_IMAGE_API_KEY=$OPENAI_API_KEY
export CORTEX_IMAGE_MODEL=gpt-4o

# Audio (Whisper)
export CORTEX_AUDIO_PROVIDER=openai
export CORTEX_AUDIO_API_KEY=$OPENAI_API_KEY
export CORTEX_AUDIO_MODEL=whisper-1
export CORTEX_AUDIO_LANGUAGE=en        # optional

# Video (ffmpeg keyframes → image processor)
export CORTEX_FFMPEG_PATH=ffmpeg
export CORTEX_VIDEO_KEYFRAMES_PER_MIN=6

# Document (OCR / PDF extraction — e.g. Tika)
export CORTEX_DOCUMENT_PROVIDER=...
export CORTEX_DOCUMENT_API_URL=...
export CORTEX_DOCUMENT_API_KEY=...

The same fields can be set under [content_processors.image] / .audio / .video / .document / .sensor. See Media ingestion.

Disk sizing

Rough rule of thumb on text-heavy workloads with text-embedding-3-small (1536 d, tq2 quantization):

Above ~10M events, plan a very large single box — clustering is experimental/not operational, so scaling out isn't an option yet. Mitigate the one-box risk with regular verified cold backups and infra-level redundancy (RAID, replicated volumes).

Backups and snapshots

The supported path is a verified cold backup of the data directory using scripts/cold_backup.py. There is no online/hot backup, no scheduled job, no object-store upload target, and no PITR in the current release — those are planned, separate work.

# Server must be STOPPED — the tool refuses a live data dir.
python scripts/cold_backup.py backup  <data_dir> <archive.tar.gz>

# Recompute every file digest against the per-file SHA-256 manifest.
python scripts/cold_backup.py verify  <archive.tar.gz>

# Restore into a FRESH directory only; refuses non-empty targets and tampered archives.
python scripts/cold_backup.py restore <archive.tar.gz> <fresh_target_dir>

The archive captures the whole data directory byte-for-byte — WAL, RocksDB, Tantivy, HNSW, and cortex.toml — with a per-file SHA-256 manifest. See Backups & Disaster Recovery for the full procedure.

Next steps

• Configuration Foundations — file/env/CLI precedence
• Security & Compliance — encryption, TLS, RBAC, audit
• Profiles & Presets — the Batch profile for high throughput