Skip to content

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.md
index 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.0
so 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 its
diff --git a/README.md b/README.md
index 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 a
diff --git a/crates/ai-memory-cli/src/commands/handoffs.rs b/crates/ai-memory-cli/src/commands/handoffs.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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. |