Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
refactor(cli): one elapsed-time renderer, and document the handoffs command (#523)
Fabio Akita1210df8aef28
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 85edd546..d7df746d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,6 +18,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0so an operator can see it and decide (#513).### Fixed+- Documented `ai-memory handoffs`. It shipped listed only in the+ ARCHITECTURE subcommand block, which a guard test enforces — so the command+ satisfied the check for being *present* without anyone being told what it+ does. README and the MCP tool table now name it beside+ `memory_handoff_cancel`, which is the tool it exists to make usable.+- Made every "how long ago" in the CLI read the same way. Four separate+ renderers had accumulated — `show`, `run`, `workstreams` and `handoffs` —+ so the same elapsed time appeared as `3 hours ago`, `3h ago` or `74 days+ ago` depending on which command produced it. They now share one helper, and+ a long-idle native session reads `2 months ago` in `run` as it already did+ elsewhere. `status`'s spool line is deliberately untouched: it renders a+ duration (`oldest: 2h 10m`), not an "ago", and answers a different question.- `install-mcp --client antigravity-cli` wrote to `~/.gemini/antigravity-cli/mcp_config.json`,but the Antigravity CLI documents its global MCP config at`~/.gemini/config/mcp_config.json`; the `antigravity-cli/` directory is itsdiff --git a/README.md b/README.mdindex e2f612b2..d0a4d17a 100644--- a/README.md+++ b/README.md@@ -225,6 +225,10 @@ priors are at the [bottom](#influences-and-prior-art).# List the workstreams that can be selected from this checkout.ai-memory workstreams++ # List open cross-agent handoffs, oldest first, with the id+ # `memory_handoff_cancel` needs to clear a stale one.+ ai-memory handoffs```- **"Pick the project instead of remembering where it lives."** Start from adiff --git a/crates/ai-memory-cli/src/commands/handoffs.rs b/crates/ai-memory-cli/src/commands/handoffs.rsindex 5a5c9a38..3b8374a0 100644--- a/crates/ai-memory-cli/src/commands/handoffs.rs+++ b/crates/ai-memory-cli/src/commands/handoffs.rs@@ -71,7 +71,7 @@ pub async fn run(config: &Config, args: HandoffsArgs) -> Result<()> {let _ = writeln!(out," {} from {} -> {}",- age(now_ms.saturating_sub(h.created_at_ms)),+ super::humanize_age_secs(now_ms.saturating_sub(h.created_at_ms) / 1_000),h.from_agent,target);@@ -88,37 +88,25 @@ pub async fn run(config: &Config, args: HandoffsArgs) -> Result<()> {Ok(())}-/// Coarse age, because the operator's question is "is this stale", not "when-/// exactly".-fn age(ms: i64) -> String {- let secs = ms.max(0) / 1_000;- let days = secs / 86_400;- if days > 0 {- return format!("{days}d ago");- }- let hours = secs / 3_600;- if hours > 0 {- return format!("{hours}h ago");- }- format!("{}m ago", secs / 60)-}-#[cfg(test)]mod tests {- use super::*;+ use super::super::humanize_age_secs;+ /// Both read-only listings render ages through one helper now; these pin+ /// the rendering the handoff listing depends on.#[test]fn age_reports_the_coarsest_useful_unit() {- assert_eq!(age(0), "0m ago");- assert_eq!(age(5 * 60 * 1_000), "5m ago");- assert_eq!(age(3 * 3_600 * 1_000), "3h ago");- assert_eq!(age(9 * 86_400 * 1_000), "9d ago");+ assert_eq!(humanize_age_secs(0), "just now");+ assert_eq!(humanize_age_secs(5 * 60), "5 minutes ago");+ assert_eq!(humanize_age_secs(3_600), "1 hour ago");+ assert_eq!(humanize_age_secs(3 * 3_600), "3 hours ago");+ assert_eq!(humanize_age_secs(9 * 86_400), "9 days ago");}- /// A clock skew between server and client must not render as a huge- /// positive age from a negative difference.+ /// Server and client clocks can disagree; a future timestamp must not+ /// render as an enormous age.#[test]- fn a_future_timestamp_clamps_to_zero() {- assert_eq!(age(-5_000), "0m ago");+ fn a_future_timestamp_clamps_to_just_now() {+ assert_eq!(humanize_age_secs(-5), "just now");}}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex 68edd247..243cefe0 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -81,6 +81,33 @@ pub mod write_page;////// Resolution is announced on stderr whenever the marker decides a field, so/// a scope that differs from the flags the user typed is never silent.+/// Render an elapsed time the way the read-only listings say it.+///+/// `ai-memory workstreams` and `ai-memory handoffs` both answer "how long+/// ago", and each shipped its own renderer a day apart — one saying+/// `3 hours ago`, the other `3h ago` — so the same quantity read differently+/// depending on which command you ran.+///+/// Deliberately does **not** cover `status`'s spool line. That renders a+/// duration (`oldest: 2h 10m`), not an "ago", and is a stable surface people+/// read; folding it in here would change output that no fix requires.+///+/// Clamps negatives to "just now": server and client clocks can disagree, and+/// a skewed timestamp must not render as an enormous age.+pub(crate) fn humanize_age_secs(seconds: i64) -> String {+ let seconds = seconds.max(0);+ if seconds < 60 {+ return "just now".to_owned();+ }+ let (value, unit) = match seconds {+ v if v < 3_600 => (v / 60, "minute"),+ v if v < 86_400 => (v / 3_600, "hour"),+ v if v < 2_592_000 => (v / 86_400, "day"),+ v => (v / 2_592_000, "month"),+ };+ format!("{value} {unit}{} ago", if value == 1 { "" } else { "s" })+}+/// `AI_MEMORY_IGNORE_MARKER=1` skips rung 2 entirely.pub(crate) fn resolve_scope(config: &Config,diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rsindex b3362b0e..c27b584e 100644--- a/crates/ai-memory-cli/src/commands/run.rs+++ b/crates/ai-memory-cli/src/commands/run.rs@@ -1135,18 +1135,13 @@ fn display_session_id(value: &str) -> String {output}+/// Age of a native session, rendered the way every other read-only listing+/// renders one. Gains a "months" tier over the previous day-capped form, so a+/// long-idle session reads as `2 months ago` here and in `show` / `workstreams`+/// / `handoffs` rather than `74 days ago` in this one command.fn session_age(updated_at: SystemTime, now: SystemTime) -> String {- let age = now.duration_since(updated_at).unwrap_or_default().as_secs();- match age {- 0..60 => "just now".into(),- 60..3_600 => plural_age(age / 60, "minute"),- 3_600..86_400 => plural_age(age / 3_600, "hour"),- _ => plural_age(age / 86_400, "day"),- }-}--fn plural_age(value: u64, unit: &str) -> String {- format!("{value} {unit}{} ago", if value == 1 { "" } else { "s" })+ let secs = now.duration_since(updated_at).unwrap_or_default().as_secs();+ super::humanize_age_secs(i64::try_from(secs).unwrap_or(i64::MAX))}async fn export_after_flush(diff --git a/crates/ai-memory-cli/src/commands/show.rs b/crates/ai-memory-cli/src/commands/show.rsindex 2031a87e..f5d6da03 100644--- a/crates/ai-memory-cli/src/commands/show.rs+++ b/crates/ai-memory-cli/src/commands/show.rs@@ -618,18 +618,7 @@ fn humanize_age(timestamp: Option<&str>) -> String {let Ok(then) = raw.parse::<jiff::Timestamp>() else {return "unknown activity".to_owned();};- let seconds = (jiff::Timestamp::now() - then).get_seconds();- if seconds < 0 {- return "just now".to_owned();- }- let (value, unit) = match seconds {- value if value < 60 => return "just now".to_owned(),- value if value < 3_600 => (value / 60, "minute"),- value if value < 86_400 => (value / 3_600, "hour"),- value if value < 2_592_000 => (value / 86_400, "day"),- value => (value / 2_592_000, "month"),- };- format!("{value} {unit}{} ago", if value == 1 { "" } else { "s" })+ super::humanize_age_secs((jiff::Timestamp::now() - then).get_seconds())}fn harness_name(harness: RunHarnessChoice) -> String {diff --git a/crates/ai-memory-cli/src/commands/workstreams.rs b/crates/ai-memory-cli/src/commands/workstreams.rsindex c6211d9f..ba259756 100644--- a/crates/ai-memory-cli/src/commands/workstreams.rs+++ b/crates/ai-memory-cli/src/commands/workstreams.rs@@ -71,17 +71,7 @@ fn humanize_age(raw: &str) -> String {let Ok(then) = raw.parse::<jiff::Timestamp>() else {return "unknown activity".to_owned();};- let seconds = (jiff::Timestamp::now() - then).get_seconds();- if seconds < 60 {- return "just now".to_owned();- }- let (value, unit) = match seconds {- value if value < 3_600 => (value / 60, "minute"),- value if value < 86_400 => (value / 3_600, "hour"),- value if value < 2_592_000 => (value / 86_400, "day"),- value => (value / 2_592_000, "month"),- };- format!("{value} {unit}{} ago", if value == 1 { "" } else { "s" })+ super::humanize_age_secs((jiff::Timestamp::now() - then).get_seconds())}#[cfg(test)]diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex b2734c24..dc9164a1 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -363,6 +363,13 @@ invariants below.| `memory_handoff_begin` | destructive | Open an owner-scoped handoff for the next agent; `shared=true` deliberately publishes it to the project. Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_accept` | destructive | Fetch + ack the latest own/shared handoff (automatic handoffs are cwd-matched). Root-only `any_owner=true` recovers across operators. Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_cancel` | destructive | Mark an exact visible open handoff id expired when it was created by mistake; root-only `any_owner=true` recovers across operators. |++`memory_handoff_cancel` needs an exact id. `ai-memory handoffs` lists the open+handoffs for a project, oldest first, with their ids — read-only, and+content-free (identity, provenance and age, never the summary body). Automatic+expiry deliberately spares manual and sibling-directory handoffs, so a+long-lived entry appearing there is that policy working rather than a fault.+| `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out. Consolidation prompts append the target project's active reserved `_prompts/consolidation.md` body as sanitized, 2,000-character-capped, JSON-encoded, untrusted advisory preferences; TTL-expired pages are ignored and a per-call `instructions` argument overrides the page for one call. Both system prompts keep schema, evidence, disclosure, tool-use, and output rules authoritative. || `memory_feedback` | write | Record a quality signal for one page by exact `path`: `helpful`/`not_helpful` step `pages.salience` for sweep-eligible episodic pages, while `stale`/`wrong` floor salience and surface any current page as a `feedback_flagged` lint finding. Never deletes; the path resolves to the current version in the transaction, so a later rewrite clears it. Retrieved content never authorizes feedback by itself. || `memory_auto_improve` | write | Manually review a completed session and apply or stage validated wiki edits through the auto-improvement approval path. Without a session ID, selects the newest completed session with no persisted auto-improvement run so repeated calls advance through preflight skips; an explicit ID remains rerunnable. The server also schedules review for new sessions; `[auto_improve] require_approval = true` leaves proposals pending for manual review. |