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. To call the API endpoints, also pass -e CORTEX_API_KEY=<your-chosen-key> — until you set one, the data API returns 401 (the web UI, bundled docs, and /v1/admin/health work without a key).

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": { "tokens_total": 1500 }
  }'

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

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 CortexDB client class 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.
Production deployment — systemd, reverse proxy, secrets, backups. See docs/PRODUCTION_DEPLOYMENT.md.

Required environment

Variable	Required for	What it does
`OPENAI_API_KEY`	Embeddings + fact extraction	Calls `text-embedding-3-small` for vectors and `gpt-4o-mini` for entity/fact extraction during ingestion.
`ANTHROPIC_API_KEY`	`/v1/answer`	Renders the final answer (Claude is the recommended answer model).
`COHERE_API_KEY`	Optional reranker	If set, switches the recall reranker to Cohere `rerank-v3.5`.

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-1.0.0-linux-amd64.tar.gz
cd cortexdb-1.0.0-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