docs(temporal): clarify feature behavior and usage

docs/openapi.json

@@ -2979,7 +2979,7 @@
 											}
 										],
 										"nullable": true,
-										"description": "Optional query anchor time for relative temporal interpretation. Accepts Unix epoch, YYYY-MM-DD, or ISO datetime."
+										"description": "Date and time to simulate the search from. Accepts a Unix epoch, YYYY-MM-DD, or ISO datetime."
 									},
 									"fields": {
 										"type": "array",

docs/platform/features/temporal-reasoning.mdx

@@ -1,139 +1,80 @@
 ---
 title: Temporal Reasoning
-description: "Time-aware memory retrieval for Mem0 Platform v3 so queries like 'last week', 'upcoming', and 'right now' return the right memories."
+description: "Boost memories whose dates match the time in a search."
 badge: "v3"
 ---
 
-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.
+Temporal Reasoning gives a ranking boost to memories whose event dates match the time in a search. Event dates are when something described in a memory happened or will happen. It runs automatically on Mem0 Platform v3.
 
-<Info>
-  **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
-</Info>
+It is not available in the OSS SDK.
 
-<Warning>
-  Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on OSS memory stores or older Platform endpoints.
-</Warning>
+Dates from new memories usually affect search within a few seconds.
 
-## Configure access
+## Time-aware searches
 
-Confirm your `MEM0_API_KEY` is set and that you are using the v3 Platform client:
+Queries can include expressions such as `yesterday`, `last week`, `tomorrow`, `currently`, and `as of March 2025`. Mem0 compares them with dates and date ranges found in stored memories.
 
-```python
-from mem0 import MemoryClient
+## Example
 
-client = MemoryClient(api_key="your-api-key")
-```
+Suppose a user has these memories:
 
-## How it works
+- "Yesterday I met Maya at the Orion conference in Paris."
+- "Last week I met Maya at the Orion conference in Tokyo."
+- "Last year I met Maya at the Orion conference in Lisbon."
 
-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.
-
-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.
-
-### Memory types Temporal Reasoning handles
-
-| 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 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." |
-
-Results come back in the normal search response shape: Temporal Reasoning affects ranking, not the response format.
-
-## Configure it
-
-Temporal Reasoning is enabled by default for all v3 searches and writes. There is no per-request toggle.
-
-Two parameters give you precise control when you need it:
-
-- `observation_date` (or `observation_datetime`, which takes priority when both are set) on `add()`: anchors an imported memory to the time it actually happened. Pair with `timezone` when resolving a date-only value.
-- `timestamp` on `add()`: a Unix epoch that sets the memory's creation time. When present it takes priority over `observation_datetime` and `observation_date` as the anchor Temporal Reasoning ranks against, so pass only the one you want to win.
-- `reference_date` on `search()`: resolves relative phrases like `last week` against a fixed point in time
+Searching for `Which city did I meet Maya in at the Orion conference last week?` gives the Tokyo memory a temporal boost and ranks it first.
 
 <CodeGroup>
 ```python Python
-from mem0 import MemoryClient
-
-client = MemoryClient(api_key="your-api-key")
-
-client.add(
-    [{"role": "user", "content": "I finished the Q1 review on March 10, 2025."}],
-    user_id="jordan",
-    observation_date="2025-03-10",
-)
-
 results = client.search(
-    "what did I do last week?",
-    filters={"user_id": "jordan"},
+    "Which city did I meet Maya in at the Orion conference last week?",
+    filters={"user_id": "maya-demo"},
+)
+```
+
+```javascript JavaScript
+const results = await client.search(
+  "Which city did I meet Maya in at the Orion conference last week?",
+  { filters: { user_id: "maya-demo" } }
+);
+```
+</CodeGroup>
+
+Search returns the usual memory results, reordered using the temporal boost.
+
+## Search from a specific time
+
+Use `reference_date` to simulate searching at a specific date and time. Mem0 treats it as the current time for that search.
+
+<CodeGroup>
+```python Python
+results = client.search(
+    "What happened last week?",
+    filters={"user_id": "user-123"},
     reference_date="2025-03-21T00:00:00Z",
 )
 ```
 
 ```javascript JavaScript
-import { MemoryClient } from "mem0ai";
-
-const client = new MemoryClient({ apiKey: "your-api-key" });
-
-await client.add(
-  [{ role: "user", content: "I finished the Q1 review on March 10, 2025." }],
-  {
-    userId: "jordan",
-    observationDate: "2025-03-10",
-  }
-);
-
-const results = await client.search("what did I do last week?", {
-  filters: { user_id: "jordan" },
+const results = await client.search("What happened last week?", {
+  filters: { user_id: "user-123" },
   referenceDate: "2025-03-21T00:00:00Z",
 });
 ```
 </CodeGroup>
 
-<Tip>
-  `reference_date` is especially useful in automated tests and demos because it makes relative phrases like `last week` resolve consistently every time.
-</Tip>
+## Parameters
 
-## Supported query patterns
+| Action | Python | TypeScript | Purpose |
+| --- | --- | --- | --- |
+| Add memories | `timestamp` | `timestamp` | Preserve the original time of an imported conversation. |
+| Search memories | `reference_date` | `referenceDate` | Simulate searching at a specific date and time. |
 
-<AccordionGroup>
-  <Accordion title="Historical questions">
-    Examples: `last week`, `last month`, `in March 2025`, `on 2025-03-10`
-  </Accordion>
-  <Accordion title="Upcoming questions">
-    Examples: `upcoming`, `next week`, `tomorrow`, `what do I have coming up?`
-  </Accordion>
-  <Accordion title="Current-state questions">
-    Examples: `right now`, `currently`, `where do I work now?`
-  </Accordion>
-  <Accordion title="As-of questions">
-    Examples: `as of March 2025`, `where was I living as of 2024?`
-  </Accordion>
-  <Accordion title="Duration questions">
-    Examples: `how long have I lived here?`, `since when have I worked there?`
-  </Accordion>
-</AccordionGroup>
-
-## Verify the feature is working
-
-- 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 events or plans matter temporally.
-- Pass `observation_date` (or `observation_datetime`) during historical imports so the ingestion time does not become the only time anchor. Do not also pass `timestamp` on those calls, since it overrides both as the ranking anchor.
-- Scope searches with `filters` so time-aware ranking operates inside the right user boundary.
-- Use `reference_date` in automated tests and reproducible demos.
+For all search inputs and returned fields, see the [Search Memories API reference](/api-reference/memory/search-memories).
 
 <CardGroup cols={1}>
   <Card title="Memory Timestamps" icon="calendar" href="/platform/features/timestamp">
-    Anchor imported memories to when they actually happened.
+    Preserve the original time of imported memories.
   </Card>
 </CardGroup>