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.mdindex 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 ofFTS5 alone, so it returns the same order as `memory_query`, and `rank` isdiff --git a/README.md b/README.mdindex 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 awritable 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.mdindex 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 Formatv0.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.mdindex 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 riskcorruption), so take a `ai-memory backup` before upgrading if you might needto 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.02.3.0 is a normal forward upgrade (the only new migration, `V64`, just adds thediff --git a/docs/upgrading-to-3.0.md b/docs/upgrading-to-3.0.mdnew file mode 100644index 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.