How to Migrate from Mem0 v0.x to v1.0: Breaking Changes and Upgrade Guide

To migrate from Mem0 v0.x to v1.0, remove all version and output_format arguments from your code, update response handling to use result["results"] instead of direct list iteration, and note that MemoryClient now defaults to async_mode=True.

The mem0ai/mem0 repository introduces a cleaner, version-agnostic API in v1.0 that eliminates legacy parameters and unifies response formats across all operations. This migration guide covers the architectural changes implemented in mem0/memory/main.py and mem0/configs/base.py, providing concrete steps to upgrade your application without breaking existing functionality.

Breaking Changes in Mem0 v1.0

Removal of Version and Output Format Arguments

In Mem0 v0.x, every public method—including add, search, and get_all—accepted explicit version and output_format parameters that controlled response behavior. According to the migration guide in MIGRATION_GUIDE_v1.0.md (lines 1-11), these arguments are completely removed in v1.0.

The Memory class in mem0/memory/main.py (lines 172-190) no longer accepts these legacy parameters. You must delete all instances of version="v1.0" and output_format="v1.0" from your API calls.

Unified Response Schema

All public methods now return a consistent dictionary containing a top-level "results" key. Where v0.x returned a plain list that required direct iteration, v1.0 always returns a structured object.

As documented in docs/migration/v0-to-v1.mdx (lines 96-20), the new canonical response format is:

# v0.x - List-style response (deprecated)

result = memory.add("I like pizza")
for item in result:  # Works only in legacy versions

    print(item["memory"])

# v1.0 - Dictionary-style response (current)

result = memory.add("I like pizza")
for item in result["results"]:  # New required pattern

    print(item["memory"])

Async Mode Default on MemoryClient

The MemoryClient class in mem0/client/main.py now defaults async_mode=True to improve throughput for network-bound operations. As noted in the documentation at docs/migration/v0-to-v1.mdx (lines 62-86), this changes the execution model from synchronous to asynchronous unless explicitly overridden.

Configuration Defaults

The MemoryConfig model in mem0/configs/base.py (lines 55-58) now defaults to "v1.1" and makes the version field optional. The configuration also introduces a new optional reranker field (lines 51-54) for enhanced search capabilities, though existing configurations continue to function without it.

Step-by-Step Migration Guide

1. Update Package Dependencies

Upgrade your environment to the latest major version:

pip install --upgrade mem0ai

# Or pin specifically:

pip install mem0ai==1.0.0

2. Refactor API Calls

Remove deprecated parameters from all Memory method invocations. The add, search, and get_all methods no longer accept version or output_format arguments.

3. Update Response Handling

Modify every location where you process memory operations to access the "results" key. This applies to both local Memory instances and remote MemoryClient calls.

4. Review Configuration Changes

Update your configuration dictionaries to remove the version field, or set it explicitly to "v1.1" if you require version pinning. According to mem0/configs/base.py, omitting the field entirely is now the recommended approach.

5. Implement Optional Enhancements

Consider adding enhanced filtering operators or configuring a reranker for improved search quality. These features use new syntax described in docs/migration/v0-to-v1.mdx (lines 34-52) but remain optional for backward compatibility.

Code Migration Examples

Before: v0.x Implementation

from mem0 import Memory

# Legacy configuration requiring explicit version

cfg = {
    "vector_store": {
        "provider": "qdrant", 
        "config": {"host": "localhost", "port": 6333}
    },
    "version": "v1.0",  # Deprecated in v1.0

}
mem = Memory.from_config(cfg)

# Old API with removed parameters

result = mem.add(
    "I love pizza",
    user_id="alice",
    version="v1.0",       # ❌ Remove this

    output_format="v1.0", # ❌ Remove this

)

# Legacy list iteration

for item in result:
    print(item["memory"])

After: v1.0 Implementation

from mem0 import Memory

# Modern configuration - version is optional

cfg = {
    "vector_store": {
        "provider": "qdrant", 
        "config": {"host": "localhost", "port": 6333}
    }
}
mem = Memory.from_config(cfg)

# Clean API signature

result = mem.add("I love pizza", user_id="alice")

# Unified response handling

for item in result["results"]:
    print(item["memory"])

# MemoryClient with async default

from mem0 import MemoryClient
client = MemoryClient(api_key="your-key")  # async_mode=True by default

Optional: Advanced Filtering and Reranking

# Enhanced search with logical operators

search_res = mem.search(
    "What cuisines do I like?",
    user_id="alice",
    filters={
        "AND": [
            {"category": "food"},
            {"rating": {"gte": 8}}
        ]
    },
    rerank=True  # Requires reranker configuration in MemoryConfig

)

for hit in search_res["results"]:
    print(hit["memory"])

Validation Test

Verify your migration with this assertion check:

from mem0 import Memory

mem = Memory()
add_res = mem.add("Testing migration", user_id="tester")
assert "results" in add_res, "Migration incomplete: response missing 'results' key"

search_res = mem.search("migration", user_id="tester")
assert "results" in search_res

Summary

• Remove legacy parameters: Delete all version and output_format arguments from Memory method calls in mem0/memory/main.py.
• Adopt new response format: Update all result processing to use response["results"] instead of direct list iteration.
• Check async defaults: Explicitly set async_mode=False on MemoryClient if you require synchronous behavior.
• Simplify configuration: Omit the version field from MemoryConfig in mem0/configs/base.py or set it to "v1.1".
• Leverage optional features: Implement advanced filtering and reranking only if your use case requires enhanced search precision.

Frequently Asked Questions

Do I need to specify a version in MemoryConfig when migrating to v1.0?

No. The MemoryConfig class in mem0/configs/base.py now defaults to "v1.1" and makes the version field optional. You can safely remove the version key from your configuration dictionaries, or explicitly set it to "v1.1" if you need to ensure minimum version compatibility with specific features.

Why did Mem0 v1.0 change the response format from a list to a dictionary?

The unified dictionary format with a "results" key provides a consistent contract across all API methods, allowing the addition of metadata fields like "relations" without breaking existing parsing logic. This change, implemented in the core Memory class, simplifies client code by eliminating version-dependent branching logic that was required in v0.x.

How do I disable async mode in MemoryClient after upgrading?

Pass async_mode=False explicitly when instantiating MemoryClient. While v1.0 defaults to async_mode=True for improved performance, the constructor accepts a boolean override to restore synchronous behavior: client = MemoryClient(api_key="key", async_mode=False).

Are the new filtering and reranking features required after migration?

No. Enhanced filtering operators (such as AND and gte) and the optional reranker configuration are additive features that improve search quality but remain entirely optional. Basic search and add operations function identically without these enhancements, ensuring backward compatibility for simple use cases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}