Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(hooks): idempotent ingest — a retried spool entry no longer duplicates
Samir Hanna Verzafc8846d8bf3c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8ce3070e..1a6a65dc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- Hook ingest is now idempotent across delivery retries. Every event mints a+ UUID `ingest_key` once when it is spooled, baked into the entry's URL so+ each retry re-sends the same key; the server claims the key in the same+ store transaction as the observation row and skips a replayed event whose+ previous delivery succeeded but whose response was lost — the conservative+ retry no longer duplicates observations or session-end auto-handoffs.+ Compatible in both directions (older servers ignore the parameter, older+ clients keep at-least-once delivery); keys expire opportunistically after+ 30 days without a scheduler job.+- The store writer only accepts `Sanitized<NewObservation>`: the privacy+ strip is enforced by the type system at the persistence boundary, so an+ unsanitized observation cannot reach disk by construction.- The session-review sampler now scores a non-empty `Stop` observation justbelow `PreCompact` (88 vs 90) instead of the low `55` prior, so the opt-inassistant/Stop excerpt (a late summary or correction) competes for a samplingdiff --git a/Cargo.lock b/Cargo.lockindex 42c5494d..432ae9c9 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -71,6 +71,7 @@ dependencies = ["tracing","tracing-appender","tracing-subscriber",+ "uuid",][[package]]diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.tomlindex c069937f..eff25308 100644--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@ -50,6 +50,7 @@ tower-http.workspace = truetracing.workspace = truetracing-appender.workspace = truetracing-subscriber.workspace = true+uuid.workspace = truetempfile.workspace = truediff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex ea5036b5..86e925ec 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -507,8 +507,14 @@ where} else {""};+ // Idempotency key: minted ONCE here and baked into the spooled URL, so+ // every retry of this entry re-sends the same key. The server claims it+ // atomically with the observation row and skips replays whose previous+ // delivery succeeded but whose response was lost — closing the+ // conservative-retry duplication vector. Older servers ignore the param.+ let ingest_key = uuid::Uuid::new_v4().simple().to_string();let event_url = format!(- "{base}/hook?event={}&agent={}{}{}",+ "{base}/hook?event={}&agent={}{}{}&ingest_key={ingest_key}",args.event, args.agent, hook_qs, capture_qs);let entry = hook_spool::entry_for(diff --git a/crates/ai-memory-cli/tests/hook_payload.rs b/crates/ai-memory-cli/tests/hook_payload.rsindex b5e05f3d..820fe5f0 100644--- a/crates/ai-memory-cli/tests/hook_payload.rs+++ b/crates/ai-memory-cli/tests/hook_payload.rs@@ -233,3 +233,46 @@ fn opted_in_non_stop_event_is_inert() {"unrelated event body must stay byte-exact");}++#[test]+fn every_spooled_event_carries_a_persistent_ingest_key() {+ // The idempotency key is minted ONCE at spool time and baked into the+ // entry's URL: every retry of that entry re-sends the same key, so the+ // server can recognize a replay whose previous delivery succeeded but+ // whose response was lost. Distinct events must carry distinct keys.+ let tmp = tempfile::tempdir().expect("tempdir");+ let payload = br#"{"session_id":"idem","cwd":"/tmp/p","tool_name":"Read"}"#;++ let extract_key = |url: &str| -> String {+ url.split("ingest_key=")+ .nth(1)+ .and_then(|tail| tail.split('&').next())+ .unwrap_or_else(|| panic!("ingest_key missing from spooled url: {url}"))+ .to_string()+ };++ assert!(run_hook(tmp.path(), payload).status.success());+ assert!(run_hook(tmp.path(), payload).status.success());++ let entries = spool_entries(tmp.path());+ assert_eq!(entries.len(), 2);+ let keys: Vec<String> = entries+ .iter()+ .map(|e| {+ let entry: serde_json::Value =+ serde_json::from_slice(&std::fs::read(e.path()).expect("read spool entry"))+ .expect("parse spool entry");+ extract_key(entry["url"].as_str().expect("spooled url"))+ })+ .collect();+ for key in &keys {+ assert!(+ (1..=64).contains(&key.len())+ && key+ .bytes()+ .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_'),+ "key must pass server-side validation: {key:?}"+ );+ }+ assert_ne!(keys[0], keys[1], "distinct events must mint distinct keys");+}diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex 3f9b2e62..54d0d3be 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -64,6 +64,13 @@ pub struct HookQuery {/// `_ai_memory_assistant` excerpt; the server still gates on its own/// `capture_assistant` config before persisting it (#196).pub capture_assistant: Option<String>,+ /// Client idempotency key, minted once when the event is spooled and+ /// re-sent verbatim on every retry of that entry. Lets the server drop+ /// a replay whose previous delivery succeeded but whose response was+ /// lost (the conservative-retry duplication vector). Absent on older+ /// clients; older servers ignore it — both directions keep today's+ /// behavior.+ pub ingest_key: Option<String>,}/// Coalesced view of an incoming hook event after light parsing of the@@ -110,6 +117,10 @@ pub struct HookEnvelope {/// command). The server still gates on its own `capture_assistant` config/// before honoring it (#196).pub capture_assistant_requested: bool,+ /// Validated client idempotency key (`ingest_key` query param): 1–64+ /// ASCII `[A-Za-z0-9_-]` chars, else dropped at parse time. `Some` makes+ /// the ingest path dedup the event against a replayed delivery.+ pub ingest_key: Option<String>,/// Optional title hint extracted from the body.pub title_hint: Option<String>,/// Optional body excerpt extracted from the agent's raw payload.@@ -420,6 +431,7 @@ impl HookEnvelope {.and_then(|_| extension_body_excerpt(&raw))})};+ let ingest_key = query.ingest_key.filter(|k| valid_ingest_key(k));Self {event,agent,@@ -432,6 +444,7 @@ impl HookEnvelope {recall_default_global_requested,managed_run,capture_assistant_requested,+ ingest_key,extension,source_event,title_hint,@@ -441,6 +454,18 @@ impl HookEnvelope {}}+/// An ingest key is client-controlled input: accept only short, plain tokens+/// (1–64 ASCII alphanumerics, `-` or `_` — a UUID simple/hyphenated form+/// fits). Anything else is treated as absent rather than rejected, so a+/// malformed key degrades to today's at-least-once behavior instead of a 4xx.+fn valid_ingest_key(key: &str) -> bool {+ !key.is_empty()+ && key.len() <= 64+ && key+ .bytes()+ .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')+}+fn legacy_tool_title(event: HookEvent,agent: AgentKind,@@ -880,6 +905,37 @@ mod tests {assert!(rendered.contains("run-1"), "managed run field went missing");}+ /// `ingest_key` is client-controlled input: only short plain tokens pass;+ /// anything else degrades to "absent" (at-least-once), never a 4xx.+ #[test]+ fn ingest_key_is_validated_at_parse_time() {+ let fire = |key: Option<&str>| {+ HookEnvelope::from_query_and_body(+ HookQuery {+ event: "stop".into(),+ ingest_key: key.map(str::to_string),+ ..Default::default()+ },+ serde_json::json!({ "session_id": "k-1" }),+ )+ };+ // A UUID in simple or hyphenated form passes untouched.+ assert_eq!(+ fire(Some("abcDEF123_-")).ingest_key.as_deref(),+ Some("abcDEF123_-")+ );+ // Empty, oversized or non-token input is dropped, not rejected.+ let oversized = "x".repeat(65);+ for bad in ["", "spaces here", "chave!", "key\n", oversized.as_str()] {+ assert_eq!(+ fire(Some(bad)).ingest_key,+ None,+ "expected {bad:?} to be dropped"+ );+ }+ assert_eq!(fire(None).ingest_key, None);+ }+#[test]fn extension_event_preserves_source_event_when_opted_in() {let env = HookEnvelope::from_query_and_body(diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex dd661bbe..b7600525 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -1992,7 +1992,24 @@ async fn process(// below wants the scrubbed title, so keep a copy before the move.let sanitized = Sanitized::new(raw_obs, &state.sanitizer);let log_title = sanitized.inner().title.clone();- let _ = state.writer.insert_observation(sanitized).await?;+ // Idempotent ingest: when the client minted an `ingest_key` for this+ // spooled event, the key claim commits atomically with the observation.+ // `None` back means a previous delivery of this exact entry already+ // landed (the response was lost and the client retried) — skip the+ // whole replay: the observation, wiki pages, handoff and log line were+ // all produced by the first delivery. The client still gets the same+ // success it would have gotten then.+ let inserted = state+ .writer+ .insert_observation_ingest(sanitized, env.ingest_key.clone())+ .await?;+ if inserted.is_none() {+ debug!(+ key = env.ingest_key.as_deref().unwrap_or(""),+ "duplicate ingest_key; skipping replayed event"+ );+ return Ok(());+ }// Append the log line to the per-project log.md.if let Err(e) = log::append_event(@@ -2681,6 +2698,81 @@ mod tests {);}+ /// A spooled event retried after a lost response re-sends the same+ /// `ingest_key`; the replay must not duplicate the observation. A fresh+ /// key (a genuinely new event) and keyless events (older clients) keep+ /// landing exactly as today.+ #[tokio::test]+ async fn replayed_ingest_key_does_not_duplicate_observation() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;+ let sid = "55555555-5555-5555-5555-555555555555";+ let cwd = tmp.path().join("idem");+ std::fs::create_dir_all(&cwd).unwrap();+ let fire = |event: &str, key: Option<&str>| {+ HookEnvelope::from_query_and_body(+ HookQuery {+ event: event.into(),+ agent: Some("claude-code".into()),+ cwd: Some(cwd.to_string_lossy().into_owned()),+ ingest_key: key.map(str::to_string),+ ..Default::default()+ },+ serde_json::json!({+ "session_id": sid,+ "cwd": cwd.to_string_lossy(),+ "prompt": "hello",+ }),+ )+ };++ process(&state, fire("session-start", None), None)+ .await+ .unwrap();+ // First delivery lands; the byte-identical replay is skipped.+ process(+ &state,+ fire("user-prompt-submit", Some("entry-abc123")),+ None,+ )+ .await+ .unwrap();+ process(+ &state,+ fire("user-prompt-submit", Some("entry-abc123")),+ None,+ )+ .await+ .unwrap();+ // A different key is a new event, not a replay.+ process(+ &state,+ fire("user-prompt-submit", Some("entry-def456")),+ None,+ )+ .await+ .unwrap();+ // Keyless events (older clients) keep at-least-once behavior.+ process(&state, fire("user-prompt-submit", None), None)+ .await+ .unwrap();+ process(&state, fire("user-prompt-submit", None), None)+ .await+ .unwrap();++ let session_id: SessionId = sid.parse().unwrap();+ let observations = state+ .reader+ .observations_for_session(session_id)+ .await+ .unwrap();+ assert_eq!(+ observations.len(),+ 5,+ "session-start + first keyed + fresh key + 2 keyless (replay skipped)"+ );+ }+// Issue #154: event capture must never create or attribute to the// reserved `_global` preferences scope — not from a directory that// happens to carry the reserved name, and not from a marker-filediff --git a/crates/ai-memory-store/migrations/V33__ingest_keys.sql b/crates/ai-memory-store/migrations/V33__ingest_keys.sqlnew file mode 100644index 00000000..358b7c25--- /dev/null+++ b/crates/ai-memory-store/migrations/V33__ingest_keys.sql@@ -0,0 +1,11 @@+-- Idempotency keys for hook ingest. A spooled event carries a stable+-- client-generated key; the writer records it in the same transaction as the+-- observation/handoff it produced, so a batch retried after a lost response+-- is recognized and skipped instead of duplicating rows. Swept by TTL from+-- the maintenance scheduler (keys only need to outlive the client spool).+CREATE TABLE ingest_keys (+ key TEXT PRIMARY KEY,+ seen_at INTEGER NOT NULL+) WITHOUT ROWID;++CREATE INDEX idx_ingest_keys_seen_at ON ingest_keys (seen_at);diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 1f277cb2..b50823eb 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -2411,6 +2411,86 @@ mod tests {}}+ /// Ingest idempotency at the store boundary: the same `ingest_key`+ /// claims once — a replay answers `None` and writes nothing — while the+ /// keyless path is untouched. Old keys are swept opportunistically by+ /// the next keyed insert once past the TTL.+ #[tokio::test]+ async fn insert_observation_ingest_dedups_on_key() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None)+ .await+ .unwrap();+ let session_id = SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ id: session_id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::ClaudeCode,+ cwd: None,+ })+ .await+ .unwrap();+ let obs = || NewObservation {+ session_id,+ workspace_id: ws,+ project_id: proj,+ kind: ObservationKind::UserPrompt,+ extension: None,+ source_event: None,+ title: "prompt".into(),+ body: "hello".into(),+ importance: 5,+ };+ let keyed = |key: &str| {+ store.writer.insert_observation_ingest(+ Sanitized::new(obs(), &Sanitizer::builtin()),+ Some(key.to_string()),+ )+ };++ // First delivery lands, the replay is recognized and skipped.+ assert!(keyed("entry-1").await.unwrap().is_some());+ assert!(keyed("entry-1").await.unwrap().is_none());+ // A different key is a new event.+ assert!(keyed("entry-2").await.unwrap().is_some());++ let conn = Connection::open(store.db_path()).unwrap();+ let rows: i64 = conn+ .query_row("SELECT COUNT(*) FROM observations", [], |r| r.get(0))+ .unwrap();+ assert_eq!(rows, 2, "replay must not append a row");++ // TTL: backdate one key past the sweep horizon; the next keyed+ // insert purges it in the same transaction.+ conn.execute(+ "UPDATE ingest_keys SET seen_at = 1 WHERE key = 'entry-1'",+ [],+ )+ .unwrap();+ drop(conn);+ assert!(keyed("entry-3").await.unwrap().is_some());+ let conn = Connection::open(store.db_path()).unwrap();+ let stale: i64 = conn+ .query_row(+ "SELECT COUNT(*) FROM ingest_keys WHERE key = 'entry-1'",+ [],+ |r| r.get(0),+ )+ .unwrap();+ assert_eq!(stale, 0, "expired key must be swept");+ }+#[tokio::test]async fn latest_completed_session_for_project_ignores_open_sessions() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 0438610c..65fc740d 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -830,6 +830,53 @@ pub fn insert_observation(conn: &mut Connection,obs: &NewObservation,) -> StoreResult<ObservationId> {+ insert_observation_row(conn, obs)+}++/// Ingest-keys older than this are swept opportunistically on every keyed+/// insert. Keys only need to outlive the client spool (7 days + retry+/// backoff); 30 days is a generous margin.+const INGEST_KEY_TTL_MICROS: i64 = 30 * 24 * 60 * 60 * 1_000_000;++/// Append an observation carrying a client idempotency key, atomically.+///+/// The key claim and the observation row commit in ONE transaction: either+/// both land or neither does, so a crash cannot claim a key without its+/// observation (which a later retry would then wrongly skip). A key that was+/// already claimed means a previous delivery of the same spooled event+/// succeeded but the client never saw the response — return `Ok(None)` so the+/// ingest path can skip the replay without erroring (the response to the+/// client is the same `202 "queued"` either way).+pub fn insert_observation_keyed(+ conn: &mut Connection,+ obs: &NewObservation,+ ingest_key: &str,+) -> StoreResult<Option<ObservationId>> {+ let now = Timestamp::now().as_microsecond();+ let tx = conn.transaction()?;+ let claimed = tx.execute(+ "INSERT OR IGNORE INTO ingest_keys (key, seen_at) VALUES (?1, ?2)",+ params![ingest_key, now],+ )?;+ if claimed == 0 {+ // Replay of an already-processed event.+ tx.commit()?;+ return Ok(None);+ }+ // Opportunistic TTL sweep — indexed on seen_at, deletes 0 rows in the+ // common case, keeps the table self-maintaining without a scheduler job.+ tx.execute(+ "DELETE FROM ingest_keys WHERE seen_at < ?1",+ params![now - INGEST_KEY_TTL_MICROS],+ )?;+ let id = insert_observation_row(&tx, obs)?;+ tx.commit()?;+ Ok(Some(id))+}++/// The observation INSERT itself, shared by the plain and keyed paths+/// (`&Connection` so it also runs inside a [`rusqlite::Transaction`]).+fn insert_observation_row(conn: &Connection, obs: &NewObservation) -> StoreResult<ObservationId> {let id = ObservationId::new();let now = Timestamp::now().as_microsecond();let kind = observation_kind_as_str(obs.kind);diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex bc22ac30..5e48606b 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -91,7 +91,11 @@ pub(crate) enum WriteCmd {},InsertObservation {obs: NewObservation,- reply: oneshot::Sender<StoreResult<ObservationId>>,+ /// Client idempotency key from the hook ingest path — `Some` claims+ /// the key atomically with the row; an already-claimed key answers+ /// `Ok(None)` (duplicate replay, skip). `None` = plain insert.+ ingest_key: Option<String>,+ reply: oneshot::Sender<StoreResult<Option<ObservationId>>>,},InsertHandoff {handoff: NewHandoff,@@ -484,10 +488,34 @@ impl WriterHandle {&self,obs: Sanitized<NewObservation>,) -> StoreResult<ObservationId> {+ let inserted = self.insert_observation_ingest(obs, None).await?;+ Ok(inserted.expect("insert without an ingest key cannot be a duplicate"))+ }++ /// Append an observation from the hook-ingest path, deduplicating on the+ /// client idempotency key when one travelled with the event.+ ///+ /// With `Some(key)`, the key claim and the row commit in one store+ /// transaction; a key already claimed by an earlier delivery answers+ /// `Ok(None)` so the caller can skip the replay's side effects and still+ /// respond identically to the client. With `None` this is exactly+ /// [`Writer::insert_observation`].+ ///+ /// # Errors+ /// Returns [`StoreError::WriterClosed`] or propagates SQL errors.+ pub async fn insert_observation_ingest(+ &self,+ obs: Sanitized<NewObservation>,+ ingest_key: Option<String>,+ ) -> StoreResult<Option<ObservationId>> {let obs = obs.into_inner();let (tx, rx) = oneshot::channel();- self.send(WriteCmd::InsertObservation { obs, reply: tx })- .await?;+ self.send(WriteCmd::InsertObservation {+ obs,+ ingest_key,+ reply: tx,+ })+ .await?;rx.await.map_err(|_| StoreError::WriterClosed)?}@@ -1251,8 +1279,15 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {let result = ops::sweep_hollow_projects(&mut conn, min_age_days);send_or_warn(reply, result, "sweep_hollow_projects");}- WriteCmd::InsertObservation { obs, reply } => {- let result = ops::insert_observation(&mut conn, &obs);+ WriteCmd::InsertObservation {+ obs,+ ingest_key,+ reply,+ } => {+ let result = match ingest_key.as_deref() {+ Some(key) => ops::insert_observation_keyed(&mut conn, &obs, key),+ None => ops::insert_observation(&mut conn, &obs).map(Some),+ };send_or_warn(reply, result, "insert_observation");}WriteCmd::InsertHandoff { handoff, reply } => {