Getting Started with CortexDB

CortexDB is a long-term memory layer for AI agents and applications. This guide gets you from zero to a running instance with stored, retrievable memories in under five minutes.

Run it (Docker — recommended)

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

The server starts immediately in local no-auth mode: every request is served as user:local and, outside Docker, the server binds to loopback only. To require authentication, pass -e CORTEX_API_KEY=<your-chosen-key> — data routes then require Authorization: Bearer <your-chosen-key> (the key value itself is the credential), wrong or missing keys get 401, and anonymous signup is disabled. The web UI, bundled docs, and /v1/admin/health work without a key in both modes.

That's it. The server is listening on :3141, serving the v1 API and the built-in admin UI. Probe with:

curl http://localhost:3141/v1/admin/health
# {"status":"healthy","version":"..."}

First memories

# Capture an experience
curl -X POST http://localhost:3141/v1/experience \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": "ws:demo",
    "modality": "observation",
    "content": { "kind": "text", "text": "Priya at Acme Corp signed for 200 seats. Q3 close." },
    "context": { "observed_at": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'" },
    "idempotency_key": "'"$(uuidgen)"'"
  }'

# Recall
curl -X POST http://localhost:3141/v1/recall \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": "ws:demo",
    "query": "How many seats did Acme sign for?",
    "budgets": { "max_tokens": 1500 }
  }'

You should see the stored memory come back as part of the recall pack.

Episodes and beliefs (the five-layer claim)

Events go in immediately. Episodes (session clusters) and beliefs (aggregated fact statements) are derived layers — they don't materialize until a synthesis pass runs.

As of v0.4.0 the synthesis scheduler is on by default (audit BLK-1). As of v0.6.3 it is also event-driven: writes and completed enrichment batches wake it directly, so episodes/beliefs typically materialize within a couple of seconds of the enrichment LLM finishing — the 60s tick is only a fallback heartbeat. Store a few events and check /v1/episodes and /v1/beliefs a few seconds later.

LLM spend has two switches. CORTEX_ENRICHMENT_DELAY_SECONDS drives fact extraction (facts → beliefs); CORTEX_V1_LAYERS_AUTO drives the synthesis scheduler whose concept-reflection stage also calls the LLM. With both unset, nothing calls an LLM in the background: episodes still build (deterministic), facts/beliefs stay empty, and concept reflection is gated off — /v1/admin/layers/stats reports health.concepts_gated_by: "enrichment_unset".

Retrieval & answer knobs (v0.8.6)

If you don't want to wait for the scheduler, trigger synthesis explicitly:

client.build_episodes(scope=SCOPE)   # → {"built": N, ...}
client.build_beliefs(scope=SCOPE)    # → {"built": N, ...}
client.synthesize(scope=SCOPE)       # → {"job_id": "...", "status": "running", "lifecycle_stream": "..."}

build_episodes and build_beliefs return synchronously. synthesize (concept reflection) is async — it returns a job id immediately and runs in the background; poll lifecycle_stream for completion before reading from /v1/understanding.

What you'll likely want next

• Browser UI — open http://localhost:3141 in a browser. The built-in admin panel lets you capture experiences and browse all five memory layers (Events, Facts, Beliefs, Episodes, Concepts).

• SDKs — pip install cortexdbai or npm i cortexdbai. Both ship a Cortex client class (Python from cortexdb import Cortex; TypeScript import { CortexDB } from "cortexdbai") that talks to whatever server URL you point it at (defaults to http://localhost:3141). See docs/API_REFERENCE_V1.md in this package or the live docs at https://cortexdb.ai/docs.

  Naming note (audit POL-2): the PyPI package is cortexdbai but you import cortexdb (or from cortexdb.v1 import V1Client). The npm package is also cortexdbai; the import remains import { V1Client } from "cortexdbai/v1". The unrelated cortexdb package on PyPI/npm is a different project — don't install that one.

• Production deployment — systemd, reverse proxy, secrets, backups. See docs/PRODUCTION_DEPLOYMENT.md.

Required environment

Without OpenAI, writes still succeed but no embeddings or extracted facts are produced — recall will be markedly weaker. Without Anthropic, /v1/answer returns 503; everything else works.

See docs/PRODUCTION_DEPLOYMENT.md for the full env-var reference.

Default config (matches our published benchmarks)

The Docker image bakes in the same recall/answer configuration that scored 93.8% on LongMemEval-S and 85.5% on LoCoMo (cats 1-4). Specifically:

• Answer model: claude-opus-4-6 (1500 tok)
• Verifier model: gpt-4.1 for single-session-user questions
• Entity/enrichment LLM: gpt-4o-mini
• Embeddings: text-embedding-3-small @ 1536-dim
• Fact validity filter ON · compositional reducer ON · direct-lookup retry on abstain ON · quantity-sum reducer ON

Override anything at runtime with -e VAR=value or --env-file your.env. The bench-reproducer doc (docs/REPRODUCE_LONGMEMEVAL_93_8.md in the repo) lists every load-bearing flag with a one-line explanation.

If you're running cortexdb continuously (not just for a benchmark), no extra config is needed. If you're reproducing the benchmark exactly, also set CORTEX_SCHEDULER_DISABLE=1 (skips background compaction during the run).

Run it (binary — for the Docker-haters)

Download the right tarball for your platform from https://github.com/cortexdb/cortexdb-releases/releases/latest and:

tar -xzf cortexdb-*-linux-amd64.tar.gz
cd cortexdb-*-linux-amd64
export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
./cortexdb 3141 ./data

The binary expects assets/wordnet_synonyms.json to live alongside it (included in the tarball).

Where data lives

Inside the container: /data (a Docker volume). Outside (binary install): the directory you pass as the second argument.

The directory contains:

• wal/ — append-only event log (RocksDB)
• vector/, entity_vector/ — HNSW indexes + sidecar snapshots
• graph/, temporal/, fulltext/ — derived indexes
• fact_store.snap.bin, scope_registry.snap.bin — checkpoints
• cognitive/ — long-running cognitive state

Back this directory up with the server stopped (or use RocksDB's checkpoint APIs if you need hot backups).

Get help

• Docs site: https://cortexdb.ai/docs
• Issues: https://github.com/cortexdb/cortexdb/issues
• Enterprise / cloud: https://cortexdb.ai/contact