From f864e9b87106a131a5ee907e455939c937d8e72e Mon Sep 17 00:00:00 2001 From: agumpandey Date: Sat, 9 May 2026 10:43:56 +0530 Subject: [PATCH] docs(temporal): remove temporal metadata from v3 search response docs Temporal fields (event_date, memory_type, effective_plan_status, etc.) are backend-only ranking signals and must not be documented as part of the public search API response. - temporal-reasoning.mdx: replace response-field table with a note that temporal reasoning affects ranking only; no metadata added to responses - temporal-memory-assistant.mdx: remove temporal field reads from all three retrieval examples; update illustrative output blocks - openapi.json: remove temporal fields from /v3/memories/search/ example response; remove temporal_boost from score_breakdown example - add-memories.mdx: remove temporal_reasoning toggle from request params Co-Authored-By: Claude Sonnet 4.6 --- docs/api-reference/memory/add-memories.mdx | 1 - .../essentials/temporal-memory-assistant.mdx | 102 +++--------------- docs/openapi.json | 22 +--- docs/platform/features/temporal-reasoning.mdx | 66 +----------- 4 files changed, 20 insertions(+), 171 deletions(-) diff --git a/docs/api-reference/memory/add-memories.mdx b/docs/api-reference/memory/add-memories.mdx index 82f3341f0..6a4d987b2 100644 --- a/docs/api-reference/memory/add-memories.mdx +++ b/docs/api-reference/memory/add-memories.mdx @@ -54,7 +54,6 @@ Provide conversation messages for Mem0 to extract memories from. At least one en | `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. | -| `temporal_reasoning` | boolean | Optional | Overrides the deployment default for temporal enrichment on this write. | > \* At least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`) is required. diff --git a/docs/cookbooks/essentials/temporal-memory-assistant.mdx b/docs/cookbooks/essentials/temporal-memory-assistant.mdx index e2e616992..ef0bc6ff7 100644 --- a/docs/cookbooks/essentials/temporal-memory-assistant.mdx +++ b/docs/cookbooks/essentials/temporal-memory-assistant.mdx @@ -81,53 +81,9 @@ await client.add( ``` -## Compare Retrieval Modes +## Run a Temporal Search -The easiest way to understand Temporal Reasoning is to compare the same query in two modes: - -- **Standard retrieval** with `temporal_reasoning=False` -- **Temporal retrieval** with the default time-aware mode enabled - -### Mode 1: Standard Retrieval - -This is useful for broad semantic lookups, but it does not try to interpret `last week` against a timeline. - - -```python Python -results = client.search( - "what did I do last week?", - filters={"user_id": USER_ID}, - reference_date=REFERENCE_DATE, - temporal_reasoning=False, -) - -for item in results["results"]: - print(item["memory"]) -``` - -```javascript JavaScript -const results = await client.search("what did I do last week?", { - filters: { user_id: USER_ID }, - referenceDate: REFERENCE_DATE, - temporalReasoning: false, -}); - -results.results.forEach((item) => console.log(item.memory)); -``` - - -**Illustrative output:** -```text -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. -``` - -That result set is semantically reasonable, but it is not yet behaving like a time-aware assistant. - -### Mode 2: Temporal Retrieval - -Now run the same query with temporal mode enabled. This is the default, so you can omit the flag. +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. ```python Python @@ -138,12 +94,7 @@ results = client.search( ) for item in results["results"]: - print( - item["memory"], - item.get("memory_type"), - item.get("event_date"), - item.get("temporal_surface"), - ) + print(item["memory"], item["score"]) ``` ```javascript JavaScript @@ -153,20 +104,20 @@ const results = await client.search("what did I do last week?", { }); results.results.forEach((item) => { - console.log(item.memory, item.memoryType, item.eventDate, item.temporalSurface); + console.log(item.memory, item.score); }); ``` **Illustrative output:** ```text -I finished the Q1 product review on March 10, 2025. event 2025-03-10 Mar 10, 2025 +I finished the Q1 product review on March 10, 2025. ``` -The impact is not just better ranking. Mem0 is now using the query’s time intent plus the stored temporal fields to prefer the memory that fits `last week`. +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. -Expected behavior: with temporal mode on, the March 10 event should lead for `last week`, while the April 18 appointment and the ongoing job title should not dominate the answer. +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. ## See the Three Query Shapes @@ -200,7 +151,7 @@ upcoming = client.search( ) for item in upcoming["results"]: - print(item["memory"], item.get("memory_type"), item.get("effective_plan_status")) + print(item["memory"], item["score"]) ``` ```javascript JavaScript @@ -210,14 +161,14 @@ const upcoming = await client.search("what do I have coming up?", { }); upcoming.results.forEach((item) => { - console.log(item.memory, item.memoryType, item.effectivePlanStatus); + console.log(item.memory, item.score); }); ``` **Illustrative output:** ```text -I have a dentist appointment on April 18, 2025 at 2 PM. plan upcoming +I have a dentist appointment on April 18, 2025 at 2 PM. ``` @@ -237,7 +188,7 @@ current = client.search( ) for item in current["results"]: - print(item["memory"], item.get("memory_type"), item.get("temporal_surface")) + print(item["memory"], item["score"]) ``` ```javascript JavaScript @@ -247,22 +198,19 @@ const current = await client.search("where do I work right now?", { }); current.results.forEach((item) => { - console.log(item.memory, item.memoryType, item.temporalSurface); + console.log(item.memory, item.score); }); ``` **Illustrative output:** ```text -I am the product lead at Acme Corp. state ongoing +I am the product lead at Acme Corp. ``` ## Use the Right Controls -There are two public controls that matter most in production: - -- `reference_date` anchors relative phrases like `last week`, `tomorrow`, and `right now` -- `temporal_reasoning` lets you switch between standard retrieval and temporal retrieval for a specific request +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 @@ -285,27 +233,6 @@ await client.search("what did I do last week?", { ``` -### Standard retrieval for timeless queries - -Turn temporal mode off when a question is not time-sensitive. - - -```python Python -client.search( - "what is my job title?", - filters={"user_id": USER_ID}, - temporal_reasoning=False, -) -``` - -```javascript JavaScript -await client.search("what is my job title?", { - filters: { user_id: USER_ID }, - temporalReasoning: false, -}); -``` - - ### Historical imports If you are backfilling old data, send the original event time instead of relying only on ingestion time. @@ -368,7 +295,6 @@ await client.search("what did we discuss last week?", { - 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. -- You can switch between standard retrieval and temporal retrieval per request with `temporal_reasoning`. ## Next Steps diff --git a/docs/openapi.json b/docs/openapi.json index 5482024a1..f08c2d5b6 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -2093,11 +2093,6 @@ "type": "boolean", "default": true, "description": "When `false`, stores each message verbatim without running the extraction LLM." - }, - "temporal_reasoning": { - "type": "boolean", - "nullable": true, - "description": "Enable V3 temporal reasoning write-path metadata. Defaults to the deployment setting." } } }, @@ -2240,11 +2235,6 @@ ], "nullable": true, "description": "Optional query anchor time for relative temporal interpretation. Accepts Unix epoch, YYYY-MM-DD, or ISO datetime." - }, - "temporal_reasoning": { - "type": "boolean", - "nullable": true, - "description": "Enable V3 temporal intent and temporal scoring. Defaults to the deployment setting." } } }, @@ -2329,18 +2319,8 @@ "score_breakdown": { "semantic": 0.78, "bm25": 0.0, - "entity": 0.0, - "temporal_boost": 0.04 + "entity": 0.0 }, - "memory_type": "event", - "event_date": "2026-01-15", - "event_start": "2026-01-15", - "event_end": "2026-01-15", - "plan_status": null, - "effective_plan_status": null, - "time_precision": "day", - "temporal_surface": "Jan 15, 2026", - "reference_date_used": "2026-01-20", "metadata": {}, "categories": [ "location" diff --git a/docs/platform/features/temporal-reasoning.mdx b/docs/platform/features/temporal-reasoning.mdx index 52149c0cb..f654b2beb 100644 --- a/docs/platform/features/temporal-reasoning.mdx +++ b/docs/platform/features/temporal-reasoning.mdx @@ -47,67 +47,13 @@ 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." | -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` +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. ## 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. - - -```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 - }' -``` - +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 @@ -208,7 +154,7 @@ results = client.search( ) for item in results["results"]: - print(item["memory"], item.get("memory_type"), item.get("event_date")) + print(item["memory"], item["score"]) ``` ```javascript JavaScript @@ -218,7 +164,7 @@ const results = await client.search("what did I do last week?", { }); results.results.forEach((item) => { - console.log(item.memory, item.memoryType, item.eventDate); + console.log(item.memory, item.score); }); ``` @@ -249,8 +195,7 @@ results.results.forEach((item) => { ## 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. +- 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`. @@ -260,7 +205,6 @@ results.results.forEach((item) => { - 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.