SmartMemory
Concepts

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

DimensionSemantics
Valid timeWhen the fact is or was true in the real world
Transaction timeWhen 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.*:

EndpointSDK methodReturns
GET /memory/temporal/{id}/historygetHistory(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}/changesgetChanges(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}/rollbackrollback(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_start in the past when ingesting historical records.
  • Belief revision: when a fact changes, the old version stays queryable.
  • Diff and blame: compareVersions shows 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 tight since/until window over getHistory() with no bound.
  • as_of_date over supersession needs the old record's creation time. In lite examples, preserve it with metadata["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: TemporalQueries
  • smartmemory/temporal/version_tracker.py: version writes
  • smartmemory/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 instantSite ASite BUnknown site or omitted site
Before February 1v1v1v1
February 1 through just before February 15v2v1v1
February 15 onwardv2v2v1

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_at captures 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_from with scope_go_lives, or scoped reads with include_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.

On this page