> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mem0.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Temporal Reasoning
> Time-aware memory retrieval for Mem0 Platform v3 so queries like 'last week', 'upcoming', and 'right now' return the right memories.
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.
**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
Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on OSS memory stores or older Platform endpoints.
## Configure access
Confirm your `MEM0_API_KEY` is set and that you are using the v3 Platform client:
```python theme={null}
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
| 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.
## 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
```python Python theme={null}
from datetime import datetime, timezone
from mem0 import MemoryClient
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 theme={null}
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",
});
```
`reference_date` is especially useful in automated tests and demos because it makes relative phrases like `last week` resolve consistently every time.
## Supported query patterns
Examples: `last week`, `last month`, `in March 2025`, `on 2025-03-10`
Examples: `upcoming`, `next week`, `tomorrow`, `what do I have coming up?`
Examples: `right now`, `currently`, `where do I work now?`
Examples: `as of March 2025`, `where was I living as of 2024?`
Examples: `how long have I lived here?`, `since when have I worked there?`
## 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.
Anchor imported memories to when they actually happened.