Bitemporality
What Is Bitemporality?
Section titled “What Is Bitemporality?”Every memory in MemLayer carries two independent time dimensions. Most databases record only when data was written. MemLayer also tracks when the information was true in the real world.
The Two Time Dimensions
Section titled “The Two Time Dimensions”Transaction Time (system_time)
Section titled “Transaction Time (system_time)”When MemLayer recorded the memory. Set automatically, cannot be changed. Answers: “When did the system learn this?”
Valid Time (valid_from / valid_to)
Section titled “Valid Time (valid_from / valid_to)”When the information was true in the real world. Determined from the content itself (the LLM resolves temporal references like “yesterday” into dates). Answers: “When was this actually true?”
valid_from— when the fact became truevalid_to— when the fact stopped being true (nullif still current)
Why Two Timelines Matter
Section titled “Why Two Timelines Matter”Consider: on Monday, a user says “I work at Acme Corp.” On Wednesday: “I just started at Beta Inc.”
With a single timeline, the Monday memory would be overwritten. With bitemporality, both are preserved:
| Memory | valid_from | valid_to | system_time |
|---|---|---|---|
| ”Works at Acme Corp” | Monday | Wednesday | Monday |
| ”Works at Beta Inc” | Wednesday | (null) | Wednesday |
This enables two distinct kinds of temporal queries:
“What did the agent know on Tuesday?” — Query by system_time. On Tuesday, only the Acme memory existed.
“Where did the user work on Tuesday?” — Query by valid_time. The Acme memory was valid (valid_from=Monday, valid_to=Wednesday).
Corrections Don’t Destroy History
Section titled “Corrections Don’t Destroy History”When a memory is updated during retain:
- The old memory’s
valid_tois set to the current time - A new memory is created with
valid_fromset to now andvalid_toas null - Both versions share the same
entity_id
Every historical state of the knowledge graph is preserved and queryable.
The as_of Parameter
Section titled “The as_of Parameter”The recall endpoint accepts as_of to query the knowledge graph at a specific point in time:
GET /api/v1/recall?query=where+does+the+user+work&as_of=2025-01-15T00:00:00ZA memory is considered valid at time T if its valid_from is at or before T, and its valid_to is either null or after T.
Temporal Re-ranking
Section titled “Temporal Re-ranking”Even without as_of, bitemporality influences recall. Superseded memories (those with valid_to set) receive a 30% score penalty:
adjusted_score = original_score * 0.7 (superseded memories)adjusted_score = original_score * 1.0 (current memories)Current information ranks higher, but historical data still surfaces if highly relevant.