cortexdb-cli

Command-line interface for CortexDB — the long-term memory layer for AI systems.

Wraps the v1 HTTP API in a small, fast Click + Rich CLI. Anonymous signup in one command, no email or card; works against the public SaaS or any self-hosted CortexDB deployment.

Install

pip install cortexdb-cli

Requires Python 3.10+.

Quickstart

# 1. One-time setup — anonymous signup, writes ~/.cortexdb/state.json
cortexdb init

# 2. Store a memory
cortexdb remember "Q3 revenue: $2.4M. We're on track for $10M ARR by year-end."

# 3. Recall it
cortexdb recall "Q3 revenue?"

# 4. Or just type — drops into a REPL
cortexdb

The signup token has a 7-day TTL on the free tier.

Re-running cortexdb init does not refresh it. init reuses an existing identity and changes nothing; against an expired one it refuses and exits 3. That is deliberate: a new identity is a new brain, and memories written under the old actor stay where they are, unreachable from the new config.

When a token expires you have two safe options:

• cortexdb init --api-key <token> --actor <actor> — keep the same brain with a token you already hold (e.g. from your IdP).
• cortexdb init --force — deliberately start a NEW brain. The previous identity is backed up to state.json.replaced first.

For a second brain alongside the first, isolate instead of replacing: cortexdb --config-dir <dir> init, or set CORTEXDB_HOME.

Commands

cortexdb init                                 anonymous signup; persist token + actor
cortexdb remember "..."                       store a memory (POST /v1/experience)
cortexdb recall   "..."                       recall a stratified context pack
cortexdb search   "..."                       granular event-level search
cortexdb forget   --memory-id ...             delete with audit
cortexdb episodes {list,get,delete}           episode CRUD
cortexdb entities {list,get,link}             entity rollups over the Facts layer
cortexdb admin    {health,usage,layers}       diagnostics
cortexdb import   data.json                   bulk-load (JSON / JSONL / CSV / TXT)
cortexdb export   -o backup.json              export memories
cortexdb config   {show,set}                  view / edit ~/.cortexdb/config.toml
cortexdb                                      interactive REPL

Configuration

Three layers, in precedence order:

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)

The state.json format matches the cortexdb-mcp 0.3.0 server's, so you can copy state across to use both tools from the same anonymous identity.

Pipe-friendly

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

cortexdb recall "Q3 revenue" | jq .context_block
cortexdb entities list      | jq '.[].subject'
echo "remember this"        | cortexdb remember -

Force JSON mode any time with --json.

Auth notes

• The v1 API requires both Authorization: Bearer <PASETO> and X-Cortex-Actor. The CLI stamps both on every request — you never need to pass them by hand.
• 401s show the specific error code (TOKEN_EXPIRED, actor_mismatch, …) and the remediation. Note that TOKEN_EXPIRED is not fixed by re-running cortexdb init — see the identity note above; that would mint a different brain rather than restore access to yours.
• 403s cite the missing capability and the policy tier that denied. If a recall returns diagnostics.read denied, pass --diagnostics none — free-tier tokens don't carry the diagnostics.read capability.

License

Apache-2.0