Skip to content

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

Rust

feat(status): report local hook-spool health

Aravind Raoe1037dab1038
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c8020b6..a89a0fab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- `ai-memory status` now reports local hook-spool health: pending event
+ count, age of the oldest queued event, and total failed-delivery attempts.
+ This makes "memory capture is delayed, not broken" visible to an operator
+ without digging through logs: a non-empty spool or an aging oldest event
+ means hook events are queued locally instead of reaching the server. The
+ spool is client-side, so the section reflects the local data-dir even when
+ the server is remote. The JSON form gains a matching `spool` object
+ (`pending`, `oldest_age_ms`, `retries_total`). (#428)
- New `strip_root_combinators` config flag (env `AI_MEMORY_STRIP_ROOT_COMBINATORS`,
or `strip_root_combinators = true` in config.toml) strips root-level
`anyOf`/`oneOf`/`allOf` from MCP tool input schemas on every `tools/list`.
diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rs
index 4fc71404..087f9329 100644
--- a/crates/ai-memory-cli/src/commands/hook_spool.rs
+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs
@@ -103,6 +103,68 @@ pub fn spool_len(spool: &Path) -> usize {
list_entries(spool).map_or(0, |f| f.len())
}
+/// Snapshot of local hook-spool health for operator status reporting.
+///
+/// Deliberately content-free: counts, ages, and attempt sums only — never
+/// payload excerpts, URLs, or token material (the spool holds private capture
+/// until it drains).
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize)]
+pub struct SpoolHealth {
+ /// Events queued locally awaiting delivery.
+ pub pending: usize,
+ /// Age (ms) of the oldest queued event, or `None` when the spool is empty.
+ pub oldest_age_ms: Option<u64>,
+ /// Sum of failed-delivery attempts across all queued events.
+ pub retries_total: u64,
+}
+
+/// Snapshot local spool health: queued count and oldest-event age from the
+/// timestamp-embedded file names (no file reads), plus total retry attempts
+/// (one bounded read per queued entry — fine for an operator-invoked status
+/// command, never on the hook hot path).
+#[must_use]
+pub fn spool_health(spool: &Path) -> SpoolHealth {
+ let Some(mut files) = list_entries(spool) else {
+ return SpoolHealth::default();
+ };
+ if files.is_empty() {
+ return SpoolHealth::default();
+ }
+ files.sort();
+ let now = now_ms();
+ let oldest_created = files[0]
+ .file_name()
+ .and_then(|name| name.to_str())
+ .map(created_ms_from_name)
+ .unwrap_or(0);
+ let mut health = SpoolHealth {
+ pending: files.len(),
+ oldest_age_ms: Some(now.saturating_sub(oldest_created)),
+ retries_total: 0,
+ };
+ for path in &files {
+ if let Ok(bytes) = std::fs::read(path)
+ && let Ok(entry) = serde_json::from_slice::<SpoolEntry>(&bytes)
+ {
+ health.retries_total += u64::from(entry.attempts);
+ }
+ }
+ health
+}
+
+/// Extract the enqueue timestamp embedded in a spool file name
+/// (`{created_ms:013}-{pid}-{seq:016x}.json`), 0 when unparseable. Filenames
+/// are the only place `created_ms` is readable without opening the file, so
+/// oldest-age reporting never pays a read per queued event.
+fn created_ms_from_name(file_name: &str) -> u64 {
+ file_name
+ .split('-')
+ .next()
+ .unwrap_or(file_name)
+ .parse()
+ .unwrap_or(0)
+}
+
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
@@ -2066,4 +2128,79 @@ mod tests {
"the spool entry survives a failed rewrite"
);
}
+
+ #[test]
+ fn spool_health_is_default_when_dir_missing_or_empty() {
+ let tmp = tempfile::tempdir().unwrap();
+ let missing = tmp.path().join("no-spool");
+ assert_eq!(spool_health(&missing), SpoolHealth::default());
+
+ let empty = spool_dir(tmp.path());
+ std::fs::create_dir_all(&empty).unwrap();
+ assert_eq!(spool_health(&empty), SpoolHealth::default());
+ }
+
+ #[test]
+ fn spool_health_reports_pending_oldest_age_and_retries() {
+ let tmp = tempfile::tempdir().unwrap();
+ let spool = spool_dir(tmp.path());
+ // Two events with distinct enqueue times; the second carries two failed
+ // attempts. Names embed `created_ms`, so oldest-age comes from the name.
+ let mut old = entry_for("https://x/hook?event=old".into(), "{}".into(), None, false);
+ old.created_ms = now_ms().saturating_sub(5 * 60 * 1000);
+ let mut new = entry_for("https://x/hook?event=new".into(), "{}".into(), None, false);
+ new.created_ms = now_ms().saturating_sub(60 * 1000);
+ new.attempts = 2;
+ enqueue(&spool, &old).unwrap();
+ enqueue(&spool, &new).unwrap();
+
+ let before = now_ms();
+ let health = spool_health(&spool);
+ assert_eq!(health.pending, 2);
+ assert_eq!(health.retries_total, 2);
+ let oldest = health
+ .oldest_age_ms
+ .expect("non-empty spool reports an age");
+ assert!(
+ (5 * 60 * 1000..=5 * 60 * 1000 + 1_000).contains(&oldest),
+ "oldest age ~5m, got {oldest}ms (measured at {before})"
+ );
+ }
+
+ #[test]
+ fn spool_health_ignores_unparseable_entries_for_retries() {
+ let tmp = tempfile::tempdir().unwrap();
+ let spool = spool_dir(tmp.path());
+ write_spool_entry(
+ &spool,
+ "0000000000042-1-0000000000000001.json",
+ "https://x/hook".into(),
+ );
+ std::fs::write(
+ spool.join("0000000000043-1-0000000000000002.json"),
+ b"not a spool entry",
+ )
+ .unwrap();
+
+ let before = now_ms();
+ let health = spool_health(&spool);
+ assert_eq!(health.pending, 2);
+ assert_eq!(health.retries_total, 0);
+ let oldest = health
+ .oldest_age_ms
+ .expect("non-empty spool reports an age");
+ assert!(
+ oldest >= before.saturating_sub(42),
+ "oldest name parses to 42ms, age {oldest}ms"
+ );
+ }
+
+ #[test]
+ fn created_ms_from_name_handles_malformed_names() {
+ assert_eq!(
+ created_ms_from_name("0000000000042-1-0000000000000001.json"),
+ 42
+ );
+ assert_eq!(created_ms_from_name("garbage.json"), 0);
+ }
}
diff --git a/crates/ai-memory-cli/src/commands/status.rs b/crates/ai-memory-cli/src/commands/status.rs
index 8a3e3e0b..a803a878 100644
--- a/crates/ai-memory-cli/src/commands/status.rs
+++ b/crates/ai-memory-cli/src/commands/status.rs
@@ -8,6 +8,7 @@ use ai_memory_llm::{ProviderHealthSnapshot, ProviderHealthStatus, ProviderRoleHe
use anyhow::Result;
use serde::{Deserialize, Serialize};
+use super::hook_spool::{spool_dir, spool_health};
use crate::cli::StatusArgs;
use crate::config::Config;
use crate::http_client::{ServerEndpoint, get_json};
@@ -71,6 +72,7 @@ struct EmbeddingTriple {
pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
let ep = ServerEndpoint::from_config_resolving_auth(config).await;
let report: Report = get_json(&ep, "/admin/status", &[]).await?;
+ let spool = spool_health(&spool_dir(&config.data_dir));
if args.json {
println!(
@@ -88,6 +90,7 @@ pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
},
"derived": report.derived,
"providers": report.providers,
+ "spool": spool,
"client": { "server_url": ep.url, "auth": ep.auth_token.is_some() },
}))?
);
@@ -120,6 +123,10 @@ pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
report.derived.unresolved_links_from_latest_pages,
report.derived.stale_links_from_latest_pages
);
+ println!(" spool:");
+ println!(" pending: {}", spool.pending);
+ println!(" oldest: {}", spool_age_line(spool.oldest_age_ms));
+ println!(" retries: {}", spool.retries_total);
println!(" providers:");
println!(
" llm: {}",
@@ -138,6 +145,25 @@ pub async fn run(config: &Config, args: StatusArgs) -> Result<()> {
Ok(())
}
+/// Render a spool age (ms) as a compact human duration, or `-` when the spool
+/// holds no events. Allowed to saturate: an operator reading a stuck-spool
+/// diagnosis wants the magnitude, not sub-second precision.
+fn spool_age_line(age_ms: Option<u64>) -> String {
+ let Some(ms) = age_ms else {
+ return "-".to_string();
+ };
+ let secs = ms / 1000;
+ if secs < 60 {
+ format!("{secs}s")
+ } else if secs < 3600 {
+ format!("{}m {}s", secs / 60, secs % 60)
+ } else if secs < 86_400 {
+ format!("{}h {}m", secs / 3600, (secs % 3600) / 60)
+ } else {
+ format!("{}d {}h", secs / 86_400, (secs % 86_400) / 3600)
+ }
+}
+
fn provider_health_line(role: &ProviderRoleHealthSnapshot) -> String {
match role.status {
ProviderHealthStatus::Disabled => "disabled".to_string(),
@@ -229,4 +255,14 @@ mod tests {
assert!(provider_health_line(&role).contains("status 401"));
assert!(provider_health_line(&role).contains("bad token"));
}
+
+ #[test]
+ fn spool_age_line_renders_durations_and_empty() {
+ assert_eq!(spool_age_line(None), "-");
+ assert_eq!(spool_age_line(Some(0)), "0s");
+ assert_eq!(spool_age_line(Some(59_999)), "59s");
+ assert_eq!(spool_age_line(Some(60_000)), "1m 0s");
+ assert_eq!(spool_age_line(Some(3_661_000)), "1h 1m");
+ assert_eq!(spool_age_line(Some(172_800_000)), "2d 0h");
+ }
}