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

> Easily migrate from Mem0 v0.x to v1.0. Discover breaking changes and follow our upgrade guide to update arguments, response handling, and client modes for a smooth transition.

- Repository: [Mem0/mem0](https://github.com/mem0ai/mem0)
- Tags: migration-guide
- Published: 2026-03-07

---

**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`](https://github.com/mem0ai/mem0/blob/main/mem0/memory/main.py) and [`mem0/configs/base.py`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/MIGRATION_GUIDE_v1.0.md) (lines 1-11), these arguments are **completely removed** in v1.0.

The `Memory` class in [`mem0/memory/main.py`](https://github.com/mem0ai/mem0/blob/main/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:

```python

# 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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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:

```bash
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`](https://github.com/mem0ai/mem0/blob/main/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

```python
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

```python
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

```python

# 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:

```python
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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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.