Self-Hosting Defaults & Prerequisites

What a default self-hosted CortexDB instance does out of the box, and which features are opt-in — enrichment, cross-encoder rerank, and the knowledge graph.

The hosted platform ships with the LLM-derived layers, cross-encoder reranking, and the knowledge graph switched on. A default self-hosted instance does not — several capabilities the docs describe as part of CortexDB's full feature set are opt-in and stay off until you configure a provider. This page is the single reference for that gap. Many other pages link here.

Why the split exists

CortexDB self-hosts in content-only mode by default: it captures, embeds, and retrieves your content without calling any LLM lane. Embedding (for vector recall) is always on and needs a provider (OpenAI or a local Ollama, below). Blob extraction (Tika / vision / whisper) is not on by default: it needs its content processors configured. The derived layers — Facts, Beliefs, Understanding — and graph/rerank retrieval channels require you to wire up a model or an external service. This keeps a bare instance cheap and dependency-free; you turn on what you need.

What runs by default

On a fresh self-hosted cortexdb/cortexdb instance, with only an embedding provider configured:

Capability	Default	Notes
Event capture (WAL)	✅ on	The append-only source of truth. Every `experience` lands here.
Episodes	✅ on	Consolidated from events; no LLM required.
Vector recall (HNSW)	✅ on	Needs an embedding provider (below). Quantization defaults to `TQ2`.
Keyword recall (BM25)	✅ on	Tantivy full-text index.
RRF fusion	✅ on	BM25 + vector results fused with Reciprocal Rank Fusion.
Blob extraction	⛔ opt-in	Configure `CORTEX_DOCUMENT_` (Tika), `CORTEX_IMAGE_` (vision), `CORTEX_AUDIO_*` (whisper). Until then blobs are stored but nothing is extracted; `/v1/admin/ready` reports `content_processors.configured: []`. Not gated on enrichment.
Facts layer	⛔ opt-in	Needs an entity LLM / enrichment. Empty otherwise.
Beliefs layer	⛔ opt-in	Synthesized from Facts. Empty otherwise.
Understanding layer	⛔ opt-in	Same enrichment prerequisite.
Knowledge-graph retrieval	⛔ opt-in	Needs `CORTEX_ENTITY_GRAPH=1` and enrichment.
Cross-encoder rerank	⛔ opt-in	Needs a reranker: a Cohere `rerank-v3.5` key or a local model (see Recall Tuning).
`/v1/answer` (LLM Q&A)	⛔ opt-in	Needs the answer lane configured (see below).

'4-channel hybrid retrieval' is the full capability, not the default

The concepts pages describe 4-channel hybrid retrieval (BM25 + HNSW vectors + graph traversal + cross-encoder reranking). On a default self-hosted instance, recall runs BM25 + vector + RRF fusion only: diagnostics: "full" shows recall.bm25_search, recall.vector_search, and recall.fusion, with no graph or rerank channel. Graph traversal and reranking are the two opt-in channels described below.

Embedding (required for vector recall)

Vector recall needs an embedding provider. Two setups are equally supported; they differ only in where the embedding model runs, and the choice is made once, before the first write (see the pin below).

	OpenAI API (`text-embedding-3-small`, 1536 dims)	Local Ollama (`nomic-embed-text`, 768 dims)
Runs	Nothing extra; the image's default endpoint	An Ollama daemon plus a ~275 MB model, on your hardware
Cost / privacy	Fractions of a cent per 1k tokens; text to embed is sent to OpenAI	Free per call; text never leaves the box
Choose it when	The machine is modest (a laptop, no GPU, limited RAM or disk), or you want the fewest moving parts	The machine is high-end (spare CPU/RAM, ideally a GPU) or the vectors must stay on-premises

OpenAI API (the image default, so only the key is needed):

CORTEX_EMBEDDING_API_KEY=sk-...           # text-embedding-3-small at 1536 dims is implied

Local Ollama:

CORTEX_EMBEDDING_PROVIDER=ollama
CORTEX_EMBEDDING_URL=http://ollama:11434
CORTEX_EMBEDDING_MODEL=nomic-embed-text
CORTEX_EMBEDDING_DIMS=768
CORTEX_EMBEDDING_API_KEY=ollama          # must be non-empty even for Ollama
CORTEX_EMBEDDING_HTTP_TIMEOUT_SECS=30

The embedding provider is pinned to the data directory

On first boot CortexDB writes an embedding_provider.pin file (e.g. ollama:nomic-embed-text:768 or openai-http:text-embedding-3-small:1536). Starting later with a different model or dimensions against the same data directory is refused at boot, so pick the provider before you ingest anything. Changing your mind later is supported as a deliberate offline rebuild (CORTEX_EMBEDDING_ALLOW_REPIN=1 + CORTEX_EMBEDDING_REBUILD_VECTORS=1, then a per-scope vector refill); see Changing the embedding model on an existing store. On earlier images the only path is a fresh volume.

