Skip to content

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

Rust

fix(okf): land the migration backup on the data volume in containers

AkitaOnRailsdf709e2c7d63
diff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rs
index be1e5d12..72d39ed6 100644
--- a/crates/ai-memory-wiki/src/backup.rs
+++ b/crates/ai-memory-wiki/src/backup.rs
@@ -48,20 +48,55 @@ impl BackupReceipt {
}
}
-/// Destination directory for archives: the explicit override when given
-/// (callers read `AI_MEMORY_BACKUP_DIR`), else the user's home. Erroring
-/// (rather than falling back into the data dir) is deliberate: a backup
-/// inside the tree it protects is not a backup.
-fn destination_dir(dest_override: Option<&Path>) -> WikiResult<PathBuf> {
- if let Some(dir) = dest_override {
- return Ok(dir.to_path_buf());
+/// Whether this process runs inside a container. Same signals as the
+/// serve handler: the official image sets `AI_MEMORY_IN_CONTAINER`;
+/// `/.dockerenv` (Docker) and `/run/.containerenv` (Podman) cover
+/// images that do not.
+#[must_use]
+pub fn running_in_container() -> bool {
+ if std::env::var("AI_MEMORY_IN_CONTAINER").is_ok_and(|v| !v.trim().is_empty()) {
+ return true;
}
- dirs::home_dir().ok_or_else(|| {
- WikiError::Io(std::io::Error::other(
- "no home directory found for the pre-migration backup; \
- set AI_MEMORY_BACKUP_DIR to a directory outside the data dir",
- ))
- })
+ Path::new("/.dockerenv").exists() || Path::new("/run/.containerenv").exists()
+}
+
+/// Destination directory for archives.
+///
+/// - the explicit override wins (callers read `AI_MEMORY_BACKUP_DIR`);
+/// - **in a container, the user's home is ephemeral** — it lives in the
+/// container layer and is destroyed on the next recreation, which
+/// would silently lose the safety archive. The only storage
+/// guaranteed to persist is the data-dir volume, so the default there
+/// is `<data_dir>/backups/` (excluded from the archive itself);
+/// - otherwise the user's home.
+///
+/// The destination may live inside the data dir (the archive protects
+/// against the MIGRATION corrupting content, not against disk loss, and
+/// the walk excludes it), but never the data dir root itself.
+fn destination_dir(
+ dest_override: Option<&Path>,
+ data_dir: &Path,
+ in_container: bool,
+) -> WikiResult<PathBuf> {
+ let dest = if let Some(dir) = dest_override {
+ dir.to_path_buf()
+ } else if in_container {
+ data_dir.join("backups")
+ } else {
+ dirs::home_dir().ok_or_else(|| {
+ WikiError::Io(std::io::Error::other(
+ "no home directory found for the pre-migration backup; \
+ set AI_MEMORY_BACKUP_DIR to a directory outside the data dir",
+ ))
+ })?
+ };
+ if dest == data_dir {
+ return Err(WikiError::Io(std::io::Error::other(
+ "the backup destination must not be the data dir root itself; \
+ use a subdirectory (e.g. <data_dir>/backups) or a path outside it",
+ )));
+ }
+ Ok(dest)
}
/// Compress `data_dir` into a timestamped tar.gz in the destination dir,
@@ -72,7 +107,16 @@ pub fn create_pre_migration_backup(
label: &str,
dest_override: Option<&Path>,
) -> WikiResult<BackupReceipt> {
- let dest_dir = destination_dir(dest_override)?;
+ create_pre_migration_backup_inner(data_dir, label, dest_override, running_in_container())
+}
+
+fn create_pre_migration_backup_inner(
+ data_dir: &Path,
+ label: &str,
+ dest_override: Option<&Path>,
+ in_container: bool,
+) -> WikiResult<BackupReceipt> {
+ let dest_dir = destination_dir(dest_override, data_dir, in_container)?;
std::fs::create_dir_all(&dest_dir)?;
let stamp = jiff::Timestamp::now().strftime("%Y%m%d-%H%M%S").to_string();
let archive_path = dest_dir.join(format!("ai-memory-backup-{label}-{stamp}.tar.gz"));
@@ -95,8 +139,22 @@ pub fn create_pre_migration_backup(
.map_err(|e| WikiError::Io(std::io::Error::other(e)))?;
let ft = entry.file_type()?;
if ft.is_dir() {
+ // Never archive the destination itself (a container
+ // default of <data_dir>/backups, or an override
+ // pointed inside the data dir) — self-inclusion
+ // would tar the half-written archive.
+ if path == dest_dir {
+ continue;
+ }
stack.push(path);
} else if ft.is_file() {
+ if path == archive_path
+ || path
+ .file_name()
+ .is_some_and(|n| n == "pre-migration-backup.json.tmp")
+ {
+ continue;
+ }
tar.append_path_with_name(&path, rel)?;
expected += 1;
}
@@ -183,6 +241,45 @@ mod tests {
);
}
+ /// In a container the home dir is ephemeral (destroyed on the next
+ /// recreation), so the default destination is the data-dir volume's
+ /// backups/ subdir — and the archive must not swallow itself.
+ #[test]
+ fn in_a_container_the_archive_lands_on_the_data_volume() {
+ let data = data_dir_with_content();
+ let receipt = create_pre_migration_backup_inner(data.path(), "test", None, true).unwrap();
+ assert!(
+ receipt
+ .archive_path
+ .starts_with(data.path().join("backups"))
+ );
+ // The two data files, not the archive or receipt.
+ assert_eq!(receipt.entries, 2);
+ assert!(receipt.archive_present());
+ }
+
+ /// A destination inside the data dir (container default or an
+ /// override) is excluded from the walk: entry counts match the
+ /// verification pass and a second backup does not tar the first.
+ #[test]
+ fn a_destination_inside_the_data_dir_is_never_self_included() {
+ let data = data_dir_with_content();
+ let dest = data.path().join("backups");
+ let first = create_pre_migration_backup(data.path(), "test", Some(&dest)).unwrap();
+ assert_eq!(first.entries, 2);
+ // Receipt now exists in the data dir; a second run must archive
+ // it (a real file) but never the prior archive in backups/.
+ let second = create_pre_migration_backup(data.path(), "test", Some(&dest)).unwrap();
+ assert_eq!(second.entries, 3, "data files + first receipt");
+ }
+
+ #[test]
+ fn the_data_dir_root_is_refused_as_a_destination() {
+ let data = data_dir_with_content();
+ let err = create_pre_migration_backup(data.path(), "test", Some(data.path()));
+ assert!(err.is_err(), "data dir root must be refused");
+ }
+
#[test]
fn a_deleted_archive_is_reported_absent() {
let data = data_dir_with_content();
diff --git a/docs/MIGRATION-2.0.md b/docs/MIGRATION-2.0.md
index d1a87fa1..02d7fa78 100644
--- a/docs/MIGRATION-2.0.md
+++ b/docs/MIGRATION-2.0.md
@@ -38,6 +38,32 @@ The migration is idempotent: restarting the server re-runs nothing and
never takes a second backup. Fresh installs skip all of it, including
the backup.
+## Running in a server or container (docker deploys)
+
+Inside a container the home directory is **ephemeral** — it lives in
+the container layer and is destroyed on the next `docker compose up
+-d` recreation, which would silently lose the safety archive. The
+migration detects containers (the official image's
+`AI_MEMORY_IN_CONTAINER`, or `/.dockerenv` / `/run/.containerenv`) and
+defaults the archive to the persistent data volume instead:
+
+```
+/data/backups/ai-memory-backup-okf-v0.2-<date>.tar.gz
+```
+
+The archive survives redeploys with the volume, and the backups
+directory is excluded from the archive itself. To copy it off-host:
+
+```bash
+docker cp ai-memory:/data/backups/ai-memory-backup-okf-v0.2-<date>.tar.gz .
+# or read it straight from the volume's host path
+```
+
+`AI_MEMORY_BACKUP_DIR` still wins when set (point it at another
+mounted volume if you prefer). Deleting the archive — from inside or
+outside the container — clears the homepage notice, same as on a
+workstation.
+
## After the migration
The wiki homepage shows a notice with the archive's location, size and
diff --git a/docs/deploy.md b/docs/deploy.md
index d440d047..2ecebd53 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -188,6 +188,13 @@ gateway's worst-case generation time.
## Backups
+> **2.0 upgrade note:** the first start of a 2.0 image runs the OKF
+> format migration, which archives the entire data dir to
+> `/data/backups/` on the volume before touching anything (containers
+> are detected automatically; `AI_MEMORY_BACKUP_DIR` overrides). The
+> wiki homepage shows the archive's location until you delete it. See
+> [`MIGRATION-2.0.md`](MIGRATION-2.0.md).
+
The data dir is whatever you mounted in `docker-compose.prod.yml`
(default: `/var/opt/docker/utils/ai-memory/data/`). It contains: