Skip to content

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.md
index 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.0
unchanged — 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 rmcp
above a quieter `log_level`. A target directive beats the global level
either way, so with `log_level = "error"` or `"off"` the cap re-enabled the
diff --git a/crates/ai-memory-cli/src/commands/backfill.rs b/crates/ai-memory-cli/src/commands/backfill.rs
index 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<MappedEvent
event: "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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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, ProjectI
store
.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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 a
16 KiB backstop to every durable observation body after redaction. The
separately 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.**