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.mdindex 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-nativereleases before v3.1.2 and replaced them transactionally with the currentLF checksums before strict migration validation. Unknown migration changesdiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 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.rsindex 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.mdindex 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 passwrites a checkpoint through libgit2 (see cross-cutting invariant #10 in[`AGENTS.md`](../AGENTS.md) and the wiki design notes indiff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 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 userthis 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