my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	---
#2	title: Migrating from v0.x to v1.0.0
#3	description: 'Complete guide to upgrade your Mem0 implementation to version 1.0.0 '
#4	icon: "arrow-right"
#5	iconType: "solid"
#6	---
#7
#8	<Warning>
#9	Breaking Changes Ahead! Mem0 1.0.0 introduces several breaking changes. Please read this guide carefully before upgrading.
#10	</Warning>
#11
#12	## Overview
#13
#14	Mem0 1.0.0 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.
#15
#16	## Key Changes Summary
#17
#18	\| Feature \| v0.x \| v1.0.0 \| Migration Required \|
#19	\|---------\|------\|-------------\|-------------------\|
#20	\| API Version \| v1.0 supported \| v1.0 removed, v1.1+ only \| ✅ Yes \|
#21	\| Async Mode (Platform Client) \| Optional/manual \| Defaults to `True`, configurable \| ⚠️ Partial \|
#22	\| Metadata Filtering \| Basic \| Enhanced with operators \| ⚠️ Optional \|
#23	\| Reranking \| Not available \| Full support \| ⚠️ Optional \|
#24
#25	## Step-by-Step Migration
#26
#27	### 1. Update Installation
#28
#29	```bash
#30	# Update to the latest version
#31	pip install --upgrade mem0ai
#32	```
#33
#34	### 2. Remove Deprecated Parameters
#35
#36	#### Before (v0.x)
#37	```python
#38	from mem0 import Memory
#39
#40	# These parameters are no longer supported
#41	m = Memory()
#42	result = m.add(
#43	"I love pizza",
#44	user_id="alice",
#45	version="v1.0" # ❌ REMOVED
#46	)
#47	```
#48
#49	#### After (v1.0.0 )
#50	```python
#51	from mem0 import Memory
#52
#53	# Clean, simplified API
#54	m = Memory()
#55	result = m.add(
#56	"I love pizza",
#57	user_id="alice"
#58	# version parameter removed
#59	)
#60	```
#61
#62	### 3. Update Configuration
#63
#64	#### Before (v0.x)
#65	```python
#66	config = {
#67	"vector_store": {
#68	"provider": "qdrant",
#69	"config": {
#70	"host": "localhost",
#71	"port": 6333
#72	}
#73	},
#74	"version": "v1.0" # ❌ No longer supported
#75	}
#76
#77	m = Memory.from_config(config)
#78	```
#79
#80	#### After (v1.0.0 )
#81	```python
#82	config = {
#83	"vector_store": {
#84	"provider": "qdrant",
#85	"config": {
#86	"host": "localhost",
#87	"port": 6333
#88	}
#89	},
#90	"version": "v1.1" # ✅ v1.1 is the minimum supported version
#91	}
#92
#93	m = Memory.from_config(config)
#94	```
#95
#96	### 4. Handle Response Format Changes
#97
#98	#### Before (v0.x)
#99	```python
#100	# Response could be a list or dict depending on version
#101	result = m.add("I love coffee", user_id="alice")
#102
#103	if isinstance(result, list):
#104	# Handle list format
#105	for item in result:
#106	print(item["memory"])
#107	else:
#108	# Handle dict format
#109	print(result["results"])
#110	```
#111
#112	#### After (v1.0.0 )
#113	```python
#114	# Response is always a standardized dict with "results" key
#115	result = m.add("I love coffee", user_id="alice")
#116
#117	# Always access via "results" key
#118	for item in result["results"]:
#119	print(item["memory"])
#120	```
#121
#122	### 5. Update Search Operations
#123
#124	#### Before (v0.x)
#125	```python
#126	# Basic search
#127	results = m.search("What do I like?", user_id="alice")
#128
#129	# With filters
#130	results = m.search(
#131	"What do I like?",
#132	user_id="alice",
#133	filters={"category": "food"}
#134	)
#135	```
#136
#137	#### After (v1.0.0 )
#138	```python
#139	# Same basic search API
#140	results = m.search("What do I like?", user_id="alice")
#141
#142	# Enhanced filtering with operators (optional upgrade)
#143	results = m.search(
#144	"What do I like?",
#145	user_id="alice",
#146	filters={
#147	"AND": [
#148	{"category": "food"},
#149	{"rating": {"gte": 8}}
#150	]
#151	}
#152	)
#153
#154	# New: Reranking support (optional)
#155	results = m.search(
#156	"What do I like?",
#157	user_id="alice",
#158	rerank=True # Requires reranker configuration
#159	)
#160	```
#161
#162	### 6. Platform Client async_mode Default Changed
#163
#164	Change: For `MemoryClient`, the `async_mode` parameter now defaults to `True` for better performance.
#165
#166	#### Before (v0.x)
#167	```python
#168	from mem0 import MemoryClient
#169
#170	client = MemoryClient(api_key="your-key")
#171
#172	# Had to explicitly set async_mode
#173	result = client.add("I enjoy hiking", user_id="alice", async_mode=True)
#174	```
#175
#176	#### After (v1.0.0 )
#177	```python
#178	from mem0 import MemoryClient
#179
#180	client = MemoryClient(api_key="your-key")
#181
#182	# async_mode now defaults to True (best performance)
#183	result = client.add("I enjoy hiking", user_id="alice")
#184
#185	# You can still override if needed for synchronous processing
#186	result = client.add("I enjoy hiking", user_id="alice", async_mode=False)
#187	```
#188
#189	## Configuration Migration
#190
#191	### Basic Configuration
#192
#193	#### Before (v0.x)
#194	```python
#195	config = {
#196	"vector_store": {
#197	"provider": "qdrant",
#198	"config": {
#199	"host": "localhost",
#200	"port": 6333
#201	}
#202	},
#203	"llm": {
#204	"provider": "openai",
#205	"config": {
#206	"model": "gpt-3.5-turbo",
#207	"api_key": "your-key"
#208	}
#209	},
#210	"version": "v1.0"
#211	}
#212	```
#213
#214	#### After (v1.0.0 )
#215	```python
#216	config = {
#217	"vector_store": {
#218	"provider": "qdrant",
#219	"config": {
#220	"host": "localhost",
#221	"port": 6333
#222	}
#223	},
#224	"llm": {
#225	"provider": "openai",
#226	"config": {
#227	"model": "gpt-3.5-turbo",
#228	"api_key": "your-key"
#229	}
#230	},
#231	"version": "v1.1", # Minimum supported version
#232
#233	# New optional features
#234	"reranker": {
#235	"provider": "cohere",
#236	"config": {
#237	"model": "rerank-english-v3.0",
#238	"api_key": "your-cohere-key"
#239	}
#240	}
#241	}
#242	```
#243
#244	### Enhanced Features (Optional)
#245
#246	```python
#247	# Take advantage of new features
#248	config = {
#249	"vector_store": {
#250	"provider": "qdrant",
#251	"config": {
#252	"host": "localhost",
#253	"port": 6333
#254	}
#255	},
#256	"llm": {
#257	"provider": "openai",
#258	"config": {
#259	"model": "gpt-4",
#260	"api_key": "your-key"
#261	}
#262	},
#263	"embedder": {
#264	"provider": "openai",
#265	"config": {
#266	"model": "text-embedding-3-small",
#267	"api_key": "your-key"
#268	}
#269	},
#270	"reranker": {
#271	"provider": "sentence_transformer",
#272	"config": {
#273	"model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
#274	}
#275	},
#276	"version": "v1.1"
#277	}
#278	```
#279
#280	## Error Handling Migration
#281
#282	### Before (v0.x)
#283	```python
#284	try:
#285	result = m.add("memory", user_id="alice", version="v1.0")
#286	except Exception as e:
#287	print(f"Error: {e}")
#288	```
#289
#290	### After (v1.0.0 )
#291	```python
#292	try:
#293	result = m.add("memory", user_id="alice")
#294	except ValueError as e:
#295	if "v1.0 API format is no longer supported" in str(e):
#296	print("Please upgrade your code to use v1.1+ format")
#297	else:
#298	print(f"Error: {e}")
#299	except Exception as e:
#300	print(f"Unexpected error: {e}")
#301	```
#302
#303	## Testing Your Migration
#304
#305	### 1. Basic Functionality Test
#306
#307	```python
#308	def test_basic_functionality():
#309	m = Memory()
#310
#311	# Test add
#312	result = m.add("I love testing", user_id="test_user")
#313	assert "results" in result
#314	assert len(result["results"]) > 0
#315
#316	# Test search
#317	search_results = m.search("testing", user_id="test_user")
#318	assert "results" in search_results
#319
#320	# Test get_all
#321	all_memories = m.get_all(user_id="test_user")
#322	assert "results" in all_memories
#323
#324	print("✅ Basic functionality test passed")
#325
#326	test_basic_functionality()
#327	```
#328
#329	### 2. Enhanced Features Test
#330
#331	```python
#332	def test_enhanced_features():
#333	config = {
#334	"reranker": {
#335	"provider": "sentence_transformer",
#336	"config": {
#337	"model": "cross-encoder/ms-marco-MiniLM-L-6-v2"
#338	}
#339	}
#340	}
#341
#342	m = Memory.from_config(config)
#343
#344	# Test reranking
#345	m.add("I love advanced features", user_id="test_user")
#346	results = m.search("features", user_id="test_user", rerank=True)
#347	assert "results" in results
#348
#349	# Test enhanced filtering
#350	results = m.search(
#351	"features",
#352	user_id="test_user",
#353	filters={"user_id": {"eq": "test_user"}}
#354	)
#355	assert "results" in results
#356
#357	print("✅ Enhanced features test passed")
#358
#359	test_enhanced_features()
#360	```
#361
#362	## Common Migration Issues
#363
#364	### Issue 1: Version Error
#365
#366	Error:
#367	```
#368	ValueError: The v1.0 API format is no longer supported in mem0ai 1.0.0+
#369	```
#370
#371	Solution:
#372	```python
#373	# Remove version parameters or set to v1.1+
#374	config = {
#375	# ... other config
#376	"version": "v1.1" # or remove entirely for default
#377	}
#378	```
#379
#380	### Issue 2: Response Format Error
#381
#382	Error:
#383	```
#384	KeyError: 'results'
#385	```
#386
#387	Solution:
#388	```python
#389	# Always access response via "results" key
#390	result = m.add("memory", user_id="alice")
#391	memories = result["results"] # Not result directly
#392	```
#393
#394	### Issue 3: Parameter Error
#395
#396	Error:
#397	```
#398	TypeError: add() got an unexpected keyword argument 'output_format'
#399	```
#400
#401	Solution:
#402	```python
#403	# Remove deprecated parameters
#404	result = m.add(
#405	"memory",
#406	user_id="alice"
#407	# Remove: version
#408	)
#409	```
#410
#411	## Rollback Plan
#412
#413	If you encounter issues during migration:
#414
#415	### 1. Immediate Rollback
#416
#417	```bash
#418	# Downgrade to last v0.x version
#419	pip install mem0ai==0.1.20 # Replace with your last working version
#420	```
#421
#422	### 2. Gradual Migration
#423
#424	```python
#425	# Test both versions side by side
#426	import mem0_v0 # Your old version
#427	import mem0 # New version
#428
#429	def compare_results(query, user_id):
#430	old_results = mem0_v0.search(query, user_id=user_id)
#431	new_results = mem0.search(query, user_id=user_id)
#432
#433	print("Old format:", old_results)
#434	print("New format:", new_results["results"])
#435	```
#436
#437	## Performance Improvements
#438
#439	### Before (v0.x)
#440	```python
#441	# Sequential operations
#442	result1 = m.add("memory 1", user_id="alice")
#443	result2 = m.add("memory 2", user_id="alice")
#444	result3 = m.search("query", user_id="alice")
#445	```
#446
#447	### After (v1.0.0 )
#448	```python
#449	# Better async performance
#450	async def batch_operations():
#451	async_memory = AsyncMemory()
#452
#453	# Concurrent operations
#454	results = await asyncio.gather(
#455	async_memory.add("memory 1", user_id="alice"),
#456	async_memory.add("memory 2", user_id="alice"),
#457	async_memory.search("query", user_id="alice")
#458	)
#459	return results
#460	```
#461
#462	## Next Steps
#463
#464	1. Complete the migration using this guide
#465	2. Test thoroughly with your existing data
#466	3. Explore new features like enhanced filtering and reranking
#467	4. Update your documentation to reflect the new API
#468	5. Monitor performance and optimize as needed
#469
#470	<CardGroup cols={2}>
#471	<Card title="Breaking Changes" icon="triangle-exclamation" href="/migration/breaking-changes">
#472	Detailed list of all breaking changes
#473	</Card>
#474	<Card title="API Changes" icon="code" href="/migration/api-changes">
#475	Complete API reference changes
#476	</Card>
#477	</CardGroup>
#478
#479	<Info>
#480	Need help with migration? Check our [GitHub Discussions](https://github.com/mem0ai/mem0/discussions) or reach out to our community for support.
#481	</Info>

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public