Bi-Temporal Versioning
Bi-Temporal Versioning & Time-Travel Queries
SmartMemory tracks two independent time dimensions for memory items, so you can answer both "what did we believe was true on date X?" and "what did the system have stored on date X?".
The two times
| Dimension | Semantics |
|---|---|
| Valid time | When the fact is or was true in the real world |
| Transaction time | When the system recorded the version |
Each version is represented by the real TemporalVersion dataclass:
from dataclasses import fields
from smartmemory.temporal import TemporalVersion
print([field.name for field in fields(TemporalVersion)])Source: smart-memory-core/smartmemory/temporal/queries.py.
A version's transaction-time interval [transaction_time_start, transaction_time_end) is closed on the left and exclusive on the right. The current version has transaction_time_end = None. The same shape applies to valid time: an open valid_time_end means "still believed to be true."
How versions are created
Manual supersession records that one memory replaces another. The default search path returns the current value only. Passing include_superseded=True returns the old and new values.
as_of_date depends on a preserved creation time for the old value. In lite mode, put that time in metadata={"reference_time": <iso datetime>} before superseding. Without reference_time, the old value may be anchored at supersession time, so a query for an earlier moment returns the new value.
Querying current state and history
from smartmemory.models.memory_item import MemoryItem
from smartmemory.pipeline.config import PipelineConfig
from smartmemory.tools.factory import lite_context
lite = dict(pipeline_profile=PipelineConfig.lite(llm_enabled=False))
with lite_context(**lite) as memory:
old = memory.add(
MemoryItem(
content="The incident channel is #ops-old",
memory_type="semantic",
)
)
new = memory.add(
MemoryItem(
content="The incident channel is #ops-war-room",
memory_type="semantic",
)
)
memory.supersede(old, new, reason="Team renamed the channel")
print([r.content for r in memory.search("incident channel")])
print([
r.content
for r in memory.search("incident channel", include_superseded=True)
])Querying what was believed before a change
from datetime import datetime, timezone
from smartmemory.models.memory_item import MemoryItem
from smartmemory.pipeline.config import PipelineConfig
from smartmemory.tools.factory import lite_context
lite = dict(pipeline_profile=PipelineConfig.lite(llm_enabled=False))
with lite_context(**lite) as memory:
old = memory.add(
MemoryItem(
content="The billing provider is Stripe",
memory_type="semantic",
metadata={
"reference_time": datetime.now(timezone.utc).isoformat(),
},
)
)
t_before_change = datetime.now(timezone.utc)
new = memory.add(
MemoryItem(
content="The billing provider is Paddle",
memory_type="semantic",
metadata={
"reference_time": datetime.now(timezone.utc).isoformat(),
},
)
)
memory.supersede(old, new, reason="Pricing model changed")
historical = memory.search(
"billing provider",
as_of_date=t_before_change,
include_superseded=True,
)
current = memory.search("billing provider")
print([r.content for r in historical])
print([r.content for r in current])Service query API
Service routes live under /memory/temporal/*. The JS SDK mirrors them on client.memories.*:
| Endpoint | SDK method | Returns |
|---|---|---|
GET /memory/temporal/{id}/history | getHistory(id, opts) | All versions of id |
GET /memory/temporal/at/{timestamp} | timeTravel(ts) | The state of every item at ts |
GET /memory/temporal/{id}/at/{timestamp} | getItemAtTime(id, ts) | The version of id valid at ts |
GET /memory/temporal/{id}/changes | getChanges(id, opts) | Change events between since and until |
POST /memory/temporal/{id}/compare?v1=&v2= | compareVersions(id, ...) | Field-level diff between two versions |
POST /memory/temporal/{id}/rollback | rollback(id, opts) | Replay a past version as the new HEAD |
GET /memory/temporal/{id}/audit | (REST only) | Full audit trail with provenance |
GET /memory/temporal/search/during | (REST only) | All items valid during a window |
GET /memory/temporal/compliance/report | (REST only) | Aggregate retention and change report |
GET /memory/temporal/relationships/{rel_id}/history etc. | (REST only) | Bi-temporal queries on edges |
JS SDK examples
const past = await client.memories.timeTravel('2024-09-01T00:00:00Z', {
limit: 100,
});const diff = await client.memories.compareVersions('item123', 3, 5);await client.memories.rollback('item123', { toVersion: 3 });
await client.memories.rollback('item123', { toTime: '2024-09-15T12:00:00Z' });A rollback writes a new version with the chosen prior content. It does not delete the intervening versions, so the audit trail stays intact.
Use cases
- Audit and compliance: answer "what did this user see on date X" exactly.
- Backdated facts: set
valid_time_startin the past when ingesting historical records. - Belief revision: when a fact changes, the old version stays queryable.
- Diff and blame:
compareVersionsshows which field changed between any two versions.
Caveats
- Time-travel queries iterate version chains in FalkorDB. For items with hundreds of versions, prefer
getChanges()with a tightsince/untilwindow overgetHistory()with no bound. as_of_dateover supersession needs the old record's creation time. In lite examples, preserve it withmetadata["reference_time"].- Rollback is best-effort for relations. Edges follow the same bi-temporal model, but rollback only restores node properties.
Key code surfaces
smartmemory/temporal/queries.py:TemporalQueriessmartmemory/temporal/version_tracker.py: version writessmartmemory/temporal/relationships.py: bi-temporal edges
Site-specific business validity
A trial amendment can take effect at different sites on different dates while keeping one rule history. scope_go_lives attaches a schedule to an amendment. business_scope selects an exact site and valid_at selects the business instant.
The clinical-trial example starts with sponsor guidance v1 on January 1, 2026. One amendment v2 activates at site A on February 1 and at site B on February 15. All boundaries below are midnight UTC.
| Business instant | Site A | Site B | Unknown site or omitted site |
|---|---|---|---|
| Before February 1 | v1 | v1 | v1 |
| February 1 through just before February 15 | v2 | v1 | v1 |
| February 15 onward | v2 | v2 | v1 |
Activation includes the exact valid_from instant. An activated exact-site entry wins. Until that activation, the site follows the latest activated sponsor entry. A well-formed unknown site also follows the sponsor. A site-only amendment does not advance sponsor guidance or globally retire v1. An explicit scope: null entry advances the sponsor timeline.
valid_at and transaction history are independent. Decision reads use as_of, and memory search uses as_of_date, to choose the schedule revision known at that recording instant. Business validity then selects within that revision. A correction recorded today cannot change the schedule observed by a transaction-time query from before the correction. Writes use their actual recording instants, even when business dates are in the past.
Inputs and limits
- Site matching is exact and case-sensitive, with no trimming or hierarchy. A site key contains 1 to 128 characters. Empty or whitespace-only keys, wildcards, country/cohort qualifiers, mixed dimensions and duplicate JSON keys are rejected.
- Dates require a time component and normalize to UTC. Naive datetimes mean UTC. An omitted
valid_atcaptures one request-start UTC instant. An omitted scope selects sponsor guidance. - A supplied schedule contains 1 to 256 entries. Omit the schedule to retain legacy behavior. An empty list is invalid. Duplicate entries, tied activations on distinct versions and non-increasing activations for the same key across amendments are rejected.
- Do not combine scalar
valid_fromwithscope_go_lives, or scoped reads withinclude_superseded=True. Unsupported qualifier combinations fail explicitly. - Resolution is bounded to 256 versions and 1024 edges. Exhaustion or inaccessible history refuses selection rather than guessing a version.
Business scope never grants access to a tenant or workspace. Authentication, workspace membership and history admission still apply. Invalid inputs return invalid_scoped_validity (400), conflicting amendments return scoped_validity_conflict (409), and unavailable history returns scoped_history_unavailable (503).
Python uses business_scope, valid_at and scope_go_lives. JavaScript uses businessScope, validAt and scopeGoLives, while nested schedule entries retain scope and valid_from. Registered MCP memory search and decision tools carry the snake_case fields through local, remote and hosted backends. Scoped replacement receipts say scheduled and carry the accepted schedule, predecessor, successor and recording instant.
See the clinical-trial guide for verified SDK calls, and the generated API reference for request fields.