Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(hooks): compose a compaction recap from captured prompts and replies
Giovanni Coutinhod62051dfc0f2
diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rsindex 38f366f7..5b83e59e 100644--- a/crates/ai-memory-hooks/src/lib.rs+++ b/crates/ai-memory-hooks/src/lib.rs@@ -28,6 +28,7 @@ pub mod drop_list;mod grants;pub mod log;pub mod payload;+mod recap;pub mod router;pub mod synth;pub mod workstream;diff --git a/crates/ai-memory-hooks/src/recap.rs b/crates/ai-memory-hooks/src/recap.rsnew file mode 100644index 00000000..dfeefa6c--- /dev/null+++ b/crates/ai-memory-hooks/src/recap.rs@@ -0,0 +1,551 @@+//! `GET /recap`: the stretch of a session that its last compaction dropped,+//! rebuilt from captured observations for a "reload context" prompt.++use ai_memory_core::scaffolding::{looks_like_codex_instructions, looks_like_scaffolding};+use ai_memory_store::ObservationRecord;++use crate::router::{UNTRUSTED_HISTORY_END, UNTRUSTED_HISTORY_START};++/// Default recap size: under the 10,000-char cap Claude Code and Grok put on+/// one `additionalContext` field.+pub(crate) const RECAP_BUDGET_DEFAULT: usize = 8_000;+const RECAP_BUDGET_MIN: usize = 2_000;+const RECAP_BUDGET_MAX: usize = 9_500;+/// The last reply and the handoffs each keep this much room when present,+/// so a long run of prompts cannot crowd them out.+const REPLY_FLOOR: usize = 1_000;+const HANDOFF_FLOOR: usize = 500;+/// Room kept for the "N earlier prompts omitted" line once prompts overflow.+const OMITTED_LINE_RESERVE: usize = 80;+const TRUNCATED: &str = "\n[truncated]";++/// One captured prompt or reply, with its capture time.+#[derive(Debug, Clone)]+pub(crate) struct RecapItem {+ pub at: String,+ pub text: String,+}++/// The stretch of a session that ended at its latest compaction.+#[derive(Debug, Clone)]+pub(crate) struct RecapWindow {+ /// The operator's prompts in the window, oldest first.+ pub prompts: Vec<RecapItem>,+ /// The newest captured reply in the window.+ pub last_reply: Option<RecapItem>,+ /// When the latest compaction was captured.+ pub boundary_at: String,+ /// When the window starts: the previous compaction, else the oldest row+ /// read. `None` when the boundary is the only row.+ pub started_at: Option<String>,+ /// The read hit its row limit before reaching the window's start.+ pub truncated: bool,+}++/// An open handoff as the recap lists it.+#[derive(Debug, Clone)]+pub(crate) struct RecapHandoff {+ pub summary: String,+ pub next_steps: Vec<String>,+ pub created_at: String,+ /// Written by the session being recapped.+ pub own: bool,+}++/// The budget a client asked for, clamped; the default when absent or not a+/// number.+pub(crate) fn clamp_budget(raw: Option<&str>) -> usize {+ raw.and_then(|value| value.trim().parse::<usize>().ok())+ .map_or(RECAP_BUDGET_DEFAULT, |n| {+ n.clamp(RECAP_BUDGET_MIN, RECAP_BUDGET_MAX)+ })+}++/// Pick the window from `user-prompt`, `stop` and `pre-compact` rows read+/// newest first: everything between the latest `pre-compact` and the one+/// before it (or the oldest row read). `None` when the session has no+/// compaction. `limit_hit` says the read stopped at its row limit, so a+/// window without a starting boundary may be missing its oldest rows.+pub(crate) fn select_window(+ rows_desc: &[ObservationRecord],+ limit_hit: bool,+) -> Option<RecapWindow> {+ let boundary = rows_desc.iter().position(|r| r.kind == "pre-compact")?;+ let mut prompts = Vec::new();+ let mut last_reply = None;+ let mut started_at = None;+ let mut reached_start = false;+ for row in &rows_desc[boundary + 1..] {+ match row.kind.as_str() {+ "pre-compact" => {+ started_at = Some(row.created_at.clone());+ reached_start = true;+ break;+ }+ "user-prompt" if is_operator_prompt(&row.body) => prompts.push(item(row)),+ "stop" if last_reply.is_none() && !row.body.trim().is_empty() => {+ last_reply = Some(item(row));+ }+ _ => {}+ }+ }+ if !reached_start && rows_desc.len() > boundary + 1 {+ started_at = rows_desc.last().map(|r| r.created_at.clone());+ }+ prompts.reverse();+ Some(RecapWindow {+ prompts,+ last_reply,+ boundary_at: rows_desc[boundary].created_at.clone(),+ started_at,+ truncated: !reached_start && limit_hit,+ })+}++/// Harness markup, task notifications and Codex's injected instructions are+/// captured as prompts but were never typed by the operator.+fn is_operator_prompt(body: &str) -> bool {+ !looks_like_scaffolding(body) && !looks_like_codex_instructions(body)+}++fn item(row: &ObservationRecord) -> RecapItem {+ RecapItem {+ at: row.created_at.clone(),+ text: row.body.trim().to_owned(),+ }+}++/// Render the recap within `budget` chars. Prompts land uncut when they fit;+/// past the room left after the reply and handoff floors, the oldest are+/// dropped first and only a lone prompt larger than the room is clipped.+pub(crate) fn compose_recap(+ session_id: &str,+ window: &RecapWindow,+ handoffs: &[RecapHandoff],+ budget: usize,+) -> String {+ let header = recap_header(session_id, window);+ let footer = format!(+ "\nFull record: `memory_read_session_observations` with `session_id: \"{session_id}\"` and `kinds: [\"user-prompt\", \"stop\"]`.\n"+ );+ let prompts_heading = "\n## Your prompts before the compaction (oldest first)\n";+ let reply_heading = "\n## The agent's last reply before the compaction\n";+ let handoffs_heading = "\n## Open handoffs in this project (none claimed)\n";+ let not_read = if window.truncated {+ "\n_Earlier rows of this window were not read._\n"+ } else {+ ""+ };+ let reply = window.last_reply.as_ref().map_or_else(+ || {+ "_Replies were not captured. Install the hooks with `--capture-assistant` and enable `capture_assistant` on the server to include them._\n".to_owned()+ },+ |r| format!("{}\n", r.text),+ );+ let handoff_text = render_handoffs(handoffs);++ let fixed = [+ header.as_str(),+ UNTRUSTED_HISTORY_START,+ "\n",+ not_read,+ prompts_heading,+ reply_heading,+ if handoffs.is_empty() {+ ""+ } else {+ handoffs_heading+ },+ UNTRUSTED_HISTORY_END,+ "\n",+ footer.as_str(),+ ]+ .iter()+ .map(|part| chars(part))+ .sum::<usize>();+ let available = budget.saturating_sub(fixed);+ let reply_floor = chars(&reply).min(REPLY_FLOOR);+ let handoff_floor = chars(&handoff_text).min(HANDOFF_FLOOR);+ let prompt_room = available.saturating_sub(reply_floor + handoff_floor);++ let prompt_section = render_prompts(&window.prompts, prompt_room);+ let mut remaining = available.saturating_sub(chars(&prompt_section));+ let reply_room = remaining.saturating_sub(handoff_floor).min(chars(&reply));+ let reply = clip(&reply, reply_room);+ remaining = remaining.saturating_sub(chars(&reply));+ let handoff_text = clip(&handoff_text, remaining);++ let mut out = String::with_capacity(budget);+ out.push_str(&header);+ out.push_str(UNTRUSTED_HISTORY_START);+ out.push('\n');+ out.push_str(not_read);+ out.push_str(prompts_heading);+ out.push_str(&prompt_section);+ out.push_str(reply_heading);+ out.push_str(&reply);+ if !handoffs.is_empty() {+ out.push_str(handoffs_heading);+ out.push_str(&handoff_text);+ }+ out.push_str(UNTRUSTED_HISTORY_END);+ out.push('\n');+ out.push_str(&footer);+ clip(&out, budget)+}++fn recap_header(session_id: &str, window: &RecapWindow) -> String {+ let from = window+ .started_at+ .as_deref()+ .map_or_else(|| "the session start".to_owned(), utc_minute);+ format!(+ "> 🧭 **ai-memory: compaction recap** (requested with \"reload context\")\n\+ > **Security boundary:** {notice}\n\n\+ Session `{session_id}`: what was captured from {from} to the compaction at {to}. \+ Session page: `sessions/{session_id}.md`.\n\n",+ notice = ai_memory_core::UNTRUSTED_MEMORY_NOTICE,+ to = utc_minute(&window.boundary_at),+ )+}++fn render_prompts(prompts: &[RecapItem], room: usize) -> String {+ if prompts.is_empty() {+ return "_No prompts were captured in this window._\n".to_owned();+ }+ let lines: Vec<String> = prompts+ .iter()+ .map(|p| format!("- [{}] {}\n", utc_minute(&p.at), p.text))+ .collect();+ if lines.iter().map(|l| chars(l)).sum::<usize>() <= room {+ return lines.concat();+ }+ let room = room.saturating_sub(OMITTED_LINE_RESERVE);+ let mut kept: Vec<String> = Vec::new();+ let mut used = 0;+ for line in lines.iter().rev() {+ let len = chars(line);+ if used + len <= room {+ kept.push(line.clone());+ used += len;+ } else if kept.is_empty() {+ let mut clipped = clip(line, room.saturating_sub(1));+ clipped.push('\n');+ used += chars(&clipped);+ kept.push(clipped);+ } else {+ break;+ }+ }+ kept.reverse();+ let omitted = lines.len() - kept.len();+ let mut out = String::new();+ if omitted > 0 {+ out.push_str(&format!(+ "- _{omitted} earlier prompts omitted to fit; see the full record below._\n"+ ));+ }+ out.push_str(&kept.concat());+ out+}++fn render_handoffs(handoffs: &[RecapHandoff]) -> String {+ let mut ordered: Vec<&RecapHandoff> = handoffs.iter().collect();+ ordered.sort_by_key(|h| !h.own);+ ordered+ .iter()+ .map(|h| {+ let next = if h.next_steps.is_empty() {+ String::new()+ } else {+ format!(" Next: {}.", h.next_steps.join("; "))+ };+ let whose = if h.own { ", from this session" } else { "" };+ format!(+ "- {}{next} (created {}{whose})\n",+ h.summary.trim(),+ utc_minute(&h.created_at)+ )+ })+ .collect()+}++/// A notice for a session that has no compaction yet.+pub(crate) fn no_compaction_notice(session_id: &str) -> String {+ format!(+ "> 🧭 **ai-memory: compaction recap**: no compaction is recorded for session `{session_id}` yet, so there is nothing to reload.\n"+ )+}++/// A notice for a session the store does not know, or one the caller may+/// not read (the two answer alike so an id cannot probe another operator).+pub(crate) fn no_session_notice() -> String {+ "> 🧭 **ai-memory: compaction recap**: no session is recorded under this id for you, so there is nothing to reload.\n".to_owned()+}++/// `2026-10-12T01:00:57.123Z` → `2026-10-12 01:00 UTC`; anything shorter is+/// shown as stored.+fn utc_minute(stamp: &str) -> String {+ match (stamp.get(..10), stamp.get(11..16)) {+ (Some(day), Some(minute)) => format!("{day} {minute} UTC"),+ _ => stamp.to_owned(),+ }+}++fn chars(text: &str) -> usize {+ text.chars().count()+}++/// Keep `text` within `max` chars, marking a cut.+fn clip(text: &str, max: usize) -> String {+ if chars(text) <= max {+ return text.to_owned();+ }+ let keep = max.saturating_sub(chars(TRUNCATED));+ let mut out: String = text.chars().take(keep).collect();+ if max >= chars(TRUNCATED) {+ out.push_str(TRUNCATED);+ }+ out+}++#[cfg(test)]+mod tests {+ use super::*;+ use ai_memory_core::{ObservationId, SessionId};+ use ai_memory_store::ObservationRecord;++ fn row(kind: &str, body: &str, at: &str) -> ObservationRecord {+ ObservationRecord {+ id: ObservationId::new(),+ session_id: SessionId::new(),+ kind: kind.to_owned(),+ title: kind.to_owned(),+ body: body.to_owned(),+ importance: 5,+ created_at: at.to_owned(),+ extension: None,+ source_event: None,+ }+ }++ fn prompts(window: &RecapWindow) -> Vec<&str> {+ window.prompts.iter().map(|p| p.text.as_str()).collect()+ }++ fn handoff(summary: &str, own: bool) -> RecapHandoff {+ RecapHandoff {+ summary: summary.to_owned(),+ next_steps: vec!["take the screenshots".to_owned()],+ created_at: "2026-10-12T01:30:57Z".to_owned(),+ own,+ }+ }++ /// Newest first, as the endpoint reads them: two boundaries, the window+ /// between them, one prompt before and one after.+ fn two_boundaries() -> Vec<ObservationRecord> {+ vec![+ row("user-prompt", "after", "2026-10-12T10:55:29Z"),+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("stop", "r2", "2026-10-12T02:01:05Z"),+ row(+ "user-prompt",+ "<task-notification>\n<summary>Goal check-in</summary>\n</task-notification>",+ "2026-10-12T02:01:05Z",+ ),+ row("stop", "r1", "2026-10-12T01:30:57Z"),+ row("user-prompt", "p2", "2026-10-12T01:07:07Z"),+ row("user-prompt", "p1", "2026-10-12T01:00:57Z"),+ row("pre-compact", "", "2026-10-12T00:55:25Z"),+ row("user-prompt", "before", "2026-10-12T00:54:26Z"),+ ]+ }++ #[test]+ fn window_is_between_the_last_two_boundaries() {+ let window = select_window(&two_boundaries(), false).unwrap();+ assert_eq!(prompts(&window), ["p1", "p2"]);+ assert_eq!(window.last_reply.as_ref().unwrap().text, "r2");+ assert_eq!(window.boundary_at, "2026-10-12T02:55:02Z");+ assert_eq!(window.started_at.as_deref(), Some("2026-10-12T00:55:25Z"));+ assert!(!window.truncated);+ }++ #[test]+ fn no_boundary_returns_none() {+ let rows = vec![+ row("stop", "r", "2026-10-12T01:30:57Z"),+ row("user-prompt", "p", "2026-10-12T01:00:57Z"),+ ];+ assert!(select_window(&rows, false).is_none());+ }++ #[test]+ fn single_boundary_reads_back_to_session_start() {+ let rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("user-prompt", "p2", "2026-10-12T01:07:07Z"),+ row("user-prompt", "p1", "2026-10-12T01:00:57Z"),+ ];+ let window = select_window(&rows, false).unwrap();+ assert_eq!(prompts(&window), ["p1", "p2"]);+ assert_eq!(window.started_at.as_deref(), Some("2026-10-12T01:00:57Z"));+ assert!(window.last_reply.is_none());+ }++ #[test]+ fn codex_instructions_and_scaffolding_are_dropped() {+ let rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("user-prompt", "real", "2026-10-12T01:09:00Z"),+ row(+ "user-prompt",+ "<system-reminder>x</system-reminder>",+ "2026-10-12T01:08:00Z",+ ),+ row(+ "user-prompt",+ "# AGENTS.md instructions for /repo\n\nrules",+ "2026-10-12T01:07:00Z",+ ),+ ];+ let window = select_window(&rows, false).unwrap();+ assert_eq!(prompts(&window), ["real"]);+ }++ #[test]+ fn limit_hit_without_start_marks_truncated() {+ let rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("user-prompt", "p", "2026-10-12T01:00:57Z"),+ ];+ assert!(select_window(&rows, true).unwrap().truncated);+ let recap = compose_recap(+ "sid",+ &select_window(&rows, true).unwrap(),+ &[],+ RECAP_BUDGET_DEFAULT,+ );+ assert!(recap.contains("not read"), "{recap}");+ }++ #[test]+ fn long_prompt_lands_intact_with_short_ones() {+ let goal = format!("/goal {}", "g".repeat(3_988));+ let rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("stop", &"r".repeat(1_994), "2026-10-12T02:01:05Z"),+ row("user-prompt", &"s".repeat(40), "2026-10-12T01:30:00Z"),+ row("user-prompt", &"m".repeat(96), "2026-10-12T01:07:07Z"),+ row("user-prompt", &goal, "2026-10-12T01:00:57Z"),+ ];+ let window = select_window(&rows, false).unwrap();+ let recap = compose_recap(+ "sid",+ &window,+ &[handoff("content session", true)],+ RECAP_BUDGET_DEFAULT,+ );+ assert!(recap.contains(&goal), "the /goal prompt was cut");+ assert!(recap.contains(&"m".repeat(96)));+ assert!(recap.contains(&"s".repeat(40)));+ assert!(recap.contains(&"r".repeat(1_000)));+ assert!(recap.contains("content session"));+ assert!(!recap.contains("omitted"), "{recap}");+ assert!(recap.chars().count() <= RECAP_BUDGET_DEFAULT);+ }++ #[test]+ fn overflow_drops_oldest_prompts_first() {+ let mut rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("stop", &"r".repeat(1_500), "2026-10-12T02:01:05Z"),+ ];+ for i in (0..10).rev() {+ rows.push(row(+ "user-prompt",+ &format!("PROMPT-{i:02} {}", "x".repeat(1_500)),+ &format!("2026-10-12T01:{i:02}:00Z"),+ ));+ }+ let window = select_window(&rows, false).unwrap();+ let recap = compose_recap("sid", &window, &[], RECAP_BUDGET_DEFAULT);+ assert!(recap.contains("PROMPT-09"), "newest prompt missing");+ assert!(!recap.contains("PROMPT-00"), "oldest prompt kept");+ assert!(recap.contains("earlier prompts omitted"), "{recap}");+ assert!(recap.contains(&"r".repeat(1_000)), "reply floor not held");+ assert!(recap.chars().count() <= RECAP_BUDGET_DEFAULT);+ }++ #[test]+ fn a_single_oversized_prompt_is_clipped_not_dropped() {+ let rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row(+ "user-prompt",+ &format!("HEAD {}", "y".repeat(20_000)),+ "2026-10-12T01:00:57Z",+ ),+ ];+ let window = select_window(&rows, false).unwrap();+ let recap = compose_recap("sid", &window, &[], RECAP_BUDGET_DEFAULT);+ assert!(recap.contains("HEAD "), "{recap}");+ assert!(recap.contains("[truncated]"), "{recap}");+ assert!(recap.chars().count() <= RECAP_BUDGET_DEFAULT);+ }++ #[test]+ fn missing_replies_say_how_to_capture_them() {+ let rows = vec![+ row("pre-compact", "", "2026-10-12T02:55:02Z"),+ row("user-prompt", "p", "2026-10-12T01:00:57Z"),+ ];+ let window = select_window(&rows, false).unwrap();+ let recap = compose_recap("sid", &window, &[], RECAP_BUDGET_DEFAULT);+ assert!(recap.contains("--capture-assistant"), "{recap}");+ }++ #[test]+ fn own_handoff_listed_first() {+ let window = select_window(&two_boundaries(), false).unwrap();+ let recap = compose_recap(+ "sid",+ &window,+ &[handoff("OTHER-BATON", false), handoff("OWN-BATON", true)],+ RECAP_BUDGET_DEFAULT,+ );+ let own = recap.find("OWN-BATON").unwrap();+ let other = recap.find("OTHER-BATON").unwrap();+ assert!(own < other, "{recap}");+ }++ #[test]+ fn recap_is_marked_untrusted_and_points_at_the_full_record() {+ let window = select_window(&two_boundaries(), false).unwrap();+ let recap = compose_recap("sid-1", &window, &[], RECAP_BUDGET_DEFAULT);+ assert!(recap.contains("compaction recap"));+ assert!(recap.contains(ai_memory_core::UNTRUSTED_MEMORY_NOTICE));+ assert!(recap.contains("<!-- ai-memory:untrusted-history:start -->"));+ assert!(recap.contains("<!-- ai-memory:untrusted-history:end -->"));+ assert!(recap.contains("memory_read_session_observations"));+ assert!(recap.contains("sessions/sid-1.md"));+ assert!(recap.contains("2026-10-12 01:00 UTC"), "{recap}");+ }++ #[test]+ fn notices_name_the_session() {+ assert!(no_compaction_notice("sid-1").contains("sid-1"));+ assert!(no_compaction_notice("sid-1").contains("no compaction"));+ assert!(no_session_notice().contains("no session"));+ }++ #[test]+ fn clamp_budget_bounds() {+ assert_eq!(clamp_budget(None), 8_000);+ assert_eq!(clamp_budget(Some("6000")), 6_000);+ assert_eq!(clamp_budget(Some("1")), 2_000);+ assert_eq!(clamp_budget(Some("99999")), 9_500);+ assert_eq!(clamp_budget(Some("x")), 8_000);+ }+}diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex ed0f867a..68c5f6c0 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -2246,8 +2246,8 @@ const BRIEF_CORE_PAGES_LIMIT: usize = 24;/// How many recently-updated page titles the brief lists as follow-up/// pointers.const BRIEF_RECENT_PAGES_LIMIT: usize = 10;-const UNTRUSTED_HISTORY_START: &str = "<!-- ai-memory:untrusted-history:start -->";-const UNTRUSTED_HISTORY_END: &str = "<!-- ai-memory:untrusted-history:end -->";+pub(crate) const UNTRUSTED_HISTORY_START: &str = "<!-- ai-memory:untrusted-history:start -->";+pub(crate) const UNTRUSTED_HISTORY_END: &str = "<!-- ai-memory:untrusted-history:end -->";/// Closing instruction to the receiving agent. Rendered after the/// untrusted-history fence, so it is never budget-negotiable.const BRIEF_AGENT_FOOTER: &str = "\n_**To the receiving agent:** this brief is compiled from this \