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.mdindex 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.rsindex 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.rsindex 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, ProviderRoleHeuse 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");+ }}