Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(migration): stop promising the auto archive rolls back to 1.x (#633)
AkitaOnRailse672f3b9d809
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bc6523c6..a80f1671 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`dest_free_bytes`, so the same number is visible right before a migration.### Fixed+- Corrected `docs/MIGRATION-2.0.md`, which wrongly promised the automatic+ pre-migration archive could roll a store back to 1.x (#633). The archive is+ written *after* `Store::open` migrates the SQLite schema forward, so its+ `db/` is already at the 2.x schema and a 1.x binary refuses to open it. The+ docs now state the archive is a 2.x recovery point and that a genuine 1.x+ rollback requires a backup taken with the 1.x binary before upgrading.+ (The underlying ordering — snapshotting before the DB migration runs — is+ tracked separately.)- Typed edges (`relations`) now actually work on OpenAI-family providers(#630). `ConsolidatedPage.relations` was an open map(`BTreeMap<String, Vec<String>>`), which the strict structured-outputdiff --git a/docs/MIGRATION-2.0.md b/docs/MIGRATION-2.0.mdindex 7d5cd58d..1e6fff08 100644--- a/docs/MIGRATION-2.0.md+++ b/docs/MIGRATION-2.0.md@@ -1,8 +1,19 @@# Upgrading to 2.02.0 changes the wiki's on-disk format to the [Open Knowledge Format-v0.2](okf.md). The upgrade is automatic, backup-gated, and reversible.-This page describes exactly what happens and how to go back.+v0.2](okf.md). The upgrade is automatic and backup-gated. This page+describes exactly what happens and what the automatic archive can and+cannot restore.++> **Rollback to 1.x needs your own 1.x-era backup.** The automatic+> archive below is written **after** the SQLite schema has already been+> migrated forward, so its `db/` is at the 2.x schema and a 1.x binary+> will refuse to open it (`store schema … newer than this ai-memory+> build`). The archive is a full **2.x** recovery point (wiki content and+> business state intact); it is **not** a 1.x rollback point. If you want+> the option to return to 1.x, take a backup with the **1.x** binary (or+> `ai-memory backup` on 1.x, or a filesystem copy of the data dir) before+> the first 2.x start. See [#633](https://github.com/akitaonrails/ai-memory/issues/633).## What happens on the first 2.0 start@@ -104,10 +115,12 @@ ai-memory status # server healthy, page counts unchangedgrep -L "^type:" <data_dir>/wiki/*/*/*/*.md # no output = all pages typed```-## Restoring the backup+## Restoring the automatic archive-Blunt and complete — returns the entire data directory to its exact-pre-migration state:+Blunt and complete — returns the entire data directory to the state it+had **the moment the OKF wiki migration began**. Note this is *after* the+SQLite schema was migrated forward, so the restored `db/` is at the 2.x+schema: reopen it with a **2.x** binary, not 1.x.```bash# 1. stop the server (docker compose down / systemctl stop ai-memory)@@ -116,9 +129,13 @@ mv <data_dir> <data_dir>.post-migration# 3. unpack the archive as the new data dirmkdir <data_dir>tar -xzf ~/ai-memory-backup-okf-v0.2-<date>.tar.gz -C <data_dir>-# 4. start the OLD (1.x) binary against it+# 4. start ai-memory 2.x against it (a 1.x binary will refuse the DB)```+To actually roll **back to 1.x**, you need a backup taken with the 1.x+binary before the upgrade (see the note at the top of this page); the+automatic archive above cannot serve that purpose.+Surgical alternative (keeps post-migration work, reverts only the wikifiles): the `pre-okf-migration checkpoint` commit in the wiki's githistory, followed by `ai-memory reindex`.@@ -129,10 +146,10 @@ A 2.0-migrated data directory records the migration in the`wiki_migrations` table. A **newer** binary opening an **older** wikimigrates it (as above). An **older 2.0+** binary opening a **newer**wiki refuses to start with `NewerWikiFormat` instead of silently mixing-formats. (1.x binaries predate the guard: they can open a migrated-directory and will tolerate the extra frontmatter, but new writes from-1.x will not carry the OKF keys — avoid mixing; restore the archive if-you need to stay on 1.x.)+formats. (1.x binaries predate the *wiki* guard, but the **SQLite** schema guard+still stops them: a 1.x binary refuses a 2.x-migrated `db/` outright, so+you cannot stay on 1.x by restoring the automatic archive — only by+restoring a backup you took with the 1.x binary before upgrading.)## Sharing bundles