Skip to content

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

Rust

feat(hooks): deliver the compaction recap to Claude Code, Codex and Grok

Giovanni Coutinhob7bd458bc1b3
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index c1215a54..f078b094 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -602,6 +602,75 @@ fn handoff_shown_path(
.join(key.file_name().unwrap_or_default())
}
+/// A Grok "reload context" request waits for the session's next tool result.
+/// Grok reuses a session id after `SessionEnd`, so an unanswered request
+/// must not outlive the moment it was made.
+const RECAP_MARKER_TTL: Duration = Duration::from_secs(30 * 60);
+/// Codex previews model-visible hook output past about 2,500 tokens, so it
+/// asks for a recap that stays under that even at three chars per token.
+const CODEX_RECAP_BUDGET: usize = 6_000;
+
+fn recap_pending_path(
+ data_dir: &Path,
+ agent: &str,
+ session_id: Option<&str>,
+ cwd: Option<&str>,
+) -> PathBuf {
+ let key = briefed_marker_path(data_dir, agent, session_id, cwd);
+ data_dir
+ .join("recap-pending")
+ .join(key.file_name().unwrap_or_default())
+}
+
+fn unix_now_secs() -> u64 {
+ std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_or(0, |d| d.as_secs())
+}
+
+/// Record a reload request for delivery on a later event. Best effort: a
+/// failed write only means the request is not delivered.
+fn mark_recap_pending(path: &Path) {
+ if let Some(parent) = path.parent()
+ && fs::create_dir_all(parent).is_ok()
+ {
+ let _ = fs::write(path, unix_now_secs().to_string());
+ }
+}
+
+/// Whether a recorded reload request is still due. A stale or unreadable
+/// marker is removed.
+fn recap_pending_is_fresh(path: &Path) -> bool {
+ let Ok(text) = fs::read_to_string(path) else {
+ return false;
+ };
+ let fresh = text
+ .trim()
+ .parse::<u64>()
+ .is_ok_and(|at| unix_now_secs().saturating_sub(at) <= RECAP_MARKER_TTL.as_secs());
+ if !fresh {
+ let _ = fs::remove_file(path);
+ }
+ fresh
+}
+
+fn recap_url(base: &str, agent: &str, session_id: &str, budget: Option<usize>) -> String {
+ let budget_qs = budget.map_or_else(String::new, |n| format!("&budget={n}"));
+ format!(
+ "{base}/recap?agent={agent}&session_id={}{budget_qs}",
+ url_encode(session_id)
+ )
+}
+
+fn user_prompt_recap_envelope(recap: &str) -> serde_json::Value {
+ serde_json::json!({
+ "hookSpecificOutput": {
+ "hookEventName": "UserPromptSubmit",
+ "additionalContext": recap,
+ }
+ })
+}
+
fn session_start_handoff_envelope(agent: AgentKind, handoff: String) -> serde_json::Value {
if agent == AgentKind::AntigravityCli {
serde_json::json!({
@@ -710,6 +779,10 @@ where
return Ok(());
}
};
+ // Read before any capture rewrite can drop the prompt text.
+ let reload_requested = hook_event == HookEvent::UserPrompt
+ && ai_memory_hooks::user_prompt_text(&json)
+ .is_some_and(|prompt| ai_memory_core::compaction_recap::is_reload_request(&prompt));
// Antigravity exposes PreInvocation rather than a true SessionStart. It
// fires before every model call; invocation zero is the only startup
// boundary. Fail closed when the documented counter is absent so a later
@@ -1074,6 +1147,55 @@ where
}
}
+ // "reload context": a recap of the window the last compaction dropped.
+ // Claude Code and Codex add the UserPromptSubmit envelope to this turn.
+ // Cursor runs Claude Code's settings too; its handling of this envelope
+ // is unverified, so a Cursor payload gets nothing. Drain first so the
+ // latest pre-compact boundary is stored before the recap reads it.
+ if reload_requested
+ && agent_kind.user_prompt_injects_context()
+ && ai_memory_hooks::agent_from_payload(&json) != Some(AgentKind::Cursor)
+ && let Some(session_id) = canonical_session_id.as_deref()
+ {
+ if !external_capture {
+ let _ = hook_spool::drain_exclusive_within_budget(
+ &spool,
+ &dd,
+ start_drain_budget(),
+ drain_event_timeout(),
+ max_attempts,
+ )
+ .await;
+ }
+ let client = build_client();
+ let bearer = hook_spool::resolve_bearer(&client, &dd, effective_token).await;
+ let budget = (agent_kind == AgentKind::Codex).then_some(CODEX_RECAP_BUDGET);
+ let url = recap_url(base, &args.agent, session_id, budget);
+ if let Some(recap) = get_handoff(&client, &url, bearer.as_deref(), handoff_timeout()).await
+ {
+ writeln!(stdout, "{}", user_prompt_recap_envelope(&recap))?;
+ return Ok(());
+ }
+ }
+ // Grok discards an allowing UserPromptSubmit's output, so the request
+ // waits for the session's next tool result (below).
+ if reload_requested && agent_kind.post_tool_injects_handoff() && !subagent_payload {
+ mark_recap_pending(&recap_pending_path(
+ &dd,
+ &args.agent,
+ canonical_session_id.as_deref(),
+ policy_cwd.as_deref(),
+ ));
+ }
+ if hook_event == HookEvent::SessionEnd && agent_kind.post_tool_injects_handoff() {
+ let _ = fs::remove_file(recap_pending_path(
+ &dd,
+ &args.agent,
+ canonical_session_id.as_deref(),
+ policy_cwd.as_deref(),
+ ));
+ }
+
// user-prompt: agents whose SessionStart stdout is discarded AND whose
// UserPromptSubmit stdout is injected (Kimi Code) receive the handoff
// here. Grok discards both, so it must not take this path: the GET
@@ -1168,8 +1290,11 @@ where
// are discarded, so this is the event that can carry a handoff without
// burning it. One fetch per session. A session that never calls a tool
// leaves the handoff open for memory_handoff_accept.
+ // The same event carries a "reload context" recap the session's prompt
+ // asked for, once, after any handoff.
if HookEvent::parse(&args.event) == HookEvent::PostToolUse
&& AgentKind::from_wire(&args.agent).post_tool_injects_handoff()
+ && !subagent_payload
{
let shown = handoff_shown_path(
&dd,
@@ -1177,26 +1302,49 @@ where
canonical_session_id.as_deref(),
policy_cwd.as_deref(),
);
- if !shown.is_file() && !subagent_payload {
+ let recap_pending = recap_pending_path(
+ &dd,
+ &args.agent,
+ canonical_session_id.as_deref(),
+ policy_cwd.as_deref(),
+ );
+ let wants_handoff = !shown.is_file();
+ let wants_recap = canonical_session_id.is_some() && recap_pending_is_fresh(&recap_pending);
+ if wants_handoff || wants_recap {
let client = build_client();
let bearer = hook_spool::resolve_bearer(&client, &dd, effective_token).await;
- let native_session_qs = canonical_session_id
- .as_deref()
- .map_or_else(String::new, |session_id| {
- format!("&session_id={}", url_encode(session_id))
- });
- let handoff_url = format!(
- "{base}/handoff?agent={}{qs}{managed_qs}{native_session_qs}",
- args.agent
- );
- let handoff =
- get_handoff(&client, &handoff_url, bearer.as_deref(), handoff_timeout()).await;
- // Only a real body consumes this session's one chance. An empty
- // or failed claim must retry on the next parent tool; a child
- // session that errors must not burn the baton for the parent.
- if let Some(handoff) = handoff {
- mark_briefed(&shown);
- let envelope = grok_post_tool_handoff_envelope(&handoff);
+ let mut parts = Vec::new();
+ if wants_handoff {
+ let native_session_qs = canonical_session_id
+ .as_deref()
+ .map_or_else(String::new, |session_id| {
+ format!("&session_id={}", url_encode(session_id))
+ });
+ let handoff_url = format!(
+ "{base}/handoff?agent={}{qs}{managed_qs}{native_session_qs}",
+ args.agent
+ );
+ // Only a real body consumes this session's one chance. An empty
+ // or failed claim must retry on the next parent tool; a child
+ // session that errors must not burn the baton for the parent.
+ if let Some(handoff) =
+ get_handoff(&client, &handoff_url, bearer.as_deref(), handoff_timeout()).await
+ {
+ mark_briefed(&shown);
+ parts.push(handoff);
+ }
+ }
+ if wants_recap && let Some(session_id) = canonical_session_id.as_deref() {
+ let url = recap_url(base, &args.agent, session_id, None);
+ if let Some(recap) =
+ get_handoff(&client, &url, bearer.as_deref(), handoff_timeout()).await
+ {
+ let _ = fs::remove_file(&recap_pending);
+ parts.push(recap);
+ }
+ }
+ if !parts.is_empty() {
+ let envelope = grok_post_tool_handoff_envelope(&parts.join("\n\n"));
writeln!(stdout, "{envelope}")?;
return Ok(());
}
@@ -6908,4 +7056,281 @@ mod tests {
.is_file()
);
}
+ fn codex_args(event: &str, server_url: &str) -> HookArgs {
+ let mut args = claude_args(event, server_url);
+ args.agent = "codex".into();
+ args
+ }
+
+ async fn run_hook(data_dir: &Path, args: HookArgs, payload: serde_json::Value) -> Vec<u8> {
+ let mut stdout = Vec::new();
+ run_with_payload(
+ Some(data_dir.to_path_buf()),
+ args,
+ payload.to_string(),
+ &mut stdout,
+ |_, _| Ok(()),
+ )
+ .await
+ .unwrap();
+ stdout
+ }
+
+ /// Every request the stub saw, waiting briefly for each.
+ async fn all_requests(
+ requests: &mut tokio::sync::mpsc::UnboundedReceiver<String>,
+ ) -> Vec<String> {
+ let mut seen = Vec::new();
+ while let Some(request) = first_request(requests).await {
+ seen.push(request);
+ }
+ seen
+ }
+
+ fn recap_requests(seen: &[String]) -> Vec<&String> {
+ seen.iter()
+ .filter(|r| r.starts_with("GET /recap"))
+ .collect()
+ }
+
+ #[tokio::test]
+ async fn claude_reload_prompt_prints_the_recap_envelope() {
+ let tmp = tempfile::tempdir().unwrap();
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+ let stdout = run_hook(
+ &tmp.path().join("data"),
+ claude_args("user-prompt-submit", &base),
+ serde_json::json!({
+ "session_id": "claude-session",
+ "cwd": tmp.path(),
+ "prompt": "reload context after last compaction, then go"
+ }),
+ )
+ .await;
+ let envelope: serde_json::Value = serde_json::from_slice(stdout.trim_ascii()).unwrap();
+ assert_eq!(
+ envelope["hookSpecificOutput"]["hookEventName"],
+ "UserPromptSubmit"
+ );
+ assert_eq!(
+ envelope["hookSpecificOutput"]["additionalContext"],
+ "RECAP-BODY"
+ );
+ let seen = all_requests(&mut requests).await;
+ let recap = recap_requests(&seen);
+ assert_eq!(recap.len(), 1, "{seen:?}");
+ assert!(
+ recap[0].contains("session_id=claude-session"),
+ "{}",
+ recap[0]
+ );
+ assert!(recap[0].contains("agent=claude-code"), "{}", recap[0]);
+ assert!(!recap[0].contains("budget="), "{}", recap[0]);
+ }
+
+ #[tokio::test]
+ async fn codex_reload_prompt_asks_for_a_smaller_recap() {
+ let tmp = tempfile::tempdir().unwrap();
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+ let stdout = run_hook(
+ &tmp.path().join("data"),
+ codex_args("user-prompt-submit", &base),
+ serde_json::json!({
+ "session_id": "codex-session",
+ "cwd": tmp.path(),
+ "prompt": "Reload context"
+ }),
+ )
+ .await;
+ let envelope: serde_json::Value = serde_json::from_slice(stdout.trim_ascii()).unwrap();
+ assert_eq!(
+ envelope["hookSpecificOutput"]["additionalContext"],
+ "RECAP-BODY"
+ );
+ let seen = all_requests(&mut requests).await;
+ let recap = recap_requests(&seen);
+ assert_eq!(recap.len(), 1, "{seen:?}");
+ assert!(recap[0].contains("budget=6000"), "{}", recap[0]);
+ }
+
+ #[tokio::test]
+ async fn ordinary_prompt_does_not_fetch_a_recap() {
+ let tmp = tempfile::tempdir().unwrap();
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+ let stdout = run_hook(
+ &tmp.path().join("data"),
+ claude_args("user-prompt-submit", &base),
+ serde_json::json!({
+ "session_id": "claude-session",
+ "cwd": tmp.path(),
+ "prompt": "can you reload context later?"
+ }),
+ )
+ .await;
+ assert_eq!(stdout, b"{}\n");
+ let seen = all_requests(&mut requests).await;
+ assert!(recap_requests(&seen).is_empty(), "{seen:?}");
+ }
+
+ #[tokio::test]
+ async fn cursor_running_claude_settings_does_not_fetch_a_recap() {
+ let tmp = tempfile::tempdir().unwrap();
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+ let stdout = run_hook(
+ &tmp.path().join("data"),
+ claude_args("user-prompt-submit", &base),
+ serde_json::json!({
+ "session_id": "cursor-session",
+ "cwd": tmp.path(),
+ "cursor_version": "2.0.0",
+ "prompt": "reload context"
+ }),
+ )
+ .await;
+ assert!(!String::from_utf8_lossy(&stdout).contains("RECAP-BODY"));
+ let seen = all_requests(&mut requests).await;
+ assert!(recap_requests(&seen).is_empty(), "{seen:?}");
+ }
+
+ #[tokio::test]
+ async fn recap_server_down_leaves_the_prompt_alone() {
+ let tmp = tempfile::tempdir().unwrap();
+ let stdout = run_hook(
+ &tmp.path().join("data"),
+ claude_args("user-prompt-submit", &dead_server_url()),
+ serde_json::json!({
+ "session_id": "claude-session",
+ "cwd": tmp.path(),
+ "prompt": "reload context"
+ }),
+ )
+ .await;
+ assert_eq!(stdout, b"{}\n");
+ }
+
+ #[tokio::test]
+ async fn grok_reload_prompt_marks_and_never_fetches() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().join("data");
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+ let stdout = run_hook(
+ &data_dir,
+ grok_hook_args("user-prompt", &base),
+ serde_json::json!({
+ "session_id": "grok-session",
+ "cwd": tmp.path(),
+ "prompt": "reload context, then continue"
+ }),
+ )
+ .await;
+ assert_eq!(stdout, b"{}\n");
+ let seen = all_requests(&mut requests).await;
+ assert!(recap_requests(&seen).is_empty(), "{seen:?}");
+ assert!(
+ data_dir
+ .join("recap-pending")
+ .join("grok-session")
+ .is_file(),
+ "recap marker missing"
+ );
+ }
+
+ fn grok_tool_payload(cwd: &Path) -> serde_json::Value {
+ serde_json::json!({
+ "session_id": "grok-session",
+ "cwd": cwd,
+ "tool_name": "read_file"
+ })
+ }
+
+ /// The handoff was already shown, so only the recap can be fetched.
+ fn mark_handoff_shown(data_dir: &Path) {
+ let shown = data_dir.join("handoff-shown");
+ std::fs::create_dir_all(&shown).unwrap();
+ std::fs::write(shown.join("grok-session"), b"").unwrap();
+ }
+
+ fn write_recap_marker(data_dir: &Path, age: Duration) {
+ let dir = data_dir.join("recap-pending");
+ std::fs::create_dir_all(&dir).unwrap();
+ let at = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .unwrap()
+ .saturating_sub(age)
+ .as_secs();
+ std::fs::write(dir.join("grok-session"), at.to_string()).unwrap();
+ }
+
+ #[tokio::test]
+ async fn grok_post_tool_delivers_the_recap_once() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().join("data");
+ mark_handoff_shown(&data_dir);
+ write_recap_marker(&data_dir, Duration::from_secs(5));
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+
+ let stdout = run_hook(
+ &data_dir,
+ grok_hook_args("post-tool-use", &base),
+ grok_tool_payload(tmp.path()),
+ )
+ .await;
+ let envelope: serde_json::Value = serde_json::from_slice(stdout.trim_ascii()).unwrap();
+ assert_eq!(
+ envelope["hookSpecificOutput"]["hookEventName"],
+ "PostToolUse"
+ );
+ assert_eq!(
+ envelope["hookSpecificOutput"]["additionalContext"],
+ "RECAP-BODY"
+ );
+ assert!(!data_dir.join("recap-pending").join("grok-session").exists());
+ let seen = all_requests(&mut requests).await;
+ let recap = recap_requests(&seen);
+ assert_eq!(recap.len(), 1, "{seen:?}");
+ assert!(recap[0].contains("agent=grok"), "{}", recap[0]);
+
+ let stdout = run_hook(
+ &data_dir,
+ grok_hook_args("post-tool-use", &base),
+ grok_tool_payload(tmp.path()),
+ )
+ .await;
+ assert!(!String::from_utf8_lossy(&stdout).contains("RECAP-BODY"));
+ let seen = all_requests(&mut requests).await;
+ assert!(recap_requests(&seen).is_empty(), "{seen:?}");
+ }
+
+ #[tokio::test]
+ async fn grok_stale_recap_marker_is_ignored() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().join("data");
+ mark_handoff_shown(&data_dir);
+ write_recap_marker(&data_dir, Duration::from_secs(31 * 60));
+ let (base, mut requests) = serve_requests("200 OK", "RECAP-BODY").await;
+ let stdout = run_hook(
+ &data_dir,
+ grok_hook_args("post-tool-use", &base),
+ grok_tool_payload(tmp.path()),
+ )
+ .await;
+ assert!(!String::from_utf8_lossy(&stdout).contains("RECAP-BODY"));
+ let seen = all_requests(&mut requests).await;
+ assert!(recap_requests(&seen).is_empty(), "{seen:?}");
+ assert!(!data_dir.join("recap-pending").join("grok-session").exists());
+ }
+
+ #[tokio::test]
+ async fn grok_session_end_removes_the_recap_marker() {
+ let tmp = tempfile::tempdir().unwrap();
+ let data_dir = tmp.path().join("data");
+ write_recap_marker(&data_dir, Duration::from_secs(5));
+ run_hook(
+ &data_dir,
+ grok_hook_args("session-end", &dead_server_url()),
+ serde_json::json!({ "session_id": "grok-session", "cwd": tmp.path() }),
+ )
+ .await;
+ assert!(!data_dir.join("recap-pending").join("grok-session").exists());
+ }
}
diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rs
index 5b83e59e..6aaa7ad2 100644
--- a/crates/ai-memory-hooks/src/lib.rs
+++ b/crates/ai-memory-hooks/src/lib.rs
@@ -56,7 +56,7 @@ pub use drop_list::IngestDropList;
pub use payload::{
HookEnvelope, HookEvent, NOTIFICATION_EXCERPT_MAX_BYTES, POST_COMPACTION_EXCERPT_MAX_BYTES,
USER_PROMPT_EXCERPT_MAX_BYTES, agent_from_payload, cap_lifecycle_body_for_client,
- hook_payload_context,
+ hook_payload_context, user_prompt_text,
};
pub use router::{
DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT, DEFAULT_INGEST_GATE_MAX_ENTRIES,
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rs
index fa502510..aff0f316 100644
--- a/crates/ai-memory-hooks/src/payload.rs
+++ b/crates/ai-memory-hooks/src/payload.rs
@@ -507,6 +507,14 @@ pub fn parse_agent(s: &str) -> AgentKind {
AgentKind::from_wire(s)
}
+/// The prompt text of a `UserPromptSubmit`-style payload, from the same keys
+/// the router reads (`prompt`, `message`, `text`), flattened when a harness
+/// sends content blocks.
+#[must_use]
+pub fn user_prompt_text(raw: &serde_json::Value) -> Option<String> {
+ extract_content(raw, &["prompt", "message", "text"])
+}
+
/// Identify the harness from the payload itself when it carries an
/// unambiguous vendor marker, overriding the `?agent=` the hook command
/// declared.