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-cliRequires 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?" # retrievecortexdb 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.
| Command | What it does | v1 endpoint |
|---|---|---|
cortexdb init | Anonymous signup; persist state.json | POST /v1/auth/signup |
cortexdb preflight | Read-only environment checks | GET /v1/admin/health |
cortexdb plan | What apply would do; writes nothing | (local) |
cortexdb apply / resume / status | Run onboarding, checkpointed | /v1/auth/signup, /v1/admin/ready |
cortexdb doctor | Diagnose an existing install | /v1/admin/{health,ready}, /v1/auth/whoami |
cortexdb verify | Prove write → recall → cleanup | /v1/experience, /v1/recall, /v1/forget |
cortexdb cleanup | Remove what verify/apply created | POST /v1/forget |
cortexdb experience "..." | Store a memory | POST /v1/experience |
cortexdb experience bulk file.jsonl | Bulk-load envelopes | POST /v1/experience/bulk |
cortexdb recall "..." | Stratified context pack | POST /v1/recall (holistic) |
cortexdb search "..." | Granular event hits | POST /v1/recall (granular) |
cortexdb answer "..." | Recall + LLM answer | POST /v1/answer |
cortexdb forget --memory-id ... --reason ... | Delete with audit | POST /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 / conflicts | Bi-temporal record history; contradiction detection | /v1/claims/history, /v1/conflicts |
cortexdb concepts | LLM-synthesized concepts and themes | /v1/concepts |
cortexdb code {...} | Code-plane repos, imports, bundles | /v1/code/* |
cortexdb compose | Structured markdown document from memory | POST /v1/compose |
cortexdb wire | Wire an agent harness to CortexDB, and prove it | (local) |
cortexdb voice status | Voice mode's readiness, the in-process model and the call sessions | /v1/admin/ready, /v1/admin/version |
cortexdb session {start,status,end} SESSION | A 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 ingest | POST /v1/experience per row (or one POST /v1/import with the server-side option) |
cortexdb export -o backup.json | Export memories | POST /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:9f2c1esession 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 readyThen 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.
| Command | What it does | v1 endpoint |
|---|---|---|
cortexdb derivation policy SCOPE [--texts] | The policy in force at a scope, where each rule was set, its hash | GET /v1/derivation/policy |
cortexdb derivation templates [NAME] · derivation taxonomy | The templates (NAME prints one body as JSON) · the sensitive-topic taxonomy and detectors | GET /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 priced | POST /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) FACT | Fix a wrong memory: --value and --valid-from with --replace, --bind with --reject | POST /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 SCOPE | The change feed as JSON lines, for a worker of your own · who reads it | GET /v1/derivation/feed, /feed/consumers |
cortexdb episodes declare SCOPE --file F · episodes delete SCOPE ID | Declare an episode over events you name, or delete one | POST, DELETE /v1/episodes |
--derived-by NAME@VERSION on experience write --triple, beliefs create and episodes declare | Stamp 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 id | GET /v1/memory/about |
cortexdb derivation status SCOPE · derivation decisions SCOPE EVENT · --include derivation on facts and beliefs reads | How memories were made, and what became of one event | /v1/derivation/status, /decisions |
--session ID on recall, search, answer and compose | The 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 createdOne 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:
| Code | Meaning | What to do |
|---|---|---|
0 | Everything passed | Continue |
2 | Usage error | Fix the command line |
10 | A stage failed transiently | Retry |
11 | A stage failed permanently | Act on remediation |
12 | Blocked: a prerequisite is absent, nothing was attempted | Satisfy the prerequisite |
1 | Unexpected internal error | Report 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):
- CLI flags:
--api-key,--endpoint,--actor,--scope,--profile - Environment:
CORTEXDB_API_KEY,CORTEXDB_URL,CORTEXDB_ACTOR,CORTEXDB_SCOPE - Persisted state:
~/.cortexdb/config.toml: endpoint, profile names (human-editable)~/.cortexdb/state.json: token, actor, scope, expiry (managed byinit;0600on 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.readdenied, pass--diagnostics none: CortexDB Cloud tokens don't carrydiagnostics.read(the CLI defaults tonone). - On CortexDB Cloud,
402 PLAN_LIMIT_REACHEDand429 SUBTREE_RATE_LIMITEDmean a plan limit (Plans and limits). - Every authenticated response carries
X-RateLimit-Limit,X-RateLimit-Reset,X-Cortex-Token-Expires-In, andX-Cortex-Token-Expires-At;cortexdb admin usagesurfaces 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.