CortexDB Docs
Docs for CortexDB 0.16.1, the version running on CortexDB Cloud (api.cortexdb.ai).
SDKs & Clients

Command-Line Interface

cortexdb: a fast, full-coverage CLI for the v1 memory API.

cortexdb-cli is a Click + Rich CLI that wraps the v1 HTTP API in a small, fast binary. It works against CortexDB Cloud or any self-hosted CortexDB deployment.

pip install cortexdb-cli

Requires Python 3.10+. The cortexdb-cli version line is independent of the CortexDB server version; see Versioning and SDK compatibility.

The happy path on CortexDB Cloud

Create an API token on your dashboard (it shows your actor and default scope too), put the four values in the environment, and go:

export CORTEXDB_URL=https://api-v1.cortexdb.ai
export CORTEXDB_API_KEY='<your API token>'
export CORTEXDB_ACTOR=user:acct_42
export CORTEXDB_SCOPE=org:acct_42/user:acct_42

cortexdb experience "Q3 revenue: $2.4M, $10M ARR target"   # store
cortexdb recall     "Q3 revenue?"                          # retrieve

cortexdb init signs up anonymously instead (POST /v1/auth/signup) and persists the identity to ~/.cortexdb/state.json (mode 0600 on POSIX). That needs a server whose minter allows anonymous signup, such as a self-hosted dev server started with CORTEX_V1_MINTER_ENABLE=1; CortexDB Cloud has it off, since its accounts come from cortexdb.ai.

Commands

This table is a curated subset

The CLI ships more commands than are listed here. The full set also includes audit, claims, code, compose, concepts, conflicts, and wire: run cortexdb --help for the authoritative list. code is the Code Intelligence Plane CLI.

