diff --git a/docs/openapi.json b/docs/openapi.json index 0bc42eb72..c57bcb80d 100644 --- a/docs/openapi.json +++ b/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", diff --git a/docs/platform/features/temporal-reasoning.mdx b/docs/platform/features/temporal-reasoning.mdx index 0a2fdd510..64882e898 100644 --- a/docs/platform/features/temporal-reasoning.mdx +++ b/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. - - **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 - +It is not available in the OSS SDK. - - Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on OSS memory stores or older Platform endpoints. - +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. ```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" } } +); +``` + + +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. + + +```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", }); ``` - - `reference_date` is especially useful in automated tests and demos because it makes relative phrases like `last week` resolve consistently every time. - +## 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. | - - - Examples: `last week`, `last month`, `in March 2025`, `on 2025-03-10` - - - Examples: `upcoming`, `next week`, `tomorrow`, `what do I have coming up?` - - - Examples: `right now`, `currently`, `where do I work now?` - - - Examples: `as of March 2025`, `where was I living as of 2024?` - - - Examples: `how long have I lived here?`, `since when have I worked there?` - - - -## 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). - Anchor imported memories to when they actually happened. + Preserve the original time of imported memories.