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: migration guide v1 (#3822)
Parth Sharma5676bebd5f36
diff --git a/docs/docs.json b/docs/docs.jsonindex 2f3d2f566..5befd49e5 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -24,9 +24,7 @@{"group": "Start Here","icon": "home",- "pages": [- "introduction"- ]+ "pages": ["introduction"]}]},@@ -107,14 +105,13 @@{"group": "Support & Troubleshooting","icon": "life-buoy",- "pages": [- "platform/faqs"- ]+ "pages": ["platform/faqs"]},{"group": "Migration Guide","icon": "arrow-right","pages": [+ "migration/oss-to-platform","migration/v0-to-v1","migration/breaking-changes","migration/api-changes"@@ -123,9 +120,7 @@{"group": "Contribute","icon": "clipboard-list",- "pages": [- "platform/contribute"- ]+ "pages": ["platform/contribute"]}]},@@ -280,10 +275,7 @@{"group": "Community & Support","icon": "users",- "pages": [- "contributing/development",- "contributing/documentation"- ]+ "pages": ["contributing/development", "contributing/documentation"]}]},@@ -307,9 +299,7 @@{"group": "Getting Started","icon": "lightbulb",- "pages": [- "cookbooks/overview"- ]+ "pages": ["cookbooks/overview"]},{"group": "Essentials",@@ -381,9 +371,7 @@{"group": "Overview","icon": "plug",- "pages": [- "integrations"- ]+ "pages": ["integrations"]},{"group": "Agent Frameworks",@@ -413,9 +401,7 @@{"group": "Cloud & Infrastructure","icon": "cloud",- "pages": [- "integrations/aws-bedrock"- ]+ "pages": ["integrations/aws-bedrock"]},{"group": "Developer Tools",@@ -437,10 +423,7 @@{"group": "Getting Started","icon": "rocket",- "pages": [- "api-reference",- "api-reference/organizations-projects"- ]+ "pages": ["api-reference", "api-reference/organizations-projects"]},{"group": "Core Memory Operations",@@ -470,10 +453,7 @@{"group": "Events APIs","icon": "clock",- "pages": [- "api-reference/events/get-events",- "api-reference/events/get-event"- ]+ "pages": ["api-reference/events/get-events", "api-reference/events/get-event"]},{"group": "Entities APIs",@@ -525,16 +505,12 @@{"group": "Changelog","icon": "rocket",- "pages": [- "changelog"- ]+ "pages": ["changelog"]},{"group": "Legacy Docs","icon": "archive",- "pages": [- "v0x/introduction"- ]+ "pages": ["v0x/introduction"]}]}@@ -555,11 +531,7 @@{"group": "Getting Started","icon": "rocket",- "pages": [- "v0x/introduction",- "v0x/quickstart",- "v0x/faqs"- ]+ "pages": ["v0x/introduction", "v0x/quickstart", "v0x/faqs"]},{"group": "Core Concepts",@@ -1075,4 +1047,4 @@"destination": "/platform/features/memory-export"}]-}\ No newline at end of file+}diff --git a/docs/migration/oss-to-platform.mdx b/docs/migration/oss-to-platform.mdxnew file mode 100644index 000000000..e9efea36e--- /dev/null+++ b/docs/migration/oss-to-platform.mdx@@ -0,0 +1,388 @@+---+title: "Migrate from Open Source to Platform"+description: "Migrate your Mem0 Open Source implementation to Mem0 Platform for managed infrastructure and advanced features."+icon: "cloud-arrow-up"+versionFrom: "Open Source"+versionTo: "Platform"+---++# Migrate from Open Source to Platform++Move your Mem0 implementation to managed infrastructure with enterprise features.++| Scope | Effort | Downtime |+| --------------------- | -------------- | ---------------------------- |+| Infrastructure & Code | Low (~30 mins) | None (Parallel run possible) |++<Info>+ **Why migrate to Platform?**++ - **Time to Market**: Set up in 5 minutes vs 30+ minutes for OSS configuration+ - **Enterprise Ready**: SOC2 Type II compliance, GDPR support, audit logs+ - **Advanced Features**: Webhooks, memory export, analytics dashboard, custom categories+ - **Multi-tenancy**: Organizations, projects, and team management out of the box+ - **Zero Infrastructure**: No vector database, LLM provider, or maintenance overhead+ - **Enhanced Search**: Reranking, keyword expansion, and advanced filters+ - **Production Grade**: Auto-scaling, high availability, dedicated support+</Info>++## Plan++1. **Sign up**: Create an account on [Mem0 Platform](https://app.mem0.ai).+2. **Get API Key**: Navigate to **Settings > API Keys** and generate a new key.+3. **Review Usage**: Identify where you instantiate `Memory` and where you call `search` or `get_all`.++## Migrate++### 1. Install or Update SDK++Ensure you have the latest version of the SDK, which supports both OSS and Platform clients.++```bash+pip install mem0ai --upgrade+```++### 2. Update Initialization++Switch from the local `Memory` class to the managed `MemoryClient`.++```python Open Source (Old)+from mem0 import Memory++config = {+ "vector_store": {+ "provider": "qdrant",+ "config": {"host": "localhost", "port": 6333}+ },+ "llm": {+ "provider": "openai",+ "config": {"model": "gpt-4"}+ }+}++m = Memory.from_config(config)+```++```python Platform (New)+from mem0 import MemoryClient+import os++# Set MEM0_API_KEY in environment or pass explicitly+client = MemoryClient(api_key="m0-...")+```++<Info icon="check">+ Run `client.get_all(filters={"user_id": "test_connection"})` to verify your API key works. It should return an empty list or valid results.+</Info>++### 3. Update Retrieval Calls (Critical)++<Warning>+ **Critical Change**: Platform uses v2 endpoints that require filtering parameters to be nested inside a `filters` dictionary.+</Warning>++| Method | Open Source | Platform |+| ------ | ----------- | -------- |+| `search()` | `m.search(query, user_id="alex")` | `client.search(query, filters={"user_id": "alex"})` |+| `get_all()` | `m.get_all(user_id="alex")` | `client.get_all(filters={"user_id": "alex"})` |+| `add()` | `m.add(memory, user_id="alex")` | `client.add(memory, user_id="alex")` |+| `delete()` | `m.delete(memory_id)` | `client.delete(memory_id)` |+| `delete_all()` | `m.delete_all(user_id="alex")` | `client.delete_all(user_id="alex")` |++Note: `add()` and `delete()` methods remain unchanged. The `update()` method is not available in Platform - use delete + add pattern instead.++<AccordionGroup>+ <Accordion title="Search Memories">+ <CodeGroup>+ ```python Open Source (Old)+ # Basic search with user filter+ results = m.search("user's preferences", user_id="alex")++ # Search with multiple filters+ results = m.search("meeting notes", user_id="alex", agent_id="assistant")+ ```++ ```python Platform (New)+ # Basic search with user filter in filters dict+ results = client.search("user's preferences", filters={"user_id": "alex"})++ # Search with multiple filters+ results = client.search("meeting notes", filters={+ "AND": [+ {"user_id": "alex"},+ {"agent_id": "assistant"}+ ]+ })+ ```+ </CodeGroup>+ </Accordion>++ <Accordion title="Get All Memories">+ <CodeGroup>+ ```python Open Source (Old)+ # Get all memories for a user+ memories = m.get_all(user_id="alex", limit=10)++ # Get memories with pagination+ memories = m.get_all(user_id="alex", limit=5, offset=10)+ ```++ ```python Platform (New)+ # Get all memories for a user+ memories = client.get_all(filters={"user_id": "alex"}, limit=10)++ # Get memories with pagination+ memories = client.get_all(filters={"user_id": "alex"}, limit=5, offset=10)+ ```+ </CodeGroup>+ </Accordion>++ <Accordion title="Add Memories">+ <CodeGroup>+ ```python Open Source (Old)+ # Add a simple memory+ m.add("Loves coffee", user_id="alex")++ # Add memory with metadata+ m.add("Completed marathon", user_id="alex", metadata={"category": "achievement"})+ ```++ ```python Platform (New)+ # Add a simple memory (no change)+ client.add("Loves coffee", user_id="alex")++ # Add memory with metadata (no change)+ client.add("Completed marathon", user_id="alex", metadata={"category": "achievement"})+ ```+ </CodeGroup>+ </Accordion>++ <Accordion title="Delete Memories">+ <CodeGroup>+ ```python Open Source (Old)+ # Delete specific memory+ m.delete(memory_id="mem_123")++ # Delete all memories for user+ m.delete_all(user_id="alex")+ ```++ ```python Platform (New)+ # Delete specific memory (no change)+ client.delete(memory_id="mem_123")++ # Delete all memories for user (no change)+ client.delete_all(user_id="alex")+ ```+ </CodeGroup>+ </Accordion>++ <Accordion title="Update Memory">+ <CodeGroup>+ ```python Open Source (Old)+ # Update memory content+ m.update(memory_id="mem_123", new_memory="Updated content")+ ```++ ```python Platform (New)+ # Update memory (not available in Platform)+ # Use delete + add pattern instead+ client.delete(memory_id="mem_123")+ client.add("Updated content", user_id="alex")+ ```+ </CodeGroup>+ </Accordion>+</AccordionGroup>++## Platform-Exclusive Features++The Platform introduces powerful capabilities not available in OSS:++<AccordionGroup>+ <Accordion title="Organizations & Multi-tenancy">+ <Info>+ **Why it matters**: Manage multiple teams and projects with hierarchical access control.+ </Info>+ ```python+ # Create an organization+ org = client.organizations.create(name="Acme Corp")++ # Create projects within the organization+ project = client.projects.create(+ name="Customer Support Bot",+ org_id=org.id+ )++ # Add team members+ client.organizations.add_member(+ org_id=org.id,+ email="[email protected]",+ role="admin"+ )+ ```+ </Accordion>++ <Accordion title="Webhooks for Real-time Events">+ <Info>+ **Why it matters**: Instantly react to memory changes in your application. Build features like notifications, audit logs, or sync with external systems.+ </Info>+ ```python+ # Create webhook for memory events+ webhook = client.webhooks.create(+ project_id="proj_123",+ name="Memory Events",+ url="https://your-app.com/webhooks/mem0",+ events=["memory_add", "memory_delete"]+ )++ # Webhook payload example:+ # {+ # "event": "memory_add",+ # "memory_id": "mem_456",+ # "user_id": "user_789",+ # "memory": "User prefers dark mode",+ # "timestamp": "2024-01-15T10:30:00Z"+ # }+ ```+ </Accordion>++ <Accordion title="Memory Export">+ <Info>+ **Why it matters**: Export your data for compliance, analytics, or migration with custom schemas and filters.+ </Info>+ ```python+ # Export memories with custom schema+ export_job = client.memories.export(+ filters={+ "AND": [+ {"user_id": "user_123"},+ {"created_at": {"gte": "2024-01-01"}}+ ]+ },+ output_format="json",+ schema={+ "memory": str,+ "categories": list[str],+ "timestamp": str+ }+ )++ # Download when ready+ if client.memories.get_export(export_job.id).status == "completed":+ data = client.memories.download_export(export_job.id)+ ```+ </Accordion>++ <Accordion title="Enhanced Search">+ <Info>+ **Why it matters**: Get better search results with AI-powered reranking and keyword expansion.+ </Info>+ ```python+ # Search with reranking for better results+ results = client.search(+ "user preferences",+ filters={"user_id": "alex"},+ rerank=True, # Platform exclusive+ limit=5+ )++ # Search with keyword expansion+ results = client.search(+ "coffee order",+ filters={"user_id": "alex"},+ keywords=["latte", "espresso", "cappuccino"],+ expand_keywords=True+ )+ ```+ </Accordion>++ <Accordion title="Custom Categories">+ <Info>+ **Why it matters**: Use domain-specific categories instead of generic ones for better organization.+ </Info>+ ```python+ # Set custom categories for your project+ client.projects.update_categories(+ project_id="proj_123",+ categories=[+ "Customer Preferences",+ "Product Feedback",+ "Support Issues",+ "Feature Requests"+ ]+ )++ # Memories will use these categories+ client.add(+ "User wants dark mode in dashboard",+ user_id="alex",+ categories=["Customer Preferences"]+ )+ ```+ </Accordion>++ <Accordion title="Events API for Analytics">+ <Info>+ **Why it matters**: Track all memory operations for audit trails, usage analytics, and debugging.+ </Info>+ ```python+ # Get audit trail of all memory operations+ events = client.events.list(+ filters={+ "AND": [+ {"user_id": "alex"},+ {"event_type": "memory_add"},+ {"timestamp": {"gte": "2024-01-01"}}+ ]+ },+ limit=100+ )++ # Monitor usage patterns+ for event in events:+ print(f"{event.timestamp}: {event.event_type} - {event.memory_id}")+ ```+ </Accordion>+</AccordionGroup>++## Summary of Changes++| Feature | Open Source | Platform | Action Required |+| ------- | ----------- | -------- | --------------- |+| **Initialization** | `Memory.from_config(config)` | `MemoryClient(api_key)` | Replace config object with API key |+| **Search Method** | `m.search(query, user_id="x")` | `client.search(query, filters={"user_id": "x"})` | Move filtering params into `filters` dict |+| **Get All Method** | `m.get_all(user_id="x")` | `client.get_all(filters={"user_id": "x"})` | Move filtering params into `filters` dict |+| **Add Method** | `m.add(memory, user_id="x")` | `client.add(memory, user_id="x")` | No change |+| **Delete Method** | `m.delete(memory_id)` | `client.delete(memory_id)` | No change |+| **Delete All** | `m.delete_all(user_id="x")` | `client.delete_all(user_id="x")` | No change |+| **Update Method** | `m.update(memory_id, new_memory)` | Use delete + add pattern | Replace with delete then add |+| **Config** | Local vector store + LLM config | Managed cloud infrastructure | Remove local config setup |++## Rollback plan++If you encounter issues, you can revert immediately by switching your import back.++1. **Revert Code**: Change `MemoryClient` back to `Memory`.+2. **Restore Config**: Uncomment your local vector store and LLM configuration.+3. **Verify**: Ensure your local vector database is still running and accessible.++## Next Steps++- [Platform Dashboard](https://app.mem0.ai) - Monitor usage and manage settings.+- [Webhooks Setup](/platform/features/webhooks) - Configure real-time event notifications.+- [Organizations & Projects](/platform/features/organizations-projects) - Set up multi-tenancy for your team.++<CardGroup cols={2}>+ <Card+ title="Platform Features"+ description="Explore capabilities exclusive to the Platform."+ icon="sparkles"+ href="/platform/overview"+ />+ <Card+ title="API Reference"+ description="Deep dive into the Platform API endpoints."+ icon="code"+ href="/api-reference/memory/add-memories"+ />+</CardGroup>