Important: This page lists all breaking changes. Please review carefully before upgrading.
API Version Changes
Removed v1.0 API Support
Breaking Change: The v1.0 API format is completely removed and no longer supported.
Before (v0.x)
# This was supported in v0.x
config = {
"version": "v1.0" # ❌ No longer supported
}
result = m.add(
"memory content",
user_id="alice",
output_format="v1.0" # ❌ No longer supported
)
After (v1.0.0 Beta)
# v1.1 is the minimum supported version
config = {
"version": "v1.1" # ✅ Required minimum
}
result = m.add(
"memory content",
user_id="alice"
# output_format parameter removed
)
Error Message:
ValueError: The v1.0 API format is no longer supported in mem0ai 1.0.0+.
Please use v1.1 format which returns a dict with 'results' key.
Parameter Removals
Removed from all methods:
Before (v0.x)
result = m.add("content", user_id="alice", output_format="v1.1")
search_results = m.search("query", user_id="alice", output_format="v1.1")
all_memories = m.get_all(user_id="alice", output_format="v1.1")
After (v1.0.0 Beta)
result = m.add("content", user_id="alice")
search_results = m.search("query", user_id="alice")
all_memories = m.get_all(user_id="alice")
2. version Parameter in Method Calls
Breaking Change: Version parameter removed from method calls.
Before (v0.x)
result = m.add("content", user_id="alice", version="v1.0")
After (v1.0.0 Beta)
result = m.add("content", user_id="alice")
3. async_mode Parameter
Breaking Change: Async mode is now default and the parameter is removed.
Before (v0.x)
# Optional async mode
result = m.add("content", user_id="alice", async_mode=True)
result = m.add("content", user_id="alice", async_mode=False) # Sync mode
After (v1.0.0 Beta)
# Always async by design, parameter removed
result = m.add("content", user_id="alice")
# For async operations, use AsyncMemory
from mem0 import AsyncMemory
async_m = AsyncMemory()
result = await async_m.add("content", user_id="alice")
Standardized Response Structure
Breaking Change: All responses now return a standardized dictionary format.
Before (v0.x)
# Could return different formats based on output_format parameter
result = m.add("content", user_id="alice", output_format="v1.0")
# Returns: [{"id": "...", "memory": "...", "event": "ADD"}]
result = m.add("content", user_id="alice", output_format="v1.1")
# Returns: {"results": [{"id": "...", "memory": "...", "event": "ADD"}]}
After (v1.0.0 Beta)
# Always returns standardized format
result = m.add("content", user_id="alice")
# Always returns: {"results": [{"id": "...", "memory": "...", "event": "ADD"}]}
# Access results consistently
for memory in result["results"]:
print(memory["memory"])
Configuration Changes
Version Configuration
Breaking Change: Default API version changed.
Before (v0.x)
# v1.0 was supported
config = {
"version": "v1.0" # ❌ No longer supported
}
After (v1.0.0 Beta)
# v1.1 is minimum, v1.1 is default
config = {
"version": "v1.1" # ✅ Minimum supported
}
# Or omit for default
config = {
# version defaults to v1.1
}
Memory Configuration
Breaking Change: Some configuration options have changed defaults.
Before (v0.x)
from mem0 import Memory
# Default configuration in v0.x
m = Memory() # Used default settings suitable for v0.x
After (v1.0.0 Beta)
from mem0 import Memory
# Default configuration optimized for v1.0.0 Beta
m = Memory() # Uses v1.1+ optimized defaults
# Explicit configuration recommended
config = {
"version": "v1.1",
"vector_store": {
"provider": "qdrant",
"config": {
"host": "localhost",
"port": 6333
}
}
}
m = Memory.from_config(config)
Method Signature Changes
Search Method
Enhanced but backward compatible:
Before (v0.x)
results = m.search(
"query",
user_id="alice",
filters={"key": "value"} # Simple key-value only
)
After (v1.0.0 Beta)
# Basic usage remains the same
results = m.search("query", user_id="alice")
# Enhanced filtering available (optional)
results = m.search(
"query",
user_id="alice",
filters={
"AND": [
{"key": "value"},
{"score": {"gte": 0.8}}
]
},
rerank=True # New parameter
)
Error Handling Changes
New Error Types
Breaking Change: More specific error types and messages.
Before (v0.x)
try:
result = m.add("content", user_id="alice", version="v1.0")
except Exception as e:
print(f"Generic error: {e}")
After (v1.0.0 Beta)
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 error specifically
print("Please upgrade your code to use v1.1+ format")
else:
print(f"Value error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
Validation Changes
Breaking Change: Stricter parameter validation.
Before (v0.x)
# Some invalid parameters might have been ignored
result = m.add(
"content",
user_id="alice",
invalid_param="ignored" # Might have been silently ignored
)
After (v1.0.0 Beta)
# Strict validation - unknown parameters cause errors
try:
result = m.add(
"content",
user_id="alice",
invalid_param="value" # ❌ Will raise TypeError
)
except TypeError as e:
print(f"Invalid parameter: {e}")
Import Changes
No Breaking Changes in Imports
Good News: Import statements remain the same.
# These imports work in both v0.x and v1.0.0 Beta
from mem0 import Memory, AsyncMemory
from mem0 import MemoryConfig
Dependency Changes
Minimum Python Version
Potential Breaking Change: Check Python version requirements.
Before (v0.x)
After (v1.0.0 Beta)
- Python 3.9+ required (check current requirements)
Package Dependencies
Breaking Change: Some dependencies updated with potential breaking changes.
# Check for conflicts after upgrade
pip install --upgrade mem0ai
pip check # Verify no dependency conflicts
Data Migration
Database Schema
Good News: No database schema changes required.
- Existing memories remain compatible
- No data migration required
- Vector store data unchanged
Good News: Memory storage format unchanged.
- Existing memories work with v1.0.0 Beta
- Search continues to work with old memories
- No re-indexing required
Testing Changes
Test Updates Required
Breaking Change: Update tests for new response format.
Before (v0.x)
def test_add_memory():
result = m.add("content", user_id="alice")
assert isinstance(result, list) # ❌ No longer true
assert len(result) > 0
After (v1.0.0 Beta)
def test_add_memory():
result = m.add("content", user_id="alice")
assert isinstance(result, dict) # ✅ Always dict
assert "results" in result # ✅ Always has results key
assert len(result["results"]) > 0
Rollback Considerations
Safe Rollback Process
If you need to rollback:
# 1. Rollback package
pip install mem0ai==0.1.20 # Last stable v0.x
# 2. Revert code changes
git checkout previous_commit
# 3. Test functionality
python test_mem0_functionality.py
Data Safety
- Safe: Memories stored in v0.x format work with v1.0.0 Beta
- Safe: Rollback doesn’t lose data
- Safe: Vector store data remains intact
Next Steps
- Review all breaking changes in your codebase
- Update method calls to remove deprecated parameters
- Update response handling to use standardized format
- Test thoroughly with your existing data
- Update error handling for new error types
Need Help? If you encounter issues during migration, check our GitHub Discussions or community support channels.