Skip to content

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.md
index 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 just
below `PreCompact` (88 vs 90) instead of the low `55` prior, so the opt-in
assistant/Stop excerpt (a late summary or correction) competes for a sampling
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index c069937f..eff25308 100644
--- a/crates/ai-memory-cli/Cargo.toml
+++ b/crates/ai-memory-cli/Cargo.toml
@@ -50,6 +50,7 @@ tower-http.workspace = true
tracing.workspace = true
tracing-appender.workspace = true
tracing-subscriber.workspace = true
+uuid.workspace = true
tempfile.workspace = true
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index 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.rs
index 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.rs
index 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.rs
index 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-file
diff --git a/crates/ai-memory-store/migrations/V33__ingest_keys.sql b/crates/ai-memory-store/migrations/V33__ingest_keys.sql
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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 } => {