Skip to content

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

Rust

docs(backup): define the host-migration boundary (#1494)

AkitaOnRailse902038323c0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e0f06b7f..12ae8ca6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,12 @@ version in [`docs/changelog/`](docs/changelog/):
relay and wiki sync companions take the same `rustls-webpki` bump.
### Fixed
+- Defined `ai-memory backup` as an online data snapshot rather than a complete
+ host image, documented the separately protected config, root credentials and
+ raw ledgers a host move may require, and corrected the missing-token startup
+ remedy so it no longer implies the snapshot contains `auth-tokens/`.
+ ([#1494](https://github.com/akitaonrails/ai-memory/issues/1494))
+
- Accepted the exact CRLF migration checksums written by Windows-native
releases before v3.1.2 and replaced them transactionally with the current
LF checksums before strict migration validation. Unknown migration changes
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index ae9dbb3e..6095512e 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -226,7 +226,11 @@ pub enum Command {
/// Prints what it would remove and changes nothing unless `--confirm` is
/// passed. See also `ai-memory status` for the reclaimable figure.
ReclaimLedgerVersions(ReclaimLedgerVersionsArgs),
- /// Snapshot wiki/, db/, and config.toml into a gzipped tarball.
+ /// Snapshot wiki/, db/, and an in-data-dir config.toml into a gzipped tarball.
+ ///
+ /// This is not a complete host-migration archive: root/hook credentials,
+ /// external config files, raw workstream ledgers, logs, and models are
+ /// intentionally excluded. See docs/lifecycle-ops.md before moving hosts.
Backup(BackupArgs),
/// Snapshot AI agent configurations, skills, and plugins into a portable archive.
#[command(name = "backup-agents")]
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 6c388ee5..2383101c 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -647,7 +647,8 @@ fn refuse_a_missing_token_file(auth: &AuthSettings) -> Result<()> {
anyhow::bail!(
"[auth].bearer_token_file names {}, which is missing or empty; refusing to serve \
without the bearer token it should hold. Run `ai-memory auth enable` to create a \
- new one, or restore the file from backup.",
+ new one, or restore it from your separate secret backup (`ai-memory backup` \
+ intentionally excludes auth token files).",
path.display()
);
}
diff --git a/docs/backup.md b/docs/backup.md
index 58e51328..80409bf4 100644
--- a/docs/backup.md
+++ b/docs/backup.md
@@ -7,6 +7,14 @@
> you already have a working tarball routine, treat this as an additional
> layer.
+The on-box tarball is an online **data snapshot**, not a complete host-move
+archive. It contains `wiki/`, a consistent SQLite snapshot, and only the
+`config.toml` located inside the data dir. It deliberately omits root and hook
+credential files, external service configuration, `raw/`, logs, and models.
+For a host move, follow the companion-material checklist in
+[`docs/lifecycle-ops.md#backup`](lifecycle-ops.md#backup); keep secrets in a
+separately protected backup and reinstall hooks/MCP wiring on the destination.
+
Ai-memory's wiki directory is a real git repository. Every consolidation pass
writes a checkpoint through libgit2 (see cross-cutting invariant #10 in
[`AGENTS.md`](../AGENTS.md) and the wiki design notes in
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index 77433473..f4a661b5 100644
--- a/docs/lifecycle-ops.md
+++ b/docs/lifecycle-ops.md
@@ -1130,7 +1130,8 @@ What happens on the server:
1. SQLite online-backup API copies the live WAL DB to a temp file,
a guaranteed consistent snapshot without stopping the writer.
-2. Server tar-gzips the snapshot + the wiki tree + `config.toml`.
+2. Server tar-gzips the snapshot + the wiki tree + `<data_dir>/config.toml`
+ when that file exists.
3. Response body IS the gzipped tarball
(`Content-Type: application/gzip`).
@@ -1138,6 +1139,29 @@ CLI writes the response body to `--to`. For a homelab user
this is the standard "snapshot before doing something dangerous"
move: `ai-memory backup` first, then proceed.
+This tarball is an online **data snapshot**, not a complete host image. It
+intentionally excludes `auth-tokens/`, the hook-side `auth-token` and
+`auth-header` files, `raw/`, logs, models, and a config passed from outside the
+data dir with `--config`. That keeps bearer credentials out of an archive that
+is commonly copied between machines, and avoids racing the actively appended
+managed-workstream ledger. The SQLite snapshot still contains the searchable
+managed-workstream events; omitting `raw/` loses their immutable source copy.
+
+For a move to another host, carry these beside the snapshot through a
+separately encrypted or otherwise access-controlled backup:
+
+- the config file the service actually loads, especially
+ `[auth].token_pepper`; packaged systemd units keep it outside the data dir;
+- `auth-tokens/` if existing root bearers must keep working (otherwise run
+ `ai-memory auth enable` and rewire clients with the replacement);
+- `raw/` when the immutable managed-workstream source ledger must be retained.
+
+Do not copy hook credential files as the destination's wiring. Run
+`install-hooks --apply` and `install-mcp --apply` there so paths, server URLs,
+and credentials match the new host. Treat both the ordinary snapshot and the
+separate material as sensitive: wiki content and SQLite can contain private
+session data even though the archive excludes bearer files.
+
Restoring a backup follows the inverse:
```bash