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

Merge remote-tracking branch 'origin/main' into docs/stale-migration

Browse Source 
# Conflicts:
#	docs/migration/api-changes.mdx
This commit is contained in:
kartik-mem0
2026-06-27 13:10:29 +05:30
parent dc857e43ca 7e7682a06d
commit d5b04e70fa
100 changed files with 2287 additions and 1204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/migration/api-changes.mdx
-564
View File
@@ -1,564 +0,0 @@
---
title: API Reference Changes
description: "Comprehensive reference of all API changes between Mem0 v0.x and v1.0.0 Beta, organized by component and method."
icon: "code"
iconType: "solid"
---
## Overview
This page documents all API changes between Mem0 v0.x and v1.0.0 Beta, organized by component and method.
## Memory Class Changes
### Constructor
#### v0.x
```python
from mem0 import Memory
# Basic initialization
m = Memory()
# With configuration
config = {
"version": "v1.0", # Supported in v0.x
"vector_store": {...}
}
m = Memory.from_config(config)
```
#### v1.0.0
```python
from mem0 import Memory
# Basic initialization (same)
m = Memory()
# With configuration
config = {
"version": "v1.1", # v1.1+ only
"vector_store": {...},
# New optional features
"reranker": {
"provider": "cohere",
"config": {...}
}
}
m = Memory.from_config(config)
```
### add() Method
#### v0.x Signature
```python
def add(
self,
messages,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
metadata: dict = None,
filters: dict = None,
output_format: str = None, # ❌ REMOVED
version: str = None # ❌ REMOVED
) -> Union[List[dict], dict]:
...
```
#### v1.0.0 Signature
```python
def add(
self,
messages,
*,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
metadata: dict = None,
infer: bool = True, # ✅ NEW: Control memory inference
memory_type: str = None, # ✅ NEW: e.g. "procedural_memory"
prompt: str = None # ✅ NEW: Custom extraction prompt
) -> dict: # Always returns dict with "results" key
...
```
#### Changes Summary
| Parameter | v0.x | v1.0.0 | Change |
|-----------|------|-----------|---------|
| `messages` | ✅ | ✅ | Unchanged |
| `user_id` | ✅ | ✅ | Unchanged |
| `agent_id` | ✅ | ✅ | Unchanged |
| `run_id` | ✅ | ✅ | Unchanged |
| `metadata` | ✅ | ✅ | Unchanged |
| `filters` | ✅ | ❌ | **REMOVED** — `add()` does not accept `filters` |
| `output_format` | ✅ | ❌ | **REMOVED** |
| `version` | ✅ | ❌ | **REMOVED** |
| `infer` | ❌ | ✅ | **NEW** |
| `memory_type` | ❌ | ✅ | **NEW** |
| `prompt` | ❌ | ✅ | **NEW** |
#### Response Format Changes
**v0.x Response (variable format):**
```python
# With output_format="v1.0"
[
{
"id": "mem_123",
"memory": "User loves pizza",
"event": "ADD"
}
]
# With output_format="v1.1"
{
"results": [
{
"id": "mem_123",
"memory": "User loves pizza",
"event": "ADD"
}
]
}
```
**v1.0.0 Response (standardized):**
```python
# Always returns this format
{
"results": [
{
"id": "mem_123",
"memory": "User loves pizza",
"metadata": {...},
"event": "ADD"
}
]
}
```
### search() Method
#### v0.x Signature
```python
def search(
self,
query: str,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
limit: int = 100,
filters: dict = None, # Basic key-value only
output_format: str = None, # ❌ REMOVED
version: str = None # ❌ REMOVED
) -> Union[List[dict], dict]:
...
```
#### v1.0.0 Signature
```python
def search(
self,
query: str,
*,
top_k: int = 20, # ✅ Renamed from limit
filters: dict = None, # ✅ ENHANCED: Advanced operators; must include user_id/agent_id/run_id
threshold: float = 0.1, # ✅ NEW: Minimum score cutoff
rerank: bool = False # ✅ NEW: Reranking support (default False)
) -> dict: # Always returns dict with "results" key
...
```
<Warning>
`user_id`, `agent_id`, and `run_id` are **not** top-level parameters in v1. They must be passed inside `filters`. Example: `m.search("query", filters={"user_id": "alice"})`.
</Warning>
#### Enhanced Filtering
**v0.x Filters (basic):**
```python
# Simple key-value filtering only
filters = {
"category": "food",
"user_id": "alice"
}
```
**v1.0.0 Filters (enhanced):**
```python
# Advanced filtering with operators
filters = {
"AND": [
{"category": "food"},
{"score": {"gte": 0.8}},
{
"OR": [
{"priority": "high"},
{"urgent": True}
]
}
]
}
# Comparison operators
filters = {
"score": {"gt": 0.5}, # Greater than
"priority": {"gte": 5}, # Greater than or equal
"rating": {"lt": 3}, # Less than
"confidence": {"lte": 0.9}, # Less than or equal
"status": {"eq": "active"}, # Equal
"archived": {"ne": True}, # Not equal
"tags": {"in": ["work", "personal"]}, # In list
"category": {"nin": ["spam", "deleted"]} # Not in list
}
```
### get_all() Method
#### v0.x Signature
```python
def get_all(
self,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
filters: dict = None,
output_format: str = None, # ❌ REMOVED
version: str = None # ❌ REMOVED
) -> Union[List[dict], dict]:
...
```
#### v1.0.0 Signature
```python
def get_all(
self,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
filters: dict = None # ✅ ENHANCED: Advanced operators
) -> dict: # Always returns dict with "results" key
...
```
### update() Method
#### No Breaking Changes
```python
# Same signature in both versions
def update(
self,
memory_id: str,
data: str
) -> dict:
...
```
### delete() Method
#### No Breaking Changes
```python
# Same signature in both versions
def delete(
self,
memory_id: str
) -> dict:
...
```
### delete_all() Method
#### Breaking Change — Empty filter no longer silently deletes everything
**Before:** calling `delete_all()` with no filters silently deleted **all memories in the project**.
**After:**
- No filters → raises a validation error (prevents accidental full-project wipe).
- Concrete ID (e.g. `user_id="alice"`) → deletes memories for that entity (unchanged).
- `"*"` for a filter → deletes all memories for that entity type across the project (new).
- All four filters set to `"*"` → explicit full project wipe (new, requires opt-in on every parameter).
This change replaces the silent full-project delete (triggered by an empty or missing filter) with a validation error, and introduces `"*"` wildcards as the intentional path for bulk deletion.
```python
# v0.x — no filter silently wiped all project memories
m.delete_all() # DANGER: deleted everything
m.delete_all(user_id="alice") # deleted alice's memories
# v1.x — no filter now raises an error; use "*" for intentional bulk deletes
m.delete_all() # ERROR: at least one filter required
m.delete_all(user_id="alice") # unchanged
m.delete_all(user_id="*") # NEW — delete all users' memories
m.delete_all(user_id="*", agent_id="*", app_id="*", run_id="*") # NEW — full project wipe
```
## Platform Client (MemoryClient) Changes
### async_mode Removed
<Note>
`async_mode` was removed in v3. Remove any `async_mode=` argument from your `MemoryClient` calls.
</Note>
## Configuration Changes
### Memory Configuration
#### v0.x Config Options
```python
config = {
"vector_store": {...},
"llm": {...},
"embedder": {...},
"version": "v1.0", # ❌ v1.0 no longer supported
"history_db_path": "...",
"custom_instructions": "..."
}
```
#### v1.0.0 Config Options
```python
config = {
"vector_store": {...},
"llm": {...},
"embedder": {...},
"reranker": { # ✅ NEW: Reranker support
"provider": "cohere",
"config": {...}
},
"version": "v1.1", # ✅ v1.1+ only
"history_db_path": "...",
"custom_instructions": "..." # ✅ Use this for custom extraction instructions
}
```
<Note>
`graph_store` is no longer a top-level `MemoryConfig` field. Graph support is configured separately.
`custom_update_memory_prompt` has been removed — use `custom_instructions` instead.
</Note>
### New Configuration Options
#### Reranker Configuration
```text
# Cohere reranker
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"api_key": "your-api-key",
"top_k": 10
}
}
# Sentence Transformer reranker
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2",
"device": "cuda"
}
}
# Hugging Face reranker
"reranker": {
"provider": "huggingface",
"config": {
"model": "BAAI/bge-reranker-base",
"device": "cuda"
}
}
# LLM-based reranker
"reranker": {
"provider": "llm_reranker",
"config": {
"llm": {
"provider": "openai",
"config": {
"model": "gpt-4",
"api_key": "your-api-key"
}
}
}
}
```
## Error Handling Changes
### New Error Types
#### v0.x Errors
```python
# Generic exceptions
try:
result = m.add("content", user_id="alice", version="v1.0")
except Exception as e:
print(f"Error: {e}")
```
#### v1.0.0 Errors
```python
# More specific error handling
try:
result = m.add("content", user_id="alice")
except ValueError as e:
if "v1.0 API format is no longer supported" in str(e):
# Handle version compatibility error
pass
elif "Invalid filter operator" in str(e):
# Handle filter syntax error
pass
except TypeError as e:
# Handle parameter errors
pass
except Exception as e:
# Handle unexpected errors
pass
```
### Validation Changes
#### Stricter Parameter Validation
**v0.x (Lenient):**
```python
# Unknown parameters might be ignored
result = m.add("content", user_id="alice", unknown_param="value")
```
**v1.0.0 (Strict):**
```python
# Unknown parameters raise TypeError
try:
result = m.add("content", user_id="alice", unknown_param="value")
except TypeError as e:
print(f"Invalid parameter: {e}")
```
## Response Schema Changes
### Memory Object Schema
#### v0.x Schema
```python
{
"id": "mem_123",
"memory": "User loves pizza",
"user_id": "alice",
"metadata": {...},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"score": 0.95 # In search results
}
```
#### v1.0.0 Schema (Enhanced)
```python
{
"id": "mem_123",
"memory": "User loves pizza",
"user_id": "alice",
"agent_id": "assistant", # ✅ More context
"run_id": "session_001", # ✅ More context
"metadata": {...},
"categories": ["food"], # ✅ NEW: Auto-categorization
"immutable": false, # ✅ NEW: Immutability flag
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"score": 0.95, # In search results
"rerank_score": 0.98 # ✅ NEW: If reranking used
}
```
## Migration Code Examples
### Simple Migration
#### Before (v0.x)
```python
from mem0 import Memory
m = Memory()
# Add with deprecated parameters
result = m.add(
"I love pizza",
user_id="alice",
output_format="v1.1",
version="v1.0"
)
# Handle variable response format
if isinstance(result, list):
memories = result
else:
memories = result.get("results", [])
for memory in memories:
print(memory["memory"])
```
#### After (v1.0.0 )
```python
from mem0 import Memory
m = Memory()
# Add without deprecated parameters
result = m.add(
"I love pizza",
user_id="alice"
)
# Always dict format with "results" key
for memory in result["results"]:
print(memory["memory"])
```
### Advanced Migration
#### Before (v0.x)
```python
# Basic filtering
results = m.search(
"food preferences",
user_id="alice",
filters={"category": "food"},
output_format="v1.1"
)
```
#### After (v1.0.0 )
```python
# Enhanced filtering with reranking
results = m.search(
"food preferences",
user_id="alice",
filters={
"AND": [
{"category": "food"},
{"score": {"gte": 0.8}}
]
},
rerank=True
)
```
## Summary
| Component | v0.x | v1.0.0 | Status |
|-----------|------|-----------|---------|
| `add()` method | Variable response | Standardized response | ⚠️ Breaking |
| `search()` method | Basic filtering | Enhanced filtering + reranking | ⚠️ Breaking |
| `get_all()` method | Variable response | Standardized response | ⚠️ Breaking |
| Response format | Variable | Always `{"results": [...]}` | ⚠️ Breaking |
| Reranking | ❌ Not available | ✅ Full support | ✅ New feature |
| Advanced filtering | ❌ Basic only | ✅ Full operators | ✅ Enhancement |
| Error handling | Generic | Specific error types | ✅ Improvement |
<Info>
Use this reference to systematically update your codebase. Test each change thoroughly before deploying to production.
</Info>
docs/migration/oss-v2-to-v3.mdx
+4 -4
View File
@@ -62,7 +62,7 @@ These changes produce a **+20 point improvement on LoCoMo** (71.4 → 91.6) and
|---|---|---|---|
| Constructor | `MemoryClient(api_key, org_id, project_id)` | `MemoryClient(api_key)` | Remove `org_id`, `project_id` from constructor |
| Method options | `client.add(messages, **kwargs)` | `client.add(messages, options=AddMemoryOptions(...))` | Use typed option classes (or `**kwargs` still works) |
| Removed params | `api_version`, `output_format`, `async_mode`, `filter_memories`, `expiration_date`, `keyword_search`, `force_add_only`, `batch_size`, `immutable`, `includes`, `excludes`, `enable_graph`, `org_name`, `project_name` | — | Remove from all calls |
| Removed params | `api_version`, `output_format`, `async_mode`, `filter_memories`, `keyword_search`, `force_add_only`, `batch_size`, `immutable`, `includes`, `excludes`, `enable_graph`, `org_name`, `project_name` | — | Remove from all calls |
### TypeScript Client SDK
@@ -70,7 +70,7 @@ These changes produce a **+20 point improvement on LoCoMo** (71.4 → 91.6) and
|---|---|---|---|
| Constructor | `new MemoryClient({ apiKey, organizationId, projectId })` | `new MemoryClient({ apiKey })` | Remove `organizationId`, `projectId`, `organizationName`, `projectName` |
| All params | snake_case: `user_id`, `agent_id`, `top_k` | camelCase: `userId`, `agentId`, `topK` | Rename all params to camelCase |
| Removed params | `api_version`, `output_format`, `async_mode`, `enable_graph`, `org_id`, `project_id`, `org_name`, `project_name`, `filter_memories`, `batch_size`, `force_add_only`, `immutable`, `expiration_date`, `includes`, `excludes`, `keyword_search` | — | Remove from all calls |
| Removed params | `api_version`, `output_format`, `async_mode`, `enable_graph`, `org_id`, `project_id`, `org_name`, `project_name`, `filter_memories`, `batch_size`, `force_add_only`, `immutable`, `includes`, `excludes`, `keyword_search` | — | Remove from all calls |
| Output format enum | `OutputFormat.V1`, `OutputFormat.V1_1` | Removed | v1.1 is now always used |
| API version enum | `API_VERSION.V1`, `API_VERSION.V2` | Removed | Handled internally |
@@ -423,7 +423,7 @@ These parameters have been removed across all SDKs. Remove them from your code:
**All methods:** `api_version`, `output_format`, `async_mode`, `org_name`, `project_name`, `org_id`, `project_id`
**add():** `enable_graph`, `immutable`, `expiration_date`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`
**add():** `enable_graph`, `immutable`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`
**search():** `enable_graph`
@@ -437,7 +437,7 @@ These parameters have been removed across all SDKs. Remove them from your code:
**All methods:** `OutputFormat` enum, `API_VERSION` enum
**add():** `enable_graph` / `enableGraph`, `async_mode` / `asyncMode`, `output_format` / `outputFormat`, `immutable`, `expiration_date` / `expirationDate`, `filter_memories` / `filterMemories`, `batch_size` / `batchSize`, `force_add_only` / `forceAddOnly`, `includes`, `excludes`, `keyword_search` / `keywordSearch`
**add():** `enable_graph` / `enableGraph`, `async_mode` / `asyncMode`, `output_format` / `outputFormat`, `immutable`, `filter_memories` / `filterMemories`, `batch_size` / `batchSize`, `force_add_only` / `forceAddOnly`, `includes`, `excludes`, `keyword_search` / `keywordSearch`
**search():** `enable_graph` / `enableGraph`
docs/migration/platform-v2-to-v3.mdx
+2 -2
View File
@@ -215,7 +215,7 @@ client.add(messages, user_id="alice")
# async_mode and output_format removed (async by default, v1.1 always)
```
**Removed parameters:** `org_id`, `project_id`, `api_version`, `output_format`, `async_mode`, `enable_graph`, `immutable`, `expiration_date`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`, `org_name`, `project_name`
**Removed parameters:** `org_id`, `project_id`, `api_version`, `output_format`, `async_mode`, `enable_graph`, `immutable`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`, `org_name`, `project_name`
### TypeScript Client SDK
@@ -242,7 +242,7 @@ await client.search("query", {
});
```
**Removed:** `OutputFormat` enum, `API_VERSION` enum, `organizationId`, `projectId`, `organizationName`, `projectName`, `enableGraph`, `asyncMode`, `outputFormat`, `immutable`, `expirationDate`, `filterMemories`, `batchSize`, `forceAddOnly`, `includes`, `excludes`, `keywordSearch`
**Removed:** `OutputFormat` enum, `API_VERSION` enum, `organizationId`, `projectId`, `organizationName`, `projectName`, `enableGraph`, `asyncMode`, `outputFormat`, `immutable`, `filterMemories`, `batchSize`, `forceAddOnly`, `includes`, `excludes`, `keywordSearch`
<Info>
For the full list of parameter changes across all SDKs, see the [OSS migration guide](/migration/oss-v2-to-v3#removed-parameters-reference).