JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: hide temporal internals from API docs

Browse Source
This commit is contained in:
agumpandey
2026-05-12 23:49:06 +05:30
parent 9532d08cdd
commit 14237e3252
9 changed files with 14 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference/memory/add-memories.mdx
-8
View File
@@ -49,10 +49,6 @@ Provide conversation messages for Mem0 to extract memories from. At least one en
| `run_id` | string | No* | Associates the memory with a run. |
| `app_id` | string | No* | Associates the memory with an app. |
| `metadata` | object | Optional | Custom key/value metadata (e.g., `{"topic": "preferences"}`). |
| `timestamp` | integer | Optional | Unix timestamp used to anchor imported or historical memories. |
| `observation_date` | string | Optional | Original conversation date (`YYYY-MM-DD`) for temporal grounding. |
| `observation_datetime` | string | Optional | Original conversation datetime for more precise temporal grounding. |
| `timezone` | string | Optional | IANA timezone used when resolving relative dates. |
| `infer` | boolean (default `true`) | Optional | Set to `false` to skip inference and store the provided text as-is. |
> \* At least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`) is required.
@@ -87,7 +83,3 @@ The request is queued for background processing. The response contains an `event
<Info>
Poll the event status via `GET /v1/event/{event_id}/`. Status will be `SUCCEEDED` or `FAILED` once processing completes.
</Info>
<Note>
Some deployments run temporal enrichment in a follow-up async step. In that mode, the add event can complete successfully before temporal search fields are fully available on later searches.
</Note>
docs/api-reference/memory/get-memories.mdx
+2 -45
View File
@@ -19,31 +19,6 @@ The `filters` object supports complex logical operations (AND, OR, NOT) and comp
Pass `page` and `page_size` as query parameters to paginate through results.
## Temporal fields on `get_all`
`get_all` returns the **stored** memory record. For temporally enriched memories, that can include top-level fields such as:
- `event_date`
- `event_start`
- `event_end`
- `time_precision`
- `timezone`
- `polarity`
- `temporal_relation`
- `state_key`
- `plan_status`
These are stored memory attributes, not search-time interpretation fields.
`get_all` does **not** add search-only fields such as:
- `effective_plan_status`
- `temporal_surface`
- `reference_date_used`
- `score_breakdown`
Those fields belong to `search`, where Mem0 interprets a query in context.
<CodeGroup>
```python Code
memories = client.get_all(
@@ -75,16 +50,7 @@ memories = client.get_all(
"metadata": {},
"categories": [],
"created_at": "2024-07-01T12:00:00Z",
"updated_at": "2024-07-01T12:00:00Z",
"event_date": "2024-07-01",
"event_start": "2024-07-01",
"event_end": "2024-07-10",
"time_precision": "interval",
"timezone": "UTC",
"polarity": "positive",
"temporal_relation": "during",
"state_key": null,
"plan_status": "pending"
"updated_at": "2024-07-01T12:00:00Z"
},
{
"id": "a2b8c3d4-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
@@ -93,16 +59,7 @@ memories = client.get_all(
"metadata": {},
"categories": [],
"created_at": "2024-07-05T15:30:00Z",
"updated_at": "2024-07-05T15:30:00Z",
"event_date": null,
"event_start": null,
"event_end": null,
"time_precision": null,
"timezone": null,
"polarity": null,
"temporal_relation": null,
"state_key": null,
"plan_status": null
"updated_at": "2024-07-05T15:30:00Z"
}
]
}
docs/api-reference/memory/search-memories.mdx
+3 -27
View File
@@ -18,20 +18,9 @@ The `filters` object supports complex logical operations (AND, OR, NOT) and comp
- `icontains`: Case-insensitive containment check
- `*`: Wildcard character that matches everything
## Temporal fields in V3 responses
## Temporal reasoning in V3 responses
When Temporal Reasoning is enabled for a query, search results can include additional **top-level** fields such as:
- `memory_type`
- `event_date`
- `event_start`
- `event_end`
- `plan_status`
- `effective_plan_status`
- `time_precision`
- `temporal_surface`
- `reference_date_used`
- `score_breakdown.temporal_boost`
Temporal Reasoning is applied internally during retrieval. Search responses keep the normal result shape.
### Search parameter defaults
@@ -78,7 +67,7 @@ related_memories = client.search(
```
</CodeGroup>
### Temporal example
### Temporal query example
<CodeGroup>
```python Platform API Example
@@ -97,15 +86,6 @@ results = client.search(
"memory": "Finished the Q1 product review on March 10, 2025.",
"user_id": "alice",
"score": 0.91,
"memory_type": "event",
"event_date": "2025-03-10",
"event_start": "2025-03-10",
"event_end": "2025-03-10",
"plan_status": null,
"effective_plan_status": null,
"time_precision": "day",
"temporal_surface": "Mar 10, 2025",
"reference_date_used": "2025-03-21",
"metadata": {},
"categories": [],
"created_at": "2025-03-10T00:00:00Z",
@@ -116,10 +96,6 @@ results = client.search(
```
</CodeGroup>
<Note>
Temporal fields are most useful on `search`. The paginated `get_all` endpoint remains a broader retrieval surface and does not mirror the full time-aware search result shape.
</Note>
<CodeGroup>
```python Wildcard Example
# Using wildcard to match all run_ids for a specific user
docs/cookbooks/essentials/temporal-memory-assistant.mdx
-316
View File
@@ -1,316 +0,0 @@
---
title: Time-Aware Retrieval
description: Use Mem0 Platform v3 Temporal Reasoning to make one memory store answer past, upcoming, and current questions correctly.
---
An assistant often stores all of these in the same user profile:
- "I finished the Q1 product review on March 10, 2025."
- "I have a dentist appointment on April 18, 2025 at 2 PM."
- "I am the product lead at Acme Corp."
Those memories are all relevant to the same person, but they should not rank the same way for every question. A query like `what did I do last week?` should favor the finished review. A query like `what do I have coming up?` should favor the appointment. A query like `where do I work right now?` should favor the ongoing role.
This cookbook shows how to get that behavior with Mem0 Platform v3 using the normal `add()` and `search()` flow.
<Info icon="clock">
**Time to complete:** ~15 minutes · **Languages:** Python, JavaScript
</Info>
## Setup
<CodeGroup>
```python Python
from mem0 import MemoryClient
client = MemoryClient(api_key="your-api-key")
USER_ID = "jordan"
REFERENCE_DATE = "2025-03-21T00:00:00Z"
```
```javascript JavaScript
import MemoryClient from "mem0ai";
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
const USER_ID = "jordan";
const REFERENCE_DATE = "2025-03-21T00:00:00Z";
```
</CodeGroup>
<Note>
These examples target **Mem0 Platform v3**. Writes are asynchronous, so allow a short delay before validating search behavior.
</Note>
## Seed Memories
Start with one past event, one future plan, and one ongoing state:
<CodeGroup>
```python Python
client.add(
[{"role": "user", "content": "I finished the Q1 product review on March 10, 2025."}],
user_id=USER_ID,
)
client.add(
[{"role": "user", "content": "I have a dentist appointment on April 18, 2025 at 2 PM."}],
user_id=USER_ID,
)
client.add(
[{"role": "user", "content": "I am the product lead at Acme Corp."}],
user_id=USER_ID,
)
```
```javascript JavaScript
await client.add(
[{ role: "user", content: "I finished the Q1 product review on March 10, 2025." }],
{ userId: USER_ID }
);
await client.add(
[{ role: "user", content: "I have a dentist appointment on April 18, 2025 at 2 PM." }],
{ userId: USER_ID }
);
await client.add(
[{ role: "user", content: "I am the product lead at Acme Corp." }],
{ userId: USER_ID }
);
```
</CodeGroup>
## Run a Temporal Search
Temporal Reasoning is always on for v3 searches — no flag required. The pipeline detects time language in the query and uses stored temporal fields to rank results appropriately.
<CodeGroup>
```python Python
results = client.search(
"what did I do last week?",
filters={"user_id": USER_ID},
reference_date=REFERENCE_DATE,
)
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: USER_ID },
referenceDate: REFERENCE_DATE,
});
results.results.forEach((item) => {
console.log(item.memory, item.score);
});
```
</CodeGroup>
**Illustrative output:**
```text
I finished the Q1 product review on March 10, 2025.
```
Mem0 uses the query’s time intent and the stored temporal metadata to rank the memory that fits `last week` higher. The April 18 appointment and the ongoing job title score lower because their temporal classification and date don’t match a historical range query.
<Info icon="check">
Expected behavior: the March 10 event leads for `last week`. The April 18 appointment and the ongoing Acme role score lower because their temporal type and date don’t match a historical range query.
</Info>
## See the Three Query Shapes
The same memory store can now support three different retrieval patterns.
### 1. Past-oriented retrieval
Use this for questions about completed activity.
```python
client.search(
"what did I do last week?",
filters={"user_id": USER_ID},
reference_date=REFERENCE_DATE,
)
```
Expected outcome: the completed review ranks above future plans and ongoing profile facts.
### 2. Upcoming retrieval
Use this for scheduled commitments and future-facing assistant flows.
<CodeGroup>
```python Python
upcoming = client.search(
"what do I have coming up?",
filters={"user_id": USER_ID},
reference_date=REFERENCE_DATE,
)
for item in upcoming["results"]:
print(item["memory"], item["score"])
```
```javascript JavaScript
const upcoming = await client.search("what do I have coming up?", {
filters: { user_id: USER_ID },
referenceDate: REFERENCE_DATE,
});
upcoming.results.forEach((item) => {
console.log(item.memory, item.score);
});
```
</CodeGroup>
**Illustrative output:**
```text
I have a dentist appointment on April 18, 2025 at 2 PM.
```
<Warning>
Upcoming queries work best when the source memory includes a real date or date range. Vague text like "we should schedule something soon" is less reliable for future-oriented retrieval.
</Warning>
### 3. Current-state retrieval
Use this for durable facts that are still true now.
<CodeGroup>
```python Python
current = client.search(
"where do I work right now?",
filters={"user_id": USER_ID},
reference_date=REFERENCE_DATE,
)
for item in current["results"]:
print(item["memory"], item["score"])
```
```javascript JavaScript
const current = await client.search("where do I work right now?", {
filters: { user_id: USER_ID },
referenceDate: REFERENCE_DATE,
});
current.results.forEach((item) => {
console.log(item.memory, item.score);
});
```
</CodeGroup>
**Illustrative output:**
```text
I am the product lead at Acme Corp.
```
## Use the Right Controls
The main control for temporal retrieval is `reference_date`, which anchors relative phrases like `last week`, `tomorrow`, and `right now` to a known point in time. Without it, the server uses the current date.
### Deterministic tests and demos
Use `reference_date` whenever the wording is relative.
<CodeGroup>
```python Python
client.search(
"what did I do last week?",
filters={"user_id": USER_ID},
reference_date="2025-03-21T00:00:00Z",
)
```
```javascript JavaScript
await client.search("what did I do last week?", {
filters: { user_id: USER_ID },
referenceDate: "2025-03-21T00:00:00Z",
});
```
</CodeGroup>
### Historical imports
If you are backfilling old data, send the original event time instead of relying only on ingestion time.
<CodeGroup>
```python Python
from datetime import datetime, timezone
client.add(
[{"role": "user", "content": "I attended the partner summit on November 15, 2024."}],
user_id=USER_ID,
timestamp=int(datetime(2024, 11, 15, tzinfo=timezone.utc).timestamp()),
)
```
```javascript JavaScript
await client.add(
[{ role: "user", content: "I attended the partner summit on November 15, 2024." }],
{
userId: USER_ID,
timestamp: Math.floor(new Date("2024-11-15T00:00:00Z").getTime() / 1000),
}
);
```
</CodeGroup>
### Combine with normal Platform filters
Temporal retrieval still respects the normal entity filters.
<CodeGroup>
```python Python
client.search(
"what did we discuss last week?",
filters={
"AND": [
{"user_id": USER_ID},
{"agent_id": "task-planner"},
]
},
reference_date=REFERENCE_DATE,
)
```
```javascript JavaScript
await client.search("what did we discuss last week?", {
filters: {
AND: [
{ user_id: USER_ID },
{ agent_id: "task-planner" },
],
},
referenceDate: REFERENCE_DATE,
});
```
</CodeGroup>
## What You Built
- Past questions can favor completed events instead of just semantically related memories.
- Upcoming questions can surface scheduled plans instead of historical notes.
- Current-state questions can keep stable facts available without letting them take over every search.
## Next Steps
If your application depends on relative time language, keep `reference_date` in your tests and evals, and pass `timestamp` when you backfill older conversations. That keeps time-aware retrieval predictable without adding a separate timeline system to your stack.
<CardGroup cols={2}>
<Card
title="Temporal Reasoning Feature Guide"
description="See the supported query patterns, public response fields, and configuration knobs."
icon="clock"
href="/platform/features/temporal-reasoning"
/>
<Card
title="Control Memory Ingestion"
description="Pair time-aware retrieval with stricter write controls and cleaner stored facts."
icon="filter"
href="/cookbooks/essentials/controlling-memory-ingestion"
/>
</CardGroup>
docs/core-concepts/memory-operations/search.mdx
+1 -1
View File
@@ -157,7 +157,7 @@ const memories = memory.search("food preferences", {
</Info>
<Note>
On Mem0 Platform v3, time-aware queries can also return top-level temporal fields such as `memory_type`, `event_date`, `event_start`, `event_end`, `effective_plan_status`, `temporal_surface`, and `score_breakdown.temporal_boost`. See <Link href="/platform/features/temporal-reasoning">Temporal Reasoning</Link>.
On Mem0 Platform v3, time-aware queries use Temporal Reasoning internally while preserving the normal search response shape. See <Link href="/platform/features/temporal-reasoning">Temporal Reasoning</Link>.
</Note>
## Filter patterns
docs/docs.json
-1
View File
@@ -330,7 +330,6 @@
"cookbooks/essentials/building-ai-companion",
"cookbooks/essentials/entity-partitioning-playbook",
"cookbooks/essentials/controlling-memory-ingestion",
"cookbooks/essentials/temporal-memory-assistant",
"cookbooks/essentials/tagging-and-organizing-memories",
"cookbooks/essentials/exporting-memories"
]
docs/migration/platform-v2-to-v3.mdx
+2 -2
View File
@@ -63,7 +63,7 @@ Search now uses hybrid retrieval, which improves ranking quality — especially
}
```
The top-level `score` remains a `[0, 1]` value. Relative ranking between results stays comparable to v2, but absolute numbers shift since the scoring method changed — retune any hard thresholds in your app against representative queries. Temporal signals are used internally for ranking and are not exposed as client-facing temporal metadata.
The top-level `score` remains a `[0, 1]` value. Relative ranking between results stays comparable to v2, but absolute numbers shift since the scoring method changed — retune any hard thresholds in your app against representative queries. Temporal signals are used internally for ranking and are not returned as extra client-facing data.
## API Changes
@@ -299,7 +299,7 @@ If your application previously read graph relations from the API response (`rela
- **V1 and V2 endpoints continue to work.** There is no requirement to migrate to V3 endpoints immediately.
- **Existing memories are preserved.** The new algorithm does not modify or re-process previously stored memories.
- **Search response shape is unchanged.** The top-level `score` and `results[]` array are the same; existing code that reads `score` continues to work. What changed is the scoring method behind the number (multi-signal fusion instead of pure cosine), so the absolute values shift even when ranking stays comparable.
- **Search remains backward-compatible at the top level.** Existing code that reads `results[]` and `score` continues to work. Temporal signals are applied internally during retrieval rather than returned as temporal fields in the client response.
- **Search remains backward-compatible at the top level.** Existing code that reads `results[]` and `score` continues to work. Temporal signals are applied internally during retrieval and do not change the client response shape.
- **List response shape changed.** `get_all` now returns a paginated envelope (`{count, next, previous, results}`) instead of a bare `{results: [...]}`. Update code that reads `response["results"]` to continue working, or switch to the client SDKs which handle both shapes.
## Performance Improvements
docs/openapi.json
+2 -81
View File
@@ -1866,55 +1866,7 @@
"updated_at": {
"type": "string",
"format": "date-time"
},
"plan_status": {
"type": "string",
"nullable": true,
"description": "Stored plan status if this memory is a plan."
},
"event_date": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Primary event date when available."
},
"event_start": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Start date for an event or interval when available."
},
"event_end": {
"type": "string",
"format": "date",
"nullable": true,
"description": "End date for an event or interval when available."
},
"time_precision": {
"type": "string",
"nullable": true,
"description": "Temporal precision for the resolved date information."
},
"timezone": {
"type": "string",
"nullable": true,
"description": "Stored timezone associated with the temporal record, when available."
},
"polarity": {
"type": "string",
"nullable": true,
"description": "Stored temporal polarity, when available."
},
"temporal_relation": {
"type": "string",
"nullable": true,
"description": "Stored temporal relation, when available."
},
"state_key": {
"type": "string",
"nullable": true,
"description": "Stored state key for state-like memories, when available."
}
}
},
"required": [
"id",
@@ -1945,16 +1897,7 @@
"location"
],
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z",
"event_date": "2026-01-15",
"event_start": "2026-01-15",
"event_end": null,
"time_precision": "day",
"timezone": "UTC",
"polarity": "positive",
"temporal_relation": "on",
"state_key": null,
"plan_status": null
"updated_at": "2026-01-15T10:30:00Z"
}
]
}
@@ -2056,33 +1999,11 @@
"type": "string",
"description": "Project-level instructions that guide extraction for this call."
},
"observation_date": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Original conversation date used for temporal grounding."
},
"observation_datetime": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Original conversation datetime used for temporal grounding."
},
"timezone": {
"type": "string",
"nullable": true,
"description": "IANA timezone used to resolve observation dates and relative dates."
},
"multilingual": {
"type": "boolean",
"nullable": true,
"description": "Extract memories in the same language as the input."
},
"timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix epoch timestamp for when the conversation happened."
},
"expiration_date": {
"type": "string",
"format": "date",
docs/platform/features/temporal-reasoning.mdx
+4 -7
View File
@@ -32,12 +32,12 @@ client = MemoryClient(api_key="your-api-key")
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.
- **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.
### Memory types
Mem0 normalizes temporal memories into a small set of developer-facing types:
Mem0 normalizes temporal memories into a small set of internal classes:
| Type | What it represents | Example |
| --- | --- | --- |
@@ -47,7 +47,7 @@ Mem0 normalizes temporal memories into a small set of developer-facing types:
| `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 — memories that match the temporal intent of the query receive a boost — but no temporal metadata is added to the API response. The ranking effect is transparent: results come back in the normal shape.
At search time, Temporal Reasoning influences how results are ranked. The ranking effect is transparent: results come back in the normal shape.
## Configure it
@@ -210,9 +210,6 @@ results.results.forEach((item) => {
<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" />