mem0/MIGRATION_GUIDE_v1.0.md

Migration Guide: Upgrading to mem0ai 1.0.0

This guide will help you migrate from mem0ai 0.x to the new 1.0.0 version.

Breaking Changes

1. API Version Changes

Before (0.x):

# Multiple API versions supported
memory = Memory(config=MemoryConfig(version="v1.1"))

# Client with output_format parameter
client.add(messages, output_format="v1.1")
client.search(query, version="v1", output_format="v1.1") 
client.get_all(version="v1", output_format="v1.1")

After (1.0.0):

# v1.1 format is default (v1.0 is deprecated)
memory = Memory()  # Defaults to v1.1 format

# Client API with correct versioning behavior:
client.add(messages)  # Uses v1 API endpoint, returns v1.1 format
client.search(query)  # Uses v2 API endpoint, returns v1.1 format  
client.get_all()  # Uses v2 API endpoint, returns v1.1 format

2. API Versioning Strategy Clarification

IMPORTANT: Understanding the New Versioning Strategy

The API versioning strategy in mem0ai 1.0.0 has been unified and simplified:

Endpoint vs Format Distinction

• API Endpoints (/v1/, /v2/): Control which REST API version to use
• Response Formats (v1.0, v1.1): Control the structure of the returned data

New Unified Strategy:

• Add operations: Always use /v1/ endpoint with v1.1 response format (no more output_format parameter)
• Search operations: Always use /v2/ endpoint with v1.1 response format
• Get_all operations: Always use /v2/ endpoint with v1.1 response format
• Response format: All operations now return v1.1 format ({"results": [...]})

What Changed:

• ✅ Consistent response format: Everything returns v1.1 format
• ✅ Simplified API: No more output_format or version parameters to manage
• ✅ Endpoint optimization: Add uses v1, Search/Get use v2 for best performance
• ❌ Removed v1.0 support: v1.0 response format is no longer supported

3. Response Format Standardization

Before (0.x):

# Inconsistent response formats based on api_version
result = memory.add(messages)
# Could return list or dict depending on version

memories = memory.get_all()  
# Could return list or dict depending on version

After (1.0.0):

# v1.1 format is now default (consistent dict format)
result = memory.add(messages)
# Returns: {"results": [...], "relations": [...] (if graph enabled)}

memories = memory.get_all()
# Returns: {"results": [...], "relations": [...] (if graph enabled)}

# v1.0 format still works but shows deprecation warning
memory_v1 = Memory(config=MemoryConfig(version="v1.0"))
result = memory_v1.add(messages)  # Returns raw list [{...}] (with warning)

Migration Steps

Step 1: Update Dependencies

pip install mem0ai==1.0.0

Step 2: Update Code

Memory API Changes

# Before
from mem0 import Memory

memory = Memory(config=MemoryConfig(version="v1.1"))

# After - no changes needed, v1.1 is automatic
from mem0 import Memory

memory = Memory()  # Defaults to v1.1 format

Client API Changes

# Before
from mem0 import MemoryClient

client = MemoryClient(api_key="your-key")

# Remove all version and output_format parameters
result = client.add(messages, output_format="v1.1")
memories = client.search(query, version="v2", output_format="v1.1")
all_memories = client.get_all(version="v2", output_format="v1.1")

# After
from mem0 import MemoryClient

client = MemoryClient(api_key="your-key")

# Simplified API calls
result = client.add(messages)
memories = client.search(query)
all_memories = client.get_all()

Response Handling

# Before - inconsistent response formats
result = memory.add(messages)
if isinstance(result, list):
    # Handle v1.0 format
    for item in result:
        print(item)
else:
    # Handle v1.1+ format
    for item in result["results"]:
        print(item)

# After - consistent response format
result = memory.add(messages)
for item in result["results"]:
    print(item)

# Access graph relations if enabled
if "relations" in result:
    for relation in result["relations"]:
        print(relation)

Step 3: Remove Deprecated Code

Remove any code that handled multiple API versions:

# Remove these patterns
if version == "v1.0":
    # handle old format
elif version == "v1.1":
    # handle new format

