Breaking Changes Ahead! Mem0 1.0.0 Beta introduces several breaking changes. Please read this guide carefully before upgrading.
Overview
Mem0 1.0.0 Beta is a major release that modernizes the API, improves performance, and adds powerful new features. This guide will help you migrate your existing v0.x implementation to the new version.
Key Changes Summary
Feature | v0.x | v1.0.0 Beta | Migration Required |
---|
API Version | v1.0 supported | v1.0 removed, v1.1+ only | ✅ Yes |
Async Mode | Optional | Default and required | ✅ Yes |
Output Format Parameter | Supported | Removed | ✅ Yes |
Response Format | Mixed | Standardized {"results": [...]} | ✅ Yes |
Metadata Filtering | Basic | Enhanced with operators | ⚠️ Optional |
Reranking | Not available | Full support | ⚠️ Optional |
Step-by-Step Migration
1. Update Installation
# Update to the latest version
pip install --upgrade mem0ai
2. Remove Deprecated Parameters
Before (v0.x)
from mem0 import Memory
# These parameters are no longer supported
m = Memory()
result = m.add(
"I love pizza",
user_id="alice",
output_format="v1.0", # ❌ REMOVED
version="v1.0" # ❌ REMOVED
)
After (v1.0.0 Beta)
from mem0 import Memory
# Clean, simplified API
m = Memory()
result = m.add(
"I love pizza",
user_id="alice"
# output_format and version parameters removed
)
3. Update Configuration
Before (v0.x)
config = {
"vector_store": {
"provider": "qdrant",
"config": {
"host": "localhost",
"port": 6333
}
},
"version": "v1.0" # ❌ No longer supported
}
m = Memory.from_config(config)
After (v1.0.0 Beta)
config = {
"vector_store": {
"provider": "qdrant",
"config": {
"host": "localhost",
"port": 6333
}
},
"version": "v1.1" # ✅ v1.1 is the minimum supported version
}
m = Memory.from_config(config)
Before (v0.x)
# Response could be a list or dict depending on version
result = m.add("I love coffee", user_id="alice")
if isinstance(result, list):
# Handle list format
for item in result:
print(item["memory"])
else:
# Handle dict format
print(result["results"])
After (v1.0.0 Beta)
# Response is always a standardized dict with "results" key
result = m.add("I love coffee", user_id="alice")
# Always access via "results" key
for item in result["results"]:
print(item["memory"])
5. Update Search Operations
Before (v0.x)
# Basic search
results = m.search("What do I like?", user_id="alice")
# With filters
results = m.search(
"What do I like?",
user_id="alice",
filters={"category": "food"}
)
After (v1.0.0 Beta)
# Same basic search API
results = m.search("What do I like?", user_id="alice")
# Enhanced filtering with operators (optional upgrade)
results = m.search(
"What do I like?",
user_id="alice",
filters={
"AND": [
{"category": "food"},
{"rating": {"gte": 8}}
]
}
)
# New: Reranking support (optional)
results = m.search(
"What do I like?",
user_id="alice",
rerank=True # Requires reranker configuration
)
6. Migrate Async Operations
Before (v0.x)
from mem0 import AsyncMemory
# Async was optional
async_memory = AsyncMemory()
async def add_memory():
result = await async_memory.add(
"I enjoy hiking",
user_id="alice",
async_mode=True # ❌ Parameter removed
)
return result
After (v1.0.0 Beta)
from mem0 import AsyncMemory
# Async is the default mode
async_memory = AsyncMemory()
async def add_memory():
result = await async_memory.add(
"I enjoy hiking",
user_id="alice"
# async_mode parameter removed - always async
)
return result
Configuration Migration
Basic Configuration
Before (v0.x)
config = {
"vector_store": {
"provider": "qdrant",
"config": {
"host": "localhost",
"port": 6333
}
},
"llm": {
"provider": "openai",
"config": {
"model": "gpt-3.5-turbo",
"api_key": "your-key"
}
},
"version": "v1.0"
}
After (v1.0.0 Beta)
config = {
"vector_store": {
"provider": "qdrant",
"config": {
"host": "localhost",
"port": 6333
}
},
"llm": {
"provider": "openai",
"config": {
"model": "gpt-3.5-turbo",
"api_key": "your-key"
}
},
"version": "v1.1", # Minimum supported version
# New optional features
"reranker": {
"provider": "cohere",
"config": {
"model": "rerank-english-v3.0",
"api_key": "your-cohere-key"
}
}
}
Enhanced Features (Optional)
# Take advantage of new features
config = {
"vector_store": {
"provider": "qdrant",
"config": {
"host": "localhost",
"port": 6333
}
},
"llm": {
"provider": "openai",
"config": {
"model": "gpt-4",
"api_key": "your-key"
}
},
"embedder": {
"provider": "openai",
"config": {
"model": "text-embedding-3-small",
"api_key": "your-key"
}
},
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
}
},
"version": "v1.1"
}
Error Handling Migration
Before (v0.x)
try:
result = m.add("memory", user_id="alice", version="v1.0")
except Exception as e:
print(f"Error: {e}")
After (v1.0.0 Beta)
try:
result = m.add("memory", user_id="alice")
except ValueError as e:
if "v1.0 API format is no longer supported" in str(e):
print("Please upgrade your code to use v1.1+ format")
else:
print(f"Error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
Testing Your Migration
1. Basic Functionality Test
def test_basic_functionality():
m = Memory()
# Test add
result = m.add("I love testing", user_id="test_user")
assert "results" in result
assert len(result["results"]) > 0
# Test search
search_results = m.search("testing", user_id="test_user")
assert "results" in search_results
# Test get_all
all_memories = m.get_all(user_id="test_user")
assert "results" in all_memories
print("✅ Basic functionality test passed")
test_basic_functionality()
2. Enhanced Features Test
def test_enhanced_features():
config = {
"reranker": {
"provider": "sentence_transformer",
"config": {
"model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
}
}
}
m = Memory.from_config(config)
# Test reranking
m.add("I love advanced features", user_id="test_user")
results = m.search("features", user_id="test_user", rerank=True)
assert "results" in results
# Test enhanced filtering
results = m.search(
"features",
user_id="test_user",
filters={"user_id": {"eq": "test_user"}}
)
assert "results" in results
print("✅ Enhanced features test passed")
test_enhanced_features()
Common Migration Issues
Issue 1: Version Error
Error:
ValueError: The v1.0 API format is no longer supported in mem0ai 1.0.0+
Solution:
# Remove version parameters or set to v1.1+
config = {
# ... other config
"version": "v1.1" # or remove entirely for default
}
Error:
Solution:
# Always access response via "results" key
result = m.add("memory", user_id="alice")
memories = result["results"] # Not result directly
Issue 3: Parameter Error
Error:
TypeError: add() got an unexpected keyword argument 'output_format'
Solution:
# Remove deprecated parameters
result = m.add(
"memory",
user_id="alice"
# Remove: output_format, version, async_mode
)
Rollback Plan
If you encounter issues during migration:
# Downgrade to last v0.x version
pip install mem0ai==0.1.20 # Replace with your last working version
2. Gradual Migration
# Test both versions side by side
import mem0_v0 # Your old version
import mem0 # New version
def compare_results(query, user_id):
old_results = mem0_v0.search(query, user_id=user_id)
new_results = mem0.search(query, user_id=user_id)
print("Old format:", old_results)
print("New format:", new_results["results"])
Before (v0.x)
# Sequential operations
result1 = m.add("memory 1", user_id="alice")
result2 = m.add("memory 2", user_id="alice")
result3 = m.search("query", user_id="alice")
After (v1.0.0 Beta)
# Better async performance
async def batch_operations():
async_memory = AsyncMemory()
# Concurrent operations
results = await asyncio.gather(
async_memory.add("memory 1", user_id="alice"),
async_memory.add("memory 2", user_id="alice"),
async_memory.search("query", user_id="alice")
)
return results
Next Steps
- Complete the migration using this guide
- Test thoroughly with your existing data
- Explore new features like enhanced filtering and reranking
- Update your documentation to reflect the new API
- Monitor performance and optimize as needed
Need help with migration? Check our GitHub Discussions or reach out to our community for support.