Feat: add temporal reasoning cookbook and docs

2026-05-05 17:54:26 +05:30
parent 6d3486ca56
commit 91033fc0e9
15 changed files with 1062 additions and 57 deletions
@@ -49,7 +49,12 @@ 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. |
+| `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.

@@ -84,3 +89,6 @@ The request is queued for background processing. The response contains an `event
 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>
@@ -19,6 +19,31 @@ 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(
@@ -46,14 +71,38 @@ memories = client.get_all(
        {
            "id": "f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c",
            "memory": "Alex is planning a trip to San Francisco from July 1st to July 10th",
+            "user_id": "alex",
+            "metadata": {},
+            "categories": [],
            "created_at": "2024-07-01T12:00:00Z",
-            "updated_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"
        },
        {
            "id": "a2b8c3d4-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
            "memory": "Alex prefers vegetarian restaurants",
+            "user_id": "alex",
+            "metadata": {},
+            "categories": [],
            "created_at": "2024-07-05T15:30:00Z",
-            "updated_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
        }
    ]
 }
@@ -65,3 +114,6 @@ memories = client.get_all(
 The response is a paginated envelope with `count`, `next`, `previous`, and `results`. Use `page` and `page_size` query params to step through results.
 </Info>

+<Note>
+`get_all` is best for exports, audits, and raw record inspection. Use <a href="/api-reference/memory/search-memories">Search Memories</a> when you want time-aware ranking or query interpretation.
+</Note>
@@ -18,6 +18,21 @@ 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
+
+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`
+
 ### Search parameter defaults

 | Parameter | V1/V2 | V3 |
@@ -49,10 +64,17 @@ related_memories = client.search(
    {
      "id": "ea925981-272f-40dd-b576-be64e4871429",
      "memory": "Likes to play cricket and plays cricket on weekends.",
+      "user_id": "alice",
      "metadata": {
        "category": "hobbies"
      },
      "score": 0.82,
+      "score_breakdown": {
+        "semantic": 0.79,
+        "bm25": 0.0,
+        "entity": 0.0,
+        "temporal_boost": 0.0
+      },
      "created_at": "2024-07-26T10:29:36.630547-07:00",
      "updated_at": null,
      "categories": ["hobbies"]
@@ -62,6 +84,54 @@ related_memories = client.search(
 ```
 </CodeGroup>

+### Temporal example
+
+<CodeGroup>
+```python Platform API Example
+results = client.search(
+    query="what did I do last week?",
+    filters={"user_id": "alice"},
+    reference_date="2025-03-21T00:00:00Z",
+)
+```
+
+```json Output
+{
+  "results": [
+    {
+      "id": "9b59b0fd-0b31-4a0b-a3ad-7f26bb4f1f8d",
+      "memory": "Finished the Q1 product review on March 10, 2025.",
+      "user_id": "alice",
+      "score": 0.91,
+      "score_breakdown": {
+        "semantic": 0.84,
+        "bm25": 0.0,
+        "entity": 0.0,
+        "temporal_boost": 0.07
+      },
+      "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",
+      "updated_at": "2025-03-10T00:00:00Z"
+    }
+  ]
+}
+```
+</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