Temporal Reasoning

​

Configure access

from mem0 import MemoryClient

client = MemoryClient(api_key="your-api-key")

​

How it works

​

Memory types Temporal Reasoning handles

​

Configure it

• observation_date (or observation_datetime, which takes priority when both are set) on add(): anchors an imported memory to the time it actually happened. Pair with timezone when resolving a date-only value.
• timestamp on add(): a Unix epoch that sets the memory’s creation time. When present it takes priority over observation_datetime and observation_date as the anchor Temporal Reasoning ranks against, so pass only the one you want to win.
• reference_date on search(): resolves relative phrases like last week against a fixed point in time

from mem0 import MemoryClient

client = MemoryClient(api_key="your-api-key")

client.add(
    [{"role": "user", "content": "I finished the Q1 review on March 10, 2025."}],
    user_id="jordan",
    observation_date="2025-03-10",
)

results = client.search(
    "what did I do last week?",
    filters={"user_id": "jordan"},
    reference_date="2025-03-21T00:00:00Z",
)

import { MemoryClient } from "mem0ai";

const client = new MemoryClient({ apiKey: "your-api-key" });

await client.add(
  [{ role: "user", content: "I finished the Q1 review on March 10, 2025." }],
  {
    userId: "jordan",
    observationDate: "2025-03-10",
  }
);

const results = await client.search("what did I do last week?", {
  filters: { user_id: "jordan" },
  referenceDate: "2025-03-21T00:00:00Z",
});

​

Supported query patterns

​

Verify the feature is working

• Run a temporal search with a time-aware query (e.g., “what did I do last week?”) and confirm the memory that fits the time window ranks first.
• Use reference_date in test queries so relative phrases resolve consistently across runs.
• For backfilled data, pass timestamp on add() to confirm the memory reflects the right point in time.

​

Best practices

• Use explicit dates in source conversations when events or plans matter temporally.
• Pass observation_date (or observation_datetime) during historical imports so the ingestion time does not become the only time anchor. Do not also pass timestamp on those calls, since it overrides both as the ranking anchor.
• Scope searches with filters so time-aware ranking operates inside the right user boundary.
• Use reference_date in automated tests and reproducible demos.