Skip to content

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

Rust

feat(hooks): serve a read-only compaction recap at GET /recap

Giovanni Coutinho936c0088f10f
diff --git a/crates/ai-memory-hooks/src/recap.rs b/crates/ai-memory-hooks/src/recap.rs
index dfeefa6c..dfc972c6 100644
--- a/crates/ai-memory-hooks/src/recap.rs
+++ b/crates/ai-memory-hooks/src/recap.rs
@@ -1,10 +1,144 @@
//! `GET /recap`: the stretch of a session that its last compaction dropped,
//! rebuilt from captured observations for a "reload context" prompt.
+use std::sync::Arc;
+
use ai_memory_core::scaffolding::{looks_like_codex_instructions, looks_like_scaffolding};
-use ai_memory_store::ObservationRecord;
+use ai_memory_core::{HandoffState, IdentityKey, ObservationKind, OwnerFilter, SessionId, UserId};
+use ai_memory_store::{ObservationOrder, ObservationPage, ObservationRecord, ProjectAccess};
+use axum::extract::{Query, State};
+use axum::http::StatusCode;
+use axum::response::IntoResponse;
+use serde::Deserialize;
+use tracing::warn;
+
+use crate::router::{HookState, UNTRUSTED_HISTORY_END, UNTRUSTED_HISTORY_START};
+
+/// Rows read for one recap, newest first. A window longer than this is
+/// recapped from its newest rows and says so.
+const RECAP_ROW_LIMIT: usize = 400;
+/// Open handoffs listed in a recap.
+const RECAP_HANDOFF_LIMIT: usize = 5;
+
+/// Query params for `GET /recap`. The recap is anchored on the session row,
+/// so no cwd or marker scope is needed.
+#[derive(Debug, Default, Deserialize)]
+pub(crate) struct RecapQuery {
+ /// The requesting harness, for logs; it does not change the recap.
+ pub agent: Option<String>,
+ /// The native session id the hook payload carried.
+ pub session_id: Option<String>,
+ /// Char budget; see [`clamp_budget`].
+ pub budget: Option<String>,
+}
+
+/// Read-only: answers a "reload context" prompt with the window of the
+/// session that ended at its latest compaction. It never claims a handoff,
+/// never publishes the active project and never records an observation, so
+/// a reload cannot take a baton a parallel session's successor needs.
+///
+/// `400` without a session id; `403` with the reason when the viewer may not
+/// read the session's project (the hook client never injects it); otherwise
+/// `200` with the recap, a notice, or an empty body on an internal error.
+pub(crate) async fn handle_recap(
+ State(state): State<Arc<HookState>>,
+ Query(query): Query<RecapQuery>,
+ actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
+ viewer_ext: Option<axum::Extension<ai_memory_core::AuthorizedViewer>>,
+) -> impl IntoResponse {
+ let Some(raw) = query
+ .session_id
+ .as_deref()
+ .map(str::trim)
+ .filter(|s| !s.is_empty())
+ else {
+ return (StatusCode::BAD_REQUEST, "session_id is required".to_owned());
+ };
+ let actor = crate::router::actor_identity(actor_ext);
+ let viewer = viewer_ext.map(|axum::Extension(viewer)| viewer.user());
+ let budget = clamp_budget(query.budget.as_deref());
+ match build_recap(&state, raw, budget, actor, viewer).await {
+ Ok(body) => (StatusCode::OK, body),
+ Err(e) => match e.downcast_ref::<ai_memory_store::ScopeResolutionError>() {
+ Some(refusal) if refusal.is_forbidden() => (StatusCode::FORBIDDEN, refusal.to_string()),
+ _ => {
+ warn!(error = %e, agent = ?query.agent, "recap failed");
+ (StatusCode::OK, String::new())
+ }
+ },
+ }
+}
-use crate::router::{UNTRUSTED_HISTORY_END, UNTRUSTED_HISTORY_START};
+async fn build_recap(
+ state: &HookState,
+ raw_session_id: &str,
+ budget: usize,
+ actor: Option<IdentityKey>,
+ viewer: Option<UserId>,
+) -> anyhow::Result<String> {
+ let session_id = SessionId::from_native(raw_session_id);
+ let Some((ws, proj)) = state.reader.session_project_ids(session_id).await? else {
+ return Ok(no_session_notice());
+ };
+ crate::grants::authorize_resolved(&state.reader, Some((ws, proj)), viewer, ProjectAccess::Read)
+ .await?;
+ // The owner filter `/handoff` uses: one operator's session and batons are
+ // not another's to read, and an unowned (single-operator) one stays shared.
+ let owner_filter = match &actor {
+ Some(key) => OwnerFilter::User(key.storage_key()),
+ None => OwnerFilter::Unattributed,
+ };
+ if state
+ .reader
+ .session_summary_scoped(ws, proj, session_id, owner_filter.clone())
+ .await?
+ .is_none()
+ {
+ return Ok(no_session_notice());
+ }
+ let page = state
+ .reader
+ .session_observations_scoped(
+ ws,
+ proj,
+ session_id,
+ ObservationPage {
+ limit: RECAP_ROW_LIMIT,
+ offset: 0,
+ order: ObservationOrder::Desc,
+ kinds: Some(vec![
+ ObservationKind::UserPrompt,
+ ObservationKind::Stop,
+ ObservationKind::PreCompact,
+ ]),
+ query: None,
+ },
+ )
+ .await?;
+ let limit_hit = page.records.len() >= RECAP_ROW_LIMIT;
+ let Some(window) = select_window(&page.records, limit_hit) else {
+ return Ok(no_compaction_notice(raw_session_id));
+ };
+ let handoffs: Vec<RecapHandoff> = state
+ .reader
+ .list_handoffs(
+ ws,
+ proj,
+ Some(HandoffState::Open),
+ owner_filter,
+ RECAP_HANDOFF_LIMIT,
+ )
+ .await?
+ .into_iter()
+ .map(|h| RecapHandoff {
+ own: h.origin.from_session_id == Some(session_id),
+ summary: h.content.summary,
+ next_steps: h.content.next_steps,
+ created_at: h.lifecycle.created_at.to_string(),
+ })
+ .collect();
+ Ok(compose_recap(raw_session_id, &window, &handoffs, budget))
+}
/// Default recap size: under the 10,000-char cap Claude Code and Grok put on
/// one `additionalContext` field.
@@ -548,4 +682,283 @@ mod tests {
assert_eq!(clamp_budget(Some("99999")), 9_500);
assert_eq!(clamp_budget(Some("x")), 8_000);
}
+ mod endpoint {
+ use super::super::*;
+ use crate::router::HookState;
+ use ai_memory_core::{
+ AgentKind, AuthorizedViewer, NewHandoff, NewObservation, NewSession, ObservationKind,
+ Sanitized, Sanitizer, SessionId,
+ };
+ use axum::extract::{Query, State};
+ use axum::http::StatusCode;
+ use axum::response::IntoResponse;
+ use std::sync::Arc;
+ use tempfile::TempDir;
+
+ const T0: i64 = 1_791_800_000_000_000;
+
+ async fn seed(
+ state: &HookState,
+ owner: Option<&str>,
+ rows: &[(ObservationKind, &str)],
+ ) -> SessionId {
+ let session_id = SessionId::new();
+ state
+ .writer
+ .begin_session(NewSession {
+ occurred_at: Some(T0),
+ id: session_id,
+ workspace_id: state.workspace_id,
+ project_id: state.project_id,
+ agent_kind: AgentKind::ClaudeCode,
+ cwd: None,
+ actor_user: owner
+ .map(|name| ai_memory_core::IdentityKey::User(name.into()).storage_key()),
+ })
+ .await
+ .unwrap();
+ for (i, (kind, body)) in rows.iter().enumerate() {
+ let offset = i64::try_from(i).unwrap() + 1;
+ state
+ .writer
+ .insert_observation(Sanitized::new(
+ NewObservation {
+ occurred_at: Some(T0 + offset * 60_000_000),
+ session_id,
+ workspace_id: state.workspace_id,
+ project_id: state.project_id,
+ kind: *kind,
+ extension: None,
+ source_event: None,
+ title: kind.as_str().into(),
+ body: (*body).into(),
+ importance: 5,
+ },
+ &Sanitizer::builtin(),
+ ))
+ .await
+ .unwrap();
+ }
+ session_id
+ }
+
+ fn compacted_rows() -> Vec<(ObservationKind, &'static str)> {
+ vec![
+ (ObservationKind::UserPrompt, "BEFORE-WINDOW"),
+ (ObservationKind::PreCompact, ""),
+ (ObservationKind::UserPrompt, "WINDOW-PROMPT"),
+ (ObservationKind::Stop, "WINDOW-REPLY"),
+ (ObservationKind::PreCompact, ""),
+ (ObservationKind::UserPrompt, "AFTER-WINDOW"),
+ ]
+ }
+
+ async fn recap(
+ state: &Arc<HookState>,
+ session_id: Option<String>,
+ budget: Option<&str>,
+ actor: Option<&str>,
+ viewer: Option<ai_memory_core::UserId>,
+ ) -> (StatusCode, String) {
+ let response = handle_recap(
+ State(state.clone()),
+ Query(RecapQuery {
+ agent: Some("claude-code".into()),
+ session_id,
+ budget: budget.map(str::to_owned),
+ }),
+ actor.map(|name| {
+ axum::Extension(ai_memory_core::ActorContext {
+ user: Some(name.into()),
+ ..ai_memory_core::ActorContext::default()
+ })
+ }),
+ viewer.map(|user| axum::Extension(AuthorizedViewer(user))),
+ )
+ .await
+ .into_response();
+ let status = response.status();
+ let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+ .await
+ .unwrap();
+ (status, String::from_utf8(bytes.to_vec()).unwrap())
+ }
+
+ async fn handoff_in(state: &HookState, summary: &str) {
+ state
+ .writer
+ .insert_handoff(NewHandoff {
+ workspace_id: state.workspace_id,
+ project_id: state.project_id,
+ from_session_id: None,
+ from_agent: AgentKind::ClaudeCode,
+ to_agent: None,
+ cwd: None,
+ summary: summary.into(),
+ open_questions: Vec::new(),
+ next_steps: Vec::new(),
+ files_touched: Vec::new(),
+ owner_user: None,
+ })
+ .await
+ .unwrap();
+ }
+
+ async fn open_handoff_exists(state: &HookState) -> bool {
+ state
+ .reader
+ .latest_open_handoff(
+ state.workspace_id,
+ state.project_id,
+ None,
+ ai_memory_core::OwnerFilter::Any,
+ )
+ .await
+ .unwrap()
+ .is_some()
+ }
+
+ async fn stored_rows(state: &HookState, session_id: SessionId) -> u64 {
+ state
+ .reader
+ .session_observations_scoped(
+ state.workspace_id,
+ state.project_id,
+ session_id,
+ ai_memory_store::ObservationPage {
+ limit: 0,
+ offset: 0,
+ order: ai_memory_store::ObservationOrder::Asc,
+ kinds: None,
+ query: None,
+ },
+ )
+ .await
+ .unwrap()
+ .total
+ }
+
+ /// The anonymous caller (a single-operator install, or a root token,
+ /// which carries no viewer and no actor) reads an unowned session.
+ #[tokio::test]
+ async fn recap_returns_the_window_and_writes_nothing() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let sid = seed(&state, None, &compacted_rows()).await;
+ handoff_in(&state, "BATON-SUMMARY").await;
+ let rows_before = stored_rows(&state, sid).await;
+
+ let (status, body) = recap(&state, Some(sid.to_string()), None, None, None).await;
+
+ assert_eq!(status, StatusCode::OK, "{body}");
+ assert!(body.contains("WINDOW-PROMPT"), "{body}");
+ assert!(body.contains("WINDOW-REPLY"), "{body}");
+ assert!(body.contains("BATON-SUMMARY"), "{body}");
+ assert!(!body.contains("BEFORE-WINDOW"), "{body}");
+ assert!(!body.contains("AFTER-WINDOW"), "{body}");
+ assert!(
+ open_handoff_exists(&state).await,
+ "a reload claimed the baton"
+ );
+ assert_eq!(
+ stored_rows(&state, sid).await,
+ rows_before,
+ "a reload wrote rows"
+ );
+ }
+
+ #[tokio::test]
+ async fn recap_without_compaction_is_a_notice() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let sid = seed(&state, None, &[(ObservationKind::UserPrompt, "ONLY")]).await;
+ let (status, body) = recap(&state, Some(sid.to_string()), None, None, None).await;
+ assert_eq!(status, StatusCode::OK);
+ assert!(body.contains("no compaction"), "{body}");
+ assert!(!body.contains("ONLY"), "{body}");
+ }
+
+ #[tokio::test]
+ async fn recap_for_unknown_session_is_a_notice() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let (status, body) = recap(&state, Some("never-seen".into()), None, None, None).await;
+ assert_eq!(status, StatusCode::OK);
+ assert!(body.contains("no session"), "{body}");
+ }
+
+ #[tokio::test]
+ async fn missing_session_id_is_400() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let (status, _) = recap(&state, None, None, None, None).await;
+ assert_eq!(status, StatusCode::BAD_REQUEST);
+ let (status, _) = recap(&state, Some(" ".into()), None, None, None).await;
+ assert_eq!(status, StatusCode::BAD_REQUEST);
+ }
+
+ #[tokio::test]
+ async fn another_operator_cannot_read_an_owned_session() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let sid = seed(&state, Some("bob"), &compacted_rows()).await;
+ let (status, body) =
+ recap(&state, Some(sid.to_string()), None, Some("alice"), None).await;
+ assert_eq!(status, StatusCode::OK);
+ assert!(body.contains("no session"), "{body}");
+ assert!(!body.contains("WINDOW-PROMPT"), "leaked: {body}");
+ }
+
+ #[tokio::test]
+ async fn owner_reads_own_session() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let sid = seed(&state, Some("bob"), &compacted_rows()).await;
+ let (_, body) = recap(&state, Some(sid.to_string()), None, Some("bob"), None).await;
+ assert!(body.contains("WINDOW-PROMPT"), "{body}");
+ }
+
+ #[tokio::test]
+ async fn db_user_without_grant_on_restricted_project_gets_403() {
+ use ai_memory_core::{NewUser, UserRole};
+ let tmp = TempDir::new().unwrap();
+ let state = crate::router::tests::make_state(&tmp).await;
+ state
+ .writer
+ .set_access_mode(state.project_id, ai_memory_store::AccessMode::Restricted)
+ .await
+ .unwrap();
+ let bob = state
+ .writer
+ .create_human_user(
+ NewUser {
+ username: "bob".into(),
+ name: None,
+ email: None,
+ },
+ UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ let state = Arc::new(state);
+ let sid = seed(&state, None, &compacted_rows()).await;
+ let (status, body) = recap(&state, Some(sid.to_string()), None, None, Some(bob)).await;
+ assert_eq!(status, StatusCode::FORBIDDEN, "{body}");
+ assert!(body.contains("not authorized"), "{body}");
+ assert!(!body.contains("WINDOW-PROMPT"), "leaked: {body}");
+ }
+
+ #[tokio::test]
+ async fn budget_param_is_clamped() {
+ let tmp = TempDir::new().unwrap();
+ let state = Arc::new(crate::router::tests::make_state(&tmp).await);
+ let sid = seed(&state, None, &compacted_rows()).await;
+ let (status, body) = recap(&state, Some(sid.to_string()), Some("1"), None, None).await;
+ assert_eq!(status, StatusCode::OK);
+ assert!(body.contains("compaction recap"), "{body}");
+ assert!(body.chars().count() <= 2_000);
+ }
+ }
}
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 68c5f6c0..b9ec16c3 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -598,7 +598,7 @@ async fn owner_stamp_for_event(
/// the same way the auth middleware already treats it. Reading `user` alone
/// would file every operator behind such a proxy as anonymous and hand them all
/// one shared bucket.
-fn actor_identity(
+pub(crate) fn actor_identity(
actor: Option<axum::Extension<ai_memory_core::ActorContext>>,
) -> Option<IdentityKey> {
actor.and_then(|axum::Extension(ctx)| ctx.identity_key())
@@ -625,13 +625,15 @@ fn admission_skips(
)
}
-/// Build a router with `POST /hook` (event ingress) and `GET /handoff`
-/// (synchronous handoff-fetch for session-start hooks).
+/// Build a router with `POST /hook` (event ingress), `GET /handoff`
+/// (synchronous handoff-fetch for session-start hooks) and `GET /recap`
+/// (the read-only compaction recap for a "reload context" prompt).
pub fn hook_router(state: HookState) -> Router {
Router::new()
.route("/hook", post(handle_hook))
.route("/hook/batch", post(handle_hook_batch))
.route("/handoff", get(handle_handoff))
+ .route("/recap", get(crate::recap::handle_recap))
.with_state(Arc::new(state))
}
@@ -4745,7 +4747,7 @@ const fn importance_for(event: HookEvent) -> u8 {
}
#[cfg(test)]
-mod tests {
+pub(crate) mod tests {
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;
@@ -6027,7 +6029,7 @@ mod tests {
id
}
- async fn make_state(tmp: &TempDir) -> HookState {
+ pub(crate) async fn make_state(tmp: &TempDir) -> HookState {
let store = Store::open(tmp.path()).unwrap();
let ws = store
.writer