Skip to content

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.md
index 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-time
snapshot.
+### 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 map
diff --git a/Cargo.lock b/Cargo.lock
index 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.rs
index 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.toml
index 95b74138..f02f256c 100644
--- a/crates/ai-memory-store/Cargo.toml
+++ b/crates/ai-memory-store/Cargo.toml
@@ -31,6 +31,8 @@ argon2.workspace = true
rusqlite.workspace = true
refinery.workspace = true
parking_lot.workspace = true
+# Destination-filesystem free space for storage_status.
+fs2.workspace = true
[dev-dependencies]
tempfile.workspace = true
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 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.rs
index 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.toml
index 8d8df69c..fcdd638d 100644
--- a/crates/ai-memory-wiki/Cargo.toml
+++ b/crates/ai-memory-wiki/Cargo.toml
@@ -22,6 +22,8 @@ jiff.workspace = true
tar.workspace = true
flate2.workspace = true
dirs.workspace = true
+# Destination-filesystem free space for the pre-migration backup receipt.
+fs2.workspace = true
tracing.workspace = true
tokio.workspace = true
notify.workspace = true
diff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rs
index 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.rs
index 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"
);