Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: add the 2.x to 3.0 upgrade guide

AkitaOnRailsb2ddceef94b0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 834bfd33..82fbe76f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -392,6 +392,10 @@ and [0.x](docs/changelog/0.x.md).
`companions/ai-memory-ts/README.md` and `docs/design-client-sdk.md`. (#1165)
### Changed
+- Documented the 2.x to 3.0 upgrade in `docs/upgrading-to-3.0.md`: what
+ changes, what replaces the removed token commands, the backup, upgrade and
+ check steps, and how to roll back by restoring the backup with the 2.x
+ binary. README, `docs/install.md` and `docs/MIGRATION-2.0.md` link to it.
- Changed scoped `/api/v1/search` (a single `workspace` + `project`, or
`scopes`) to rank with the same hybrid ranker as `memory_query` instead of
FTS5 alone, so it returns the same order as `memory_query`, and `rank` is
diff --git a/README.md b/README.md
index 871478aa..27ae13f2 100644
--- a/README.md
+++ b/README.md
@@ -375,6 +375,8 @@ refresh); see
[`docs/install.md#keeping-ai-memory-up-to-date`](docs/install.md#keeping-ai-memory-up-to-date).
The same native upgrade path covers Windows x86_64 zip installs under a
writable prefix (see [`docs/windows.md`](docs/windows.md) Scenario C).
+Upgrading a 2.x install of any kind to 3.0? Read
+[`docs/upgrading-to-3.0.md`](docs/upgrading-to-3.0.md) first.
Wiring another agent is the same two commands with a different name:
`--client codex`, `--agent codex`, and so on for every row of the support
@@ -626,6 +628,7 @@ diagram, crate breakdown, schema notes, and invariants.
| [`DATA_HANDLING.md`](DATA_HANDLING.md) | **Data-flow reference for security/legal review.** What's stored, what's local-only, the two opt-in external paths, and how deletion/retention work. |
| [`docs/sso.md`](docs/sso.md) | Enterprise identity: the OIDC device-auth flow, its scope, and how to front the server with an OIDC-aware gateway. |
| [`docs/airgapped-install.md`](docs/airgapped-install.md) | Offline/air-gapped install: self-contained build, checksum-verified release binaries, and offline local embedding models. |
+| [`docs/upgrading-to-3.0.md`](docs/upgrading-to-3.0.md) | Upgrading a 2.x install to 3.0: what changed, the removed token commands and their replacements, upgrade steps, and rollback. |
| [`docs/MIGRATION-2.0.md`](docs/MIGRATION-2.0.md) | Upgrading an existing store to 2.0: the backup-gated automatic migration and how to restore. |
| [`docs/benchmarks/`](docs/benchmarks/README.md) | Published retrieval-quality numbers with provenance, reproducible from the in-repo harness. |
| [`docs/okf.md`](docs/okf.md) | The wiki is natively an Open Knowledge Format (OKF v0.2) bundle; design and field mapping. |
diff --git a/docs/MIGRATION-2.0.md b/docs/MIGRATION-2.0.md
index a2a9d50c..09bdccaf 100644
--- a/docs/MIGRATION-2.0.md
+++ b/docs/MIGRATION-2.0.md
@@ -1,5 +1,7 @@
# Upgrading to 2.0
+Upgrading a 2.x install to 3.0? See [Upgrading to 3.0](upgrading-to-3.0.md).
+
2.0 changes the wiki's on-disk format to the [Open Knowledge Format
v0.2](okf.md). The upgrade is automatic, runs only after a backup succeeds,
and is reversible. This page describes what happens and how to go back.
diff --git a/docs/install.md b/docs/install.md
index 7fbe8c03..03ca4ece 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -3305,6 +3305,13 @@ will refuse to open that data dir (it fails closed rather than risk
corruption), so take a `ai-memory backup` before upgrading if you might need
to roll back to the previous version.
+### Upgrading to 3.0
+
+3.0 removes the 1.x `user add`, `user expire`, `user revive` and
+`user rotate-token` commands; tokens they issued keep working as API keys.
+[`upgrading-to-3.0.md`](upgrading-to-3.0.md) covers what changed, the upgrade
+steps and how to roll back.
+
### Upgrading to 2.3.0
2.3.0 is a normal forward upgrade (the only new migration, `V64`, just adds the
diff --git a/docs/upgrading-to-3.0.md b/docs/upgrading-to-3.0.md
new file mode 100644
index 00000000..a898e4d3
--- /dev/null
+++ b/docs/upgrading-to-3.0.md
@@ -0,0 +1,165 @@
+# Upgrading to 3.0
+
+3.0 is a major release because it removes the 1.x compatibility-token
+commands. Most 2.x installs upgrade with no action: the server applies its
+schema migrations on the first start, and existing tokens, pages, sessions
+and handoffs carry over. Read this page if you script user management, run a
+multi-user server, or want to know which defaults changed.
+
+For the full list of changes, see the 3.0.0 section of
+[`CHANGELOG.md`](../CHANGELOG.md).
+
+## Before you upgrade
+
+1. Search your scripts, CI jobs and runbooks for `ai-memory user add`,
+ `user expire`, `user revive`, `user rotate-token`, and for HTTP calls to
+ `POST /admin/users` or `/admin/users/<name>/expire`, `/revive` and
+ `/rotate-token`. These are gone in 3.0. The
+ [replacement table](#the-1x-token-commands-are-gone) below lists what to
+ use instead.
+2. Take a backup while the 2.x server is running:
+
+ ```bash
+ ai-memory backup --to ~/ai-memory-pre-3.0.tar.gz
+ ```
+
+ The backup uses SQLite's online backup, so the server can keep running.
+ It is your only way back to 2.x (see [Rolling back](#rolling-back)).
+3. Note the 2.x version you run (`ai-memory --version`) in case you need to
+ reinstall it.
+4. If you use the `ai-memory-wikisync` or `ai-memory-importer` companions,
+ upgrade the server first. Their 3.0 versions refuse to write to a server
+ older than 3.0.
+
+## Upgrade steps
+
+1. Upgrade the binary or image the way you installed it:
+ - Native release binary or Docker wrapper: `ai-memory upgrade`.
+ - Homebrew, AUR or another package manager: that package manager's
+ upgrade command.
+ - Docker Compose deployment: `docker compose pull && docker compose up -d`
+ in the deploy directory.
+ - A server on another host: upgrade it there as well. `ai-memory upgrade`
+ on a client machine only refreshes the local client and hooks.
+2. Restart the server if the upgrade did not. On the first start it applies
+ migrations V77, V78 and V79 before it accepts traffic. V78 and V79 rebuild
+ the `sessions` and `users` tables, so the first start on a large store can
+ take longer than usual.
+3. Check the result:
+
+ ```bash
+ ai-memory doctor
+ ai-memory status
+ ```
+
+4. If anyone on the server used the 1.x token commands, list the tokens they
+ issued:
+
+ ```bash
+ ai-memory api-key list
+ ```
+
+## What changes
+
+### The 1.x token commands are gone
+
+`ai-memory user add`, `user expire`, `user revive` and `user rotate-token`
+were deprecated in 2.0 and are removed, together with their admin endpoints.
+`POST /admin/users` now answers 405, and the three per-user routes answer 404.
+Every other `user` subcommand (`add-human`, `list`, `reset-password`,
+`disable`, `enable`, `patch`, `grant`, `revoke`, `grants`) is unchanged.
+
+Tokens those commands issued keep working. Since 2.0 each one has been stored
+as an API key with the label `legacy-user-token`, and authentication has read
+only API keys. After the upgrade they authenticate exactly as before, as the
+same non-root user. A token that was expired before the upgrade stays
+refused.
+
+Manage them with the `api-key` commands. Each legacy key's id is the id of the
+user it belongs to, which `ai-memory user list --json` prints.
+
+| 2.x command | 3.0 replacement |
+|---|---|
+| `user add --username alice` | `user add-human --username alice` for a person (prints a temporary password), then `api-key add --username alice --label <name>` for a machine credential |
+| `user expire alice` | `api-key revoke <id>` |
+| `user rotate-token alice` | `api-key rotate <id>`, which prints a new secret and retires the old one |
+| `user revive alice` | `api-key rotate <id>`: it reactivates the key with a new secret. The old secret cannot be restored. |
+
+Over HTTP, create people with `POST /admin/human-users` and keys with
+`POST /admin/api-credentials`.
+
+Migration V79 drops the `users.token_hash` and `users.token_expired_at`
+columns, which nothing used once the commands were gone. User records from
+`GET /admin/users` and `ai-memory user list --json` no longer carry
+`token_expired_at`, and `ai-memory user list` no longer shows an `expired`
+status. Check `api-key list` for a key's state instead.
+
+### New installs require a token; existing installs do not change
+
+`ai-memory init` on a fresh data directory now creates a root bearer token at
+`<data_dir>/auth-tokens/default` and turns auth on. An existing install keeps
+running without auth after the upgrade. To turn it on, run
+`ai-memory auth enable` and restart the server. It reuses or creates the token
+file, gives it to the installed hooks, and re-registers the MCP clients that
+point at this server. `ai-memory status` and `ai-memory doctor` now print the
+server's auth posture.
+
+### `memory_query` searches observations by default
+
+The observation stream is now on by default: project and `scopes` searches
+also match raw session observations and rank the session page that holds the
+answer. To get the 2.x ranking back, set this in `config.toml`:
+
+```toml
+[retrieval]
+observation_stream = false
+```
+
+or set `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false` in the server's
+environment.
+
+### Scoped `/api/v1/search` uses the `memory_query` ranker
+
+A `/api/v1/search` call with one `workspace` and `project`, or with `scopes`,
+now ranks with the same hybrid ranker as `memory_query`, and `rank` is the
+fused rank. If a client depended on the FTS5-only order, expect different
+results. Search without a scope is unchanged.
+
+### Re-running `backfill --force` over old imports
+
+Backfill and recovery replay now use reserved `recovery_*` idempotency keys
+(migration V77). Running `backfill --force` again over sessions that
+ai-memory 2.6.0 or older imported can store some of those observations a
+second time. Avoid forcing a re-import of sessions you already imported.
+
+### Library change
+
+The `ai-memory-llm` crate no longer exports `OPENCODE_ZEN_BASE_URL`. Use
+`OPENCODE_GO_BASE_URL`, which holds the same URL. This matters only if you
+build against the crate; the `opencode-zen` provider name still works.
+
+## Rolling back
+
+Migrations are forward-only. Once 3.0 has migrated a data directory, a 2.x
+binary refuses to open it and reports that the memory database schema is
+newer than that build. To go back to 2.x, restore the backup you took before
+upgrading:
+
+1. Stop the 3.0 server.
+2. Reinstall the 2.x version you noted, for example
+ `ai-memory upgrade --version v2.6.6` for a native release binary, or
+ `AI_MEMORY_IMAGE=docker.io/akitaonrails/ai-memory:2.6.6` (or the same image
+ tag in your Compose file) for Docker.
+3. With the 2.x binary, restore the backup:
+
+ ```bash
+ ai-memory restore --from ~/ai-memory-pre-3.0.tar.gz --data-dir <data dir> --force
+ ```
+
+ `restore` applies the running binary's migrations to the snapshot, so
+ running it with the 3.0 binary would migrate the backup forward again.
+4. Start the 2.x server.
+
+Everything written after the upgrade is lost, including API keys issued or
+rotated under 3.0. A client that switched to a key rotated under 3.0 has to go
+back to the token it used before, or get a new one issued under 2.x.