From 9532d08cdda14e4b6c2db54eef2522d830f9b50d Mon Sep 17 00:00:00 2001
From: agumpandey <agam.pandey@mem0.ai>
Date: Tue, 12 May 2026 23:43:16 +0530
Subject: [PATCH] docs: remove exposed temporal fields from migration guide

---
 docs/migration/platform-v2-to-v3.mdx | 27 +++++++++------------------
 1 file changed, 9 insertions(+), 18 deletions(-)

diff --git a/docs/migration/platform-v2-to-v3.mdx b/docs/migration/platform-v2-to-v3.mdx
index f1cc3e2f0..73b13754f 100644
--- a/docs/migration/platform-v2-to-v3.mdx
+++ b/docs/migration/platform-v2-to-v3.mdx
@@ -52,19 +52,18 @@ Search now uses hybrid retrieval, which improves ranking quality — especially
       "memory": "User moved to San Francisco in January 2026",
       "score": 0.82,
       "score_breakdown": {
-        "temporal_boost": 0.18
+        "semantic": 0.74,
+        "bm25": 0.68,
+        "entity": 0.12
       },
       "metadata": {},
-      "categories": ["location"],
-      "memory_type": "state",
-      "event_date": "2026-01-15",
-      "temporal_surface": "January 2026"
+      "categories": ["location"]
     }
   ]
 }
 ```
 
-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. Search responses may include fields such as `score_breakdown`, `memory_type`, `event_date`, `effective_plan_status`, `temporal_surface`, and `reference_date_used` when relevant.
+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.
 
 ## API Changes
 
@@ -171,14 +170,12 @@ Poll status via `GET /v1/event/{event_id}/` — status will be `SUCCEEDED` or `F
       "memory": "User moved to San Francisco from New York in January 2026",
       "score": 0.82,
       "score_breakdown": {
-        "temporal_boost": 0.18
+        "semantic": 0.74,
+        "bm25": 0.68,
+        "entity": 0.12
       },
       "metadata": {},
       "categories": ["location"],
-      "memory_type": "state",
-      "event_date": "2026-01-15",
-      "temporal_surface": "January 2026",
-      "reference_date_used": "2026-01-20",
       "created_at": "2026-01-15T10:30:00Z",
       "updated_at": "2026-01-15T10:30:00Z"
     }
@@ -199,12 +196,6 @@ Poll status via `GET /v1/event/{event_id}/` — status will be `SUCCEEDED` or `F
       "memory": "...",
       "metadata": {},
       "categories": [],
-      "event_date": "2026-01-15",
-      "event_start": "2026-01-15",
-      "event_end": null,
-      "time_precision": "day",
-      "timezone": "UTC",
-      "plan_status": null,
       "created_at": "2026-01-15T10:30:00Z",
       "updated_at": "2026-01-15T10:30:00Z"
     }
@@ -308,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, but V3 can now include extra top-level result fields such as `score_breakdown`, `memory_type`, and temporal fields when available.
+- **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.
 - **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