Skip to content

armgit / mem0

Public Imported from GitHub
0

The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.

docs: remove inaccurate api-changes migration page (#5857)

Kartikee600705c2e1
diff --git a/docs/docs.json b/docs/docs.json
index 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.txt
index 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.mdx
deleted file mode 100644
index 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>