Feat: add temporal reasoning cookbook and docs
This commit is contained in:
agumpandey
@@ -73,7 +73,7 @@ await client.search("What is Alice's favorite sport?", { filters: { userId: "ali
|
||||
|
||||
### Get All
|
||||
|
||||
Retrieve all memories for a user asynchronously.
|
||||
Retrieve a paginated list of memories for a user asynchronously.
|
||||
|
||||
<Callout type="warning" title="Filters Required">
|
||||
`get_all()` now requires filters to be specified.
|
||||
@@ -82,15 +82,27 @@ Retrieve all memories for a user asynchronously.
|
||||
<CodeGroup>
|
||||
|
||||
```python Python
|
||||
await client.get_all(filters={"AND": [{"user_id": "alice"}]})
|
||||
page = await client.get_all(
|
||||
filters={"AND": [{"user_id": "alice"}]},
|
||||
page=1,
|
||||
page_size=50,
|
||||
)
|
||||
```
|
||||
|
||||
```javascript JavaScript
|
||||
await client.getAll({ filters: {"AND": [{"user_id": "alice"}]} });
|
||||
const page = await client.getAll({
|
||||
filters: { "AND": [{ user_id: "alice" }] },
|
||||
page: 1,
|
||||
pageSize: 50,
|
||||
});
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
The async client returns the same paginated envelope as the sync client: `{"count", "next", "previous", "results"}`.
|
||||
</Note>
|
||||
|
||||
### Delete
|
||||
|
||||
Delete a specific memory asynchronously.
|
||||
|
||||
@@ -23,11 +23,27 @@ client.add(messages, user_id="alice", infer=False)
|
||||
```
|
||||
|
||||
```markdown Output
|
||||
[]
|
||||
{
|
||||
"message": "Memories stored successfully",
|
||||
"status": "SUCCEEDED",
|
||||
"event_id": "evt_123",
|
||||
"results": [
|
||||
{
|
||||
"id": "19d6d7aa-2454-4e58-96fc-e74d9e9f8dd1",
|
||||
"memory": "Alice loves playing badminton",
|
||||
"event": "ADD"
|
||||
},
|
||||
{
|
||||
"id": "8557f05d-7b3c-47e5-b409-9886f9e314fc",
|
||||
"memory": "Alice mostly cooks at home because of her gym plan",
|
||||
"event": "ADD"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
You can see that the output of the add call is an empty list.
|
||||
In V3, `infer=False` stores the supplied memory text directly and returns a successful event envelope with the created memories in `results`.
|
||||
|
||||
<Note>Only messages with the role "user" will be used for storage. Messages with roles such as "assistant" or "system" will be ignored during the storage process.</Note>
|
||||
|
||||
@@ -79,6 +95,9 @@ client.get_all(filters={"AND": [{"user_id": "alice"}]})
|
||||
|
||||
```json Output
|
||||
{
|
||||
"count": 2,
|
||||
"next": null,
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": "19d6d7aa-2454-4e58-96fc-e74d9e9f8dd1",
|
||||
|
||||
@@ -0,0 +1,274 @@
|
||||
---
|
||||
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 has two public-facing parts:
|
||||
|
||||
- **Write-time enrichment**: when Mem0 stores a memory, it can attach temporal structure such as memory type and date bounds 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 the stored temporal fields to return more appropriate results.
|
||||
|
||||
### Memory types
|
||||
|
||||
Mem0 normalizes temporal memories into a small set of developer-facing types:
|
||||
|
||||
| Type | What it represents | Example |
|
||||
| --- | --- | --- |
|
||||
| `event` | A dated occurrence | "I finished the Q1 review on March 10, 2025." |
|
||||
| `plan` | A future commitment or scheduled item | "I have a dentist appointment on March 18, 2025." |
|
||||
| `state` | An ongoing 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." |
|
||||
|
||||
On search responses, temporal fields are returned as top-level result attributes when Temporal Reasoning is active. The most useful ones are:
|
||||
|
||||
- `memory_type`
|
||||
- `event_date`
|
||||
- `event_start`
|
||||
- `event_end`
|
||||
- `plan_status`
|
||||
- `effective_plan_status`
|
||||
- `time_precision`
|
||||
- `temporal_surface`
|
||||
- `reference_date_used`
|
||||
- `score_breakdown.temporal_boost`
|
||||
|
||||
## Configure it
|
||||
|
||||
### Default behavior
|
||||
|
||||
Temporal Reasoning is enabled by default for supported v3 searches and writes.
|
||||
|
||||
### Per-request override
|
||||
|
||||
Use `temporal_reasoning=False` when you want a specific call to behave like a normal semantic add or search.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
client.add(
|
||||
[{"role": "user", "content": "Preferred language is English."}],
|
||||
user_id="jordan",
|
||||
temporal_reasoning=False,
|
||||
)
|
||||
|
||||
results = client.search(
|
||||
"preferred language",
|
||||
filters={"user_id": "jordan"},
|
||||
temporal_reasoning=False,
|
||||
)
|
||||
```
|
||||
|
||||
```javascript JavaScript
|
||||
await client.add(
|
||||
[{ role: "user", content: "Preferred language is English." }],
|
||||
{ userId: "jordan", temporalReasoning: false }
|
||||
);
|
||||
|
||||
const results = await client.search("preferred language", {
|
||||
filters: { user_id: "jordan" },
|
||||
temporalReasoning: false,
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "https://api.mem0.ai/v3/memories/search/" \
|
||||
-H "Authorization: Token your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"query": "preferred language",
|
||||
"filters": { "user_id": "jordan" },
|
||||
"temporal_reasoning": false
|
||||
}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### 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, backfills, and cookbook examples 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.get("memory_type"), item.get("event_date"))
|
||||
```
|
||||
|
||||
```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.memoryType, item.eventDate);
|
||||
});
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Info icon="check">
|
||||
Expected behavior: the March 10 review appears as a past `event`, the April 18 appointment does not lead this result set, 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 and confirm results include top-level fields like `memory_type`, `event_date`, or `effective_plan_status`.
|
||||
- Repeat the same query with `temporal_reasoning=False` and confirm ranking changes for time-sensitive prompts.
|
||||
- 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.
|
||||
- Disable Temporal Reasoning only for clearly timeless lookups such as static profile fields.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Memory Timestamps" icon="calendar" href="/platform/features/timestamp">
|
||||
Anchor imported memories to when they actually happened.
|
||||
</Card>
|
||||
<Card title="Answer Time-Aware Questions" icon="book-open" href="/cookbooks/essentials/temporal-memory-assistant">
|
||||
Follow the cookbook for an end-to-end temporal retrieval workflow.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Snippet file="get-help.mdx" />
|
||||
Reference in New Issue
Block a user