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 external LLM. Embedding (for vector recall) and blob extraction (Tika / vision / whisper) run locally and are always on. 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	✅ on	Tika (documents), vision (images), whisper (audio). Runs regardless of LLM config.
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 Cohere `rerank-v3.5` key.
`/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 — verified live: 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. A common self-hosted setup pins Ollama's nomic-embed-text (768 dims):

CORTEX_EMBEDDING_PROVIDER=ollama
CORTEX_EMBEDDING_URL=http://ollama:11434
CORTEX_EMBEDDING_MODEL=nomic-embed-text
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). Changing model or dimensions afterward against the same data directory is rejected — start a fresh volume if you need to switch embedders.

CORTEX_EMBEDDING_API_KEY must be non-empty even for Ollama (which ignores the value) — an empty key fails the readiness check.

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."

Triples land as events, not Facts, without enrichment

Writing a triple returns indexed and appears in recall as a raw [triple] event, but facts() / facts(subject=…) return 0 — even with CORTEX_V1_LAYERS_AUTO=1. The event is written deterministically; promotion into the queryable Facts layer still needs the enrichment pipeline. The Graph Memory, Entity Extraction, and Beliefs examples elsewhere in the docs silently 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+).

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_*, /v1/answer returns "/v1/answer disabled (503) provider=anthropic."

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, blob extraction.
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).