The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.
Python agentic-memoryagentic-memory-systemagentsaiai-agentschatgptgenaillmlong-term-memorymemorymemory-managementpythonragstate-management
docs: remove inaccurate api-changes migration page (#5857)
Kartikee600705c2e1
diff --git a/docs/docs.json b/docs/docs.jsonindex c27b158a2..575512c95 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -123,8 +123,7 @@"icon": "arrow-right","pages": ["migration/platform-v2-to-v3",- "migration/oss-to-platform",- "migration/api-changes"+ "migration/oss-to-platform"]},{@@ -642,6 +641,10 @@"source": "/migration/v0-to-v1","destination": "/"},+ {+ "source": "/migration/api-changes",+ "destination": "/migration/oss-v2-to-v3"+ },{"source": "/platform/features/expiration-date","destination": "/"diff --git a/docs/llms.txt b/docs/llms.txtindex ec1c284d4..a05dd5e62 100644--- a/docs/llms.txt+++ b/docs/llms.txt@@ -228,7 +228,6 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f- [OSS to Platform Migration](https://docs.mem0.ai/migration/oss-to-platform) [Both]: Use when moving from self-hosted to managed.- [OSS v2 to v3 Migration](https://docs.mem0.ai/migration/oss-v2-to-v3) [OSS]: Use when upgrading a self-hosted deployment across major versions.- [Platform v2 to v3 Migration](https://docs.mem0.ai/migration/platform-v2-to-v3) [Platform]: Use when upgrading a Platform integration across major versions.-- [API Changes](https://docs.mem0.ai/migration/api-changes) [Both]: Use when the upgrade involves API surface changes.- [Server pgvector Image Upgrade](https://docs.mem0.ai/migration/server-pgvector-upgrade) [OSS]: Use when upgrading the self-hosted server Docker image from ankane/pgvector to pgvector/pgvector.- [Changelog](https://docs.mem0.ai/changelog/highlights) [Both]: Use when the user asks what shipped recently.diff --git a/docs/migration/api-changes.mdx b/docs/migration/api-changes.mdxdeleted file mode 100644index e072971f1..000000000--- a/docs/migration/api-changes.mdx+++ /dev/null@@ -1,574 +0,0 @@-----title: API Reference Changes-description: "Comprehensive reference of all API changes between Mem0 v0.x and v1.0.0 Beta, organized by component and method."-icon: "code"-iconType: "solid"------## Overview--This page documents all API changes between Mem0 v0.x and v1.0.0 Beta, organized by component and method.--## Memory Class Changes--### Constructor--#### v0.x-```python-from mem0 import Memory--# Basic initialization-m = Memory()--# With configuration-config = {- "version": "v1.0", # Supported in v0.x- "vector_store": {...}-}-m = Memory.from_config(config)-```--#### v1.0.0-```python-from mem0 import Memory--# Basic initialization (same)-m = Memory()--# With configuration-config = {- "version": "v1.1", # v1.1+ only- "vector_store": {...},- # New optional features- "reranker": {- "provider": "cohere",- "config": {...}- }-}-m = Memory.from_config(config)-```--### add() Method--#### v0.x Signature-```python-def add(- self,- messages,- user_id: str = None,- agent_id: str = None,- run_id: str = None,- metadata: dict = None,- filters: dict = None,- output_format: str = None, # ❌ REMOVED- version: str = None # ❌ REMOVED-) -> Union[List[dict], dict]:- ...-```--#### v1.0.0 Signature-```python-def add(- self,- messages,- user_id: str = None,- agent_id: str = None,- run_id: str = None,- metadata: dict = None,- filters: dict = None,- infer: bool = True # ✅ NEW: Control memory inference-) -> dict: # Always returns dict with "results" key- ...-```--#### Changes Summary--| Parameter | v0.x | v1.0.0 | Change |-|-----------|------|-----------|---------|-| `messages` | ✅ | ✅ | Unchanged |-| `user_id` | ✅ | ✅ | Unchanged |-| `agent_id` | ✅ | ✅ | Unchanged |-| `run_id` | ✅ | ✅ | Unchanged |-| `metadata` | ✅ | ✅ | Unchanged |-| `filters` | ✅ | ✅ | Unchanged |-| `output_format` | ✅ | ❌ | **REMOVED** |-| `version` | ✅ | ❌ | **REMOVED** |-| `infer` | ❌ | ✅ | **NEW** |--#### Response Format Changes--**v0.x Response (variable format):**-```python-# With output_format="v1.0"-[- {- "id": "mem_123",- "memory": "User loves pizza",- "event": "ADD"- }-]--# With output_format="v1.1"-{- "results": [- {- "id": "mem_123",- "memory": "User loves pizza",- "event": "ADD"- }- ]-}-```--**v1.0.0 Response (standardized):**-```python-# Always returns this format-{- "results": [- {- "id": "mem_123",- "memory": "User loves pizza",- "metadata": {...},- "event": "ADD"- }- ]-}-```--### search() Method--#### v0.x Signature-```python-def search(- self,- query: str,- user_id: str = None,- agent_id: str = None,- run_id: str = None,- limit: int = 100,- filters: dict = None, # Basic key-value only- output_format: str = None, # ❌ REMOVED- version: str = None # ❌ REMOVED-) -> Union[List[dict], dict]:- ...-```--#### v1.0.0 Signature-```python-def search(- self,- query: str,- user_id: str = None,- agent_id: str = None,- run_id: str = None,- limit: int = 100,- filters: dict = None, # ✅ ENHANCED: Advanced operators- rerank: bool = True # ✅ NEW: Reranking support-) -> dict: # Always returns dict with "results" key- ...-```--#### Enhanced Filtering--**v0.x Filters (basic):**-```python-# Simple key-value filtering only-filters = {- "category": "food",- "user_id": "alice"-}-```--**v1.0.0 Filters (enhanced):**-```python-# Advanced filtering with operators-filters = {- "AND": [- {"category": "food"},- {"score": {"gte": 0.8}},- {- "OR": [- {"priority": "high"},- {"urgent": True}- ]- }- ]-}--# Comparison operators-filters = {- "score": {"gt": 0.5}, # Greater than- "priority": {"gte": 5}, # Greater than or equal- "rating": {"lt": 3}, # Less than- "confidence": {"lte": 0.9}, # Less than or equal- "status": {"eq": "active"}, # Equal- "archived": {"ne": True}, # Not equal- "tags": {"in": ["work", "personal"]}, # In list- "category": {"nin": ["spam", "deleted"]} # Not in list-}-```--### get_all() Method--#### v0.x Signature-```python-def get_all(- self,- user_id: str = None,- agent_id: str = None,- run_id: str = None,- filters: dict = None,- output_format: str = None, # ❌ REMOVED- version: str = None # ❌ REMOVED-) -> Union[List[dict], dict]:- ...-```--#### v1.0.0 Signature-```python-def get_all(- self,- user_id: str = None,- agent_id: str = None,- run_id: str = None,- filters: dict = None # ✅ ENHANCED: Advanced operators-) -> dict: # Always returns dict with "results" key- ...-```--### update() Method--#### No Breaking Changes-```python-# Same signature in both versions-def update(- self,- memory_id: str,- data: str-) -> dict:- ...-```--### delete() Method--#### No Breaking Changes-```python-# Same signature in both versions-def delete(- self,- memory_id: str-) -> dict:- ...-```--### delete_all() Method--#### Breaking Change — Empty filter no longer silently deletes everything--**Before:** calling `delete_all()` with no filters silently deleted **all memories in the project**.--**After:**-- No filters → raises a validation error (prevents accidental full-project wipe).-- Concrete ID (e.g. `user_id="alice"`) → deletes memories for that entity (unchanged).-- `"*"` for a filter → deletes all memories for that entity type across the project (new).-- All four filters set to `"*"` → explicit full project wipe (new, requires opt-in on every parameter).--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.--```python-# v0.x — no filter silently wiped all project memories-m.delete_all() # DANGER: deleted everything-m.delete_all(user_id="alice") # deleted alice's memories--# v1.x — no filter now raises an error; use "*" for intentional bulk deletes-m.delete_all() # ERROR: at least one filter required-m.delete_all(user_id="alice") # unchanged-m.delete_all(user_id="*") # NEW — delete all users' memories-m.delete_all(user_id="*", agent_id="*", app_id="*", run_id="*") # NEW — full project wipe-```--## Platform Client (MemoryClient) Changes--### async_mode Default Changed--#### v0.x-```python-from mem0 import MemoryClient--client = MemoryClient(api_key="your-key")--# async_mode had to be explicitly set or had different default-result = client.add("content", user_id="alice", async_mode=True)-```--#### v1.0.0-```python-from mem0 import MemoryClient--client = MemoryClient(api_key="your-key")--# async_mode defaults to True now (better performance)-result = client.add("content", user_id="alice") # Uses async_mode=True by default--# Can still override if needed-result = client.add("content", user_id="alice", async_mode=False)-```--## Configuration Changes--### Memory Configuration--#### v0.x Config Options-```python-config = {- "vector_store": {...},- "llm": {...},- "embedder": {...},- "graph_store": {...},- "version": "v1.0", # ❌ v1.0 no longer supported- "history_db_path": "...",- "custom_instructions": "..."-}-```--#### v1.0.0 Config Options-```python-config = {- "vector_store": {...},- "llm": {...},- "embedder": {...},- "graph_store": {...},- "reranker": { # ✅ NEW: Reranker support- "provider": "cohere",- "config": {...}- },- "version": "v1.1", # ✅ v1.1+ only- "history_db_path": "...",- "custom_instructions": "...",- "custom_update_memory_prompt": "..." # ✅ NEW: Custom update prompt-}-```--### New Configuration Options--#### Reranker Configuration-```text-# Cohere reranker-"reranker": {- "provider": "cohere",- "config": {- "model": "rerank-english-v3.0",- "api_key": "your-api-key",- "top_k": 10- }-}--# Sentence Transformer reranker-"reranker": {- "provider": "sentence_transformer",- "config": {- "model": "cross-encoder/ms-marco-MiniLM-L-6-v2",- "device": "cuda"- }-}--# Hugging Face reranker-"reranker": {- "provider": "huggingface",- "config": {- "model": "BAAI/bge-reranker-base",- "device": "cuda"- }-}--# LLM-based reranker-"reranker": {- "provider": "llm_reranker",- "config": {- "llm": {- "provider": "openai",- "config": {- "model": "gpt-4",- "api_key": "your-api-key"- }- }- }-}-```--## Error Handling Changes--### New Error Types--#### v0.x Errors-```python-# Generic exceptions-try:- result = m.add("content", user_id="alice", version="v1.0")-except Exception as e:- print(f"Error: {e}")-```--#### v1.0.0 Errors-```python-# More specific error handling-try:- result = m.add("content", user_id="alice")-except ValueError as e:- if "v1.0 API format is no longer supported" in str(e):- # Handle version compatibility error- pass- elif "Invalid filter operator" in str(e):- # Handle filter syntax error- pass-except TypeError as e:- # Handle parameter errors- pass-except Exception as e:- # Handle unexpected errors- pass-```--### Validation Changes--#### Stricter Parameter Validation--**v0.x (Lenient):**-```python-# Unknown parameters might be ignored-result = m.add("content", user_id="alice", unknown_param="value")-```--**v1.0.0 (Strict):**-```python-# Unknown parameters raise TypeError-try:- result = m.add("content", user_id="alice", unknown_param="value")-except TypeError as e:- print(f"Invalid parameter: {e}")-```--## Response Schema Changes--### Memory Object Schema--#### v0.x Schema-```python-{- "id": "mem_123",- "memory": "User loves pizza",- "user_id": "alice",- "metadata": {...},- "created_at": "2024-01-01T00:00:00Z",- "updated_at": "2024-01-01T00:00:00Z",- "score": 0.95 # In search results-}-```--#### v1.0.0 Schema (Enhanced)-```python-{- "id": "mem_123",- "memory": "User loves pizza",- "user_id": "alice",- "agent_id": "assistant", # ✅ More context- "run_id": "session_001", # ✅ More context- "metadata": {...},- "categories": ["food"], # ✅ NEW: Auto-categorization- "immutable": false, # ✅ NEW: Immutability flag- "created_at": "2024-01-01T00:00:00Z",- "updated_at": "2024-01-01T00:00:00Z",- "score": 0.95, # In search results- "rerank_score": 0.98 # ✅ NEW: If reranking used-}-```--## Migration Code Examples--### Simple Migration--#### Before (v0.x)-```python-from mem0 import Memory--m = Memory()--# Add with deprecated parameters-result = m.add(- "I love pizza",- user_id="alice",- output_format="v1.1",- version="v1.0"-)--# Handle variable response format-if isinstance(result, list):- memories = result-else:- memories = result.get("results", [])--for memory in memories:- print(memory["memory"])-```--#### After (v1.0.0 )-```python-from mem0 import Memory--m = Memory()--# Add without deprecated parameters-result = m.add(- "I love pizza",- user_id="alice"-)--# Always dict format with "results" key-for memory in result["results"]:- print(memory["memory"])-```--### Advanced Migration--#### Before (v0.x)-```python-# Basic filtering-results = m.search(- "food preferences",- user_id="alice",- filters={"category": "food"},- output_format="v1.1"-)-```--#### After (v1.0.0 )-```python-# Enhanced filtering with reranking-results = m.search(- "food preferences",- user_id="alice",- filters={- "AND": [- {"category": "food"},- {"score": {"gte": 0.8}}- ]- },- rerank=True-)-```--## Summary--| Component | v0.x | v1.0.0 | Status |-|-----------|------|-----------|---------|-| `add()` method | Variable response | Standardized response | ⚠️ Breaking |-| `search()` method | Basic filtering | Enhanced filtering + reranking | ⚠️ Breaking |-| `get_all()` method | Variable response | Standardized response | ⚠️ Breaking |-| Response format | Variable | Always `{"results": [...]}` | ⚠️ Breaking |-| Reranking | ❌ Not available | ✅ Full support | ✅ New feature |-| Advanced filtering | ❌ Basic only | ✅ Full operators | ✅ Enhancement |-| Error handling | Generic | Specific error types | ✅ Improvement |--<Info>-Use this reference to systematically update your codebase. Test each change thoroughly before deploying to production.-</Info>