JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: migration guide v1 (#3822)

Browse Source
This commit is contained in:
Parth Sharma
2025-12-10 23:45:19 +05:30
committed by GitHub
parent f14132db44
commit 5676bebd5f
2 changed files with 402 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs.json
+13 -41
View File
@@ -24,9 +24,7 @@
{ {
"group": "Start Here", "group": "Start Here",
"icon": "home", "icon": "home",
"pages": [ "pages": ["introduction"]
"introduction"
]
} }
] ]
}, },
@@ -107,14 +105,13 @@
{ {
"group": "Support & Troubleshooting", "group": "Support & Troubleshooting",
"icon": "life-buoy", "icon": "life-buoy",
"pages": [ "pages": ["platform/faqs"]
"platform/faqs"
]
}, },
{ {
"group": "Migration Guide", "group": "Migration Guide",
"icon": "arrow-right", "icon": "arrow-right",
"pages": [ "pages": [
"migration/oss-to-platform",
"migration/v0-to-v1", "migration/v0-to-v1",
"migration/breaking-changes", "migration/breaking-changes",
"migration/api-changes" "migration/api-changes"
@@ -123,9 +120,7 @@
{ {
"group": "Contribute", "group": "Contribute",
"icon": "clipboard-list", "icon": "clipboard-list",
"pages": [ "pages": ["platform/contribute"]
"platform/contribute"
]
} }
] ]
}, },
@@ -280,10 +275,7 @@
{ {
"group": "Community & Support", "group": "Community & Support",
"icon": "users", "icon": "users",
"pages": [ "pages": ["contributing/development", "contributing/documentation"]
"contributing/development",
"contributing/documentation"
]
} }
] ]
}, },
@@ -307,9 +299,7 @@
{ {
"group": "Getting Started", "group": "Getting Started",
"icon": "lightbulb", "icon": "lightbulb",
"pages": [ "pages": ["cookbooks/overview"]
"cookbooks/overview"
]
}, },
{ {
"group": "Essentials", "group": "Essentials",
@@ -381,9 +371,7 @@
{ {
"group": "Overview", "group": "Overview",
"icon": "plug", "icon": "plug",
"pages": [ "pages": ["integrations"]
"integrations"
]
}, },
{ {
"group": "Agent Frameworks", "group": "Agent Frameworks",
@@ -413,9 +401,7 @@
{ {
"group": "Cloud & Infrastructure", "group": "Cloud & Infrastructure",
"icon": "cloud", "icon": "cloud",
"pages": [ "pages": ["integrations/aws-bedrock"]
"integrations/aws-bedrock"
]
}, },
{ {
"group": "Developer Tools", "group": "Developer Tools",
@@ -437,10 +423,7 @@
{ {
"group": "Getting Started", "group": "Getting Started",
"icon": "rocket", "icon": "rocket",
"pages": [ "pages": ["api-reference", "api-reference/organizations-projects"]
"api-reference",
"api-reference/organizations-projects"
]
}, },
{ {
"group": "Core Memory Operations", "group": "Core Memory Operations",
@@ -470,10 +453,7 @@
{ {
"group": "Events APIs", "group": "Events APIs",
"icon": "clock", "icon": "clock",
"pages": [ "pages": ["api-reference/events/get-events", "api-reference/events/get-event"]
"api-reference/events/get-events",
"api-reference/events/get-event"
]
}, },
{ {
"group": "Entities APIs", "group": "Entities APIs",
@@ -525,16 +505,12 @@
{ {
"group": "Changelog", "group": "Changelog",
"icon": "rocket", "icon": "rocket",
"pages": [ "pages": ["changelog"]
"changelog"
]
}, },
{ {
"group": "Legacy Docs", "group": "Legacy Docs",
"icon": "archive", "icon": "archive",
"pages": [ "pages": ["v0x/introduction"]
"v0x/introduction"
]
} }
] ]
} }
@@ -555,11 +531,7 @@
{ {
"group": "Getting Started", "group": "Getting Started",
"icon": "rocket", "icon": "rocket",
"pages": [ "pages": ["v0x/introduction", "v0x/quickstart", "v0x/faqs"]
"v0x/introduction",
"v0x/quickstart",
"v0x/faqs"
]
}, },
{ {
"group": "Core Concepts", "group": "Core Concepts",
docs/migration/oss-to-platform.mdx
+388
View File
@@ -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="team@acme.com",
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>