agumpandey
216 lines
7.0 KiB
Plaintext
216 lines
7.0 KiB
Plaintext
---
|
|
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" />
|