The bi-temporal model
When pgmem learned a fact versus when it was true.
pgmem's semantic memory (Tier 4) tracks two independent timelines for every fact: valid time — when the fact was true in the world — and transaction time — when pgmem learned it. Because it keeps both, a correction adds history instead of erasing it: you can always ask "what's true now?" and "what did we believe back then?"
Why it matters
Agents get things wrong, learn late, and need to be corrected — and you need to be able to audit why the agent said what it said. A store that overwrites facts in place can answer "what's true now" but loses the rest: it can't show that a fact was corrected, when, or what the agent believed at the time of a past decision. Bi-temporal storage keeps that history without making "current" queries harder.
The two timelines
- Valid time — the interval a fact was true (
valid_at…invalid_at). A fact with no end is still in effect. This is the world's timeline. - Transaction time — when pgmem recorded or superseded the fact (its
created_at, and when a later edge invalidated it). This is pgmem's timeline.
The two are independent. pgmem can learn today (transaction time) that something was true last week (valid time), and it records both.
How it works
Facts are never casually overwritten. When new information contradicts an existing relationship, pgmem closes the old fact's valid interval and writes a new one — both rows survive, with their time bounds intact. Retrieval defaults to what's valid now, but the superseded history remains queryable for audit and for reconstructing past context.
This is also the deep reason behind events vs state:
- An event is a point in valid time — it happened,
valid_atis enough, and it can never need correcting. pgmem owns it cleanly. - Current state is an interval whose endpoints another system can move. You can't maintain a valid-time interval correctly for a fact whose source you don't control — so you don't store it; you fetch it live. "Don't store foreign state" falls straight out of the bi-temporal model.
Tradeoffs & pitfalls
Don't expect overwrite/UPDATE semantics. A correction creates a new validity interval; the old fact still exists with its bounds. "The latest value" is a query (what's valid now), not the only row in the table.
- More history means more rows — that's the cost of being able to audit and correct. Retrieval handles "current" for you; reach for historical queries deliberately.
- Valid time is only trustworthy for facts pgmem actually owns. For foreign state, the live fetch is the source of truth, not a stored interval.
Related
- Events vs state — why this model says "don't store foreign state"
- The five-tier model — bi-temporality lives in Tier 4
- Trust & memory formation — how facts enter the graph
- Pitfalls & footguns — the overwrite-semantics trap