Documentation Index
Fetch the complete documentation index at: https://docs.mem0.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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
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
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
def add(
self,
messages,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
metadata: dict = None,
filters: dict = None,
infer: bool = True # ✅ NEW: Control memory inference
) -> 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 | ✅ | ✅ | Unchanged |
output_format | ✅ | ❌ | REMOVED |
version | ✅ | ❌ | REMOVED |
infer | ❌ | ✅ | NEW |
# 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"
}
]
}
# Always returns this format
{
"results": [
{
"id": "mem_123",
"memory": "User loves pizza",
"metadata": {...},
"event": "ADD"
}
]
}
search() Method
v0.x Signature
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
def search(
self,
query: str,
user_id: str = None,
agent_id: str = None,
run_id: str = None,
limit: int = 100,
filters: dict = None, # ✅ ENHANCED: Advanced operators
rerank: bool = True # ✅ NEW: Reranking support
) -> dict # Always returns dict with "results" key
Enhanced Filtering
v0.x Filters (basic):
# Simple key-value filtering only
filters = {
"category": "food",
"user_id": "alice"
}
# 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
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
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
# Same signature in both versions
def update(
self,
memory_id: str,
data: str
) -> dict
delete() Method
No Breaking Changes
# 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.
# 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
async_mode Default Changed
v0.x
from mem0 import MemoryClient
client = MemoryClient(api_key="your-key")
# async_mode had to be explicitly set or had different default
result = client.add("content", user_id="alice", async_mode=True)
v1.0.0
from mem0 import MemoryClient
client = MemoryClient(api_key="your-key")
# async_mode defaults to True now (better performance)
result = client.add("content", user_id="alice") # Uses async_mode=True by default
# Can still override if needed
result = client.add("content", user_id="alice", async_mode=False)
Configuration Changes
Memory Configuration
v0.x Config Options
config = {
"vector_store": {...},
"llm": {...},
"embedder": {...},
"graph_store": {...},
"version": "v1.0", # ❌ v1.0 no longer supported
"history_db_path": "...",
"custom_instructions": "..."
}
v1.0.0 Config Options
config = {
"vector_store": {...},
"llm": {...},
"embedder": {...},
"graph_store": {...},
"reranker": { # ✅ NEW: Reranker support
"provider": "cohere",
"config": {...}
},
"version": "v1.1", # ✅ v1.1+ only
"history_db_path": "...",
"custom_instructions": "...",
"custom_update_memory_prompt": "..." # ✅ NEW: Custom update prompt
}
New Configuration Options
Reranker Configuration
# 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
# 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
# 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):
# Unknown parameters might be ignored
result = m.add("content", user_id="alice", unknown_param="value")
# 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
{
"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)
{
"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)
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 )
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)
# Basic filtering
results = m.search(
"food preferences",
user_id="alice",
filters={"category": "food"},
output_format="v1.1"
)
After (v1.0.0 )
# 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 |
Use this reference to systematically update your codebase. Test each change thoroughly before deploying to production.
