Time-aware memory: ask what was true at one moment

A time-aware memory is a memory with a validity window. The window starts at active_from and ends at active_to. A search can ask what was true at one moment, or what was true during a range.

Why dates matter

Facts change. Alice lived in Paris, then she moved to Lisbon. A memory store that keeps one fact per topic cannot answer where she lived last January. Dates let you ask both questions.

How a memory gets its dates

You do not set active_from or active_to yourself. Smritea sets them when it stores the memory.

An empty date means unknown. Your one input is event_occurred_at on add. It says when the event in the text happened. Send it as an RFC 3339 time with a time zone, such as 2026-10-12T10:00:00Z.

Search by time

Search takes three optional time fields. The table shows which memories each field returns.

A memory is valid at a moment when active_from is on or before it, and active_to is empty or on or after it. A memory with an empty active_from matches every moment.

Ask about January, then handle the mistake

import os

from smritea import (
    MemoryScope,
    SmriteaBadRequestError,
    SmriteaClient,
)

client = SmriteaClient(
    api_key=os.environ["SMRITEA_API_KEY"],
    app_id=os.environ["SMRITEA_APP_ID"],
)
alice = MemoryScope(actor_id="alice", actor_type="user")

results = client.search(
    "Where does Alice live?",
    scope=alice,
    valid_at="2026-01-15T00:00:00Z",
)
for r in results:
    print(r.memory.active_from, r.memory.content)

try:
    client.search(
        "trips",
        scope=alice,
        valid_at="2026-01-15T00:00:00Z",
        from_time="2026-01-01T00:00:00Z",
    )
except SmriteaBadRequestError as e:
    print(e.code)  # VALIDATION_FAILED

You cannot combine valid_at with from_time or to_time. Use valid_at for one moment, and the other two for a range.

Learn more

The guide Search at one moment or over a range shows the TypeScript version. The concept page Time-aware memory lists every error.