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

Mem0 1.0.0 (#3545)

Browse Source
This commit is contained in:
Parshva Daftari
2025-10-16 15:50:20 +05:30
committed by GitHub
parent 8f5151c344
commit 394203d1b5
77 changed files with 3445 additions and 990 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/platform/advanced-memory-operations.mdx
+180 -66
View File
@@ -283,36 +283,70 @@ curl -X POST "https://api.mem0.ai/v1/memories/" \
### Search with Custom Filters
Our advanced search allows you to set custom search filters. You can filter by `user_id`, `agent_id`, `app_id`, `run_id`, `created_at`, `updated_at`, `categories`, and `text`. The filters support logical operators (AND, OR) and comparison operators (`in`, `gte`, `lte`, `gt`, `lt`, `ne`, `contains`, `icontains`, `*`). The wildcard character (`*`) matches everything for a specific field.
Our advanced search allows you to set custom search filters for precise memory retrieval. You can filter by `user_id`, `agent_id`, `app_id`, `run_id`, `created_at`, `updated_at`, `categories`, and `text`. The filters support logical operators (AND, OR) and comparison operators (`in`, `gte`, `lte`, `gt`, `lt`, `ne`, `contains`, `icontains`, `*`). The wildcard character (`*`) matches everything for a specific field.
For the **categories** field specifically:
- Use `contains` for partial matching (e.g., `{"categories": {"contains": "finance"}}`)
- Use `in` for exact matching (e.g., `{"categories": {"in": ["personal_information"]}}`).
#### Filterable Fields
You need to define `version` as `v2` in the search method.
You can filter by the following fields:
- **Session identifiers**: `user_id`, `agent_id`, `run_id`, `app_id`
- **Timestamps**: `created_at`, `updated_at`
- **Content**: `categories`, `metadata` fields
- **Text**: Memory content (platform-specific)
#### Example 1: Search using user_id and agent_id filters
#### Filter Operators
**Logical Operators:**
- `AND`: All conditions must match
- `OR`: At least one condition must match
- `NOT`: Exclude matching conditions (platform-specific)
**Comparison Operators:**
- `in`: Match any value in array (e.g., `{"agent_id": {"in": ["bot1", "bot2"]}}`)
- `gte`, `lte`: Greater/less than or equal (dates, numbers)
- `gt`, `lt`: Greater/less than (dates, numbers)
- `ne`: Not equal to
- `contains`: Partial text match (e.g., `{"categories": {"contains": "finance"}}`)
- `icontains`: Case-insensitive partial match
- `*`: Wildcard - matches any value for the field
#### Using Filters
**Method 1: Direct Parameters (Recommended for simple queries)**
```python
# Search for a specific user
client.search("query", user_id="alice")
# Search with agent context
client.search("query", user_id="alice", agent_id="travel-bot")
```
**Method 2: Filters Object (For complex queries)**
```python
# Combine multiple conditions
filters = {
"AND": [
{"user_id": "alice"},
{"agent_id": {"in": ["bot1", "bot2"]}}
]
}
client.search("query", filters=filters)
```
#### Example 1: OR Logic - Multiple User or Agent IDs
Search memories from either a specific user OR from specific agents:
<CodeGroup>
```python Python
query = "What do you know about me?"
filters = {
"OR":[
{
"user_id":"alex"
},
{
"agent_id":{
"in":[
"travel-assistant",
"customer-support"
]
}
}
"OR": [
{"user_id": "alex"},
{"agent_id": {"in": ["travel-assistant", "customer-support"]}}
]
}
client.search(query, version="v2", filters=filters)
client.search(query, filters=filters)
```
```javascript JavaScript
@@ -332,13 +366,13 @@ const filters = {
}
]
};
client.search(query, { version: "v2", filters })
client.search(query, { filters })
.then(results => console.log(results))
.catch(error => console.error(error));
```
```bash cURL
curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
curl -X POST "https://api.mem0.ai/v2/memories/search/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
@@ -367,43 +401,41 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
query = "What do you know about me?"
filters = {
"AND": [
{"created_at": {"gte": "2024-07-20", "lte": "2024-07-10"}},
{"user_id": "alex"}
{"user_id": "alex"},
{"created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}}
]
}
client.search(query, version="v2", filters=filters)
client.search(query, filters=filters)
```
```javascript JavaScript
const query = "What do you know about me?";
const filters = {
"AND": [
{"created_at": {"gte": "2024-07-20", "lte": "2024-07-10"}},
{"user_id": "alex"}
{"user_id": "alex"},
{"created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}}
]
};
client.search(query, { version: "v2", filters })
client.search(query, { filters })
.then(results => console.log(results))
.catch(error => console.error(error));
```
```bash cURL
curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
curl -X POST "https://api.mem0.ai/v2/memories/search/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
"query": "What do you know about me?",
"filters": {
"AND": [
{"user_id": "alex"},
{
"created_at": {
"gte": "2024-07-20",
"lte": "2024-07-10"
"gte": "2024-07-01",
"lte": "2024-07-31"
}
},
{
"user_id": "alex"
}
]
}
@@ -427,7 +459,7 @@ filters = {
}
]
}
client.search(query, version="v2", filters=filters)
client.search(query, filters=filters)
# Example 3b: Using 'in' for exact matching
query = "What personal information do you have?"
@@ -441,7 +473,7 @@ filters = {
}
]
}
client.search(query, version="v2", filters=filters)
client.search(query, filters=filters)
```
```javascript JavaScript
@@ -458,7 +490,7 @@ const filters1 = {
]
};
client.search(query1, { version: "v2", filters: filters1 })
client.search(query1, { filters: filters1 })
.then(results => console.log(results))
.catch(error => console.error(error));
@@ -475,14 +507,14 @@ const filters2 = {
]
};
client.search(query2, { version: "v2", filters: filters2 })
client.search(query2, { filters: filters2 })
.then(results => console.log(results))
.catch(error => console.error(error));
```
```bash cURL
# Example 3a: Using 'contains' for partial matching
curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
curl -X POST "https://api.mem0.ai/v2/memories/search/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
@@ -500,7 +532,7 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
}'
# Example 3b: Using 'in' for exact matching
curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
curl -X POST "https://api.mem0.ai/v2/memories/search/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
@@ -525,36 +557,38 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
```python Python
query = "What do you know about me?"
filters = {
"NOT": [
"AND": [
{"user_id": "alex"},
{
"categories": {
"contains": "food_preferences"
}
"NOT": [
{"categories": {"contains": "food_preferences"}}
]
}
]
}
client.search(query, version="v2", filters=filters)
client.search(query, filters=filters)
```
```javascript JavaScript
const query = "What do you know about me?";
const filters = {
"NOT": [
"AND": [
{"user_id": "alex"},
{
"categories": {
"contains": "food_preferences"
}
"NOT": [
{"categories": {"contains": "food_preferences"}}
]
}
]
};
client.search(query, { version: "v2", filters })
client.search(query, { filters })
.then(results => console.log(results))
.catch(error => console.error(error));
```
```bash cURL
curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
curl -X POST "https://api.mem0.ai/v2/memories/search/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
@@ -572,22 +606,20 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
```
</CodeGroup>
#### Example 5: Search using wildcard filters
#### Example 5: Wildcard Filters - Match Any Value
Use `*` wildcard to match memories that have any value for a specific field:
<CodeGroup>
```python Python
query = "What do you know about me?"
filters = {
"AND": [
{
"user_id": "alex"
},
{
"run_id": "*" # Matches all run_ids
}
{"user_id": "alex"},
{"run_id": "*"} # Only memories that have a run_id (any value)
]
}
client.search(query, version="v2", filters=filters)
client.search(query, filters=filters)
```
```javascript JavaScript
@@ -603,13 +635,13 @@ const filters = {
]
};
client.search(query, { version: "v2", filters })
client.search(query, { filters })
.then(results => console.log(results))
.catch(error => console.error(error));
```
```bash cURL
curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
curl -X POST "https://api.mem0.ai/v2/memories/search/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
@@ -628,6 +660,88 @@ curl -X POST "https://api.mem0.ai/v1/memories/search/?version=v2" \
```
</CodeGroup>
### Filter Best Practices
**1. Always Scope to User or Agent**
Always include at least a `user_id`, `agent_id`, or `run_id` to scope your search:
```python
# Good: Scoped to user
client.search("query", user_id="alice")
# Better: Scoped to user and agent
client.search("query", user_id="alice", agent_id="travel-bot")
# Best: Scoped to specific session
client.search("query", user_id="alice", agent_id="travel-bot", run_id="session-123")
```
**2. Use Direct Parameters for Simple Queries**
For single-condition filters, use direct parameters instead of the filters object:
```python
# Simple and clean
client.search("query", user_id="alice", agent_id="bot")
# Unnecessarily complex
client.search("query", filters={"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]})
```
**3. Use Filters Object for Complex Logic**
Use the `filters` parameter when you need OR logic, comparison operators, or nested conditions:
```python
# Multiple agents OR specific run
filters = {
"OR": [
{"agent_id": {"in": ["bot1", "bot2"]}},
{"run_id": "special-session"}
]
}
client.search("query", user_id="alice", filters=filters)
```
**4. Combine Direct Parameters with Filters**
You can mix direct parameters with filters for cleaner code:
```python
# User is required, plus complex date/category logic
filters = {
"AND": [
{"created_at": {"gte": "2024-07-01"}},
{"categories": {"contains": "important"}}
]
}
client.search("query", user_id="alice", filters=filters)
```
**5. Platform vs OSS Differences**
Some features are Platform-only:
- **Categories**: Auto-generated on Platform, manual on OSS
- **Date filters**: Platform tracks timestamps automatically
- **NOT operator**: Only available on Platform
- **Wildcard (`*`)**: Behavior may vary
```python
# This works everywhere
m.search("query", user_id="alice", agent_id="bot")
# This is Platform-only
client.search("query", filters={
"AND": [
{"user_id": "alice"},
{"categories": {"contains": "travel"}} # Platform only
]
})
```
---
## Advanced Retrieval Operations
### Get All Memories with Pagination
@@ -774,10 +888,10 @@ filters = {
}
# Default (No Pagination)
client.get_all(version="v2", filters=filters)
client.get_all(filters=filters)
# Pagination (You can also use the page and page_size parameters)
client.get_all(version="v2", filters=filters, page=1, page_size=50)
client.get_all(filters=filters, page=1, page_size=50)
```
```javascript JavaScript
@@ -801,19 +915,19 @@ const filters = {
};
// Default (No Pagination)
client.getAll({ version: "v2", filters })
client.getAll({ filters })
.then(memories => console.log(memories))
.catch(error => console.error(error));
// Pagination (You can also use the page and page_size parameters)
client.getAll({ version: "v2", filters, page: 1, page_size: 50 })
client.getAll({ filters, page: 1, page_size: 50 })
.then(memories => console.log(memories))
.catch(error => console.error(error));
```
```bash cURL
# Default (No Pagination)
curl -X GET "https://api.mem0.ai/v1/memories/?version=v2" \
curl -X GET "https://api.mem0.ai/v2/memories/" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
@@ -832,7 +946,7 @@ curl -X GET "https://api.mem0.ai/v1/memories/?version=v2" \
}'
# Pagination (You can also use the page and page_size parameters)
curl -X GET "https://api.mem0.ai/v1/memories/?version=v2&page=1&page_size=50" \
curl -X GET "https://api.mem0.ai/v2/memories/&page=1&page_size=50" \
-H "Authorization: Token your-api-key" \
-H "Content-Type: application/json" \
-d '{
docs/platform/features/criteria-retrieval.mdx
+16 -20
View File
@@ -81,7 +81,7 @@ Once defined, register the criteria to your project:
client.project.update(retrieval_criteria=retrieval_criteria)
```
Criteria apply project-wide. Once set, they affect all searches using `version="v2"`.
Criteria apply project-wide. Once set, they affect all searches automatically.
## Example Walkthrough
@@ -104,22 +104,18 @@ client.add(messages, user_id="alice")
### Run Standard vs. Criteria-Based Search
```python
# With criteria
filters = {
"AND": [
{"user_id": "alice"}
]
}
# Search with criteria enabled
filters = {"user_id": "alice"}
results_with_criteria = client.search(
query="Why I am feeling happy today?",
filters=filters,
version="v2"
filters=filters
)
# Without criteria
# To disable criteria for a specific search
results_without_criteria = client.search(
query="Why I am feeling happy today?",
user_id="alice"
filters=filters,
use_criteria=False # Disable criteria-based scoring
)
```
@@ -163,10 +159,10 @@ results_without_criteria = client.search(
| Control Over Relevance | None | Fully customizable with weighted criteria |
| Memory Reordering | Static based on similarity | Dynamically re-ranked by intent alignment |
| Emotional Sensitivity | No tone or trait awareness | Incorporates emotion, tone, or custom behaviors |
| Version Required | Defaults | `search(version="v2")` |
| Activation | Default (no criteria defined) | Enabled when criteria are defined in project |
<Note>
If no criteria are defined for a project, `version="v2"` behaves like normal search.
If no criteria are defined for a project, search behaves normally based on semantic similarity only.
</Note>
@@ -184,23 +180,23 @@ If no criteria are defined for a project, `version="v2"` behaves like normal sea
## How It Works
1. **Criteria Definition**: Define custom criteria with a name, description, and weight. These describe what matters in a memory (e.g., joy, urgency, empathy).
2. **Project Configuration**: Register these criteria using `project.update()`. They apply at the project level and influence all searches using `version="v2"`.
3. **Memory Retrieval**: When you perform a search with `version="v2"`, Mem0 first retrieves relevant memories based on the query and your defined criteria.
4. **Weighted Scoring**: Each retrieved memory is evaluated and scored against the defined criteria and weights.
2. **Project Configuration**: Register these criteria using `project.update()`. They apply at the project level and automatically influence all searches.
3. **Memory Retrieval**: When you perform a search, Mem0 first retrieves relevant memories based on the query.
4. **Weighted Scoring**: Each retrieved memory is evaluated and scored against your defined criteria and weights.
This lets you prioritize memories that align with your agent’s goals and not just those that look similar to the query.
This lets you prioritize memories that align with your agent's goals and not just those that look similar to the query.
<Note>
Criteria retrieval is currently supported only in search v2. Make sure to use `version="v2"` when performing searches with custom criteria.
Criteria retrieval is automatically enabled when criteria are defined in your project. Use `use_criteria=False` in search to temporarily disable it for a specific query.
</Note>
## Summary
- Define what “relevant” means using criteria
- Define what "relevant" means using criteria
- Apply them per project via `project.update()`
- Use `version="v2"` to activate criteria-aware search
- Criteria-aware search activates automatically when criteria are configured
- Build agents that reason not just with relevance, but **contextual importance**
---
docs/platform/features/direct-import.mdx
+1 -1
View File
@@ -68,7 +68,7 @@ You can retrieve all memories using the `get_all` method.
<CodeGroup>
```python Python
client.get_all(query="What is Alice's favorite sport?", user_id="alice", output_format="v1.1")
client.get_all(query="What is Alice's favorite sport?", user_id="alice")
```
```json Output
docs/platform/features/graph-memory.mdx
+15 -25
View File
@@ -21,7 +21,7 @@ The Graph Memory feature analyzes how each entity connects and relates to each o
## Using Graph Memory
To use Graph Memory, you need to enable it in your API calls by setting the `enable_graph=True` parameter. You'll also need to specify `output_format="v1.1"` to receive the enriched response format.
To use Graph Memory, you need to enable it in your API calls by setting the `enable_graph=True` parameter.
### Adding Memories with Graph Memory
@@ -46,11 +46,9 @@ messages = [
# Enable graph memory when adding
client.add(
messages,
user_id="joseph",
version="v1",
enable_graph=True,
output_format="v1.1"
messages,
user_id="joseph",
enable_graph=True
)
```
@@ -73,9 +71,7 @@ const messages = [
await client.add({
messages,
user_id: "joseph",
version: "v1",
enable_graph: true,
output_format: "v1.1"
enable_graph: true
});
```
@@ -125,10 +121,9 @@ When searching memories, Graph Memory helps retrieve entities that are contextua
```python Python
# Search with graph memory enabled
results = client.search(
"what is my name?",
user_id="joseph",
enable_graph=True,
output_format="v1.1"
"what is my name?",
user_id="joseph",
enable_graph=True
)
print(results)
@@ -139,8 +134,7 @@ print(results)
const results = await client.search({
query: "what is my name?",
user_id: "joseph",
enable_graph: true,
output_format: "v1.1"
enable_graph: true
});
console.log(results);
@@ -196,9 +190,8 @@ When retrieving all memories, Graph Memory provides additional relationship cont
```python Python
# Get all memories with graph context
memories = client.get_all(
user_id="joseph",
enable_graph=True,
output_format="v1.1"
user_id="joseph",
enable_graph=True
)
print(memories)
@@ -208,8 +201,7 @@ print(memories)
// Get all memories with graph context
const memories = await client.getAll({
user_id: "joseph",
enable_graph: true,
output_format: "v1.1"
enable_graph: true
});
console.log(memories);
@@ -304,8 +296,7 @@ messages = [
client.add(
messages,
user_id="joseph",
output_format="v1.1"
user_id="joseph"
)
```
@@ -319,7 +310,7 @@ const client = new MemoryClient({
});
// Enable graph memory for all operations in this project
await client.updateProject({ enable_graph: true, version: "v1" });
await client.project.update({ enable_graph: true });
// Now all add operations will use graph memory by default
const messages = [
@@ -330,8 +321,7 @@ const messages = [
await client.add({
messages,
user_id: "joseph",
output_format: "v1.1"
user_id: "joseph"
});
```
docs/platform/features/group-chat.mdx
+4 -6
View File
@@ -63,7 +63,6 @@ messages = [
response = client.add(
messages,
run_id="group_chat_1",
output_format="v1.1",
infer=True
)
print(response)
@@ -103,6 +102,7 @@ Retrieve all memories from a specific group chat session:
```python Python
# Get all memories for a specific run_id
# Use wildcard "*" for user_id to match all participants
filters = {
"AND": [
{"user_id": "*"},
@@ -110,7 +110,7 @@ filters = {
]
}
all_memories = client.get_all(version="v2", filters=filters, page=1)
all_memories = client.get_all(filters=filters, page=1)
print(all_memories)
```
@@ -160,7 +160,7 @@ filters = {
]
}
charlie_memories = client.get_all(version="v2", filters=filters, page=1)
charlie_memories = client.get_all(filters=filters, page=1)
print(charlie_memories)
```
@@ -197,8 +197,7 @@ filters = {
search_response = client.search(
query="What are the tasks?",
filters=filters,
version="v2"
filters=filters
)
print(search_response)
```
@@ -229,7 +228,6 @@ Group chat also supports async processing for improved performance:
response = client.add(
messages,
run_id="groupchat_async",
output_format="v1.1",
infer=True,
async_mode=True
)
docs/platform/features/memory-export.mdx
+11 -8
View File
@@ -77,12 +77,13 @@ You can optionally provide additional instructions to guide how memories are pro
```python Python
# Basic export request
filters = {"user_id": "alice"}
response = client.create_memory_export(
schema=json_schema,
user_id="alice"
filters=filters
)
# Export with custom instructions
# Export with custom instructions and additional filters
export_instructions = """
1. Create a comprehensive profile with detailed information in each category
2. Only mark fields as "None" when absolutely no relevant information exists
@@ -91,10 +92,10 @@ export_instructions = """
5. Clearly distinguish between factual statements and inferences
"""
# For create operation, using only user_id filter as requested
filters = {
"AND": [
{"user_id": "alex"}
{"user_id": "alex"},
{"created_at": {"gte": "2024-01-01"}}
]
}
@@ -109,12 +110,13 @@ print(response)
```javascript JavaScript
// Basic Export request
const filters = {"user_id": "alice"};
const response = await client.createMemoryExport({
schema: json_schema,
user_id: "alice"
filters: filters
});
// Export with custom instructions
// Export with custom instructions and additional filters
const export_instructions = `
1. Create a comprehensive profile with detailed information in each category
2. Only mark fields as "None" when absolutely no relevant information exists
@@ -126,7 +128,8 @@ const export_instructions = `
// For create operation, using only user_id filter as requested
const filters = {
"AND": [
{"user_id": "alex"}
{"user_id": "alex"},
{"created_at": {"gte": "2024-01-01"}}
]
}
@@ -145,7 +148,7 @@ curl -X POST "https://api.mem0.ai/v1/memories/export/" \
-H "Content-Type: application/json" \
-d '{
"schema": {json_schema},
"user_id": "alice",
"filters": {"user_id": "alice"},
"export_instructions": "1. Create a comprehensive profile with detailed information\n2. Only mark fields as \"None\" when absolutely no relevant information exists"
}'
```