CommandWhat it doesv1 endpoint
cortexdb initAnonymous signup; persist state.jsonPOST /v1/auth/signup
cortexdb preflightRead-only environment checksGET /v1/admin/health
cortexdb planWhat apply would do; writes nothing(local)
cortexdb apply / resume / statusRun onboarding, checkpointed/v1/auth/signup, /v1/admin/ready
cortexdb doctorDiagnose an existing install/v1/admin/{health,ready}, /v1/auth/whoami
cortexdb verifyProve write → recall → cleanup/v1/experience, /v1/recall, /v1/forget
cortexdb cleanupRemove what verify/apply createdPOST /v1/forget
cortexdb experience "..."Store a memoryPOST /v1/experience
cortexdb experience bulk file.jsonlBulk-load envelopesPOST /v1/experience/bulk
cortexdb recall "..."Stratified context packPOST /v1/recall (holistic)
cortexdb search "..."Granular event hitsPOST /v1/recall (granular)
cortexdb answer "..."Recall + LLM answerPOST /v1/answer
cortexdb forget --memory-id ... --reason ...Delete with auditPOST /v1/forget
cortexdb episodes {list,get,delete}Episode + event ops/v1/episodes, /v1/events/{id}
cortexdb entities {list,get,link}Entity rollups/v1/facts
cortexdb facts {list,timeline}Typed triples + bi-temporal lineage/v1/facts, /v1/facts/timeline
cortexdb beliefs {list,why,build}Aggregated beliefs + provenance/v1/beliefs*
cortexdb understanding {list,coverage,synthesize}Synthesized concepts/v1/concepts, /v1/concepts/coverage, /v1/understanding/synthesize
cortexdb scopes {list,register,members}Hierarchical scopes/v1/scopes*
cortexdb auth {whoami,signup,tokens,revoke}Identity + mint + revoke/v1/auth*
cortexdb policy {effective,deployment}What can this actor do, where?/v1/policy*
cortexdb admin {health,usage,layers}Diagnostics/v1/auth/whoami, /v1/admin/layers/stats
cortexdb admin retention {show,set,sweep,delete}Retention rules and the expiry sweep/v1/admin/retention, /v1/admin/retention/policies, /v1/admin/retention/sweep: see Retention & WAL
cortexdb admin wal {status,compact}Unified WAL census and dead-row compaction/v1/admin/wal, /v1/admin/wal/compact
cortexdb audit {status,verify}Audit hash-chain integrity/v1/audit*
cortexdb claims / conflictsBi-temporal record history; contradiction detection/v1/claims/history, /v1/conflicts
cortexdb conceptsLLM-synthesized concepts and themes/v1/concepts
cortexdb code {...}Code-plane repos, imports, bundles/v1/code/*
cortexdb composeStructured markdown document from memoryPOST /v1/compose
cortexdb wireWire an agent harness to CortexDB, and prove it(local)
cortexdb voice statusVoice mode's readiness, the in-process model and the call sessions/v1/admin/ready, /v1/admin/version
cortexdb session {start,status,end} SESSIONA live voice call's session and its brief/v1/sessions*
cortexdb reembed {estimate,start,status,cancel,cleanup}Move a single node to another embedding model while it serves/v1/admin/reembed*
cortexdb import data.{json,jsonl,csv,txt}Bulk ingestPOST /v1/experience per row (or one POST /v1/import with the server-side option)
cortexdb export -o backup.jsonExport memoriesPOST /v1/export
cortexdb config {show,set}Edit ~/.cortexdb/config.toml(local)
cortexdb (no args)Interactive REPL(wraps the above)

cortexdb auth tokens: --scope does not confine

cortexdb auth tokens --scope PATH only says where your own auth.mint is checked; it does not confine the token. To confine it, pass --confine CAP:PREFIX (repeatable), which is sent as the token's scopes claim:

cortexdb auth tokens --subject agent:b --ttl 3600 --confine 'scope.read:org:acme/team:b/*'

The CLI refuses a --scope value that looks like a CAP:PREFIX entry and points you at --confine. See Auth for how scope, scopes and caps differ.

cortexdb remember "..." is a hidden alias for experience: kept so old scripts and muscle memory keep working.

--wait indexed and the 30-second budget

The CLI's HTTP timeout is 30 s, the same as the server's wait budget, so cortexdb experience --wait indexed "…" against a server that can't index in time ends with the CLI's own Request timed out. (exit code 2) after about 30 s, not the server's 408 WAIT_TIMEOUT. The write is captured and durable either way. The CLI derives each write's idempotency_key from the scope and the text, so re-running the same command replays that write instead of storing it twice.

Voice mode

On a server in voice mode, check it is ready, open a call and recall on the voice path:

cortexdb voice status
cortexdb session start call_01JF8M2Q7R --scope ws:acme/caller:9f2c1e --query "billing question"
cortexdb recall "what did I order last time" --scope ws:acme/caller:9f2c1e \
  --profile voice --session call_01JF8M2Q7R
cortexdb session end call_01JF8M2Q7R --scope ws:acme/caller:9f2c1e

session start also takes --max-tokens, --include, --deadline-ms and --idle-timeout-s; recall takes --alpha (0.0 to 1.0, vector search against keyword search) on any recall.

To move an existing store to voice mode, or to any other embedding model, run the online re-embed:

cortexdb reembed estimate --to local:potion-multilingual-128M   # what the move would take
cortexdb reembed start --to local:potion-multilingual-128M
cortexdb reembed status --watch                                  # until the state is ready

Then restart with the settings the estimate names. reembed cancel and reembed cleanup match the admin routes; --to also takes openai:text-embedding-3-large --dims 3072.

Governed memory

Governed memory lets you decide what CortexDB's background enrichment learns from your events, and correct what it learned wrongly. The commands below need a server that lists the matching capability in GET /v1/admin/version.

Check the capability first

Against a server without the capability each route answers 404, which reads like "not found" (for most of these routes the CLI's hint then names the capability the server lacks). Check that GET /v1/admin/version lists the capability first: derivation_policy_v1, corrections_v1, derivation_review_v1, derivation_rederive_v1, derivation_feed_v1, derived_by_v1, declared_episodes_v1, derivation_use_rules_v1 or derivation_provenance_v1. They are experimental, and a server held at data format 10 answers 503 FORMAT_UPGRADE_PENDING on most of these routes.

CommandWhat it doesv1 endpoint
cortexdb derivation policy SCOPE [--texts]The policy in force at a scope, where each rule was set, its hashGET /v1/derivation/policy
cortexdb derivation templates [NAME] · derivation taxonomyThe templates (NAME prints one body as JSON) · the sensitive-topic taxonomy and detectorsGET /v1/derivation/templates, /taxonomy
cortexdb derivation test SCOPE --file F [--recent N] [--max-cost USD]Run a draft over a sample of your events: each candidate's verdict and the rule that decided it. Needs enrichment on (a server with it off answers 409 ENRICHMENT_OFF). Writes nothing; its model calls are pricedPOST /v1/derivation/policy/test
cortexdb derivation stage SCOPE (--file F | --template NAME)Stage, preview and activate a policy as a change set (asks before it activates)/v1/access/changes*
cortexdb derivation settings SCOPE [--mode M] [--deny-topic T] [--consent CAT:PURPOSE] [--delete]Show or change a subject's own settings and consents; they take effect at once/v1/derivation/settings
cortexdb derivation texts SCOPE [--erase ID]A policy's instructions and examples, and their erasure/v1/derivation/texts*
cortexdb corrections add SCOPE (--reject | --replace | --pin | --confirm) FACTFix a wrong memory: --value and --valid-from with --replace, --bind with --rejectPOST /v1/corrections
cortexdb corrections {list,show,undo} SCOPE [ID]List, read or undo corrections/v1/corrections*
cortexdb review list SCOPE · review {approve,reject} SCOPE HELD…The candidates a policy held for review · decide them/v1/review*
cortexdb derivation rederive SCOPE --mode regate|reextract [--apply]Bring what was learned in line with the policy in force: a dry run unless --apply (a reextract apply also names --estimate and --cap)POST /v1/derivation/rederive
cortexdb derivation {job,cancel} SCOPE JOB_ID · derivation report SCOPE [--csv]Follow or stop a job · what was derived over a period, counts and ids only/v1/derivation/rederive/*, /report
cortexdb derivation feed SCOPE --consumer NAME [--follow] [--cursor-file F] · derivation consumers SCOPEThe change feed as JSON lines, for a worker of your own · who reads itGET /v1/derivation/feed, /feed/consumers
cortexdb episodes declare SCOPE --file F · episodes delete SCOPE IDDeclare an episode over events you name, or delete onePOST, DELETE /v1/episodes
--derived-by NAME@VERSION on experience write --triple, beliefs create and episodes declareStamp a write-back with the pipeline that made it(a field of the write)
cortexdb memory about SCOPE [--corrections]What is known about a subject, each item with its sources and its fact idGET /v1/memory/about
cortexdb derivation status SCOPE · derivation decisions SCOPE EVENT · --include derivation on facts and beliefs readsHow memories were made, and what became of one event/v1/derivation/status, /decisions
--session ID on recall, search, answer and composeThe session a read is made in: where an opt-in read-time use rule is in force, memory from other sessions is withheld. A server without that capability refuses it on recall and search with 422 INVALID_BODY (an unknown field) and ignores it on answer and compose: pass it only to a server whose GET /v1/admin/version lists derivation_use_rules_v1(a field of the read)

Test a template on your own events, then stage it:

SCOPE=org:acme/app:companion
cortexdb derivation templates consumer > policy.json        # a template's body, to edit
cortexdb derivation test "$SCOPE" --file policy.json --recent 20 --max-cost 0.25
cortexdb derivation stage "$SCOPE" --file policy.json --reason "consumer defaults"
cortexdb derivation policy "$SCOPE"                         # the policy in force, and its hash

--max-cost caps the test's model spend, which is reserved from the tenant's daily budget of tests and dry runs. A topic rule depends on the extraction model's topic labels, so a denied topic can still be learned when the model labels a candidate otherwise; detectors and the structural rules (stages, sources, grounding, writer rules) are exact. To fix a wrong memory, use cortexdb corrections add rather than cortexdb forget: what a forget of derived memory removes can be learned again from the events that are kept, while a corrected claim stays corrected. corrections add --reject, corrections undo and review reject ask first on a terminal; a script passes --yes.

The routes in full: Derivation Policies, Corrections, Review, Re-derivation, Change Feed and Memory About.

Onboarding and diagnostics

Eight commands exist specifically so a coding agent can install, verify and diagnose CortexDB without guessing. They share one output envelope and one exit-code contract.

cortexdb preflight            # can this machine talk to CortexDB at all?
cortexdb plan                 # what would apply do? (no writes)
cortexdb apply                # do it, checkpointing after each stage
cortexdb resume               # continue after an interruption
cortexdb doctor               # why is my existing install unhappy?
cortexdb verify               # prove write -> recall -> cleanup end to end
cortexdb cleanup              # remove what verify/apply created

One envelope

Every one of them emits the same document, so you parse one shape rather than eight. --json works before or after the subcommand, and is implied when stdout is not a TTY.

{
  "schema": "cortexdb.cli.diagnostic/v1",
  "command": "doctor",
  "ok": false,
  "exit_code": 11,
  "outcome": "failure",
  "first_failing_stage": "authenticated",
  "counts": { "pass": 4, "fail": 1, "skip": 0, "blocked": 1 },
  "stages": [
    {
      "id": "authenticated",
      "title": "Token is accepted",
      "state": "fail",
      "detail": "HTTP 401: token expired",
      "retriable": false,
      "remediation": "The token is missing, expired or revoked. Run `cortexdb init`.",
      "doc_url": "https://cortexdb.ai/docs/api-reference/auth"
    }
  ]
}

Every stage that is not pass carries retriable, remediation and doc_url.

Exit codes

Branch on these instead of parsing the message:

CodeMeaningWhat to do
0Everything passedContinue
2Usage errorFix the command line
10A stage failed transientlyRetry
11A stage failed permanentlyAct on remediation
12Blocked: a prerequisite is absent, nothing was attemptedSatisfy the prerequisite
1Unexpected internal errorReport the JSON

blocked is deliberately distinct from fail: "you have no credentials" and "your credentials were rejected" need different responses.

Stages are idempotent

Each stage probes before it acts, so a stage that is already satisfied reports skip with the reason. Re-running a partial onboarding is safe, apply never mints a second identity, and resume is simply apply reading the checkpoint at ~/.cortexdb/onboarding.json.

apply stops at the first failing stage rather than continuing.

verify is safe against a real deployment

verify writes one synthetic marker with ?wait=indexed, so read-your-writes is guaranteed by the time the write returns. Everything it writes goes into a cortexdb-cli-verify leaf subtree of your scope, and cleanup removes exactly that subtree: it cannot reach your real data. Pass --keep to leave the marker in place for inspection.

Pipe-friendly

Auto-detects when stdout isn't a TTY and switches to JSON:

cortexdb recall "Q3 revenue" | jq .context_block
cortexdb facts list          | jq '.items[] | {predicate, object}'
echo "remember this"         | cortexdb experience -
cat envelopes.jsonl          | cortexdb experience bulk -

Force JSON any time with --json.

Configuration

Three layers, in precedence order (high to low):

  1. CLI flags: --api-key, --endpoint, --actor, --scope, --profile
  2. Environment: CORTEXDB_API_KEY, CORTEXDB_URL, CORTEXDB_ACTOR, CORTEXDB_SCOPE
  3. Persisted state:
    • ~/.cortexdb/config.toml: endpoint, profile names (human-editable)
    • ~/.cortexdb/state.json: token, actor, scope, expiry (managed by init; 0600 on POSIX)

state.json is not a drop-in copy to the MCP server

The CLI and connectors use ~/.cortexdb/state.json, while cortexdb-mcp reads <APPDATA|XDG>/cortexdb-mcp/state.json: and the key names differ: the CLI writes { token, user_id, scope, expires_at }, the MCP server reads { token, actor, scope }. Reusing one anonymous identity across both tools means copying the file to the other tool's path and renaming user_id ↔ actor; a straight copy leaves the MCP server without an actor, so its calls fail the actor-vs-token check.

Also available: --config-dir (env CORTEXDB_HOME) isolates one project's identity and checkpoints from another's; --profile alone does not.

Auth notes

Against the cloud (and any server with CORTEX_API_KEY set), authenticated requests carry both Authorization: Bearer <token> and X-Cortex-Actor: the bearer is a PASETO v4 token, or the CORTEX_API_KEY value itself on self-hosted servers. The CLI stamps both for you.

Local no-auth mode is opt-in

A self-hosted server started with CORTEX_INSECURE_NO_AUTH=1 serves everything as user:local: no headers required (and /v1/admin/health / ready never need auth). Otherwise the CLI sends the CORTEX_API_KEY value as the bearer for you; a keyless, network-exposed server auto-generates a key and requires it.

  • 401s show the specific error code (EXPIRED_TOKEN, ACTOR_MISMATCH, INVALID_TOKEN_SIGNATURE) and the remediation: on CortexDB Cloud, a new token from your dashboard.
  • 403s cite the missing capability and the policy tier that denied. If a recall returns diagnostics.read denied, pass --diagnostics none: CortexDB Cloud tokens don't carry diagnostics.read (the CLI defaults to none).
  • On CortexDB Cloud, 402 PLAN_LIMIT_REACHED and 429 SUBTREE_RATE_LIMITED mean a plan limit (Plans and limits).
  • Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Reset, X-Cortex-Token-Expires-In, and X-Cortex-Token-Expires-At; cortexdb admin usage surfaces them.

Profiles

Run against multiple deployments by passing --profile:

cortexdb --profile prod --endpoint https://api-v1.cortexdb.ai --api-key "$PROD_TOKEN" --actor user:acct_42 auth whoami
cortexdb --profile staging init --endpoint https://staging.cortexdb.example
cortexdb --profile staging experience "test memory"

Each profile gets its own block in ~/.cortexdb/config.toml. The state.json is shared: if you need separate identities per profile, run cortexdb auth signup --save after switching, or isolate with --config-dir.

See also

  • Python SDK: programmatic access from Python.
  • TypeScript SDK: programmatic access from JS/TS.
  • MCP Server: same v1 surface exposed to Claude / Cursor / VS Code Copilot.
  • Auth: how tokens, actors, and capabilities fit together.

On this page