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 | - - -Use this reference to systematically update your codebase. Test each change thoroughly before deploying to production. -