CortexDB Docs
Docs for CortexDB 0.16.1, the version running on CortexDB Cloud (api.cortexdb.ai).
Self-Hosting

Upgrading

Move a self-hosted server, its clients and its connectors to a newer release, what each upgrade does to existing data, and how to roll back.

Start on CortexDB Cloud

We recommend starting on CortexDB Cloud: sign up on cortexdb.ai and you have an endpoint and a token in two minutes, with nothing to run. If you need CortexDB on-prem or on your own infrastructure, talk to us and we will provide a self-host license. Licensed releases then come from the customer portal, and these pages cover running them.

The rest of these docs describe the current release. This page is the one place that lists what changes when you move an existing deployment forward, and how to do it without losing settings or data. The steps below were run end to end on a licensed 0.14.2 server upgraded to 0.15.2, for both a Docker install and a Linux binary install.

Before you start

  1. Find the version you run: curl -s http://127.0.0.1:3141/v1/admin/version (use your port).
  2. Find how it was installed. The portal installer makes either a Docker container (named cortexdb unless you set CORTEXDB_NAME) or a Linux binary under ~/cortexdb (or CORTEXDB_DIR).
  3. Find your path in the table below and read its section before you stop anything.
FromToKind of upgradeRead
0.15.x0.16.1Drop-in, not one way: a 0.15.x release still opens the directory, unless it was moved to the built-in embedding modelFrom 0.15.x to 0.16.1
0.15.0 or 0.15.10.15.2Drop-in: an older 0.15 release still opens the directoryThe steps below
0.14.x0.15.xOne way (data format 11): back up firstFrom 0.14.x to 0.15.x
0.14.0 or 0.14.10.14.2Drop-inThe steps below
0.13.x0.14.xOne way (data format 10): back up firstFrom 0.13.x to 0.14.0
0.12.x0.13.xDrop-in; a single node can go back by changing the image againThe steps below
0.11.x0.12.xDrop-in; from 0.12.1 the server needs your licenseThe license note below
0.10.x0.11.0 or laterOne way (data migration)From 0.10.x to 0.11.0 or later
0.9.x0.10.xChanges for existing deploymentsFrom v0.9.13 to v0.10.1, From v0.9.9 or earlier

Each release's notes describe its one-way step from the release just before it. To cross more than one one-way release in a single upgrade (for example from 0.13.x straight to 0.15.2), check the path with your CortexDB contact first.

What not to do (people and agents alike)

  • Don't re-run the installer. It installs; it never upgrades. On a machine that already has a cortexdb container or install folder it stops, by design.
  • Don't docker rm -f the server, and don't docker pull. There is no public image to pull: licensed images come from the portal as a file you docker load.
  • Don't retype the docker run from memory or from an example. Start the new release with the old one's exact settings (the steps below do this for you). A different embedding provider or model stops the server at start, and a missing CORTEX_API_KEY locks out every client.
  • Don't delete a file or record that an error names until you have read the release notes. Some records are meant to be there (see From 0.14.x to 0.15.x).
  • Don't upgrade from the console's Updates page. Its update check doesn't see licensed releases, and its one-click updater cannot install them. New releases are on the portal's Releases page.
  • An agent doing the upgrade stops and asks a person before the first start of a one-way release, and shows that the backup verified.

Moving to 0.12.1 or later from an earlier release: add your license once

From 0.12.1 a server runs under your company's license. Add -e CORTEX_LICENSE to the new container after export CORTEX_LICENSE='<your license>' (copy it from the release page's License section), or paste the license on the console's License page afterwards. Without one the server keeps serving for 14 days. After that first time the server keeps the license itself. See Your license.

Installer scripts contain your license

A cortexdb-install.sh downloaded from the portal carries your company license. Delete it from the folder you ran the installer in, along with any other saved copy, and check anything that logged it. Deleting a copy does not affect the license itself. If a copy leaked, ask your CortexDB contact about rotating it.

Upgrade a Docker install

1. Load the new image. On the new release's page on customer.cortexdb.ai, take the "Docker image, x86-64" file and its SHA-256 (or download it with your agent key), check it and load it. Run only these three steps: the release page's own docker run creates a new, empty server.

