my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	title: API Reference Changes
#3	description: 'Complete API changes between v0.x and v1.0.0 Beta'
#4	icon: "code"
#5	iconType: "solid"
#6	---
#7
#8	## Overview
#9
#10	This page documents all API changes between Mem0 v0.x and v1.0.0 Beta, organized by component and method.
#11
#12	## Memory Class Changes
#13
#14	### Constructor
#15
#16	#### v0.x
#17	```python
#18	from mem0 import Memory
#19
#20	# Basic initialization
#21	m = Memory()
#22
#23	# With configuration
#24	config = {
#25	"version": "v1.0", # Supported in v0.x
#26	"vector_store": {...}
#27	}
#28	m = Memory.from_config(config)
#29	```
#30
#31	#### v1.0.0
#32	```python
#33	from mem0 import Memory
#34
#35	# Basic initialization (same)
#36	m = Memory()
#37
#38	# With configuration
#39	config = {
#40	"version": "v1.1", # v1.1+ only
#41	"vector_store": {...},
#42	# New optional features
#43	"reranker": {
#44	"provider": "cohere",
#45	"config": {...}
#46	}
#47	}
#48	m = Memory.from_config(config)
#49	```
#50
#51	### add() Method
#52
#53	#### v0.x Signature
#54	```python
#55	def add(
#56	self,
#57	messages,
#58	user_id: str = None,
#59	agent_id: str = None,
#60	run_id: str = None,
#61	metadata: dict = None,
#62	filters: dict = None,
#63	output_format: str = None, # ❌ REMOVED
#64	version: str = None # ❌ REMOVED
#65	) -> Union[List[dict], dict]
#66	```
#67
#68	#### v1.0.0 Signature
#69	```python
#70	def add(
#71	self,
#72	messages,
#73	user_id: str = None,
#74	agent_id: str = None,
#75	run_id: str = None,
#76	metadata: dict = None,
#77	filters: dict = None,
#78	infer: bool = True # ✅ NEW: Control memory inference
#79	) -> dict # Always returns dict with "results" key
#80	```
#81
#82	#### Changes Summary
#83
#84	\| Parameter \| v0.x \| v1.0.0 \| Change \|
#85	\|-----------\|------\|-----------\|---------\|
#86	\| `messages` \| ✅ \| ✅ \| Unchanged \|
#87	\| `user_id` \| ✅ \| ✅ \| Unchanged \|
#88	\| `agent_id` \| ✅ \| ✅ \| Unchanged \|
#89	\| `run_id` \| ✅ \| ✅ \| Unchanged \|
#90	\| `metadata` \| ✅ \| ✅ \| Unchanged \|
#91	\| `filters` \| ✅ \| ✅ \| Unchanged \|
#92	\| `output_format` \| ✅ \| ❌ \| REMOVED \|
#93	\| `version` \| ✅ \| ❌ \| REMOVED \|
#94	\| `infer` \| ❌ \| ✅ \| NEW \|
#95
#96	#### Response Format Changes
#97
#98	v0.x Response (variable format):
#99	```python
#100	# With output_format="v1.0"
#101	[
#102	{
#103	"id": "mem_123",
#104	"memory": "User loves pizza",
#105	"event": "ADD"
#106	}
#107	]
#108
#109	# With output_format="v1.1"
#110	{
#111	"results": [
#112	{
#113	"id": "mem_123",
#114	"memory": "User loves pizza",
#115	"event": "ADD"
#116	}
#117	]
#118	}
#119	```
#120
#121	v1.0.0 Response (standardized):
#122	```python
#123	# Always returns this format
#124	{
#125	"results": [
#126	{
#127	"id": "mem_123",
#128	"memory": "User loves pizza",
#129	"metadata": {...},
#130	"event": "ADD"
#131	}
#132	]
#133	}
#134	```
#135
#136	### search() Method
#137
#138	#### v0.x Signature
#139	```python
#140	def search(
#141	self,
#142	query: str,
#143	user_id: str = None,
#144	agent_id: str = None,
#145	run_id: str = None,
#146	limit: int = 100,
#147	filters: dict = None, # Basic key-value only
#148	output_format: str = None, # ❌ REMOVED
#149	version: str = None # ❌ REMOVED
#150	) -> Union[List[dict], dict]
#151	```
#152
#153	#### v1.0.0 Signature
#154	```python
#155	def search(
#156	self,
#157	query: str,
#158	user_id: str = None,
#159	agent_id: str = None,
#160	run_id: str = None,
#161	limit: int = 100,
#162	filters: dict = None, # ✅ ENHANCED: Advanced operators
#163	rerank: bool = True # ✅ NEW: Reranking support
#164	) -> dict # Always returns dict with "results" key
#165	```
#166
#167	#### Enhanced Filtering
#168
#169	v0.x Filters (basic):
#170	```python
#171	# Simple key-value filtering only
#172	filters = {
#173	"category": "food",
#174	"user_id": "alice"
#175	}
#176	```
#177
#178	v1.0.0 Filters (enhanced):
#179	```python
#180	# Advanced filtering with operators
#181	filters = {
#182	"AND": [
#183	{"category": "food"},
#184	{"score": {"gte": 0.8}},
#185	{
#186	"OR": [
#187	{"priority": "high"},
#188	{"urgent": True}
#189	]
#190	}
#191	]
#192	}
#193
#194	# Comparison operators
#195	filters = {
#196	"score": {"gt": 0.5}, # Greater than
#197	"priority": {"gte": 5}, # Greater than or equal
#198	"rating": {"lt": 3}, # Less than
#199	"confidence": {"lte": 0.9}, # Less than or equal
#200	"status": {"eq": "active"}, # Equal
#201	"archived": {"ne": True}, # Not equal
#202	"tags": {"in": ["work", "personal"]}, # In list
#203	"category": {"nin": ["spam", "deleted"]} # Not in list
#204	}
#205	```
#206
#207	### get_all() Method
#208
#209	#### v0.x Signature
#210	```python
#211	def get_all(
#212	self,
#213	user_id: str = None,
#214	agent_id: str = None,
#215	run_id: str = None,
#216	filters: dict = None,
#217	output_format: str = None, # ❌ REMOVED
#218	version: str = None # ❌ REMOVED
#219	) -> Union[List[dict], dict]
#220	```
#221
#222	#### v1.0.0 Signature
#223	```python
#224	def get_all(
#225	self,
#226	user_id: str = None,
#227	agent_id: str = None,
#228	run_id: str = None,
#229	filters: dict = None # ✅ ENHANCED: Advanced operators
#230	) -> dict # Always returns dict with "results" key
#231	```
#232
#233	### update() Method
#234
#235	#### No Breaking Changes
#236	```python
#237	# Same signature in both versions
#238	def update(
#239	self,
#240	memory_id: str,
#241	data: str
#242	) -> dict
#243	```
#244
#245	### delete() Method
#246
#247	#### No Breaking Changes
#248	```python
#249	# Same signature in both versions
#250	def delete(
#251	self,
#252	memory_id: str
#253	) -> dict
#254	```
#255
#256	### delete_all() Method
#257
#258	#### Breaking Change — Empty filter no longer silently deletes everything
#259
#260	Before: calling `delete_all()` with no filters silently deleted all memories in the project.
#261
#262	After:
#263	- No filters → raises a validation error (prevents accidental full-project wipe).
#264	- Concrete ID (e.g. `user_id="alice"`) → deletes memories for that entity (unchanged).
#265	- `"*"` for a filter → deletes all memories for that entity type across the project (new).
#266	- All four filters set to `"*"` → explicit full project wipe (new, requires opt-in on every parameter).
#267
#268	This change replaces the silent full-project delete (triggered by an empty or missing filter) with a validation error, and introduces `"*"` wildcards as the intentional path for bulk deletion.
#269
#270	```python
#271	# v0.x — no filter silently wiped all project memories
#272	m.delete_all() # DANGER: deleted everything
#273	m.delete_all(user_id="alice") # deleted alice's memories
#274
#275	# v1.x — no filter now raises an error; use "*" for intentional bulk deletes
#276	m.delete_all() # ERROR: at least one filter required
#277	m.delete_all(user_id="alice") # unchanged
#278	m.delete_all(user_id="*") # NEW — delete all users' memories
#279	m.delete_all(user_id="", agent_id="", app_id="", run_id="") # NEW — full project wipe
#280	```
#281
#282	## Platform Client (MemoryClient) Changes
#283
#284	### async_mode Default Changed
#285
#286	#### v0.x
#287	```python
#288	from mem0 import MemoryClient
#289
#290	client = MemoryClient(api_key="your-key")
#291
#292	# async_mode had to be explicitly set or had different default
#293	result = client.add("content", user_id="alice", async_mode=True)
#294	```
#295
#296	#### v1.0.0
#297	```python
#298	from mem0 import MemoryClient
#299
#300	client = MemoryClient(api_key="your-key")
#301
#302	# async_mode defaults to True now (better performance)
#303	result = client.add("content", user_id="alice") # Uses async_mode=True by default
#304
#305	# Can still override if needed
#306	result = client.add("content", user_id="alice", async_mode=False)
#307	```
#308
#309	## Configuration Changes
#310
#311	### Memory Configuration
#312
#313	#### v0.x Config Options
#314	```python
#315	config = {
#316	"vector_store": {...},
#317	"llm": {...},
#318	"embedder": {...},
#319	"graph_store": {...},
#320	"version": "v1.0", # ❌ v1.0 no longer supported
#321	"history_db_path": "...",
#322	"custom_fact_extraction_prompt": "..."
#323	}
#324	```
#325
#326	#### v1.0.0 Config Options
#327	```python
#328	config = {
#329	"vector_store": {...},
#330	"llm": {...},
#331	"embedder": {...},
#332	"graph_store": {...},
#333	"reranker": { # ✅ NEW: Reranker support
#334	"provider": "cohere",
#335	"config": {...}
#336	},
#337	"version": "v1.1", # ✅ v1.1+ only
#338	"history_db_path": "...",
#339	"custom_fact_extraction_prompt": "...",
#340	"custom_update_memory_prompt": "..." # ✅ NEW: Custom update prompt
#341	}
#342	```
#343
#344	### New Configuration Options
#345
#346	#### Reranker Configuration
#347	```python
#348	# Cohere reranker
#349	"reranker": {
#350	"provider": "cohere",
#351	"config": {
#352	"model": "rerank-english-v3.0",
#353	"api_key": "your-api-key",
#354	"top_k": 10
#355	}
#356	}
#357
#358	# Sentence Transformer reranker
#359	"reranker": {
#360	"provider": "sentence_transformer",
#361	"config": {
#362	"model": "cross-encoder/ms-marco-MiniLM-L-6-v2",
#363	"device": "cuda"
#364	}
#365	}
#366
#367	# Hugging Face reranker
#368	"reranker": {
#369	"provider": "huggingface",
#370	"config": {
#371	"model": "BAAI/bge-reranker-base",
#372	"device": "cuda"
#373	}
#374	}
#375
#376	# LLM-based reranker
#377	"reranker": {
#378	"provider": "llm_reranker",
#379	"config": {
#380	"llm": {
#381	"provider": "openai",
#382	"config": {
#383	"model": "gpt-4",
#384	"api_key": "your-api-key"
#385	}
#386	}
#387	}
#388	}
#389	```
#390
#391	## Error Handling Changes
#392
#393	### New Error Types
#394
#395	#### v0.x Errors
#396	```python
#397	# Generic exceptions
#398	try:
#399	result = m.add("content", user_id="alice", version="v1.0")
#400	except Exception as e:
#401	print(f"Error: {e}")
#402	```
#403
#404	#### v1.0.0 Errors
#405	```python
#406	# More specific error handling
#407	try:
#408	result = m.add("content", user_id="alice")
#409	except ValueError as e:
#410	if "v1.0 API format is no longer supported" in str(e):
#411	# Handle version compatibility error
#412	pass
#413	elif "Invalid filter operator" in str(e):
#414	# Handle filter syntax error
#415	pass
#416	except TypeError as e:
#417	# Handle parameter errors
#418	pass
#419	except Exception as e:
#420	# Handle unexpected errors
#421	pass
#422	```
#423
#424	### Validation Changes
#425
#426	#### Stricter Parameter Validation
#427
#428	v0.x (Lenient):
#429	```python
#430	# Unknown parameters might be ignored
#431	result = m.add("content", user_id="alice", unknown_param="value")
#432	```
#433
#434	v1.0.0 (Strict):
#435	```python
#436	# Unknown parameters raise TypeError
#437	try:
#438	result = m.add("content", user_id="alice", unknown_param="value")
#439	except TypeError as e:
#440	print(f"Invalid parameter: {e}")
#441	```
#442
#443	## Response Schema Changes
#444
#445	### Memory Object Schema
#446
#447	#### v0.x Schema
#448	```python
#449	{
#450	"id": "mem_123",
#451	"memory": "User loves pizza",
#452	"user_id": "alice",
#453	"metadata": {...},
#454	"created_at": "2024-01-01T00:00:00Z",
#455	"updated_at": "2024-01-01T00:00:00Z",
#456	"score": 0.95 # In search results
#457	}
#458	```
#459
#460	#### v1.0.0 Schema (Enhanced)
#461	```python
#462	{
#463	"id": "mem_123",
#464	"memory": "User loves pizza",
#465	"user_id": "alice",
#466	"agent_id": "assistant", # ✅ More context
#467	"run_id": "session_001", # ✅ More context
#468	"metadata": {...},
#469	"categories": ["food"], # ✅ NEW: Auto-categorization
#470	"immutable": false, # ✅ NEW: Immutability flag
#471	"created_at": "2024-01-01T00:00:00Z",
#472	"updated_at": "2024-01-01T00:00:00Z",
#473	"score": 0.95, # In search results
#474	"rerank_score": 0.98 # ✅ NEW: If reranking used
#475	}
#476	```
#477
#478	## Migration Code Examples
#479
#480	### Simple Migration
#481
#482	#### Before (v0.x)
#483	```python
#484	from mem0 import Memory
#485
#486	m = Memory()
#487
#488	# Add with deprecated parameters
#489	result = m.add(
#490	"I love pizza",
#491	user_id="alice",
#492	output_format="v1.1",
#493	version="v1.0"
#494	)
#495
#496	# Handle variable response format
#497	if isinstance(result, list):
#498	memories = result
#499	else:
#500	memories = result.get("results", [])
#501
#502	for memory in memories:
#503	print(memory["memory"])
#504	```
#505
#506	#### After (v1.0.0 )
#507	```python
#508	from mem0 import Memory
#509
#510	m = Memory()
#511
#512	# Add without deprecated parameters
#513	result = m.add(
#514	"I love pizza",
#515	user_id="alice"
#516	)
#517
#518	# Always dict format with "results" key
#519	for memory in result["results"]:
#520	print(memory["memory"])
#521	```
#522
#523	### Advanced Migration
#524
#525	#### Before (v0.x)
#526	```python
#527	# Basic filtering
#528	results = m.search(
#529	"food preferences",
#530	user_id="alice",
#531	filters={"category": "food"},
#532	output_format="v1.1"
#533	)
#534	```
#535
#536	#### After (v1.0.0 )
#537	```python
#538	# Enhanced filtering with reranking
#539	results = m.search(
#540	"food preferences",
#541	user_id="alice",
#542	filters={
#543	"AND": [
#544	{"category": "food"},
#545	{"score": {"gte": 0.8}}
#546	]
#547	},
#548	rerank=True
#549	)
#550	```
#551
#552	## Summary
#553
#554	\| Component \| v0.x \| v1.0.0 \| Status \|
#555	\|-----------\|------\|-----------\|---------\|
#556	\| `add()` method \| Variable response \| Standardized response \| ⚠️ Breaking \|
#557	\| `search()` method \| Basic filtering \| Enhanced filtering + reranking \| ⚠️ Breaking \|
#558	\| `get_all()` method \| Variable response \| Standardized response \| ⚠️ Breaking \|
#559	\| Response format \| Variable \| Always `{"results": [...]}` \| ⚠️ Breaking \|
#560	\| Reranking \| ❌ Not available \| ✅ Full support \| ✅ New feature \|
#561	\| Advanced filtering \| ❌ Basic only \| ✅ Full operators \| ✅ Enhancement \|
#562	\| Error handling \| Generic \| Specific error types \| ✅ Improvement \|
#563
#564	<Info>
#565	Use this reference to systematically update your codebase. Test each change thoroughly before deploying to production.
#566	</Info>

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public