Skip to content

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.md
index 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-output
diff --git a/docs/MIGRATION-2.0.md b/docs/MIGRATION-2.0.md
index 7d5cd58d..1e6fff08 100644
--- a/docs/MIGRATION-2.0.md
+++ b/docs/MIGRATION-2.0.md
@@ -1,8 +1,19 @@
# Upgrading to 2.0
2.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 unchanged
grep -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 dir
mkdir <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 wiki
files): the `pre-okf-migration checkpoint` commit in the wiki's git
history, 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** wiki
migrates 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