diff --git a/docs/platform/features/temporal-reasoning.mdx b/docs/platform/features/temporal-reasoning.mdx
index 9df007114..7ea1de697 100644
--- a/docs/platform/features/temporal-reasoning.mdx
+++ b/docs/platform/features/temporal-reasoning.mdx
@@ -1,26 +1,26 @@
 ---
 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."
+description: "Time-aware memory retrieval for Mem0 Platform v3 so queries 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.
+Some memories matter because of **when** they happened, not just because they sound similar. Temporal Reasoning lets Mem0 Platform v3 understand time-aware queries and return the most contextually appropriate results.
 
 <Info>
-  **You'll use this when…**
+  **Use Temporal Reasoning 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
+  - 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.
+  Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on 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:
+Confirm your `MEM0_API_KEY` is set and that you are using the v3 Platform client:
 
 ```python
 from mem0 import MemoryClient
@@ -30,48 +30,46 @@ client = MemoryClient(api_key="your-api-key")
 
 ## How it works
 
-Temporal Reasoning works in two parts:
+When a memory describes an event, a future plan, or an ongoing state, Temporal Reasoning recognizes the time context so the right results surface at search time.
 
-- **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.
+A query like `what did I do last week?` should return a completed past event — not an upcoming appointment and not a stable fact that hasn't changed. Temporal Reasoning handles that distinction automatically.
 
-### Temporal patterns
+### Memory types Temporal Reasoning handles
 
-Mem0 handles several common temporal patterns:
-
-| Pattern | What it represents | Example |
+| Type | What it represents | Example |
 | --- | --- | --- |
 | Dated occurrence | Something that happened at a known time | "I finished the Q1 review on March 10, 2025." |
 | Future plan | A future commitment or scheduled item | "I have a dentist appointment on March 18, 2025." |
-| Ongoing state | A fact that can remain true over time | "I am the product lead at Acme Corp." |
+| Ongoing state | A fact that remains 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." |
 
-At search time, Temporal Reasoning influences how results are ranked. The ranking effect is transparent: results come back in the normal shape.
+Results come back in the normal search response shape — Temporal Reasoning affects ranking, not the response format.
 
 ## Configure it
 
-### Default behavior
+Temporal Reasoning is enabled by default for all v3 searches and writes. There is no per-request toggle.
 
-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.
+Two parameters give you precise control when you need it:
 
-### 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
+- `timestamp` on `add()` — anchors an imported memory to the time it actually happened, rather than the time it was added to Mem0
+- `reference_date` on `search()` — resolves relative phrases like `last week` against a fixed point in time
 
 <CodeGroup>
 ```python Python
 from datetime import datetime, timezone
+from mem0 import MemoryClient
 
+client = MemoryClient(api_key="your-api-key")
+
+# Import a historical memory anchored to when it happened
 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()),
 )
 
+# Search with a relative query anchored to a known date
 results = client.search(
     "what did I do last week?",
     filters={"user_id": "jordan"},
@@ -80,6 +78,11 @@ results = client.search(
 ```
 
 ```javascript JavaScript
+import { MemoryClient } from "mem0ai";
+
+const client = new MemoryClient({ apiKey: "your-api-key" });
+
+// Import a historical memory anchored to when it happened
 await client.add(
   [{ role: "user", content: "I finished the Q1 review on March 10, 2025." }],
   {
@@ -88,6 +91,7 @@ await client.add(
   }
 );
 
+// Search with a relative query anchored to a known date
 const results = await client.search("what did I do last week?", {
   filters: { user_id: "jordan" },
   referenceDate: "2025-03-21T00:00:00Z",
@@ -96,7 +100,7 @@ const results = await client.search("what did I do last week?", {
 </CodeGroup>
 
 <Tip>
-  `reference_date` is especially useful for tests and backfills because it makes relative phrases reproducible.
+  `reference_date` is especially useful in automated tests and demos because it makes relative phrases like `last week` resolve consistently every time.
 </Tip>
 
 ## Supported query patterns
@@ -121,15 +125,15 @@ const results = await client.search("what did I do last week?", {
 
 ## Verify the feature is working
 
-- 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`.
+- Run a temporal search with a time-aware query (e.g., "what did I do last week?") and confirm the memory that fits the time window ranks first.
+- Use `reference_date` in test queries so relative phrases resolve consistently across runs.
+- For backfilled data, pass `timestamp` on `add()` to confirm the memory reflects the right point in time.
 
 ## 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 explicit dates in source conversations when events or plans matter temporally.
+- Pass `timestamp` during historical imports so the ingestion time does not become the only time anchor.
+- Scope searches with `filters` so time-aware ranking operates inside the right user boundary.
 - Use `reference_date` in automated tests and reproducible demos.
 
 <CardGroup cols={1}>