docs/platform/features/temporal-reasoning.mdx
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.
<Info> **Use Temporal Reasoning when…** - Users ask questions like "what happened last week?" or "what do I have coming up?" - Your app stores both past events and future plans for the same person - You want time-aware retrieval without building your own date-parsing layer </Info> <Warning> Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on OSS memory stores or older Platform endpoints. </Warning>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")
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.
| Type | What it represents | Example |
|---|---|---|
| Dated occurrence | Something that happened at a known time | "I finished the Q1 review on March 10, 2025." |
| Future plan | A future commitment or scheduled item | "I have a dentist appointment on March 18, 2025." |
| Ongoing state | A fact that remains true over time | "I am the product lead at Acme Corp." |
| Relationship | A durable connection between people or entities | "Priya manages Jordan." |
| Preference | A stable preference or habit | "I prefer morning meetings." |
Results come back in the normal search response shape: Temporal Reasoning affects ranking, not the response format.
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:
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 timeclient = 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", )
```javascript JavaScript
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",
});
reference_date in test queries so relative phrases resolve consistently across runs.timestamp on add() to confirm the memory reflects the right point in time.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.filters so time-aware ranking operates inside the right user boundary.reference_date in automated tests and reproducible demos.