← All use cases
The scenario
You import a year of history on a Tuesday. Every one of those memories was
recorded on Tuesday and happened months apart, and almost every interesting
question is about the second clock.
Three controls use the two clocks, and mixing them up is the usual bug.
Step 1 — Write with the event’s own time
timestamp is yours to set and means when it happened. The record time is the
system’s and you cannot set it.
Step 2 — Filter on event time
Step 3 — Replay what the space knew
as_of is record time, not event time. Both rows above were written today,
so a year ago the space knew nothing — and returning nothing is correct. This is
the control people expect to filter by event date, and it does not.
Step 4 — Move “now”
query_timestamp re-ranks rather than filters: it moves the “now” that recency,
and phrases like last quarter, resolve against.
Evals
- Write two memories with event dates months apart, both today.
- Window to one month. Assert only one returns.
as_of a date before you wrote them. Assert nothing returns — if
something does, you are filtering on the wrong clock.- Move
query_timestamp and check the ordering changes while the set does not.
Guardrails
as_of and occurred_before answer different questions and look identical
at the call site. “What did we know then” is as_of; “what happened then” is
occurred_*. Choosing wrong returns a plausible, wrong answer rather than an
error.
- Undated writes collapse to their write time, so a backfill without
timestamp makes every temporal question unanswerable and there is no bulk fix.
- An event-time filter narrows hard. If a window returns less than you
expect, check the memories actually carry event time before tuning recall.
The script
Complete and runnable:
time_travel.py. 