export CORTEXDB_KEY='<your agent key>'      # from the portal's Keys page
curl -fL -H "Authorization: Bearer $CORTEXDB_KEY" -o cortexdb-0.16.1-image-linux-amd64.tar.gz \
  https://customer.cortexdb.ai/d/0.16.1/image-linux-amd64
echo "<SHA-256 from the release page>  cortexdb-0.16.1-image-linux-amd64.tar.gz" | sha256sum -c -
docker load -i cortexdb-0.16.1-image-linux-amd64.tar.gz      # prints: Loaded image: cortexdb/cortexdb:v0.16.1

2. Stop the server and back it up with the release it runs now. The backup is your way back from a one-way upgrade, and it must be made with the old release.

NAME=cortexdb                               # your container (CORTEXDB_NAME if you set one)
OLD_IMAGE="$(docker inspect -f '{{.Config.Image}}' "$NAME")"
VOLUME="$(docker inspect -f '{{range .Mounts}}{{if eq .Destination "/data"}}{{if .Name}}{{.Name}}{{else}}{{.Source}}{{end}}{{end}}{{end}}' "$NAME")"
docker stop -t 120 "$NAME"                  # graceful stop: never docker rm -f a running server
docker run --rm -v "$VOLUME":/data -v "$PWD":/backup --entrypoint cortexdb "$OLD_IMAGE" \
  backup /data /backup/cortexdb-$(date +%F).tar.gz
docker run --rm -v "$PWD":/backup --entrypoint cortexdb "$OLD_IMAGE" \
  backup-verify /backup/cortexdb-$(date +%F).tar.gz              # prints: archive verified: …

3. Start the new release with the same settings, in the same shell as step 2. This keeps the old container (renamed cortexdb-previous, stopped) and starts the new image with its network, ports, volumes and your own environment settings: license, API key, embedding provider, everything you passed with -e, but not the defaults the old image set itself. The settings are read through <( … ), so no file with your keys is written. Run it with bash.

