Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(restore): accept the GNU-sparse SQLite entry that backup produces (#718)
AkitaOnRails80743a42eb8f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bc93e329..c720bd9f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -25,6 +25,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0a missed window now spools instead of dropping (above). The handoff GET keepsits 1 s: it is fed synchronously to the agent's context, and truncating analmost-ready handoff costs more than it saves (#719).+- `ai-memory restore` no longer rejects the GNU-sparse SQLite entry that+ `ai-memory backup` itself produces. `tar::Builder`'s default sparse+ detection archives `db/memory.sqlite` as a GNU-sparse entry (header type+ `S`) whenever the SQLite snapshot has real holes on disk, which+ `validate_restore_entry`'s `is_file()`/`is_dir()` check rejected as an+ "unsupported entry type" — a verified, valid backup could not be restored,+ with no recovery path but hand-editing the archive. `tar` already expands+ GNU-sparse blocks to their full logical content while iterating entries, so+ restore now accepts the type and unpacks it exactly like a regular file+ (#718).## [2.2.0] - 2026-09-12diff --git a/crates/ai-memory-cli/src/commands/restore.rs b/crates/ai-memory-cli/src/commands/restore.rsindex 4f3b04a9..0aecf1f2 100644--- a/crates/ai-memory-cli/src/commands/restore.rs+++ b/crates/ai-memory-cli/src/commands/restore.rs@@ -97,6 +97,17 @@ fn unpack_checked_archive<R: std::io::Read>(Ok(())}+/// The backup writes `db/memory.sqlite` via `tar::Builder`'s default sparse+/// detection: on a sparse SQLite snapshot the entry type is GNU-sparse+/// (header byte `S`), not plain `Regular` — `tar::EntryType::is_file()` is+/// `false` for it even though it is a hole-encoded regular file. `tar`+/// already expands the sparse blocks to their full logical content while+/// iterating entries (see `Archive::parse_sparse_header`), so `unpack_in`+/// on such an entry writes byte-identical content to a non-sparse one.+fn is_regular_file(entry_type: tar::EntryType) -> bool {+ entry_type.is_file() || entry_type == tar::EntryType::GNUSparse+}+fn validate_restore_entry(path: &Path, entry_type: tar::EntryType) -> Result<()> {if !path.components().all(|c| matches!(c, Component::Normal(_))) {bail!("backup contains unsafe path: {}", path.display());@@ -104,7 +115,7 @@ fn validate_restore_entry(path: &Path, entry_type: tar::EntryType) -> Result<()>if entry_type.is_symlink() || entry_type.is_hard_link() {bail!("backup contains unsupported link entry: {}", path.display());}- if !(entry_type.is_file() || entry_type.is_dir()) {+ if !(is_regular_file(entry_type) || entry_type.is_dir()) {bail!("backup contains unsupported entry type: {}", path.display());}let path_str = path.to_string_lossy();@@ -191,6 +202,22 @@ mod tests {}}+ #[test]+ fn validate_restore_entry_accepts_gnu_sparse_for_the_sqlite_path() {+ validate_restore_entry(Path::new("db/memory.sqlite"), tar::EntryType::GNUSparse)+ .expect("a GNU-sparse db/memory.sqlite entry is a regular file, just hole-encoded");+ }++ #[test]+ fn validate_restore_entry_still_rejects_gnu_sparse_at_an_unexpected_path() {+ let err =+ validate_restore_entry(Path::new("secret.txt"), tar::EntryType::GNUSparse).unwrap_err();+ assert!(+ err.to_string().contains("unexpected path"),+ "unexpected error: {err}"+ );+ }+#[test]fn restore_rejects_unexpected_or_unsafe_paths() {for path in ["../config.toml", "/tmp/x"] {@@ -211,4 +238,118 @@ mod tests {"unexpected error for {path}: {err}");}++ fn sha256_hex(bytes: &[u8]) -> String {+ use sha2::{Digest, Sha256};+ let mut hasher = Sha256::new();+ hasher.update(bytes);+ format!("{:x}", hasher.finalize())+ }++ /// Whether the `tar` on PATH is GNU tar with sparse support, so the+ /// real-fixture test below can be skipped everywhere else (musl/BSD+ /// `tar`, or no `tar` at all) without breaking those environments.+ fn gnu_tar_with_sparse_available() -> bool {+ std::process::Command::new("tar")+ .arg("--version")+ .output()+ .is_ok_and(|out| String::from_utf8_lossy(&out.stdout).contains("GNU tar"))+ }++ /// Reproduces #718: the backup command's `tar::Builder` (default+ /// `sparse: true`) writes `db/memory.sqlite` as a GNU-sparse entry+ /// whenever the SQLite snapshot has real holes on disk. This builds an+ /// actual sparse file, archives it with real GNU tar (never a hand-built+ /// header — that would prove nothing about whether unpacking works), and+ /// asserts the restored file is byte-identical to the original logical+ /// content.+ #[cfg(target_os = "linux")]+ #[test]+ fn restore_round_trips_a_real_gnu_sparse_sqlite_snapshot() {+ if !gnu_tar_with_sparse_available() {+ eprintln!(+ "skipping restore_round_trips_a_real_gnu_sparse_sqlite_snapshot: \+ GNU tar with --sparse not available on PATH"+ );+ return;+ }++ use std::io::{Seek, SeekFrom, Write};++ let src = tempfile::TempDir::new().unwrap();+ std::fs::create_dir_all(src.path().join("wiki/default/project/notes")).unwrap();+ std::fs::write(src.path().join("wiki/default/project/notes/a.md"), b"body").unwrap();+ std::fs::write(src.path().join("config.toml"), b"# cfg\n").unwrap();+ std::fs::create_dir_all(src.path().join("db")).unwrap();+ let sqlite_path = src.path().join("db/memory.sqlite");+ {+ let mut f = std::fs::File::create(&sqlite_path).unwrap();+ f.write_all(&[0xAB; 8192]).unwrap();+ // Seek far past the last write without writing the gap: on a+ // filesystem that supports holes (tmpfs, ext4, xfs, btrfs) this+ // leaves a real hole rather than allocated zero pages.+ f.seek(SeekFrom::Start(8 * 1024 * 1024)).unwrap();+ f.write_all(&[0xCD; 8192]).unwrap();+ }+ let expected_hash = sha256_hex(&std::fs::read(&sqlite_path).unwrap());++ let archive_dir = tempfile::TempDir::new().unwrap();+ let archive_path = archive_dir.path().join("backup.tar.gz");+ let status = std::process::Command::new("tar")+ .arg("--sparse")+ .arg("-czf")+ .arg(&archive_path)+ .arg("-C")+ .arg(src.path())+ .arg("config.toml")+ .arg("wiki")+ .arg("db/memory.sqlite")+ .status()+ .unwrap();+ assert!(+ status.success(),+ "GNU tar failed to build the fixture archive"+ );++ // Confirm the fixture actually reproduces the bug before trusting the+ // restore result: db/memory.sqlite must be a GNU-sparse entry, not a+ // plain regular file (which would exercise nothing new).+ {+ let file = std::fs::File::open(&archive_path).unwrap();+ let dec = GzDecoder::new(file);+ let mut ar = tar::Archive::new(dec);+ let mut found_sparse = false;+ for entry in ar.entries().unwrap() {+ let entry = entry.unwrap();+ if entry.path().unwrap().as_ref() == Path::new("db/memory.sqlite") {+ found_sparse = entry.header().entry_type() == tar::EntryType::GNUSparse;+ }+ }+ assert!(+ found_sparse,+ "fixture archive did not encode db/memory.sqlite as GNU-sparse; \+ test does not exercise #718"+ );+ }++ let restore_dir = tempfile::TempDir::new().unwrap();+ let file = std::fs::File::open(&archive_path).unwrap();+ let dec = GzDecoder::new(file);+ let mut ar = tar::Archive::new(dec);+ unpack_checked_archive(&mut ar, restore_dir.path()).unwrap();++ let restored = std::fs::read(restore_dir.path().join("db/memory.sqlite")).unwrap();+ assert_eq!(+ sha256_hex(&restored),+ expected_hash,+ "restored SQLite content must byte-match the original logical content"+ );+ assert!(restore_dir.path().join("config.toml").is_file());+ assert!(+ restore_dir+ .path()+ .join("wiki/default/project/notes/a.md")+ .is_file()+ );+ }}