Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(status): surface data-dir filesystem free space in status + backup log (#629)
AkitaOnRailsa6a8a9d26f08
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 35ada4d6..bc6523c6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -24,6 +24,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`ai-memory pending-writes list` / SQLite; the sidecar is a staging-timesnapshot.+### Added+- `ai-memory status` and the pre-migration backup log now report the data+ directory's **filesystem free space** (#629). The OKF-migration backup gate+ proves the archive is writable but said nothing about disk headroom — an+ operator whose 447 MB safety archive left 77 MB free had the store fail to+ extend its WAL eight minutes later, unlogged, for hours. This is pure signal+ (no threshold, no refusal): `status` shows `filesystem free:` beside the+ storage figures, and the "pre-migration backup verified" line now carries+ `dest_free_bytes`, so the same number is visible right before a migration.+### Fixed- Typed edges (`relations`) now actually work on OpenAI-family providers(#630). `ConsolidatedPage.relations` was an open mapdiff --git a/Cargo.lock b/Cargo.lockindex af1a4adb..23aa19dc 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -232,6 +232,7 @@ dependencies = ["anyhow","argon2","base64 0.22.1",+ "fs2","getrandom 0.3.4","jiff","parking_lot",@@ -284,6 +285,7 @@ dependencies = ["axum","dirs","flate2",+ "fs2","futures-util","git2","jiff",diff --git a/crates/ai-memory-cli/src/commands/status.rs b/crates/ai-memory-cli/src/commands/status.rsindex 83169370..607ff3bf 100644--- a/crates/ai-memory-cli/src/commands/status.rs+++ b/crates/ai-memory-cli/src/commands/status.rs@@ -114,6 +114,10 @@ struct Storage {freelist_count: u64,database_bytes: u64,reclaimable_bytes: u64,+ /// Free space on the filesystem holding the database (absent from+ /// pre-#629 servers).+ #[serde(default)]+ data_dir_free_bytes: Option<u64>,}#[derive(Debug, Deserialize, Serialize)]@@ -282,6 +286,9 @@ pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {super::compact::human_bytes(report.storage.database_bytes),super::compact::human_bytes(report.storage.reclaimable_bytes),);+ if let Some(free) = report.storage.data_dir_free_bytes {+ println!(" filesystem free: {}", super::compact::human_bytes(free));+ }if pct >= RECLAIM_ADVICE_PCT&& report.storage.reclaimable_bytes >= RECLAIM_ADVICE_MIN_BYTES{@@ -506,6 +513,32 @@ mod tests {report_offline_spool(&spool, true);}+ /// A pre-#629 server's `/admin/status` response has no+ /// `data_dir_free_bytes` key at all; the field must default to `None`+ /// rather than fail the whole `storage` object.+ #[test]+ fn storage_deserializes_without_free_space_from_an_older_server() {+ let storage: Storage = serde_json::from_str(+ r#"{"page_size":4096,"page_count":10,"freelist_count":0,+ "database_bytes":40960,"reclaimable_bytes":0}"#,+ )+ .unwrap();+ assert_eq!(storage.data_dir_free_bytes, None);+ }++ /// The signal #629 adds: once a server reports free space, it round-trips+ /// through the CLI's own struct unchanged.+ #[test]+ fn storage_deserializes_free_space_from_a_current_server() {+ let storage: Storage = serde_json::from_str(+ r#"{"page_size":4096,"page_count":10,"freelist_count":0,+ "database_bytes":40960,"reclaimable_bytes":0,+ "data_dir_free_bytes":80740352}"#,+ )+ .unwrap();+ assert_eq!(storage.data_dir_free_bytes, Some(80_740_352));+ }+#[test]fn provider_health_line_renders_unknown_and_disabled() {assert_eq!(diff --git a/crates/ai-memory-store/Cargo.toml b/crates/ai-memory-store/Cargo.tomlindex 95b74138..f02f256c 100644--- a/crates/ai-memory-store/Cargo.toml+++ b/crates/ai-memory-store/Cargo.toml@@ -31,6 +31,8 @@ argon2.workspace = truerusqlite.workspace = truerefinery.workspace = trueparking_lot.workspace = true+# Destination-filesystem free space for storage_status.+fs2.workspace = true[dev-dependencies]tempfile.workspace = truediff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex d391849a..dae39c5e 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -996,6 +996,15 @@ pub struct StorageStatus {/// release slightly less. Treat it as the signal for "is this worth an/// exclusive lock", not as an exact figure.pub reclaimable_bytes: u64,+ /// Free space on the filesystem holding the database file, in bytes.+ /// `None` when it could not be read (e.g. an unsupported filesystem).+ ///+ /// The database's own size says nothing about how much headroom is left+ /// for it to keep growing — a store that is small can still be minutes+ /// away from a WAL that cannot extend because the *disk*, not the+ /// database, is full. This is that signal, reported alongside the+ /// database's own figures rather than gated on them.+ pub data_dir_free_bytes: Option<u64>,}impl StorageStatus {@@ -7005,7 +7014,17 @@ impl ReaderPool {/// # Errors/// Propagates the SQL error from the pragma reads.pub async fn storage_status(&self) -> StoreResult<StorageStatus> {- self.with_conn(|conn| {+ // The database's own dir may not exist as a distinct mount point+ // (it usually doesn't), but `available_space` walks up to whatever+ // filesystem holds it either way. A read failure (unsupported+ // filesystem, transient error) is a signal we don't have, not a+ // reason to fail the whole status report.+ let data_dir_free_bytes = self+ .inner+ .db_path+ .parent()+ .and_then(|dir| fs2::available_space(dir).ok());+ self.with_conn(move |conn| {let page_size: i64 = conn.query_row("PRAGMA page_size", [], |r| r.get(0))?;let page_count: i64 = conn.query_row("PRAGMA page_count", [], |r| r.get(0))?;let freelist_count: i64 = conn.query_row("PRAGMA freelist_count", [], |r| r.get(0))?;@@ -7018,6 +7037,7 @@ impl ReaderPool {freelist_count,database_bytes: page_count.saturating_mul(page_size),reclaimable_bytes: freelist_count.saturating_mul(page_size),+ data_dir_free_bytes,})}).await@@ -8456,9 +8476,26 @@ mod tests {freelist_count: 100,database_bytes: 400 * 4096,reclaimable_bytes: 100 * 4096,+ data_dir_free_bytes: None,};assert!((quarter.reclaimable_pct() - 25.0).abs() < f64::EPSILON);}++ /// The signal this field exists for: a store's own size says nothing+ /// about disk headroom, so `storage_status` must also report the+ /// filesystem's free space. A temp dir always has some, so this is+ /// `Some(n)` with `n > 0`, not just "doesn't crash".+ #[tokio::test]+ async fn storage_status_reports_filesystem_free_space() {+ let tmp = tempfile::TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let status = store.reader.storage_status().await.unwrap();+ let free = status+ .data_dir_free_bytes+ .expect("free space should be readable for a real temp dir");+ assert!(free > 0);+ }+use super::{DESCRIPTOR_MAX_CHARS, StorageStatus, entity_query_tokens, handoff_listing_sql, like_escape,page_descriptor, page_descriptor_expr,diff --git a/crates/ai-memory-web/src/mount.rs b/crates/ai-memory-web/src/mount.rsindex 6100b6f5..76a2d086 100644--- a/crates/ai-memory-web/src/mount.rs+++ b/crates/ai-memory-web/src/mount.rs@@ -643,6 +643,7 @@ mod tests {entries: 1,created_at: "2026-09-01T00:00:00Z".into(),label: "okf-v0.2".into(),+ dest_free_bytes: None,};std::fs::write(tmp.path().join(ai_memory_wiki::backup::BACKUP_RECEIPT_FILE),@@ -690,6 +691,7 @@ mod tests {entries: 1,created_at: "2026-09-01T00:00:00Z".into(),label: "okf-v0.2".into(),+ dest_free_bytes: None,};std::fs::write(tmp.path().join(ai_memory_wiki::backup::BACKUP_RECEIPT_FILE),diff --git a/crates/ai-memory-wiki/Cargo.toml b/crates/ai-memory-wiki/Cargo.tomlindex 8d8df69c..fcdd638d 100644--- a/crates/ai-memory-wiki/Cargo.toml+++ b/crates/ai-memory-wiki/Cargo.toml@@ -22,6 +22,8 @@ jiff.workspace = truetar.workspace = trueflate2.workspace = truedirs.workspace = true+# Destination-filesystem free space for the pre-migration backup receipt.+fs2.workspace = truetracing.workspace = truetokio.workspace = truenotify.workspace = truediff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rsindex ebd174b3..c4ed8438 100644--- a/crates/ai-memory-wiki/src/backup.rs+++ b/crates/ai-memory-wiki/src/backup.rs@@ -31,6 +31,13 @@ pub struct BackupReceipt {pub created_at: String,/// What the backup was taken for (e.g. "okf-v0.2-migration").pub label: String,+ /// Free space on the destination filesystem right after the archive was+ /// written, in bytes. `None` when it could not be read (e.g. an+ /// unsupported filesystem) — never fails the backup on its own. A+ /// verified archive next to a nearly-full disk is the exact shape of+ /// the outage that motivated this field: the WAL had nowhere left to+ /// extend minutes after a backup that "succeeded".+ pub dest_free_bytes: Option<u64>,}impl BackupReceipt {@@ -211,6 +218,21 @@ fn create_pre_migration_backup_inner())));}+ // A signal only: the backup itself already succeeded and verified, so a+ // free-space read that fails (unsupported filesystem, transient error)+ // must not turn a good archive into a failed migration.+ let dest_free_bytes = match fs2::available_space(&dest_dir) {+ Ok(bytes) => Some(bytes),+ Err(e) => {+ tracing::debug!(+ dest = %dest_dir.display(),+ error = %e,+ "could not read destination free space"+ );+ None+ }+ };+let receipt = BackupReceipt {archive_path,size_bytes,@@ -219,6 +241,7 @@ fn create_pre_migration_backup_inner(.strftime("%Y-%m-%dT%H:%M:%SZ").to_string(),label: label.to_string(),+ dest_free_bytes,};let tmp = data_dir.join(format!("{BACKUP_RECEIPT_FILE}.tmp"));std::fs::write(&tmp, serde_json::to_vec_pretty(&receipt)?)?;@@ -258,6 +281,22 @@ mod tests {assert_eq!(loaded.archive_path, receipt.archive_path);}+ /// The signal this field exists for: a verified archive next to a+ /// nearly-full disk. A temp dir always reports some free space, and the+ /// receipt (round-tripped through the JSON file) must carry it.+ #[test]+ fn the_receipt_carries_destination_free_space() {+ let data = data_dir_with_content();+ let dest = TempDir::new().unwrap();+ let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();+ let free = receipt+ .dest_free_bytes+ .expect("free space should be readable for a real temp dir");+ assert!(free > 0);+ let loaded = BackupReceipt::load(data.path()).unwrap();+ assert_eq!(loaded.dest_free_bytes, receipt.dest_free_bytes);+ }+#[test]fn an_unwritable_destination_aborts_instead_of_falling_back() {let data = data_dir_with_content();diff --git a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rsindex 30f22c54..c477c5b0 100644--- a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs+++ b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs@@ -86,6 +86,7 @@ impl WikiMigration for OkfConformance {archive = %receipt.archive_path.display(),size_bytes = receipt.size_bytes,entries = receipt.entries,+ dest_free_bytes = ?receipt.dest_free_bytes,"pre-migration backup verified");