# Remove version-specific logic
def handle_response(response, api_version):
    if api_version == "v1.0":
        return response  # list format
    else:
        return response["results"]  # dict format

Step 4: Update Configuration

Vector Store Configuration

# Before - version in config
config = MemoryConfig(
    version="v1.1",
    vector_store=VectorStoreConfig(...)
)

# After - no version needed
config = MemoryConfig(
    vector_store=VectorStoreConfig(...)
)

Enhanced GCP Support

# New: Enhanced Vertex AI configuration options
from mem0.configs.vector_stores.vertex_ai_vector_search import GoogleMatchingEngineConfig

# Option 1: Using credentials file (existing)
config = GoogleMatchingEngineConfig(
    project_id="your-project",
    credentials_path="/path/to/service-account.json",
    # ... other params
)

# Option 2: Using credentials dict (new in v1.0.0)
service_account_info = {
    "type": "service_account",
    "project_id": "your-project",
    # ... rest of service account JSON
}

config = GoogleMatchingEngineConfig(
    project_id="your-project",
    service_account_json=service_account_info,
    # ... other params
)

Testing Your Migration

1. Test Basic Functionality

from mem0 import Memory

# Test memory operations
memory = Memory()

# Test adding memories
result = memory.add("I like pizza")
assert "results" in result
assert len(result["results"]) > 0

# Test searching
search_result = memory.search("food preferences", user_id="test_user")
assert "results" in search_result

# Test listing all
all_memories = memory.get_all(user_id="test_user")
assert "results" in all_memories

2. Test Client Operations

from mem0 import MemoryClient

client = MemoryClient(api_key="your-api-key")

# Test all client methods work without deprecated parameters
messages = [{"role": "user", "content": "I love traveling"}]
result = client.add(messages, user_id="test_user")
assert "results" in result or isinstance(result, list)  # Platform may vary

memories = client.search("travel", user_id="test_user")
all_memories = client.get_all(user_id="test_user")

New Features in v1.0.0

1. Improved Vector Store Support

• Fixed OpenSearch vector store integration
• Enhanced error handling across all vector stores
• Better performance and reliability

2. Enhanced GCP Integration

• Support for service account JSON dict (in addition to file path)
• Improved Vertex AI Vector Search configuration

3. Simplified API

• Default API version is now v1.1 (v1.0 deprecated)
• Removed deprecated parameters
• Standardized response formats

Deprecation Warning for v1.0 Users

If you're currently using version="v1.0", you'll see a deprecation warning:

DeprecationWarning: The v1.0 API format is deprecated and will be removed in mem0ai 2.0.0. 
Please upgrade to v1.1 format which returns a dict with 'results' key. 
Set version='v1.1' in your MemoryConfig.

To resolve this:

# Before (shows warning)
memory = Memory(config=MemoryConfig(version="v1.0"))

# After (no warning)
memory = Memory()  # Uses v1.1 by default
# OR explicitly set v1.1
memory = Memory(config=MemoryConfig(version="v1.1"))

Common Issues and Solutions

Issue 1: "KeyError: 'results'"

Problem: Your code expects the old list format response.

Solution: Update response handling:

# Before
for memory in response:  # Assuming response is a list
    print(memory)

# After  
for memory in response["results"]:
    print(memory)

Issue 2: "TypeError: unexpected keyword argument 'output_format'"

Problem: Code still passing deprecated parameters.

Solution: Remove all deprecated parameters:

# Before
client.add(messages, output_format="v1.1", async_mode=True)

# After
client.add(messages)

Issue 3: Vector Store Connection Issues

Problem: Vector store tests failing after upgrade.

Solution: The OpenSearch integration has been fixed. Update your test configurations and retry.

Support

If you encounter issues during migration:

1. Check the GitHub Issues for similar problems
2. Review the updated API documentation
3. Create a new issue with your specific migration problem

Summary

mem0ai 1.0.0 provides a cleaner, more consistent API while removing deprecated features. The migration primarily involves:

1. Removing deprecated parameters (output_format, version, async_mode)
2. Updating response handling to expect consistent {"results": [...]} format
3. Updating dependencies to v1.0.0

Most applications will require minimal changes, mainly removing deprecated parameters and updating response parsing logic.