CORTEX_EMBEDDING_API_KEY must be non-empty even for Ollama (which ignores the value) — an empty key fails the readiness check, and a configured endpoint with no credential refuses to boot rather than fall back to mock vectors.

Enrichment (required for Facts / Beliefs / Understanding)

The Facts, Beliefs, and Understanding layers are LLM-derived. Without an enrichment model configured, a self-hosted instance boots in content-only mode and those layers stay empty — boot logs a WARN like "legacy fact pipeline not configured — facts+beliefs will stay empty."

Triple captures write facts without enrichment

A triple capture writes its fact directly, with no LLM call, so it is on GET /v1/facts as soon as a ?wait=indexed write returns, and POST /v1/beliefs/build can build beliefs from it. Facts extracted from free text, and the Graph Memory and Entity Extraction examples elsewhere in the docs, need enrichment and return empty on a content-only instance.

To turn enrichment on, configure the enrichment router (it has its own key — it does not reuse the answer lane's):

CORTEX_ENRICHMENT_DELAY_SECONDS=5        # enables the async enrichment scanner
CORTEX_ENRICHMENT_MODEL=gpt-4o-mini      # the LLM used for fact augmentation
CORTEX_ENRICHMENT_URL=...                # falls back to CORTEX_LLM_URL if unset
CORTEX_ENRICHMENT_API_KEY=...            # falls back to OPENAI_API_KEY / LLM_API_KEY

Boot confirms success with "Enrichment LLM router enabled for fact augmentation." Facts populate within ~5–30 s of a write; Beliefs and Understanding are synthesized asynchronously (minutes+). With gpt-4o-mini, enrichment costs about $0.40 per 1,000 events; see Cost Planning.

The answer lane (`/v1/answer`)

/v1/answer (natural-language Q&A with citations) routes through a separate LLM lane from entity extraction. Setting CORTEX_LLM_* alone is not enough — that configures the entity-extraction lane. Without CORTEX_ANSWER_* (or a bare ANTHROPIC_API_KEY, which enables the baked claude-opus-4-6), /v1/answer returns 503 ANSWER_UNAVAILABLE ("no answer LLM is configured on this deployment").

Recommended hosted setup (about 2 to 4 cents per answer; gpt-5.6-luna for about a tenth of that; see Cost Planning):

CORTEX_ANSWER_PROVIDER=openai
CORTEX_ANSWER_URL=https://api.openai.com/v1
CORTEX_ANSWER_API_KEY=sk-...
CORTEX_ANSWER_MODEL=gpt-5.6-terra

Fully local, on hardware that can run a capable model (see Ollama):

CORTEX_ANSWER_PROVIDER=ollama
CORTEX_ANSWER_URL=http://ollama:11434
CORTEX_ANSWER_API_KEY=ollama
CORTEX_ANSWER_MODEL=llama3.1

Cloud-default model names are overridden self-hosted

The image bakes CORTEX_ANSWER_PROVIDER=anthropic and CORTEX_ANSWER_MODEL=claude-opus-4-6 as the cloud defaults. Self-hosted, set the four CORTEX_ANSWER_* vars to your own provider — the baked-in model name does not apply.

Content-only recall and capture work fine without the answer lane; only /v1/answer needs it.

Cross-encoder rerank (Cohere)

Cross-encoder reranking uses Cohere rerank-v3.5 (an external service). It is off by default; supply a Cohere key via the reranker settings (CORTEX_RERANKER_*) to enable the rerank channel. Recall works without it — RRF fusion of BM25 + vector is the default ranking.

Knowledge graph

Graph-fused retrieval is gated behind CORTEX_ENTITY_GRAPH=1 and enrichment (the graph is built from extracted entities/Facts). config_lint notes the cost: "~3x write / ~4x recall cost."

Graph traversal is not a recall request parameter

Graph traversal is an internal fused channel, not an API surface. There is no graph field in the /v1/recall body — sending one returns 422 "unknown field graph" even with CORTEX_ENTITY_GRAPH=1. See Knowledge Graph.

Quick reference: default vs opt-in

Always on (with embedding configured): event capture, episodes, BM25 + vector + RRF recall.
Needs content processors: blob extraction (Tika / vision / whisper).
Needs enrichment: Facts, Beliefs, Understanding, and the knowledge graph (graph also needs CORTEX_ENTITY_GRAPH=1).
Needs its own provider: /v1/answer (answer lane), cross-encoder rerank (Cohere).