---
title: Temporal Reasoning
description: "Use time-aware memory retrieval in Mem0 Platform v3 so searches like 'last week', 'upcoming', and 'right now' return the right memories."
icon: "clock"
badge: "v3"
---

Some memories should matter because of **when** they happened, not just because they sound similar. Temporal Reasoning helps Mem0 Platform v3 classify time-aware memories on write and interpret time-aware queries on search.

<Info>
  **You'll use this 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 does not apply to OSS memory stores or older Platform endpoints.
</Warning>

## Configure access

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

```python
from mem0 import MemoryClient

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

## How it works

Temporal Reasoning works in two parts:

- **Write-time enrichment**: when Mem0 stores a memory, it can infer internal temporal structure when that information is present in the text.
- **Search-time interpretation**: when a query includes time language like `last week`, `upcoming`, or `right now`, Mem0 uses internal temporal signals to return more appropriate results.

### Temporal patterns

Mem0 handles several common temporal patterns:

| Pattern | 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 can remain 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." |

At search time, Temporal Reasoning influences how results are ranked. The ranking effect is transparent: results come back in the normal shape.

## Configure it

### Default behavior

Temporal Reasoning is enabled by default for all v3 searches and writes. There is no per-request toggle — the pipeline runs automatically when temporal structure is detectable in the memory text or query.

### Anchor imports and tests

Two fields matter when you want predictable temporal behavior:

- `timestamp` on `add()` anchors imported memories to the time they actually happened
- `reference_date` on `search()` anchors relative queries like `last week` to a known point in time

<CodeGroup>
```python Python
from datetime import datetime, timezone

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()),
)

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

```javascript JavaScript
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),
  }
);

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

<Tip>
  `reference_date` is especially useful for tests and backfills because it makes relative phrases reproducible.
</Tip>

## See it in action

### Add a few dated memories

<CodeGroup>
```python Python
client.add(
    [{"role": "user", "content": "I finished the Q1 product review on March 10, 2025."}],
    user_id="jordan",
)

client.add(
    [{"role": "user", "content": "I have a dentist appointment on April 18, 2025 at 2 PM."}],
    user_id="jordan",
)

client.add(
    [{"role": "user", "content": "I am the product lead at Acme Corp."}],
    user_id="jordan",
)
```

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

await client.add(
  [{ role: "user", content: "I have a dentist appointment on April 18, 2025 at 2 PM." }],
  { userId: "jordan" }
);

await client.add(
  [{ role: "user", content: "I am the product lead at Acme Corp." }],
  { userId: "jordan" }
);
```
</CodeGroup>

<Note>
  Platform writes are asynchronous. For quick validation, wait briefly before searching or verify the completed event in the dashboard or CLI.
</Note>

### Search with a temporal query

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

for item in results["results"]:
    print(item["memory"], item["score"])
```

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

results.results.forEach((item) => {
  console.log(item.memory, item.score);
});
```
</CodeGroup>

<Info icon="check">
  Expected behavior: the March 10 review leads this result set, the April 18 appointment does not, and the ongoing role at Acme does not crowd out the dated answer.
</Info>

## Supported query patterns

<AccordionGroup>
  <Accordion title="Historical questions">
    Examples: `last week`, `last month`, `in March 2025`, `on 2025-03-10`
  </Accordion>
  <Accordion title="Upcoming questions">
    Examples: `upcoming`, `next week`, `tomorrow`, `what do I have coming up?`
  </Accordion>
  <Accordion title="Current-state questions">
    Examples: `right now`, `currently`, `where do I work now?`
  </Accordion>
  <Accordion title="As-of questions">
    Examples: `as of March 2025`, `where was I living as of 2024?`
  </Accordion>
  <Accordion title="Duration questions">
    Examples: `how long have I lived here?`, `since when have I worked there?`
  </Accordion>
</AccordionGroup>

## Verify the feature is working

- Run a temporal search with a time-aware query ("what did I do last week?") and confirm the result ordering matches temporal intent — the memory that fits the time window should rank first.
- Use `reference_date` in test queries so relative phrases resolve consistently.
- For backfilled data, confirm imported memories use the expected chronology after you set `timestamp`.

## Best practices

- Use explicit dates in source conversations when plans or events matter.
- Pass `timestamp` during historical imports so ingestion time does not become the only time anchor.
- Keep search scoped with `filters` so time-aware ranking runs inside the right entity boundary.
- Use `reference_date` in automated tests and reproducible demos.

<CardGroup cols={1}>
  <Card title="Memory Timestamps" icon="calendar" href="/platform/features/timestamp">
    Anchor imported memories to when they actually happened.
  </Card>
</CardGroup>

<Snippet file="get-help.mdx" />