Some memories matter because of when they happened, not just because they sound similar. Temporal Reasoning lets Mem0 Platform v3 understand time-aware queries and return the most contextually appropriate results.

Configure access

Confirm your MEM0_API_KEY is set and that you are using the v3 Platform client:

from mem0 import MemoryClient

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

How it works

When a memory describes an event, a future plan, or an ongoing state, Temporal Reasoning recognizes the time context so the right results surface at search time.

A query like what did I do last week? should return a completed past event — not an upcoming appointment and not a stable fact that hasn't changed. Temporal Reasoning handles that distinction automatically.

Memory types Temporal Reasoning handles

Results come back in the normal search response shape — Temporal Reasoning affects ranking, not the response format.

Configure it

Temporal Reasoning is enabled by default for all v3 searches and writes. There is no per-request toggle.

Two parameters give you precise control when you need it:

• timestamp on add() — anchors an imported memory to the time it actually happened, rather than the time it was added to Mem0
• reference_date on search() — resolves relative phrases like last week against a fixed point in time

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

Import a historical memory anchored to when it happened

client.add( [{"role": "user", "content": "I finished the Q1 review on March 10, 2025."}], user_id="jordan", timestamp=int(datetime(2025, 3, 10, tzinfo=timezone.utc).timestamp()), )

Search with a relative query anchored to a known date

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

```javascript JavaScript
import { MemoryClient } from "mem0ai";

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

// Import a historical memory anchored to when it happened
await client.add(
  [{ role: "user", content: "I finished the Q1 review on March 10, 2025." }],
  {
    userId: "jordan",
    timestamp: Math.floor(new Date("2025-03-10T00:00:00Z").getTime() / 1000),
  }
);

// Search with a relative query anchored to a known date
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 timestamp during historical imports so the ingestion time does not become the only time anchor.
• Scope searches with filters so time-aware ranking operates inside the right user boundary.
• Use reference_date in automated tests and reproducible demos.