JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into mintlify/af82bda4

Browse Source
This commit is contained in:
mintlify[bot]
2026-08-03 18:43:02 +00:00
parent 1ee9196506 6e6f5b8d59
commit 79d336dac9
59 changed files with 4693 additions and 1231 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/platform/cli.mdx
+17 -1
View File
@@ -122,12 +122,20 @@ echo "Loves hiking on weekends" | mem0 add --user-id alice
| `--messages` | Conversation messages as JSON |
| `-f, --file` | Read messages from a JSON file |
| `-m, --metadata` | Custom metadata as JSON |
| `--categories` | Categories (JSON array or comma-separated) |
| `--categories` | Rejected on `add`. Use `--custom-categories` instead |
| `--custom-categories` | Custom categories as a JSON array of `{name: description}` objects |
| `--custom-instructions` | Custom instructions for fact extraction |
| `--structured-data-schema` | Schema for structured data extraction, as JSON |
| `--timestamp` | Unix timestamp for the memory |
| `--expires` | Expiration date, after which the memory stops being returned |
| `--immutable` | Store the memory so it can never be updated or overwritten |
| `--no-infer` | Store the text exactly as given, skipping fact extraction |
| `-o, --output` | Output format: `text`, `json`, `quiet` |
<Note>
`--categories` is not supported on `add` and exits with an error pointing at `--custom-categories`.
</Note>
### `mem0 search`
Search memories using natural language.
@@ -149,6 +157,9 @@ mem0 search "preferred tools" --user-id alice --output json --top-k 5
| `--keyword` | Use keyword search instead of semantic |
| `--filter` | Advanced filter expression (JSON) |
| `--fields` | Return only the named fields |
| `--show-expired` | Include expired memories |
| `--reference-date` | Reference date for relative queries (`YYYY-MM-DD` or Unix timestamp) |
| `--latest-only` | Only return the latest version of each memory |
| `-o, --output` | Output format: `text`, `json`, `table` |
### `mem0 list`
@@ -172,6 +183,8 @@ mem0 list --user-id alice --after 2024-01-01 --page-size 50
| `--category` | Filter by category |
| `--after` | Created after date (YYYY-MM-DD) |
| `--before` | Created before date (YYYY-MM-DD) |
| `--show-expired` | Include expired memories |
| `--latest-only` | Only return the latest version of each memory |
| `-o, --output` | Output format: `text`, `json`, `table` |
### `mem0 get`
@@ -200,6 +213,8 @@ echo "new text" | mem0 update <memory-id>
| Flag | Description |
|------|-------------|
| `-m, --metadata` | Replace the memory's metadata with this JSON |
| `--expires` | Expiration date (YYYY-MM-DD) |
| `--timestamp` | Unix timestamp for the memory |
| `-o, --output` | Output format: `text`, `json`, `quiet` |
### `mem0 delete`
@@ -229,6 +244,7 @@ mem0 delete --all --user-id alice --dry-run
| `--all` | Delete all memories matching scope filters |
| `--entity` | Delete the entity and all its memories |
| `--project` | With `--all`: delete all memories project-wide |
| `--delete-linked` | Also delete memories linked to this memory |
| `--dry-run` | Preview without deleting |
| `--force` | Skip confirmation prompt |
docs/platform/features/entity-scoped-memory.mdx
+1 -1
View File
@@ -83,7 +83,7 @@ Passing both `user_id` and `agent_id` to `client.add` does **not** produce recor
As a result, `{"AND": [{"user_id": ...}, {"agent_id": ...}]}` returns nothing for memories created this way. Use `OR` to match either scope. Records with both fields populated only come from [Direct Import](/platform/features/direct-import) (`infer=False`), which writes your text verbatim without attribution splitting.
</Warning>
The HTTP equivalent uses `POST /v1/memories/` with the same identifiers in the JSON body. See the Add Memories API reference for REST details.
The HTTP equivalent uses `POST /v3/memories/add/` with the same identifiers in the JSON body. See the [Add Memories](/api-reference/memory/add-memories) API reference for REST details.
## See it in action
docs/platform/features/temporal-reasoning.mdx
+45 -104
View File
@@ -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>