Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(backfill): store each event's original time instead of the import time
Maxsuel Einstein191a8eea114a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4a28b987..3dc43fa3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -48,6 +48,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0unchanged — this only makes the existing warning reliably visible. (#903)### Fixed+- `ai-memory backfill` stamps each imported session and observation with the+ transcript's own event time instead of the moment it was imported, so a+ transcript from weeks ago no longer looks like it just happened. An event+ without a valid timestamp inherits the nearest one, and the session's start+ and end are the earliest and latest event times. The `/hook` body accepts a+ top-level RFC 3339 `occurred_at`; it must be positive and no more than five+ minutes in the future, and anything missing, malformed or out of bounds+ falls back to "now" instead of failing the hook. Because an imported+ session now ends in the past, it can sit below the auto-improve watermark+ and the experience-pass anchor (no automatic review until a newer session+ moves them), an opt-in observation retention window can prune its older+ observations right after import, and the "most recently active project"+ fallback after a restart may not pick a project that was just backfilled.+ (#919)- The default log filter's `rmcp=warn` cap (#894) no longer raises rmcpabove a quieter `log_level`. A target directive beats the global leveleither way, so with `log_level = "error"` or `"off"` the cap re-enabled thediff --git a/crates/ai-memory-cli/src/commands/backfill.rs b/crates/ai-memory-cli/src/commands/backfill.rsindex 4d322719..f60a8593 100644--- a/crates/ai-memory-cli/src/commands/backfill.rs+++ b/crates/ai-memory-cli/src/commands/backfill.rs@@ -354,6 +354,7 @@ async fn import_one(let sid = &session.native_session_id;let agent = session.harness.agent_kind().as_str();+ let resolved = resolve_occurred_at(&transcript.events);let mut items = Vec::with_capacity(transcript.events.len() + 2);items.push(hook_item(endpoint,@@ -364,11 +365,11 @@ async fn import_one(sid,&format!("{sid}:session-start"),None,- serde_json::json!({ "session_id": sid }),+ serde_json::json!({ "session_id": sid, "occurred_at": resolved.earliest }),)?);let mut content = 0usize;- for event in &transcript.events {- if let Some(mapped) = map_event(sid, event) {+ for (event, occurred_at) in transcript.events.iter().zip(&resolved.per_event) {+ if let Some(mapped) = map_event(sid, event, occurred_at.as_deref()) {items.push(hook_item(endpoint,workspace,@@ -392,13 +393,85 @@ async fn import_one(sid,&format!("{sid}:session-end"),None,- serde_json::json!({ "session_id": sid }),+ serde_json::json!({ "session_id": sid, "occurred_at": resolved.latest }),)?);post_hook_items(endpoint, &items).await?;Ok(content)}+/// Per-event `occurred_at` resolution for one transcript, plus the session's+/// overall boundary times.+struct ResolvedOccurredAt {+ /// Effective `occurred_at` for each event, in transcript order (RFC 3339).+ per_event: Vec<Option<String>>,+ /// The earliest valid event time — the session-start's `occurred_at`.+ /// A transcript is not guaranteed to be time-sorted (a reordered or+ /// clock-skewed import), so the first *entry* is not reliably the+ /// earliest *time*.+ earliest: Option<String>,+ /// The latest valid event time — the session-end's `occurred_at`, same+ /// reasoning as `earliest`.+ latest: Option<String>,+}++/// Resolve each event's effective `occurred_at`, letting one missing or+/// unparsable own timestamp inherit the nearest preceding *valid* one; an+/// event before the first valid timestamp inherits that first one instead of+/// staying unresolved (there is nothing earlier to inherit from). A value+/// that fails to parse as RFC 3339 is treated exactly like a missing one — it+/// never reaches the hook body, so a malformed transcript timestamp cannot+/// masquerade as a validated one downstream.+fn resolve_occurred_at(events: &[NewWorkstreamEvent]) -> ResolvedOccurredAt {+ let valid: Vec<Option<jiff::Timestamp>> = events+ .iter()+ .map(|event| {+ event+ .occurred_at+ .as_deref()+ .and_then(|s| s.parse::<jiff::Timestamp>().ok())+ })+ .collect();++ let mut per_event: Vec<Option<jiff::Timestamp>> = Vec::with_capacity(events.len());+ let mut last_valid: Option<jiff::Timestamp> = None;+ for ts in &valid {+ if ts.is_some() {+ last_valid = *ts;+ }+ per_event.push(last_valid);+ }+ // Backward-fill the leading gap: events before the first valid timestamp+ // had nothing preceding them to inherit above.+ if let Some(first_valid) = valid.iter().copied().flatten().next() {+ for slot in per_event.iter_mut() {+ match slot {+ Some(_) => break,+ None => *slot = Some(first_valid),+ }+ }+ }++ let (earliest, latest) = valid.into_iter().flatten().fold(+ (None, None),+ |(min, max): (Option<jiff::Timestamp>, Option<jiff::Timestamp>), ts| {+ (+ Some(min.map_or(ts, |m| m.min(ts))),+ Some(max.map_or(ts, |m| m.max(ts))),+ )+ },+ );++ ResolvedOccurredAt {+ per_event: per_event+ .into_iter()+ .map(|ts| ts.map(|t| t.to_string()))+ .collect(),+ earliest: earliest.map(|t| t.to_string()),+ latest: latest.map(|t| t.to_string()),+ }+}+/// A transcript event mapped to its `/hook` shape.struct MappedEvent {event: String,@@ -411,7 +484,15 @@ struct MappedEvent {/// `user-prompt` observation; every other content-bearing event is recorded as/// a backfill extension observation. Non-content boundary events (compaction,/// checkpoint, annotation) are dropped — they are not session content.-fn map_event(session_id: &str, event: &NewWorkstreamEvent) -> Option<MappedEvent> {+///+/// `occurred_at` (RFC 3339), already resolved by the caller, rides in the hook+/// body so the imported observation is dated at the transcript's own event+/// time rather than at import time.+fn map_event(+ session_id: &str,+ event: &NewWorkstreamEvent,+ occurred_at: Option<&str>,+) -> Option<MappedEvent> {let content = event.content.trim();if content.is_empty() {return None;@@ -423,7 +504,11 @@ fn map_event(session_id: &str, event: &NewWorkstreamEvent) -> Option<MappedEventevent: "user-prompt".to_string(),source_event: None,ingest_key,- body: serde_json::json!({ "session_id": session_id, "prompt": event.content }),+ body: serde_json::json!({+ "session_id": session_id,+ "prompt": event.content,+ "occurred_at": occurred_at,+ }),}),WorkstreamEventKind::Message| WorkstreamEventKind::ToolCall@@ -442,6 +527,7 @@ fn map_event(session_id: &str, event: &NewWorkstreamEvent) -> Option<MappedEvent"session_id": session_id,"title": first_line(content),"message": event.content,+ "occurred_at": occurred_at,}),})}@@ -660,6 +746,7 @@ mod tests {let m = map_event("sid",&event(WorkstreamEventKind::Message, Some("user"), "do the thing"),+ Some("2026-09-10T12:00:00Z"),).expect("user message maps");assert_eq!(m.event, "user-prompt");@@ -668,6 +755,7 @@ mod tests {"user-prompt is a lifecycle event, not an extension");assert_eq!(m.body["prompt"], "do the thing");+ assert_eq!(m.body["occurred_at"], "2026-09-10T12:00:00Z");assert_eq!(m.ingest_key, "sid:evt-1","ingest key is stable per source event"@@ -683,6 +771,7 @@ mod tests {Some("assistant"),"here is the plan\nline2",),+ None,).expect("assistant maps");assert_eq!(a.event, "backfill.assistant-message");@@ -692,22 +781,134 @@ mod tests {"title is the first line");assert_eq!(a.body["message"], "here is the plan\nline2");+ assert!(+ a.body["occurred_at"].is_null(),+ "no occurred_at was supplied"+ );let t = map_event("sid",&event(WorkstreamEventKind::ToolCall, None, "grep foo"),+ None,).expect("tool call maps");assert_eq!(t.event, "backfill.tool_call");assert_eq!(t.source_event.as_deref(), Some("tool_call"));}+ /// Round-trips a literal RFC 3339 string through `jiff::Timestamp` so+ /// expectations match `resolve_occurred_at`'s own parse-then-format+ /// output rather than assuming it echoes the input string verbatim.+ fn ts(literal: &str) -> String {+ literal.parse::<jiff::Timestamp>().unwrap().to_string()+ }++ #[test]+ fn resolve_occurred_at_fills_gaps_from_the_preceding_event() {+ let mut e1 = event(WorkstreamEventKind::Message, Some("user"), "one");+ e1.occurred_at = Some("2026-09-10T12:00:00Z".to_string());+ let e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two"); // no timestamp+ let mut e3 = event(WorkstreamEventKind::ToolCall, None, "three");+ e3.occurred_at = Some("2026-09-10T12:05:00Z".to_string());+ let e4 = event(WorkstreamEventKind::ToolResult, None, "four"); // no timestamp++ let resolved = resolve_occurred_at(&[e1, e2, e3, e4]);+ assert_eq!(+ resolved.per_event,+ vec![+ Some(ts("2026-09-10T12:00:00Z")),+ Some(ts("2026-09-10T12:00:00Z")),+ Some(ts("2026-09-10T12:05:00Z")),+ Some(ts("2026-09-10T12:05:00Z")),+ ],+ "an event without its own timestamp inherits the nearest preceding one"+ );+ assert_eq!(resolved.earliest, Some(ts("2026-09-10T12:00:00Z")));+ assert_eq!(resolved.latest, Some(ts("2026-09-10T12:05:00Z")));+ }++ #[test]+ fn resolve_occurred_at_backfills_the_leading_gap_from_the_first_valid_timestamp() {+ let e1 = event(WorkstreamEventKind::Message, Some("user"), "one"); // no timestamp+ let e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two"); // no timestamp+ let mut e3 = event(WorkstreamEventKind::ToolCall, None, "three");+ e3.occurred_at = Some("2026-09-10T12:05:00Z".to_string());++ let resolved = resolve_occurred_at(&[e1, e2, e3]);+ assert_eq!(+ resolved.per_event,+ vec![+ Some(ts("2026-09-10T12:05:00Z")),+ Some(ts("2026-09-10T12:05:00Z")),+ Some(ts("2026-09-10T12:05:00Z")),+ ],+ "events before the first valid timestamp inherit it backward, \+ not just the ones after"+ );+ }++ #[test]+ fn resolve_occurred_at_treats_an_unparsable_timestamp_as_missing() {+ let mut e1 = event(WorkstreamEventKind::Message, Some("user"), "one");+ e1.occurred_at = Some("2026-09-10T12:00:00Z".to_string());+ let mut e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two");+ e2.occurred_at = Some("not-a-timestamp".to_string());++ let resolved = resolve_occurred_at(&[e1, e2]);+ assert_eq!(+ resolved.per_event,+ vec![+ Some(ts("2026-09-10T12:00:00Z")),+ Some(ts("2026-09-10T12:00:00Z"))+ ],+ "an unparsable timestamp must not reach the hook body; the \+ preceding valid one is inherited instead"+ );+ assert_eq!(resolved.latest, Some(ts("2026-09-10T12:00:00Z")));+ }++ #[test]+ fn resolve_occurred_at_uses_min_and_max_not_first_and_last_when_out_of_order() {+ // A transcript is not guaranteed to be time-sorted (clock skew,+ // reordering); the session boundary must reflect the actual extremes,+ // not just the first/last entries.+ let mut e1 = event(WorkstreamEventKind::Message, Some("user"), "one");+ e1.occurred_at = Some("2026-09-10T12:05:00Z".to_string());+ let mut e2 = event(WorkstreamEventKind::Message, Some("assistant"), "two");+ e2.occurred_at = Some("2026-09-10T12:00:00Z".to_string());++ let resolved = resolve_occurred_at(&[e1, e2]);+ assert_eq!(+ resolved.earliest,+ Some(ts("2026-09-10T12:00:00Z")),+ "earliest must be the minimum valid time, not the first entry"+ );+ assert_eq!(+ resolved.latest,+ Some(ts("2026-09-10T12:05:00Z")),+ "latest must be the maximum valid time, not the last entry"+ );+ }++ #[test]+ fn resolve_occurred_at_stays_none_when_nothing_has_a_timestamp() {+ let events = vec![+ event(WorkstreamEventKind::Message, Some("user"), "one"),+ event(WorkstreamEventKind::Message, Some("assistant"), "two"),+ ];+ let resolved = resolve_occurred_at(&events);+ assert_eq!(resolved.per_event, vec![None, None]);+ assert_eq!(resolved.earliest, None);+ assert_eq!(resolved.latest, None);+ }+#[test]fn empty_and_boundary_events_are_dropped() {assert!(map_event("sid",- &event(WorkstreamEventKind::Message, Some("user"), " ")+ &event(WorkstreamEventKind::Message, Some("user"), " "),+ None,).is_none(),"whitespace-only content is not an observation"@@ -718,7 +919,7 @@ mod tests {WorkstreamEventKind::Annotation,] {assert!(- map_event("sid", &event(kind, None, "boundary")).is_none(),+ map_event("sid", &event(kind, None, "boundary"), None).is_none(),"{kind:?} is not session content");}diff --git a/crates/ai-memory-cli/src/commands/finalize_session.rs b/crates/ai-memory-cli/src/commands/finalize_session.rsindex 2246cd41..ea1b9f9e 100644--- a/crates/ai-memory-cli/src/commands/finalize_session.rs+++ b/crates/ai-memory-cli/src/commands/finalize_session.rs@@ -290,6 +290,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id,@@ -344,6 +345,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex be489d74..8b5f3f18 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -3776,6 +3776,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id: worked_in,@@ -3789,6 +3790,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id: worked_in,@@ -3877,6 +3879,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id: elsewhere,@@ -3890,6 +3893,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id: elsewhere,@@ -3939,6 +3943,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id,@@ -3952,6 +3957,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id,diff --git a/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rsindex 89fa3c08..b2f98c56 100644--- a/crates/ai-memory-consolidate/src/auto_improve.rs+++ b/crates/ai-memory-consolidate/src/auto_improve.rs@@ -2346,6 +2346,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -2360,6 +2361,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -2450,6 +2452,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -2464,6 +2467,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-consolidate/src/auto_improve_schedule.rs b/crates/ai-memory-consolidate/src/auto_improve_schedule.rsindex d5399d96..9ee8cbcc 100644--- a/crates/ai-memory-consolidate/src/auto_improve_schedule.rs+++ b/crates/ai-memory-consolidate/src/auto_improve_schedule.rs@@ -662,6 +662,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: before_startup_init,workspace_id: ws,project_id,@@ -692,6 +693,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id,@@ -829,6 +831,7 @@ mod tests {store.writer.begin_session(ai_memory_core::NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: project,@@ -955,6 +958,7 @@ mod tests {store.writer.begin_session(ai_memory_core::NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: project,@@ -1074,6 +1078,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -1088,6 +1093,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-consolidate/tests/suite/entropy_experience.rs b/crates/ai-memory-consolidate/tests/suite/entropy_experience.rsindex 67766805..c03f06c4 100644--- a/crates/ai-memory-consolidate/tests/suite/entropy_experience.rs+++ b/crates/ai-memory-consolidate/tests/suite/entropy_experience.rs@@ -110,6 +110,7 @@ async fn harness_with_two_sessions() -> Harness {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-consolidate/tests/suite/observation_retention.rs b/crates/ai-memory-consolidate/tests/suite/observation_retention.rsindex 4f1d441c..d28b88db 100644--- a/crates/ai-memory-consolidate/tests/suite/observation_retention.rs+++ b/crates/ai-memory-consolidate/tests/suite/observation_retention.rs@@ -105,6 +105,7 @@ async fn session(store: &Store, ws: WorkspaceId, proj: ProjectId, n: u8, body: &store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,@@ -120,6 +121,7 @@ async fn session(store: &Store, ws: WorkspaceId, proj: ProjectId, n: u8, body: &.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-consolidate/tests/suite/recall_eval.rs b/crates/ai-memory-consolidate/tests/suite/recall_eval.rsindex 1a78e3e6..8fe95aba 100644--- a/crates/ai-memory-consolidate/tests/suite/recall_eval.rs+++ b/crates/ai-memory-consolidate/tests/suite/recall_eval.rs@@ -354,6 +354,7 @@ async fn raw_observation_fallback_recovers_detail_when_wiki_misses() {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -367,6 +368,7 @@ async fn raw_observation_fallback_recovers_detail_when_wiki_misses() {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-core/src/observation.rs b/crates/ai-memory-core/src/observation.rsindex 1b4bd031..107fa3c1 100644--- a/crates/ai-memory-core/src/observation.rs+++ b/crates/ai-memory-core/src/observation.rs@@ -106,6 +106,11 @@ pub struct NewObservation {pub body: String,/// 1..=10. Default 5.pub importance: u8,+ /// Original event time in microseconds, when known (e.g. backfill+ /// replaying a transcript's own timestamps). `None` means "now" — the+ /// store fills it in at write time.+ #[serde(default)]+ pub occurred_at: Option<i64>,}/// Materialised view of an observation row.@@ -154,6 +159,11 @@ pub struct NewSession {/// session shared, which is the single-operator behaviour.#[serde(default)]pub actor_user: Option<String>,+ /// Original event time in microseconds, when known (e.g. backfill+ /// replaying a transcript's own timestamps). `None` means "now" — the+ /// store fills it in at write time.+ #[serde(default)]+ pub occurred_at: Option<i64>,}#[cfg(test)]diff --git a/crates/ai-memory-core/src/sanitize.rs b/crates/ai-memory-core/src/sanitize.rsindex a691c2db..688a01c4 100644--- a/crates/ai-memory-core/src/sanitize.rs+++ b/crates/ai-memory-core/src/sanitize.rs@@ -808,6 +808,7 @@ mod tests {#[test]fn observation_round_trip() {let raw = NewObservation {+ occurred_at: None,session_id: SessionId::new(),workspace_id: WorkspaceId::new(),project_id: ProjectId::new(),@@ -826,6 +827,7 @@ mod tests {#[test]fn observation_boundary_caps_after_sanitizing_without_splitting_utf8() {let raw = NewObservation {+ occurred_at: None,session_id: SessionId::new(),workspace_id: WorkspaceId::new(),project_id: ProjectId::new(),diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex 275acc04..8b3f8c64 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -148,6 +148,12 @@ pub struct HookEnvelope {pub title_hint: Option<String>,/// Optional body excerpt extracted from the agent's raw payload.pub body_excerpt: Option<String>,+ /// Original event time (RFC 3339), when the client supplied one —+ /// notably backfill replaying a transcript's own per-event timestamps.+ /// Bounded and converted at the point of use via+ /// [`HookEnvelope::occurred_at_micros`]; never trust it unchecked.+ #[serde(default)]+ pub occurred_at: Option<String>,/// The agent's raw JSON, kept for forensics.pub raw: serde_json::Value,}@@ -176,6 +182,17 @@ impl std::fmt::Debug for HookEnvelope {).field("extension", &self.extension).field("source_event", &self.source_event)+ // Client-controlled and only loosely shaped at this point (parsed+ // and bounded later, in `occurred_at_micros`), so it is capped+ // here rather than logged verbatim — a valid RFC 3339 timestamp+ // is well under this, only a hostile payload would hit it.+ .field(+ "occurred_at",+ &self+ .occurred_at+ .as_deref()+ .map(|s| truncate_utf8_bytes(s, 64)),+ ).field("title_hint",&self.title_hint.as_ref().map(|_| "<redacted>"),@@ -554,6 +571,25 @@ impl HookEnvelope {})};let ingest_key = query.ingest_key.filter(|k| valid_ingest_key(k));+ // Original event time (RFC 3339), when the client carried one — currently+ // only `ai-memory backfill`, replaying a transcript's own per-event+ // timestamps. This is numeric metadata, not text, so it never goes+ // through the sanitizer (invariant #6 is about untrusted TEXT reaching+ // storage/prompts unscrubbed; a timestamp has no such surface). It is+ // still client-controlled input over the hook endpoint, so it is bounded+ // at parse time in `occurred_at_micros`, not trusted here.+ //+ // Read from the top-level body only, unlike `extract_string`'s nested+ // `payload`/`event`/`properties`/`info`/`path` search: that search+ // exists for text fields real agent harnesses nest under those keys,+ // but a real harness payload happening to carry an `occurred_at` key+ // somewhere in that structure must not be mistaken for backfill's own+ // top-level field.+ let occurred_at = raw+ .get("occurred_at")+ .and_then(serde_json::Value::as_str)+ .filter(|s| !s.is_empty())+ .map(str::to_string);Self {event,agent,@@ -573,11 +609,43 @@ impl HookEnvelope {source_event,title_hint,body_excerpt,+ occurred_at,raw,}}++ /// Parse and bound [`Self::occurred_at`] into a microsecond timestamp+ /// suitable for `NewSession`/`NewObservation::occurred_at`.+ ///+ /// `occurred_at` arrives from a client over the hook endpoint, so it is+ /// bounded here rather than trusted outright: only strictly positive+ /// values that are no more than [`MAX_OCCURRED_AT_FUTURE_SKEW_MICROS`]+ /// ahead of server time are honored. Anything else — an unparseable+ /// string, a non-positive value, or a suspicious far-future timestamp —+ /// resolves to `None`, which callers fall back to "now" for. Hooks are+ /// fire-and-forget, so this never errors.+ #[must_use]+ pub fn occurred_at_micros(&self) -> Option<i64> {+ let parsed = self+ .occurred_at+ .as_deref()?+ .parse::<jiff::Timestamp>()+ .ok()?+ .as_microsecond();+ let now = jiff::Timestamp::now().as_microsecond();+ if parsed > 0 && parsed <= now.saturating_add(MAX_OCCURRED_AT_FUTURE_SKEW_MICROS) {+ Some(parsed)+ } else {+ None+ }+ }}+/// How far ahead of server time a client-supplied `occurred_at` may sit+/// before it is treated as bogus (clock skew, or a hostile client) and+/// dropped to `None` instead of being trusted.+const MAX_OCCURRED_AT_FUTURE_SKEW_MICROS: i64 = 5 * 60 * 1_000_000;+/// 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@@ -1184,6 +1252,89 @@ mod tests {assert_eq!(env.project_source, ProjectSource::RepoRoot);}+ /// `occurred_at` is client-controlled input arriving over the hook+ /// endpoint, so it must be bounded, not trusted outright. A valid past+ /// timestamp is stored exactly; garbage, non-positive, and far-future+ /// values must all fall back to `None` ("now" at the store boundary) —+ /// never an error, since hooks are fire-and-forget.+ #[test]+ fn occurred_at_micros_accepts_a_valid_past_timestamp() {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "user-prompt-submit".into(),+ ..Default::default()+ },+ serde_json::json!({ "session_id": "s", "occurred_at": "2026-09-10T12:00:00Z" }),+ );+ let expected = "2026-09-10T12:00:00Z"+ .parse::<jiff::Timestamp>()+ .unwrap()+ .as_microsecond();+ assert_eq!(env.occurred_at_micros(), Some(expected));+ }++ #[test]+ fn occurred_at_micros_rejects_a_far_future_timestamp() {+ // Adversarial: a client claiming its event happened next year must not+ // be trusted — the bound must actually reject it.+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "user-prompt-submit".into(),+ ..Default::default()+ },+ serde_json::json!({ "session_id": "s", "occurred_at": "2099-01-01T00:00:00Z" }),+ );+ assert_eq!(+ env.occurred_at_micros(),+ None,+ "a far-future timestamp must not be trusted"+ );+ }++ #[test]+ fn occurred_at_micros_rejects_non_positive_values() {+ for bogus in ["1970-01-01T00:00:00Z", "0000-01-01T00:00:00Z"] {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "user-prompt-submit".into(),+ ..Default::default()+ },+ serde_json::json!({ "session_id": "s", "occurred_at": bogus }),+ );+ // The epoch and earlier parse fine as an RFC 3339 timestamp but+ // must still be rejected: a non-positive microsecond value is+ // never a plausible original event time.+ let micros = bogus.parse::<jiff::Timestamp>().unwrap().as_microsecond();+ assert!(micros <= 0, "fixture must actually be non-positive");+ assert_eq!(env.occurred_at_micros(), None);+ }+ }++ #[test]+ fn occurred_at_micros_rejects_garbage_strings() {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "user-prompt-submit".into(),+ ..Default::default()+ },+ serde_json::json!({ "session_id": "s", "occurred_at": "not-a-timestamp" }),+ );+ assert_eq!(env.occurred_at_micros(), None);+ }++ #[test]+ fn occurred_at_missing_from_the_body_parses_as_none() {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "user-prompt-submit".into(),+ ..Default::default()+ },+ serde_json::json!({ "session_id": "s" }),+ );+ assert_eq!(env.occurred_at, None);+ assert_eq!(env.occurred_at_micros(), None);+ }+#[test]fn body_is_subagent_detects_harness_markers() {// grok tags subagent tool-use events with `subagentType`.diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex ad7517cb..f8474527 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -1353,6 +1353,7 @@ async fn fetch_and_accept_handoff(let receiving_session = if handoff.is_some() {match accepting_session {Some(id) => Some(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,@@ -2653,6 +2654,7 @@ async fn process_authorized(agent_kind: env.agent,cwd: env.cwd.as_ref().map(std::path::PathBuf::from),actor_user: owner_stamp.clone(),+ occurred_at: env.occurred_at_micros(),};let kind = env.event.to_observation_kind();let raw_obs = NewObservation {@@ -2668,6 +2670,7 @@ async fn process_authorized(.unwrap_or_else(|| kind.as_str().to_string()),body: env.body_excerpt.clone().unwrap_or_default(),importance: importance_for(env.event),+ occurred_at: env.occurred_at_micros(),};let sanitized = Sanitized::new(raw_obs, &state.sanitizer);let log_title = sanitized.inner().title.clone();@@ -2853,7 +2856,7 @@ async fn process_authorized(if is_ephemeral_session(&observations) {let outcome = state.writer- .end_admitted_lifecycle_only_session(admitted.clone())+ .end_admitted_lifecycle_only_session(admitted.clone(), env.occurred_at_micros()).await?;match outcome {ai_memory_store::LifecycleOnlyEndOutcome::Ended { reopened_handoff } => {@@ -2982,13 +2985,18 @@ async fn process_authorized(Some(handoff) => Some(state.writer- .end_admitted_session_with_handoff(admitted.clone(), Some(page_id), handoff)+ .end_admitted_session_with_handoff(+ admitted.clone(),+ Some(page_id),+ handoff,+ env.occurred_at_micros(),+ ).await?,),None => {state.writer- .end_admitted_session(admitted.clone(), Some(page_id))+ .end_admitted_session(admitted.clone(), Some(page_id), env.occurred_at_micros()).await?;None}@@ -3778,6 +3786,7 @@ mod tests {state.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: state.workspace_id,project_id: state.project_id,@@ -3792,6 +3801,7 @@ mod tests {.insert_observation_ingest(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: state.workspace_id,project_id: state.project_id,@@ -4961,6 +4971,7 @@ mod tests {let pending_obs = || {Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -7549,6 +7560,7 @@ mod tests {.insert_observation_ingest(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: state.workspace_id,project_id: state.project_id,@@ -8390,6 +8402,7 @@ mod tests {state.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: state.workspace_id,project_id,@@ -8490,6 +8503,7 @@ mod tests {state.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: state.workspace_id,project_id,@@ -9632,6 +9646,7 @@ mod tests {state.writer.begin_session(NewSession {+ occurred_at: None,id: sid,workspace_id: state.workspace_id,project_id: target,@@ -9771,6 +9786,7 @@ mod tests {let pending_observation = || {Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id,@@ -10260,6 +10276,7 @@ mod tests {state.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: state.workspace_id,project_id: state.project_id,@@ -13166,4 +13183,110 @@ mod tests {assert!(!is_acknowledgment("fix the bug in main.rs"));assert!(!is_acknowledgment("what is the return type?"));}++ /// End-to-end proof that a client-supplied `occurred_at` reaches every+ /// timestamp column it is supposed to via the real `/hook` ingest path+ /// (`process_authorized` -> `admit_hook_session_event` for the session+ /// row, `insert_observation*` for the observation), not just the+ /// lower-level store functions those handlers call. `admit_hook_session_event`+ /// creates the `sessions` row on its own INSERT, separate from+ /// `begin_session_row`, so this is the path a real backfilled+ /// session-start actually takes.+ #[tokio::test]+ async fn hook_occurred_at_stamps_session_and_observation_times_end_to_end() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;+ let session = "occurred-at-e2e";+ let start_at = "2025-09-10T12:00:00Z";+ let prompt_at = "2025-09-10T12:01:00Z";+ let end_at = "2025-09-10T12:05:00Z";+ let envelope = |event: &str, occurred_at: &str, prompt: Option<&str>| {+ let mut body = serde_json::json!({+ "session_id": session,+ "occurred_at": occurred_at,+ });+ if let Some(prompt) = prompt {+ body["prompt"] = serde_json::json!(prompt);+ }+ HookEnvelope::from_query_and_body(+ HookQuery {+ event: event.into(),+ agent: Some("claude-code".into()),+ workspace: Some("default".into()),+ project: Some("scratch".into()),+ ..Default::default()+ },+ body,+ )+ };++ process(+ &state,+ envelope("session-start", start_at, None),+ None,+ Vec::new(),+ )+ .await+ .unwrap();+ process(+ &state,+ envelope("user-prompt-submit", prompt_at, Some("backfilled prompt")),+ None,+ Vec::new(),+ )+ .await+ .unwrap();+ process(+ &state,+ envelope("session-end", end_at, None),+ None,+ Vec::new(),+ )+ .await+ .unwrap();++ let session_id = resolve_native_session_id(session);+ let summary = state+ .reader+ .session_summary_scoped(+ state.workspace_id,+ state.project_id,+ session_id,+ ai_memory_core::OwnerFilter::Any,+ )+ .await+ .unwrap()+ .expect("session row exists");+ let expected_start = start_at.parse::<jiff::Timestamp>().unwrap().to_string();+ let expected_end = end_at.parse::<jiff::Timestamp>().unwrap().to_string();+ assert_eq!(+ summary.started_at, expected_start,+ "started_at must come from the session-start event's occurred_at, \+ not import time (admit_hook_session_event's own INSERT)"+ );+ assert_eq!(+ summary.ended_at.as_deref(),+ Some(expected_end.as_str()),+ "ended_at must come from the session-end event's occurred_at"+ );+ assert!(+ summary.started_at <= expected_end,+ "a backfilled session must not end before it starts"+ );++ let observations = state+ .reader+ .observations_for_session(session_id)+ .await+ .unwrap();+ let prompt_obs = observations+ .iter()+ .find(|o| o.body == "backfilled prompt")+ .expect("the user-prompt observation was recorded");+ let expected_prompt_at = prompt_at.parse::<jiff::Timestamp>().unwrap();+ assert_eq!(+ prompt_obs.created_at, expected_prompt_at,+ "created_at must come from the observation's own occurred_at"+ );+ }}diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 60194333..15545426 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -7864,6 +7864,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id: ws,project_id,@@ -7878,6 +7879,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id: ws,project_id: target,@@ -8098,6 +8100,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id,@@ -8113,6 +8116,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: target,@@ -8307,6 +8311,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id,@@ -9186,6 +9191,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9199,6 +9205,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -9342,6 +9349,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9355,6 +9363,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -9482,6 +9491,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9495,6 +9505,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -9600,6 +9611,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9613,6 +9625,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -9701,6 +9714,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9714,6 +9728,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -9800,6 +9815,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9813,6 +9829,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 10d4e0ee..86b529a9 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -6200,6 +6200,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id,@@ -6213,6 +6214,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id,@@ -8515,6 +8517,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -8528,6 +8531,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -8595,6 +8599,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: scoped,@@ -8608,6 +8613,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: scoped,@@ -9610,6 +9616,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -9624,6 +9631,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -9685,6 +9693,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: other,@@ -13074,6 +13083,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id,@@ -13087,6 +13097,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id,@@ -13267,6 +13278,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -13280,6 +13292,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-mcp/tests/suite/admin_move.rs b/crates/ai-memory-mcp/tests/suite/admin_move.rsindex 141132aa..44957257 100644--- a/crates/ai-memory-mcp/tests/suite/admin_move.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_move.rs@@ -588,6 +588,7 @@ async fn move_project_true_move_preserves_sessions_and_observations() {store.writer.begin_session(NewSession {+ occurred_at: None,id: sid,workspace_id: src_ws,project_id: src_proj,@@ -601,6 +602,7 @@ async fn move_project_true_move_preserves_sessions_and_observations() {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid,workspace_id: src_ws,project_id: src_proj,diff --git a/crates/ai-memory-mcp/tests/suite/admin_move_session.rs b/crates/ai-memory-mcp/tests/suite/admin_move_session.rsindex 1dba81a8..f7a5a1a4 100644--- a/crates/ai-memory-mcp/tests/suite/admin_move_session.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_move_session.rs@@ -138,6 +138,7 @@ async fn seed_session(store.writer.begin_session(NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -152,6 +153,7 @@ async fn seed_session(.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: proj,@@ -515,6 +517,7 @@ async fn move_session_pending_job_or_open_session_needs_force() {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid,workspace_id: scopes.ws,project_id: scopes.src,@@ -573,6 +576,7 @@ async fn move_session_pending_job_or_open_session_needs_force() {store.writer.begin_session(NewSession {+ occurred_at: None,id: open,workspace_id: scopes.ws,project_id: scopes.src,@@ -689,6 +693,7 @@ async fn move_session_batch_stops_at_first_error_and_reports_progress() {store.writer.begin_session(NewSession {+ occurred_at: None,id: open,workspace_id: scopes.ws,project_id: scopes.src,@@ -925,6 +930,7 @@ async fn scatter_observations(.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: proj,@@ -1035,6 +1041,7 @@ async fn move_session_rehome_of_open_session_needs_no_force() {store.writer.begin_session(NewSession {+ occurred_at: None,id: sid,workspace_id: scopes.ws,project_id: scopes.dst,diff --git a/crates/ai-memory-mcp/tests/suite/admin_phase3.rs b/crates/ai-memory-mcp/tests/suite/admin_phase3.rsindex 61a85750..7382316f 100644--- a/crates/ai-memory-mcp/tests/suite/admin_phase3.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_phase3.rs@@ -317,6 +317,7 @@ async fn seed_sessions_for_reorg(store: &Store) -> (SessionId, SessionId) {store.writer.begin_session(NewSession {+ occurred_at: None,id: sid_a,workspace_id: ws,project_id: scratch,@@ -330,6 +331,7 @@ async fn seed_sessions_for_reorg(store: &Store) -> (SessionId, SessionId) {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid_a,workspace_id: ws,project_id: scratch,@@ -349,6 +351,7 @@ async fn seed_sessions_for_reorg(store: &Store) -> (SessionId, SessionId) {store.writer.begin_session(NewSession {+ occurred_at: None,id: sid_b,workspace_id: ws,project_id: scratch,@@ -362,6 +365,7 @@ async fn seed_sessions_for_reorg(store: &Store) -> (SessionId, SessionId) {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid_b,workspace_id: ws,project_id: scratch,diff --git a/crates/ai-memory-mcp/tests/suite/admin_purge.rs b/crates/ai-memory-mcp/tests/suite/admin_purge.rsindex 1050e28f..4f939289 100644--- a/crates/ai-memory-mcp/tests/suite/admin_purge.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_purge.rs@@ -111,6 +111,7 @@ async fn seed_ended_session_summary(store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -210,6 +211,7 @@ async fn seed_two_projects(store: &Store, wiki: &Wiki) -> (WorkspaceId, ProjectIstore.writer.begin_session(NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -224,6 +226,7 @@ async fn seed_two_projects(store: &Store, wiki: &Wiki) -> (WorkspaceId, ProjectI.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 58365e34..87c83e19 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -827,6 +827,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: out_of_scope_session,workspace_id: ws,project_id: other,@@ -1727,6 +1728,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: claimed_session,workspace_id: src_ws,project_id: proj,@@ -2082,6 +2084,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id: ws,project_id: proj,@@ -3206,6 +3209,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -3219,6 +3223,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -3266,6 +3271,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -3279,6 +3285,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -3340,6 +3347,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id,@@ -3351,6 +3359,7 @@ mod tests {.unwrap();}let obs = |session_id, project_id| NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id,@@ -3454,6 +3463,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,@@ -3499,6 +3509,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -3609,6 +3620,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -3643,6 +3655,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -3686,6 +3699,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -3747,6 +3761,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: historical,workspace_id: ws,project_id: proj,@@ -3778,6 +3793,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,@@ -3853,6 +3869,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: reviewed_after_watermark,workspace_id: ws,project_id: proj,@@ -3928,6 +3945,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: historical,workspace_id: ws,project_id,@@ -3955,6 +3973,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id,@@ -3998,6 +4017,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: first_session,workspace_id: ws,project_id: proj,@@ -4045,6 +4065,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,@@ -4124,6 +4145,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session,workspace_id: ws,project_id: proj,@@ -4262,6 +4284,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -4344,6 +4367,7 @@ mod tests {super::ops::insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,@@ -6117,6 +6141,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id,diff --git a/crates/ai-memory-store/src/migrations.rs b/crates/ai-memory-store/src/migrations.rsindex 67f35b17..aba7e9cd 100644--- a/crates/ai-memory-store/src/migrations.rs+++ b/crates/ai-memory-store/src/migrations.rs@@ -404,6 +404,7 @@ mod tests {crate::ops::insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id,workspace_id,project_id,@@ -597,6 +598,7 @@ mod tests {crate::ops::begin_session(&mut conn,&NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id,project_id,@@ -655,6 +657,7 @@ mod tests {crate::ops::begin_session(&mut conn,&NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id,project_id,@@ -727,6 +730,7 @@ mod tests {crate::ops::begin_session(&mut conn,&NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id,project_id,@@ -799,6 +803,7 @@ mod tests {crate::ops::begin_session(&mut conn,&NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id,project_id,@@ -866,6 +871,7 @@ mod tests {crate::ops::begin_session(&mut conn,&NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id,project_id,diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex a8383662..75c1baa1 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -1462,7 +1462,9 @@ fn begin_session_row(conn: &Connection, session: &NewSession) -> StoreResult<()>if session_is_purged(conn, session)? {return Err(StoreError::SessionPurged(session.id.to_string()));}- let now = Timestamp::now().as_microsecond();+ let now = session+ .occurred_at+ .unwrap_or_else(|| Timestamp::now().as_microsecond());let agent = session.agent_kind.as_str();let cwd: Option<String> = session.cwd@@ -1493,7 +1495,7 @@ pub fn end_session(session_id: &SessionId,summary_page_id: Option<&PageId>,) -> StoreResult<()> {- end_session_row(conn, session_id, summary_page_id)+ end_session_row(conn, session_id, summary_page_id, None)}/// Atomically end a lifecycle-only session and return its startup handoff to@@ -1508,7 +1510,7 @@ pub fn end_lifecycle_only_session(session_id: &SessionId,) -> StoreResult<LifecycleOnlyEndOutcome> {let tx = conn.transaction()?;- let outcome = end_lifecycle_only_session_in_tx(&tx, session_id)?;+ let outcome = end_lifecycle_only_session_in_tx(&tx, session_id, None)?;tx.commit()?;Ok(outcome)}@@ -1516,6 +1518,7 @@ pub fn end_lifecycle_only_session(fn end_lifecycle_only_session_in_tx(tx: &Transaction<'_>,session_id: &SessionId,+ occurred_at: Option<i64>,) -> StoreResult<LifecycleOnlyEndOutcome> {// Substantive is defined POSITIVELY: at least one observation that is// real work (a user prompt or a tool use). This MUST stay in sync with@@ -1536,7 +1539,7 @@ fn end_lifecycle_only_session_in_tx(if has_substantive_observation {return Ok(LifecycleOnlyEndOutcome::Substantive);}- end_session_row(tx, session_id, None)?;+ end_session_row(tx, session_id, None, occurred_at)?;let reopened: Option<(Vec<u8>, Vec<u8>, Vec<u8>)> = tx.query_row("UPDATE handoffs \@@ -1578,8 +1581,9 @@ fn end_session_row(conn: &Connection,session_id: &SessionId,summary_page_id: Option<&PageId>,+ occurred_at: Option<i64>,) -> StoreResult<()> {- let now = Timestamp::now().as_microsecond();+ let now = occurred_at.unwrap_or_else(|| Timestamp::now().as_microsecond());let page_blob: Option<&[u8]> = summary_page_id.map(|p| &p.as_bytes()[..]);conn.execute("UPDATE sessions \@@ -1724,9 +1728,13 @@ pub fn admit_hook_session_event(if !owner_filter.admits(session.actor_user.as_deref()) {return Err(StoreError::SessionCollision);}+ // `now` is also the ingest-key TTL clock above; started_at honors+ // the caller's original event time (backfill) and only falls+ // back to it when absent (live capture).+ let started_at = session.occurred_at.unwrap_or(now);tx.execute("INSERT INTO sessions (id, workspace_id, project_id, agent_kind, cwd, started_at, actor_user) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",- params![session.id.as_bytes(), session.workspace_id.as_bytes(), session.project_id.as_bytes(), session.agent_kind.as_str(), session.cwd.as_ref().map(|p| p.to_string_lossy().into_owned()), now, session.actor_user.as_deref()],+ params![session.id.as_bytes(), session.workspace_id.as_bytes(), session.project_id.as_bytes(), session.agent_kind.as_str(), session.cwd.as_ref().map(|p| p.to_string_lossy().into_owned()), started_at, session.actor_user.as_deref()],)?;(session.actor_user.clone(), None, 0)}@@ -1817,10 +1825,11 @@ pub fn end_admitted_session(conn: &mut Connection,admitted: &AdmittedSession,page: Option<&PageId>,+ occurred_at: Option<i64>,) -> StoreResult<()> {let tx = conn.transaction()?;validate_admitted_session(&tx, admitted)?;- end_session_row(&tx, &admitted.session_id, page)?;+ end_session_row(&tx, &admitted.session_id, page, occurred_at)?;tx.commit()?;Ok(())}@@ -1829,10 +1838,11 @@ pub fn end_admitted_session(pub fn end_admitted_lifecycle_only_session(conn: &mut Connection,admitted: &AdmittedSession,+ occurred_at: Option<i64>,) -> StoreResult<LifecycleOnlyEndOutcome> {let tx = conn.transaction()?;validate_admitted_session(&tx, admitted)?;- let outcome = end_lifecycle_only_session_in_tx(&tx, &admitted.session_id)?;+ let outcome = end_lifecycle_only_session_in_tx(&tx, &admitted.session_id, occurred_at)?;tx.commit()?;Ok(outcome)}@@ -1843,6 +1853,7 @@ pub fn end_admitted_session_with_handoff(admitted: &AdmittedSession,page: Option<&PageId>,handoff: &NewHandoff,+ occurred_at: Option<i64>,) -> StoreResult<HandoffId> {if handoff.from_session_id != Some(admitted.session_id)|| handoff.workspace_id != admitted.workspace_id@@ -1853,7 +1864,7 @@ pub fn end_admitted_session_with_handoff(}let tx = conn.transaction()?;validate_admitted_session(&tx, admitted)?;- end_session_row(&tx, &admitted.session_id, page)?;+ end_session_row(&tx, &admitted.session_id, page, occurred_at)?;let id = insert_handoff_row(&tx, handoff)?;tx.commit()?;Ok(id)@@ -1899,7 +1910,9 @@ pub fn complete_observation_ingest_if_claimed(/// (`&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 now = obs+ .occurred_at+ .unwrap_or_else(|| Timestamp::now().as_microsecond());let kind = observation_kind_as_str(obs.kind);let importance: i64 = i64::from(obs.importance.clamp(1, 10));let (extension, source_event) = match (&obs.extension, &obs.source_event) {@@ -2740,7 +2753,7 @@ pub fn end_session_with_handoff("automatic handoff owner does not match the ended session".into(),));}- end_session_row(&tx, session_id, summary_page_id)?;+ end_session_row(&tx, session_id, summary_page_id, None)?;let id = insert_handoff_row(&tx, handoff)?;tx.commit()?;Ok(id)@@ -5450,6 +5463,7 @@ pub(crate) mod tests {let (_tmp, mut conn, ws, proj) = fresh_db();for kind in ai_memory_core::AgentKind::ALL {let session = NewSession {+ occurred_at: None,id: ai_memory_core::SessionId::new(),workspace_id: ws,project_id: proj,@@ -5696,6 +5710,7 @@ pub(crate) mod tests {owner: Option<&str>,) -> NewSession {NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,@@ -5707,6 +5722,7 @@ pub(crate) mod tests {fn hook_observation(session: &NewSession) -> NewObservation {NewObservation {+ occurred_at: None,session_id: session.id,workspace_id: session.workspace_id,project_id: session.project_id,@@ -8011,6 +8027,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: receiver,workspace_id: ws,project_id: proj,@@ -8110,6 +8127,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: receiver,workspace_id: ws,project_id: proj,@@ -8142,6 +8160,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: receiver,workspace_id: ws,project_id: proj,@@ -8189,6 +8208,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: receiver,workspace_id: ws,project_id: proj,@@ -8201,6 +8221,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: receiver,workspace_id: ws,project_id: proj,@@ -8234,6 +8255,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: receiver,workspace_id: ws,project_id: proj,@@ -8246,6 +8268,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: receiver,workspace_id: ws,project_id: proj,@@ -8272,6 +8295,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: first_session,workspace_id: ws,project_id: proj,@@ -8477,6 +8501,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -8507,6 +8532,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -8550,6 +8576,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -8570,6 +8597,197 @@ pub(crate) mod tests {assert!(summary.is_none());}+ /// `occurred_at` lets a caller (backfill) stamp a session with the+ /// transcript's own original start time instead of import time.+ #[test]+ fn begin_session_with_occurred_at_stamps_started_at_from_it() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let sid = SessionId::new();+ let original: i64 = 1_757_505_600_000_000; // 2025-09-10T12:00:00Z+ begin_session(+ &mut conn,+ &NewSession {+ occurred_at: Some(original),+ id: sid,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::ClaudeCode,+ cwd: None,+ actor_user: None,+ },+ )+ .unwrap();+ let started_at: i64 = conn+ .query_row(+ "SELECT started_at FROM sessions WHERE id = ?1",+ params![&sid.as_bytes()[..]],+ |r| r.get(0),+ )+ .unwrap();+ assert_eq!(started_at, original);+ }++ /// Without `occurred_at`, `begin_session` keeps stamping "now" — the+ /// live-capture behaviour must not regress.+ #[test]+ fn begin_session_without_occurred_at_stamps_now() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let sid = SessionId::new();+ let before = Timestamp::now().as_microsecond();+ begin_session(+ &mut conn,+ &NewSession {+ occurred_at: None,+ id: sid,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::ClaudeCode,+ cwd: None,+ actor_user: None,+ },+ )+ .unwrap();+ let after = Timestamp::now().as_microsecond();+ let started_at: i64 = conn+ .query_row(+ "SELECT started_at FROM sessions WHERE id = ?1",+ params![&sid.as_bytes()[..]],+ |r| r.get(0),+ )+ .unwrap();+ assert!(+ (before..=after).contains(&started_at),+ "started_at {started_at} must fall within [{before}, {after}]"+ );+ }++ /// `end_session`'s `occurred_at` param stamps `ended_at` with the+ /// original event time (e.g. backfill's last transcript event) rather+ /// than import time.+ #[test]+ fn end_session_with_occurred_at_stamps_ended_at_from_it() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let sid = SessionId::new();+ begin_session(+ &mut conn,+ &NewSession {+ occurred_at: None,+ id: sid,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::ClaudeCode,+ cwd: None,+ actor_user: None,+ },+ )+ .unwrap();+ let original: i64 = 1_757_505_900_000_000; // 2025-09-10T12:05:00Z+ end_session_row(&conn, &sid, None, Some(original)).unwrap();+ let ended_at: i64 = conn+ .query_row(+ "SELECT ended_at FROM sessions WHERE id = ?1",+ params![&sid.as_bytes()[..]],+ |r| r.get(0),+ )+ .unwrap();+ assert_eq!(ended_at, original);+ }++ /// `insert_observation`'s `occurred_at` stamps `created_at` with the+ /// original event time instead of import time.+ #[test]+ fn insert_observation_with_occurred_at_stamps_created_at_from_it() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let sid = SessionId::new();+ begin_session(+ &mut conn,+ &NewSession {+ occurred_at: None,+ id: sid,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::ClaudeCode,+ cwd: None,+ actor_user: None,+ },+ )+ .unwrap();+ let original: i64 = 1_757_505_660_000_000; // 2025-09-10T12:01:00Z+ let obs_id = insert_observation(+ &mut conn,+ &NewObservation {+ occurred_at: Some(original),+ session_id: sid,+ workspace_id: ws,+ project_id: proj,+ kind: ObservationKind::UserPrompt,+ extension: None,+ source_event: None,+ title: "hook".into(),+ body: "observation".into(),+ importance: 5,+ },+ )+ .unwrap();+ let created_at: i64 = conn+ .query_row(+ "SELECT created_at FROM observations WHERE id = ?1",+ params![&obs_id.as_bytes()[..]],+ |r| r.get(0),+ )+ .unwrap();+ assert_eq!(created_at, original);+ }++ /// Without `occurred_at`, `insert_observation` keeps stamping "now".+ #[test]+ fn insert_observation_without_occurred_at_stamps_now() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let sid = SessionId::new();+ begin_session(+ &mut conn,+ &NewSession {+ occurred_at: None,+ id: sid,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::ClaudeCode,+ cwd: None,+ actor_user: None,+ },+ )+ .unwrap();+ let before = Timestamp::now().as_microsecond();+ let obs_id = insert_observation(+ &mut conn,+ &NewObservation {+ occurred_at: None,+ session_id: sid,+ workspace_id: ws,+ project_id: proj,+ kind: ObservationKind::UserPrompt,+ extension: None,+ source_event: None,+ title: "hook".into(),+ body: "observation".into(),+ importance: 5,+ },+ )+ .unwrap();+ let after = Timestamp::now().as_microsecond();+ let created_at: i64 = conn+ .query_row(+ "SELECT created_at FROM observations WHERE id = ?1",+ params![&obs_id.as_bytes()[..]],+ |r| r.get(0),+ )+ .unwrap();+ assert!(+ (before..=after).contains(&created_at),+ "created_at {created_at} must fall within [{before}, {after}]"+ );+ }+/// Embeddings are keyed by page_id (PK). Re-storing for the same/// page must REPLACE, not duplicate — otherwise `ai-memory embed/// --reembed` would multiply rows on each run.@@ -8836,6 +9054,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: sid,workspace_id: src_ws,project_id: proj,@@ -8848,6 +9067,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: sid,workspace_id: src_ws,project_id: proj,@@ -8987,6 +9207,7 @@ pub(crate) mod tests {begin_session(conn,&NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -9000,6 +9221,7 @@ pub(crate) mod tests {insert_observation(conn,&NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: proj,@@ -9478,6 +9700,7 @@ pub(crate) mod tests {insert_observation(conn,&NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: proj,@@ -9790,6 +10013,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: fragment,@@ -9874,6 +10098,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id: ws,project_id: with_data,@@ -9995,6 +10220,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: sid,workspace_id: ws,project_id: fragment,@@ -10086,6 +10312,7 @@ pub(crate) mod tests {insert_observation(&mut conn,&NewObservation {+ occurred_at: None,session_id: existing_sid,workspace_id: ws,project_id: proj,@@ -10584,6 +10811,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: bad_sid,workspace_id: other_ws,project_id: proj,@@ -10600,6 +10828,7 @@ pub(crate) mod tests {begin_session(&mut conn,&NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,@@ -10613,6 +10842,7 @@ pub(crate) mod tests {// The split-brain case the maintainer flagged: a hook writes an// observation with a stale workspace id for a moved project.let mismatched_obs = NewObservation {+ occurred_at: None,session_id: sid,workspace_id: other_ws,project_id: proj,@@ -11660,7 +11890,7 @@ pub(crate) mod tests {).unwrap();assert!(matches!(- end_admitted_session(&mut conn, &guard, None),+ end_admitted_session(&mut conn, &guard, None, None),Err(StoreError::SessionCollision)));begin_session(&mut conn, &session).unwrap();@@ -11670,7 +11900,7 @@ pub(crate) mod tests {).unwrap();assert!(matches!(- end_admitted_lifecycle_only_session(&mut conn, &guard),+ end_admitted_lifecycle_only_session(&mut conn, &guard, None),Err(StoreError::SessionCollision)));let handoff = NewHandoff {@@ -11687,7 +11917,7 @@ pub(crate) mod tests {owner_user: Some("user:alice".into()),};assert!(matches!(- end_admitted_session_with_handoff(&mut conn, &guard, None, &handoff),+ end_admitted_session_with_handoff(&mut conn, &guard, None, &handoff, None),Err(StoreError::SessionCollision)));@@ -11722,7 +11952,7 @@ pub(crate) mod tests {acceptance.accepting_session = Some(receiver.id);assert!(accept_handoff(&mut conn, &acceptance).unwrap());assert_eq!(- end_admitted_lifecycle_only_session(&mut conn, &receiver_guard).unwrap(),+ end_admitted_lifecycle_only_session(&mut conn, &receiver_guard, None).unwrap(),LifecycleOnlyEndOutcome::Ended {reopened_handoff: Some(handoff_id)}diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 2d02dc17..c8ddeaf0 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -10506,6 +10506,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id,diff --git a/crates/ai-memory-store/src/session_consolidation.rs b/crates/ai-memory-store/src/session_consolidation.rsindex 24e075f2..767e1f8e 100644--- a/crates/ai-memory-store/src/session_consolidation.rs+++ b/crates/ai-memory-store/src/session_consolidation.rs@@ -368,6 +368,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id,project_id,@@ -392,6 +393,7 @@ mod tests {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id,project_id,diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 50f793e1..e7c7d033 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -169,16 +169,19 @@ pub(crate) enum WriteCmd {EndAdmittedSession {admitted: AdmittedSession,summary_page_id: Option<PageId>,+ occurred_at: Option<i64>,reply: oneshot::Sender<StoreResult<()>>,},EndAdmittedSessionWithHandoff {admitted: AdmittedSession,summary_page_id: Option<PageId>,handoff: NewHandoff,+ occurred_at: Option<i64>,reply: oneshot::Sender<StoreResult<HandoffId>>,},EndAdmittedLifecycleOnlySession {admitted: AdmittedSession,+ occurred_at: Option<i64>,reply: oneshot::Sender<StoreResult<LifecycleOnlyEndOutcome>>,},CompleteObservationIngest {@@ -1045,15 +1048,20 @@ impl WriterHandle {}/// Guarded hook end.+ ///+ /// `occurred_at` is the SessionEnd event's own original time (microseconds),+ /// when known; `None` falls back to "now" at the store boundary.pub async fn end_admitted_session(&self,admitted: AdmittedSession,summary_page_id: Option<PageId>,+ occurred_at: Option<i64>,) -> StoreResult<()> {let (tx, rx) = oneshot::channel();self.send(WriteCmd::EndAdmittedSession {admitted,summary_page_id,+ occurred_at,reply: tx,}).await?;@@ -1061,17 +1069,22 @@ impl WriterHandle {}/// Guarded hook end plus automatic handoff.+ ///+ /// `occurred_at` is the SessionEnd event's own original time (microseconds),+ /// when known; `None` falls back to "now" at the store boundary.pub async fn end_admitted_session_with_handoff(&self,admitted: AdmittedSession,summary_page_id: Option<PageId>,handoff: NewHandoff,+ occurred_at: Option<i64>,) -> StoreResult<HandoffId> {let (tx, rx) = oneshot::channel();self.send(WriteCmd::EndAdmittedSessionWithHandoff {admitted,summary_page_id,handoff,+ occurred_at,reply: tx,}).await?;@@ -1079,13 +1092,18 @@ impl WriterHandle {}/// Guarded hook lifecycle-only end.+ ///+ /// `occurred_at` is the SessionEnd event's own original time (microseconds),+ /// when known; `None` falls back to "now" at the store boundary.pub async fn end_admitted_lifecycle_only_session(&self,admitted: AdmittedSession,+ occurred_at: Option<i64>,) -> StoreResult<LifecycleOnlyEndOutcome> {let (tx, rx) = oneshot::channel();self.send(WriteCmd::EndAdmittedLifecycleOnlySession {admitted,+ occurred_at,reply: tx,}).await?;@@ -2891,16 +2909,22 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {WriteCmd::EndAdmittedSession {admitted,summary_page_id,+ occurred_at,reply,} => {- let result =- ops::end_admitted_session(&mut conn, &admitted, summary_page_id.as_ref());+ let result = ops::end_admitted_session(+ &mut conn,+ &admitted,+ summary_page_id.as_ref(),+ occurred_at,+ );send_or_warn(reply, result, "end_admitted_session");}WriteCmd::EndAdmittedSessionWithHandoff {admitted,summary_page_id,handoff,+ occurred_at,reply,} => {let result = ops::end_admitted_session_with_handoff(@@ -2908,11 +2932,17 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {&admitted,summary_page_id.as_ref(),&handoff,+ occurred_at,);send_or_warn(reply, result, "end_admitted_session_with_handoff");}- WriteCmd::EndAdmittedLifecycleOnlySession { admitted, reply } => {- let result = ops::end_admitted_lifecycle_only_session(&mut conn, &admitted);+ WriteCmd::EndAdmittedLifecycleOnlySession {+ admitted,+ occurred_at,+ reply,+ } => {+ let result =+ ops::end_admitted_lifecycle_only_session(&mut conn, &admitted, occurred_at);send_or_warn(reply, result, "end_admitted_lifecycle_only_session");}WriteCmd::CompleteObservationIngest {@@ -3928,6 +3958,7 @@ mod tests {store.writer.begin_session(NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: src,diff --git a/crates/ai-memory-store/tests/suite/fts_drift_status.rs b/crates/ai-memory-store/tests/suite/fts_drift_status.rsindex cd108ee0..b7cb88ee 100644--- a/crates/ai-memory-store/tests/suite/fts_drift_status.rs+++ b/crates/ai-memory-store/tests/suite/fts_drift_status.rs@@ -99,6 +99,7 @@ async fn observation_fts_rows_report_index_drift() {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -112,6 +113,7 @@ async fn observation_fts_rows_report_index_drift() {.writer.insert_observation(Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-store/tests/suite/handoff_ownership.rs b/crates/ai-memory-store/tests/suite/handoff_ownership.rsindex e83a2b37..a7f4b289 100644--- a/crates/ai-memory-store/tests/suite/handoff_ownership.rs+++ b/crates/ai-memory-store/tests/suite/handoff_ownership.rs@@ -186,6 +186,7 @@ async fn ownership_writes_reject_malformed_identity_keys() {store.writer.begin_session(ai_memory_core::NewSession {+ occurred_at: None,id: invalid_session,workspace_id: ws,project_id: proj,@@ -760,6 +761,7 @@ async fn automatic_supersession_does_not_reach_across_operators() {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -887,6 +889,7 @@ async fn open_session_lookup_is_owner_scoped() {store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-store/tests/suite/multi_session.rs b/crates/ai-memory-store/tests/suite/multi_session.rsindex 87a9fddb..1f58b572 100644--- a/crates/ai-memory-store/tests/suite/multi_session.rs+++ b/crates/ai-memory-store/tests/suite/multi_session.rs@@ -52,6 +52,7 @@ async fn open_session(store.writer.begin_session(NewSession {+ occurred_at: None,id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-store/tests/suite/sessions_by_agent.rs b/crates/ai-memory-store/tests/suite/sessions_by_agent.rsindex 13a95392..842427b3 100644--- a/crates/ai-memory-store/tests/suite/sessions_by_agent.rs+++ b/crates/ai-memory-store/tests/suite/sessions_by_agent.rs@@ -45,6 +45,7 @@ async fn session(store.writer.begin_session(NewSession {+ occurred_at: None,id: SessionId::new(),workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-store/tests/suite/stress_writer_throughput.rs b/crates/ai-memory-store/tests/suite/stress_writer_throughput.rsindex 133755a6..d4ad56a2 100644--- a/crates/ai-memory-store/tests/suite/stress_writer_throughput.rs+++ b/crates/ai-memory-store/tests/suite/stress_writer_throughput.rs@@ -37,6 +37,7 @@ async fn scope(store: &Store) -> (WorkspaceId, ProjectId, SessionId) {store.writer.begin_session(NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -57,6 +58,7 @@ fn observation() -> Sanitized<NewObservation> {Sanitized::new(NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-web/tests/suite/routes.rs b/crates/ai-memory-web/tests/suite/routes.rsindex 1086fdab..d87e6248 100644--- a/crates/ai-memory-web/tests/suite/routes.rs+++ b/crates/ai-memory-web/tests/suite/routes.rs@@ -1087,6 +1087,7 @@ async fn seed_session(store.writer.begin_session(ai_memory_core::NewSession {+ occurred_at: None,id: session_id,workspace_id: ws,project_id: proj,@@ -1101,6 +1102,7 @@ async fn seed_session(.writer.insert_observation(ai_memory_core::Sanitized::new(ai_memory_core::NewObservation {+ occurred_at: None,session_id,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rsindex 2012680e..25a60f3b 100644--- a/crates/ai-memory-wiki/src/watcher.rs+++ b/crates/ai-memory-wiki/src/watcher.rs@@ -671,6 +671,7 @@ mod tests {store.writer.begin_session(ai_memory_core::NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: proj,diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 0c4c4efb..8d34ff4c 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -5522,6 +5522,7 @@ mod tests {store.writer.begin_session(ai_memory_core::NewSession {+ occurred_at: None,id: sid,workspace_id: ws,project_id: src,diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex ab3b6d80..9a701f4a 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -252,6 +252,26 @@ and older clients cannot bypass it. The typed sanitizer boundary then applies a16 KiB backstop to every durable observation body after redaction. Theseparately gated Claude Code assistant/Stop excerpt remains capped at 2 KB.+An optional RFC 3339 `occurred_at` on the hook body lets a client supply the+event's own original time — currently only `ai-memory backfill`, replaying a+transcript's per-event timestamps, so imported sessions/observations are+stamped with when they actually happened instead of import time. It is read+from the top level of the body only (unlike the nested `payload`/`event`/+`properties`/`info`/`path` search other hook fields use), so a real harness+payload that happens to carry an `occurred_at` key somewhere in its own+structure is never mistaken for this field. It is numeric metadata, not text,+so it never goes through the sanitizer (outside invariant #6's boundary); it+is still client-controlled input over `/hook`, so+`HookEnvelope::occurred_at_micros` bounds it (must be > 0 and no more than+five minutes ahead of server time) before trusting it. Anything else —+missing, unparsable, or out of bounds — resolves to `None`, which the store+treats as "now", never an error, keeping hooks fire-and-forget (invariant #5).+A backfilled session's `ended_at` can therefore land well in the past, which+can push it below the auto-improve watermark and the experience-pass anchor+(both keyed on `ended_at`), and a retention window measured from an+observation's own time can make an old backfilled observation immediately+prunable rather than only after it ages in place.+## Storage architecture**Two layers, one source of truth.**