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
- Find the version you run:
curl -s http://127.0.0.1:3141/v1/admin/version(use your port). - Find how it was installed. The portal installer makes either a Docker container (named
cortexdbunless you setCORTEXDB_NAME) or a Linux binary under~/cortexdb(orCORTEXDB_DIR). - Find your path in the table below and read its section before you stop anything.
| From | To | Kind of upgrade | Read |
|---|---|---|---|
| 0.15.x | 0.16.1 | Drop-in, not one way: a 0.15.x release still opens the directory, unless it was moved to the built-in embedding model | From 0.15.x to 0.16.1 |
| 0.15.0 or 0.15.1 | 0.15.2 | Drop-in: an older 0.15 release still opens the directory | The steps below |
| 0.14.x | 0.15.x | One way (data format 11): back up first | From 0.14.x to 0.15.x |
| 0.14.0 or 0.14.1 | 0.14.2 | Drop-in | The steps below |
| 0.13.x | 0.14.x | One way (data format 10): back up first | From 0.13.x to 0.14.0 |
| 0.12.x | 0.13.x | Drop-in; a single node can go back by changing the image again | The steps below |
| 0.11.x | 0.12.x | Drop-in; from 0.12.1 the server needs your license | The license note below |
| 0.10.x | 0.11.0 or later | One way (data migration) | From 0.10.x to 0.11.0 or later |
| 0.9.x | 0.10.x | Changes for existing deployments | From 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
cortexdbcontainer or install folder it stops, by design. - Don't
docker rm -fthe server, and don'tdocker pull. There is no public image to pull: licensed images come from the portal as a file youdocker load. - Don't retype the
docker runfrom 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 missingCORTEX_API_KEYlocks 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.12. 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=12. 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, 200Leave 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 see | Why | What 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 one | Start 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_KEY | The embedding key was not passed | The same |
Every client gets 401 MISSING_TOKEN | CORTEX_API_KEY was not passed, so the server made a key of its own | Start it with the old settings. The installer keeps the key in ~/.cortexdb/cortexdb.api-key |
Conflict. The container name "/cortexdb" is already in use | Install commands were run instead of upgrade steps | Follow Upgrade a Docker install |
The installer stops: A container named cortexdb already exists | The installer never upgrades | The 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 directory | Run the new release, or go back from the backup (Rolling back) |
503 ACCESS_RESTORE_PENDING on reads | The server runs on a restored backup and waits for an access acknowledgement | Before 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 routes | CORTEX_FORMAT_CEILING=10 is set, or the server runs 0.15.0 on a directory holding unit companions | Remove the ceiling and restart; on 0.15.0, upgrade to 0.15.1 or later |
402 LICENSE_REQUIRED | No 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 running | kill $(cat cortexdb.pid) stopped the installer's shell, not the server | Stop it by name: kill "$(pgrep -u "$(id -u)" -x cortexdb)" |
Binary: version `GLIBC_2.39' not found | The host's C library is older than the binary needs | A newer host, or the Docker image |
| The console's Updates page says there is nothing new | It doesn't see licensed releases | Releases 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.
- 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.
- Go straight to 0.15.1 or later, not 0.15.0. On 0.15.0, a directory that holds unit companions
(
<scope>/attrs:unitrecords, which change sets write for org roots, application roots and teams) stays at format 10, and the governed-memory routes answer503 FORMAT_UPGRADE_PENDINGwithdetails.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. - To upgrade now and arm later, start 0.15.x with
CORTEX_FORMAT_CEILING=10(format_ceiling = 10in every cluster member's[engine]table). It then serves what 0.14.2 served,format_armed.jsonstays{"format":10}, and the routes that need format 11 answer503 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. - 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.extractderives only the stages it names.["entities"]no longer produces facts,["facts"]builds no belief unless the list also namesbeliefs, and[]derives nothing. An event with a list joins episodes only when it namesepisodes. An omitted list still derives everything.- A write that names a directive nothing acts on carries
directive_not_enforced:<name>in its acknowledgement'swarnings. - A change set's
attrs:unitput that leavesenrichout 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 inCORTEX_MODEL_PRICES: until then the backfill that turning a scope'senrichon 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 setCORTEX_ANSWER_MODEL. Its thinking counts againstCORTEX_ANSWER_MAX_TOKENS(1,500): raise it if the server log shows the stop reasonmax_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
- 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 backupandcortexdb backup-verify(Backups & DR). - 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.
- The operator key on
cloud_shared_saas. Its operator mode is nowdenythere: 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, setCORTEX_OPERATOR_DATA_READS=allow, orauditto count whatdenywould refuse, until it uses per-person tokens (Operator Modes). The other presets keepallow. - 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 carriesscopesholds only the families its entries name. Every mint names its tenant root (scope,tenantorscopes), and a minted token reaches no more than its minter (Identity and Tokens). - 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 holdsauth.mintand every family the account tokens carry, each as<family>:*inscopes, and names those capabilities in each account mint'scaps. - 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 misspeltlayers(unknown_layer); tree.display_namein a registry write (422 INVALID_SCOPE_TREE): names go to the directory;/v1/understandingand/v1/conceptswithoutunderstanding.readin an explicitcapslist;- a decimal offset as
GET /v1/events'scursor(it pages newest first with an opaque cursor now); - a few error codes changed status or
retriableflag (a client that readsretriableneeds no change).
- forget and erasure selector fields a route does not apply (
- 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).
| Set | When |
|---|---|
CORTEX_OPERATOR_DATA_READS=allow (or audit) | cloud_shared_saas, and an application uses the operator key for data |
CORTEX_MINT_LIFETIME_ENFORCE=off | Clients hold minted tokens past the lifetime ceilings |
CORTEX_TOKEN_CONFINEMENT_ENFORCE=off | Clients hold tokens whose scopes do not name every family they use |
CORTEX_MINT_REACH_ENFORCE=off | A 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=off | A client writes tree.display_name |
CORTEX_AUDIT_RETENTION_ENFORCE=off, or CORTEX_AUDIT_RETENTION=off | The 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=off | A 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/versionreports0.14.0and the new capabilities;GET /v1/admin/metricsauth.enforceshows 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 answersGET /v1/auth/whoami; a401 lifetime_over_ceilingnames a token to mint again. - Mint the long-lived tokens again, move display names to the directory, and remove each
offonce 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 holdsv1_wal/, stops the server at start (exit 78,LEGACY_WAL_RETIRED). Runcortexdb migrate-unified-wal --data-dir DIR --confirmfirst. - 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, systemdRestart=always). - Retired variables:
CORTEX_BULK_DEFER_VECTORS(ignored with a warning),CORTEX_DRAIN_EMBED_CONCURRENCYandCORTEX_V1_MIRROR_MAX_IN_FLIGHT(ignored). AnyCORTEX_CLUSTER_*variable on a single server exits 78 (CLUSTER_MODE_UNSUPPORTED). - After the upgrade,
GET /v1/admin/metricsreportsvectors.embed_inputs0 before any write: the upgrade re-embeds nothing. Once you trust the release, deletepre_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.readyistrueonGET /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 untilGET /v1/admin/layers/statsreportsbelief_reconcile.done: true. Without incremental layers, old beliefs stay until you runPOST /v1/beliefs/buildfor each scope. Belief ids are now stable across rebuilds; earlier builds minted new ids on every build. - Code plane (only with
CORTEX_CODE_PLANEon): 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 answers404 REPO_NOT_FOUNDto per-actor tokens until you register that scope (POST /v1/scopes) and seat its members.
After the upgrade:
- Capabilities.
GET /v1/admin/versionlists tencapabilities. Gate the new request fields (language,scripts,query_variants, and the others) on that list: an older server refuses them with422 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/rederiverepairs 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 asent_Jos_) still resolve on reads. - Error codes. A capture that waits on a running forget gets the retriable
409 DESTRUCTIVE_OPERATION_IN_PROGRESS(was403 POLICY_DENIED). Forgetting an id stored in another scope answers200with zero counts (was502 FORGET_BACKEND_FAILED). A?wait=indexedcapture that a concurrent forget blanked is no longer reported as502 INDEXING_FAILED. Cancelling a finished erasure answers404 NOT_FOUND(was405). - 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-Actorand no bearer now gets401on every deployment preset, including the defaultdev_local. See Authorization. - Retention is enforced. A sweeper erases events older than the deployment's
default_retention_ttl_secsor 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), followingallowed_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_cacheand deletes nothing; setCORTEX_EXTRACTION_CACHE_PURGE=1once 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:
| Package | With 0.14.0 | Breaking changes |
|---|---|---|
cortexdbai (Python) | 0.13.0 | Every 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.0 | Error codes come back as their own classes; forget and erasure selectors are two types; no default view; TypeScript 5.0 or later |
cortexdb-mcp | 0.9.0 | A 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-cli | 0.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-connectors | 0.3.0 | Nothing 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-mcp0.2.x used retired endpoints (/v1/remember,/v1/recall_memories) and gets404on 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 port3142; current releases default to3141. Pass the URL explicitly either way.cortexdb-cli:cortexdb auth tokens --scopeno longer confines a token (0.5.4 sent it asscopes). 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, soGET /v1/experience/status?idempotency_key=needs thecxsrc: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.
Keys and Credentials
The five credentials a CortexDB pilot or customer handles, what each one is for, and where it comes from.
Self-Hosting Defaults & Prerequisites
What a default self-hosted CortexDB instance does out of the box, and which features are opt-in: enrichment, cross-encoder rerank, and the knowledge graph.