NEW=cortexdb/cortexdb:v0.16.1               # the tag docker load printed
NET="$(docker inspect -f '{{.HostConfig.NetworkMode}}' "$NAME")"
PORTS="$(docker inspect -f '{{range $p, $b := .HostConfig.PortBindings}}{{range $b}}-p {{if .HostIp}}{{.HostIp}}:{{end}}{{.HostPort}}:{{$p}} {{end}}{{end}}' "$NAME")"
VOLUMES="$(docker inspect -f '{{range .Mounts}}-v {{if .Name}}{{.Name}}{{else}}{{.Source}}{{end}}:{{.Destination}} {{end}}' "$NAME")"
docker rename "$NAME" "$NAME-previous"
docker run -d --name "$NAME" --restart unless-stopped --stop-timeout 120 \
  --network "$NET" $PORTS $VOLUMES \
  --env-file <(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' "$NAME-previous" \
               | grep -vxF -f <(docker image inspect -f '{{range .Config.Env}}{{println .}}{{end}}' "$OLD_IMAGE")) \
  "$NEW"

4. Check it (Check the upgrade). When you trust the new release, remove the old container with docker rm "$NAME-previous"; the volume stays. For a drop-in release you can go back until then: stop the new container, rename it aside, rename cortexdb-previous back and docker start it.

With Docker Compose, load the image and take the backup as above, then change the image tag in the Compose file and run docker compose up -d: Compose keeps the file's settings. Set stop_grace_period: 120s on the service.

Upgrade a Linux binary install

The Linux binary needs glibc 2.39 or later (for example Ubuntu 24.04 or Debian 13); on an older host it stops at once with version `GLIBC_2.39' not found. Use the Docker image there.

1. Download and unpack the new release into its own folder, next to the old one. Don't run the release page's binary commands: they start the new server straight away.

DIR="${CORTEXDB_DIR:-$HOME/cortexdb}"
export CORTEXDB_KEY='<your agent key>'
curl -fL -H "Authorization: Bearer $CORTEXDB_KEY" -o cortexdb-0.16.1-linux-amd64.tar.gz \
  https://customer.cortexdb.ai/d/0.16.1/linux-amd64
echo "<SHA-256 from the release page>  cortexdb-0.16.1-linux-amd64.tar.gz" | sha256sum -c -
NEW_DIR="$DIR/cortexdb-0.16.1-linux-amd64"
mkdir "$NEW_DIR" && tar -xzf cortexdb-0.16.1-linux-amd64.tar.gz -C "$NEW_DIR" --strip-components=1

2. Read the running server's settings, stop it and back it up with the old binary. Find the server by its process name: the cortexdb.pid file the installer writes names the shell that started it, not the server, so kill $(cat cortexdb.pid) does not stop CortexDB.

PID="$(pgrep -u "$(id -u)" -x cortexdb)"                         # one server on this machine
OLD_BIN="$(readlink -f /proc/$PID/exe)"
PORT="$(tr '\0' '\n' < /proc/$PID/cmdline | sed -n 2p)"
mapfile -t SETTINGS < <(tr '\0' '\n' < /proc/$PID/environ | grep '^CORTEX_')
kill "$PID"; while kill -0 "$PID" 2>/dev/null; do sleep 1; done  # waits for a graceful stop
"$OLD_BIN" backup "$DIR/data" "$DIR/cortexdb-backup-$(date +%F).tar.gz"
"$OLD_BIN" backup-verify "$DIR/cortexdb-backup-$(date +%F).tar.gz"

3. Start the new binary with the same settings (in the same shell, so it still has them):

(cd "$NEW_DIR"; nohup env "${SETTINGS[@]}" "$NEW_DIR/cortexdb" "$PORT" "$DIR/data" \
  >> "$DIR/cortexdb.log" 2>&1 & echo $! > "$DIR/cortexdb.pid")

This cortexdb.pid names the server itself. A server run by systemd upgrades by pointing ExecStart at the new folder's cortexdb (with TimeoutStopSec=120) and restarting the unit, after the same backup.

Check the upgrade

curl -s http://127.0.0.1:3141/v1/admin/version                 # the new version
curl -s 'http://127.0.0.1:3141/v1/admin/ready?deep=1'          # ready, with one real embedding call
curl -s -H "Authorization: Bearer $CORTEX_API_KEY" http://127.0.0.1:3141/internal/ui/license     # "state":"active"
curl -s -H "Authorization: Bearer $CORTEX_API_KEY" \
  "http://127.0.0.1:3141/v1/events/<an event id you know>?scope=<its scope>"                     # your memory, 200

Leave out the Authorization header if the server runs with CORTEX_INSECURE_NO_AUTH=1. After a one-way release, the data directory records the format it was armed for: docker exec cortexdb cat /data/format_armed.json (or cat ~/cortexdb/data/format_armed.json) shows {"format":11} on 0.15.x.

If something goes wrong

What you seeWhyWhat to do
FATAL: embedding provider mismatch: data dir /data is pinned to '…' but the configured provider resolves to '…'The new server has different embedding settings from the old oneStart it with the old settings (step 3). Nothing was changed. To change provider on purpose, see Embeddings
FATAL: an explicit CORTEX_EMBEDDING_URL requires CORTEX_EMBEDDING_API_KEY, OPENAI_API_KEY, or LLM_API_KEYThe embedding key was not passedThe same
Every client gets 401 MISSING_TOKENCORTEX_API_KEY was not passed, so the server made a key of its ownStart it with the old settings. The installer keeps the key in ~/.cortexdb/cortexdb.api-key
Conflict. The container name "/cortexdb" is already in useInstall commands were run instead of upgrade stepsFollow Upgrade a Docker install
The installer stops: A container named cortexdb already existsThe installer never upgradesThe same. Don't remove the container to make it run
FATAL [SHARD_FORMAT_UNSUPPORTED]: … armed for shard apply format 11 … this binary applies format 10 at most (exit 78)An older release was started on an upgraded directoryRun the new release, or go back from the backup (Rolling back)
503 ACCESS_RESTORE_PENDING on readsThe server runs on a restored backup and waits for an access acknowledgementBefore its first start, mark it with restore-check --access-state unchanged if access did not change (Backups & DR)
503 FORMAT_UPGRADE_PENDING on governed-memory routesCORTEX_FORMAT_CEILING=10 is set, or the server runs 0.15.0 on a directory holding unit companionsRemove the ceiling and restart; on 0.15.0, upgrade to 0.15.1 or later
402 LICENSE_REQUIREDNo license yet (an upgrade from before 0.12.1)Add your license (the note above)
Binary: the new server cannot use its port, or the old one keeps runningkill $(cat cortexdb.pid) stopped the installer's shell, not the serverStop it by name: kill "$(pgrep -u "$(id -u)" -x cortexdb)"
Binary: version `GLIBC_2.39' not foundThe host's C library is older than the binary needsA newer host, or the Docker image
The console's Updates page says there is nothing newIt doesn't see licensed releasesReleases are on the portal's Releases page

From 0.15.x to 0.16.1

0.16.1 adds voice mode, a built-in embedding model that runs inside the server, voice call sessions and the online re-embed. A deployment that does not turn voice mode on serves as before, and recalls get faster for every deployment. (0.16.0 was not published; 0.16.1 is the release.)

  • A drop-in upgrade, not one way. 0.16.1 keeps data format 11, so a 0.15.x release still opens a directory 0.16.1 ran. Upgrade with the steps above; the backup is still worth taking.
  • The exception: a directory moved to the built-in model (CORTEX_EMBEDDING_PROVIDER=local, which voice mode sets). Only 0.16.1 and later know that provider, so an older release refuses the directory at its embedding check and changes nothing. To go back to 0.15.x, move it to an API provider with the online re-embed first, or restore the backup taken before the move.
  • Voice mode on existing data. A directory embedded through an API does not switch to voice mode by a setting: the start is refused with VOICE_PROFILE_CONFIG. Move it with the online re-embed first (Moving an existing store to voice mode).
  • A graceful stop can take 0.15 to 0.2 s longer than on 0.15.x; keep the 120 s stop timeout.
  • Clients. The voice calls, commands and tools come with the client releases made for 0.16.1 (Clients).

From 0.14.x to 0.15.x

0.15.0 is the governed memory formation release, and its first start upgrades the data directory one way, for data format 11: it writes format_armed.json ({"format":11}) and logs shard armed for apply format 11: this is one-way. From then on a 0.14.x release refuses the directory (SHARD_FORMAT_UNSUPPORTED, exit 78), and the only way back is the backup taken before the upgrade.

  1. Back up with the 0.14.x release and keep the archive with that image or binary (step 2 of Docker or binary), and rehearse on a restored copy first if you can.
  2. Go straight to 0.15.1 or later, not 0.15.0. On 0.15.0, a directory that holds unit companions (<scope>/attrs:unit records, which change sets write for org roots, application roots and teams) stays at format 10, and the governed-memory routes answer 503 FORMAT_UPGRADE_PENDING with details.reason: "reserved_path_in_use". Do not delete those records: they hold the unit's heads, grants and members. 0.15.1 and later arm over them.
  3. To upgrade now and arm later, start 0.15.x with CORTEX_FORMAT_CEILING=10 (format_ceiling = 10 in every cluster member's [engine] table). It then serves what 0.14.2 served, format_armed.json stays {"format":10}, and the routes that need format 11 answer 503 FORMAT_UPGRADE_PENDING. Remove the setting and restart to arm format 11. Holding at 10 is not a way back to 0.14.x: the backup is.
  4. Upgrade by hand, with the steps above. The one-click updater cannot install 0.15.x.

What 0.14.2 served that 0.15.x changes:

  • directives.extract derives only the stages it names. ["entities"] no longer produces facts, ["facts"] builds no belief unless the list also names beliefs, and [] derives nothing. An event with a list joins episodes only when it names episodes. An omitted list still derives everything.
  • A write that names a directive nothing acts on carries directive_not_enforced:<name> in its acknowledgement's warnings.
  • A change set's attrs:unit put that leaves enrich out keeps it; send "inherit" to clear it.
  • Entity-extraction calls are priced on CORTEX_LLM_MODEL. If the price book does not know that model, declare its rate in CORTEX_MODEL_PRICES: until then the backfill that turning a scope's enrich on starts waits, and the cost estimates read unpriced.
  • Imports are idempotent: a row is keyed by its source id, and a row changed under the same id is refused alone.
  • On a cluster, data nodes no longer run the fact sweeper or the fact consolidator.
  • The default answer model is claude-opus-5-5 (0.15.2) for a deployment that does not set CORTEX_ANSWER_MODEL. Its thinking counts against CORTEX_ANSWER_MAX_TOKENS (1,500): raise it if the server log shows the stop reason max_tokens.

Without a derivation policy, subject settings or correction, 0.15.x serves the same recall packs, answers and default reads as 0.14.2, apart from the changes above. Upgrade the clients too (Clients); against a server before 0.15.0 their new calls answer 404, so check the capability first.

From 0.13.x to 0.14.0

0.14.0 is the shared-memory release, and the one upgrade that cannot be undone in place. Its first start arms the data directory for the new record formats, before it serves: it writes format_armed.json ({"format": 10}) and logs SHARD_ARMED_ONE_WAY. From then on a 0.13.x binary refuses the directory, and the only way back is the backup you took before. Nothing stored is lost by the upgrade, but several requests 0.13.x served are refused by default. Work through this list first.

Before the first start

  1. Take a cold backup with the 0.13.x image, and keep it with that image. Stop the server with its 120-second grace, then cortexdb backup and cortexdb backup-verify (Backups & DR).
  2. Rehearse on a copy. Restore the backup into a new, empty volume and start 0.14.0 on it with your real environment. Point a client of each kind at it and note what is refused.
  3. The operator key on cloud_shared_saas. Its operator mode is now deny there: reads of stored memories, registrations and the other in-band actions need a break-glass header. If an application reads, writes or mints with the operator key, set CORTEX_OPERATOR_DATA_READS=allow, or audit to count what deny would refuse, until it uses per-person tokens (Operator Modes). The other presets keep allow.
  4. Tokens. On 0.14.0 a token this server's minter signed lives at most 7 days for a person or an agent, 30 for a service, 24 hours with a chain claim; a longer one answers 401 INVALID_TOKEN_CLAIM (lifetime_over_ceiling) from the first request, tokens minted before the upgrade included. 0.14.1 and later make these settings (CORTEX_MINT_MAX_LIFETIME_*) with 90 days for a person by default. A token that carries scopes holds only the families its entries name. Every mint names its tenant root (scope, tenant or scopes), and a minted token reaches no more than its minter (Identity and Tokens).
  5. A deployment that mints account tokens through its own service (a website minter): list that principal in the issuers file's deployment_minters, and mint its own token again so that it holds auth.mint and every family the account tokens carry, each as <family>:* in scopes, and names those capabilities in each account mint's caps.
  6. Callers. These are now refused where 0.13.x served them:
    • forget and erasure selector fields a route does not apply (422 INVALID_BODY, unknown_selector_field), and a forget's misspelt layers (unknown_layer);
    • tree.display_name in a registry write (422 INVALID_SCOPE_TREE): names go to the directory;
    • /v1/understanding and /v1/concepts without understanding.read in an explicit caps list;
    • a decimal offset as GET /v1/events's cursor (it pages newest first with an opaque cursor now);
    • a few error codes changed status or retriable flag (a client that reads retriable needs no change).
  7. Clients. Upgrade them with the server (below, Clients); the earlier releases predate shared memory.

The switches

Most checks that refuse what 0.13.x served have a switch, on by default. off serves what the check refuses and counts it in GET /v1/admin/access/report?scope=<tenant root> instead, so you can see when it is safe to turn it back on. Any other value refuses the start (exit 78).

SetWhen
CORTEX_OPERATOR_DATA_READS=allow (or audit)cloud_shared_saas, and an application uses the operator key for data
CORTEX_MINT_LIFETIME_ENFORCE=offClients hold minted tokens past the lifetime ceilings
CORTEX_TOKEN_CONFINEMENT_ENFORCE=offClients hold tokens whose scopes do not name every family they use
CORTEX_MINT_REACH_ENFORCE=offA minter's mints name no tenant root, or more than the minter holds
CORTEX_PERSON_DISPLAY_NAME_ENFORCE=off, CORTEX_DISPLAY_NAME_IN_RECORD_ENFORCE=offA client writes tree.display_name
CORTEX_AUDIT_RETENTION_ENFORCE=off, or CORTEX_AUDIT_RETENTION=offThe deployment names its preset and must keep audit rows older than the preset's period: a daily sweep, five minutes after the first start, deletes them
CORTEX_DELIVERY_GATE_ENFORCE=offA reader reads rows (lifecycle frames, exports) at homes where it holds no Reader role

Leave CORTEX_FORMAT_CEILING unset. 7 keeps the directory unarmed, and the new features then answer 503 FORMAT_UPGRADE_PENDING; it is not a way back either.

After the first start

  • GET /v1/admin/version reports 0.14.0 and the new capabilities; GET /v1/admin/metrics auth.enforce shows each switch as you set it.
  • A memory you know is found by GET /v1/events/{id} and by /v1/recall, and each kind of client token answers GET /v1/auth/whoami; a 401 lifetime_over_ceiling names a token to mint again.
  • Mint the long-lived tokens again, move display names to the directory, and remove each off once its count in the access report stays at zero.
  • A copy restored from a 0.14.0 backup waits for an acknowledgement before it serves (Backups & DR).

From 0.10.x to 0.11.0 or later

0.11.0's first start migrates the data directory one way: it keeps a copy of the event log as it was (pre_stage2/ in the data directory), then moves the derived rows, idempotency records, vocabularies, temporal phrases and retention policies into the replicated log. Every later release does the same on a 0.10.x directory.

  • Don't use a 0.10.x server's one-click updater for this upgrade. It does not know the upgrade is one way. Upgrade by hand.
  • Disk: the first start takes longer on a large directory and needs up to two to three times the event log's size while pre_stage2/ is kept.
  • The legacy dual WAL is gone: CORTEX_UNIFIED_WAL=0, or a directory that still holds v1_wal/, stops the server at start (exit 78, LEGACY_WAL_RETIRED). Run cortexdb migrate-unified-wal --data-dir DIR --confirm first.
  • A storage or fsync error stops the process (exit 74, WAL_FATAL): run the server under a supervisor that restarts it (Docker --restart unless-stopped, systemd Restart=always).
  • Retired variables: CORTEX_BULK_DEFER_VECTORS (ignored with a warning), CORTEX_DRAIN_EMBED_CONCURRENCY and CORTEX_V1_MIRROR_MAX_IN_FLIGHT (ignored). Any CORTEX_CLUSTER_* variable on a single server exits 78 (CLUSTER_MODE_UNSUPPORTED).
  • After the upgrade, GET /v1/admin/metrics reports vectors.embed_inputs 0 before any write: the upgrade re-embeds nothing. Once you trust the release, delete pre_stage2/: until then it holds the event log as it was, erased events included, and erasures report that copy as pending.

From v0.9.13 to v0.10.1

v0.10.1 opens a v0.9.13 data directory with no migration step and does its one-time work in the background:

  • Erasure index backfill. The first start files every existing event into a new erasure index. Until erasure_index.wal.ready is true on GET /v1/admin/metrics, erasures still work but read the whole store.
  • Belief rebuild (only with incremental layers, CORTEX_V1_LAYERS_INCREMENTAL). Beliefs whose topic key changed are swept and rebuilt; they are missing until GET /v1/admin/layers/stats reports belief_reconcile.done: true. Without incremental layers, old beliefs stay until you run POST /v1/beliefs/build for each scope. Belief ids are now stable across rebuilds; earlier builds minted new ids on every build.
  • Code plane (only with CORTEX_CODE_PLANE on): every registered repository re-indexes once. Repository access is now checked against the repository's scope, not only the tenant: a repository bound under a scope no roster governs answers 404 REPO_NOT_FOUND to per-actor tokens until you register that scope (POST /v1/scopes) and seat its members.

After the upgrade:

  • Capabilities. GET /v1/admin/version lists ten capabilities. Gate the new request fields (language, scripts, query_variants, and the others) on that list: an older server refuses them with 422 INVALID_BODY.
  • Blob links for older events. Events written before the upgrade carry no source_blob_ids, so erasing them does not delete their blobs. Run the backfill once: POST /v1/admin/index-audit/source-blob-links (dry run by default; see Admin).
  • Derived data from enrichment-on stores. Earlier builds could store facts with a lost negation, merge different people into one entity, and count opposite-polarity facts in beliefs. v0.10.1 stops new damage; POST /v1/admin/derived/rederive repairs what is stored, from the event log (Admin). Take a cold backup before an apply.
  • Entity ids. Names with non-ASCII characters now get hashed ids (ent_jose-0f66606aa13f1258). Ids stored earlier (such as ent_Jos_) still resolve on reads.
  • Error codes. A capture that waits on a running forget gets the retriable 409 DESTRUCTIVE_OPERATION_IN_PROGRESS (was 403 POLICY_DENIED). Forgetting an id stored in another scope answers 200 with zero counts (was 502 FORGET_BACKEND_FAILED). A ?wait=indexed capture that a concurrent forget blanked is no longer reported as 502 INDEXING_FAILED. Cancelling a finished erasure answers 404 NOT_FOUND (was 405).
  • Usage ledger. Streamed answers now book their input tokens, so the recorded answer cost rises if your clients stream.

From v0.9.9 or earlier

Several v0.9.10 to v0.9.12 changes affect a deployment that was set up earlier. Check each before upgrading:

  • The key is required on every preset. A request with only X-Cortex-Actor and no bearer now gets 401 on every deployment preset, including the default dev_local. See Authorization.
  • Retention is enforced. A sweeper erases events older than the deployment's default_retention_ttl_secs or a per-scope policy. Check both before upgrading, because expiry is irreversible. See Retention & WAL.
  • Scope types are validated when a scope is created (422 UNREGISTERED_SCOPE_TYPE), following allowed_scope_types. See Scopes.
  • No silent mock embeddings. A configured embedding endpoint without a credential refuses to boot. Earlier images booted on mock embeddings and pinned the data directory to them; such a store needs a fresh volume or the offline rebuild in Embeddings.
  • Cluster flags are refused at boot (exit 78, CLUSTER_MODE_UNSUPPORTED). Earlier images started independent single-node servers. Remove the flags. See Storage & Cluster.
  • The extraction cache is retired. A boot measures the old <data_dir>/extraction_cache and deletes nothing; set CORTEX_EXTRACTION_CACHE_PURGE=1 once to remove it.
  • Usage figures. The durable usage ledger uses one price book for every lane; re-check any cost figures taken from an older server.

Rolling back

Within a drop-in upgrade (0.15.0 to 0.15.2, 0.14.0 to 0.14.2 and the like), start the older release again on the same directory: for Docker, stop the new container, rename it aside, rename cortexdb-previous back and docker start it.

From 0.15.x to 0.14.x, only from the backup. Stop 0.15.x and keep its directory aside. Restore the backup into a new, empty volume with the 0.14.x image's cortexdb restore, then, before its first start, run cortexdb restore-check --data-dir /data --access-state unchanged with the same image if access has not changed since the backup (otherwise reads answer 503 ACCESS_RESTORE_PENDING until the access sources acknowledge it; see Backups & DR). Start 0.14.x on that volume. Every write made after the upgrade is lost. Never start 0.14.x on the upgraded directory: it refuses it.

From 0.14.0, only from the backup. Stop 0.14.0 and keep its directory aside. Restore the backup you took before the upgrade into a new, empty volume with the 0.13.x image's cortexdb restore, and start 0.13.x on that volume. Every write made after the upgrade is lost. Never start 0.13.x on the upgraded directory: it refuses it. The one-click updater treats 0.14.0 as a one-way upgrade (it asks for accept_one_way and the backup) and never rolls back onto an armed directory.

From v0.10.1 to v0.9.13. A v0.9.13 image opens and serves a data directory v0.10.1 has used. Stop v0.10.1 with the 120-second grace, then start the older image on the same volume. During the rollback window v0.9.13 ignores the new event fields (language, scripts, context.timezone, context.refers_to, source_blob_ids), deletes no blobs on erasure, and builds beliefs without claim keys. After a derived-data repair apply, roll back only by restoring the cold backup taken before it. The v0.10.1 release notes have the full list and the steps for upgrading again.

Clients

Keep every client on its current release; the table in Versioning and SDK compatibility lists them. With 0.16.1 they are the Python SDK cortexdbai 0.15.0, the TypeScript SDK cortexdbai 0.13.0, cortexdb-cli 0.9.0, cortexdb-mcp 0.11.0 and cortexdb-connectors 0.3.0; they add the voice mode and online re-embed calls, commands and tools (client.sessions, cortexdb session, cortexdb voice, cortexdb reembed, the MCP call_brief tool). With 0.15.2 they were cortexdbai 0.14.0 (Python) and 0.12.0 (TypeScript), cortexdb-cli 0.8.0 and cortexdb-mcp 0.10.1. Coming from clients older than 0.14.0's, these are the breaking changes 0.14.0's client releases made; the earlier ones predate shared memory and reach none of its routes:

PackageWith 0.14.0Breaking changes
cortexdbai (Python)0.13.0Every refusal raises the class of its error code; a token bearer with no actor sends the token's sub as X-Cortex-Actor; recall, recall_stream, answer and compose send view only when you pass it
cortexdbai (TypeScript)0.11.0Error codes come back as their own classes; forget and erasure selectors are two types; no default view; TypeScript 5.0 or later
cortexdb-mcp0.9.0A tool refuses an argument it does not take; the default profile no longer lists publish and forget_by_key (use --tool-profile write); the recall tools send view only when CORTEXDB_VIEW is set; X-Cortex-Actor comes from the token when CORTEXDB_ACTOR is unset
cortexdb-cli0.7.0/forget QUERY and cortexdb forget --query resolve the query to event ids you confirm; --cascade none is gone; names go to the directory (cortexdb directory put)
cortexdb-connectors0.3.0Nothing breaks without a container root: container mode is opt-in (CORTEXDB_CONTAINER_ROOT)

cortexdb-cli 0.6.0's interactive /forget is refused by 0.14.0's strict selectors; 0.7.0 fixes it. Points that matter when you upgrade from an older client:

  • cortexdb-mcp 0.2.x used retired endpoints (/v1/remember, /v1/recall_memories) and gets 404 on every call. Releases 0.7.3 and 0.7.4 have tool failures; use the current release.
  • cortexdbai (Python) 0.10.0 and earlier default to port 3142; current releases default to 3141. Pass the URL explicitly either way.
  • cortexdb-cli: cortexdb auth tokens --scope no longer confines a token (0.5.4 sent it as scopes). Use --confine CAP:PREFIX; see CLI.

Connectors

  • GitHub. Connector releases before 0.2.22 stored most GitHub content empty (pull requests without a description, pushes without commits, comments cut at 200 characters, no inline review comments), and 0.2.22 re-keys GitHub records. Events written earlier stay as they were; re-sync to get the full text. See GitHub.

  • Wire keys. From 0.2.21 the key sent to CortexDB is a derived cxsrc: value, so GET /v1/experience/status?idempotency_key= needs the cxsrc: value from the connector log.

  • Freshdesk 0.2.19 or earlier stopped ingesting tickets after 10 conversations. Backfill after upgrading; re-ingest is safe, unchanged records converge on the events already stored:

    cortexdb-sync status                      # note the current cursor first
    cortexdb-sync sync freshdesk --since 2020-01-01T00:00:00Z
  • Teams 0.2.20 or earlier deduplicated an edited message against its first ingest instead of keeping it as a new version. Current releases keep edits.

On this page