add(docs): migration guide from zep to supermemory (#612)12-06-add_docs_migration_guide_from_zep_to_supermemory

add docs for Migration Guide from zep to supermemory

12 files changed, 387 insertions, 15 deletions

diff --git a/apps/docs/add-memories/overview.mdx b/apps/docs/add-memories/overview.mdx
index 5b1ecaf0..28778b0e 100644
--- a/apps/docs/add-memories/overview.mdx
+++ b/apps/docs/add-memories/overview.mdx
@@ -245,7 +245,7 @@ curl -X PATCH "https://api.supermemory.ai/v3/documents/doc_id" \
 
 ## Next Steps
 
-- [Track Processing Status](/api/track-progress) - Monitor document processing
+- [Track Processing Status](/memory-api/track-progress) - Monitor document processing
 - [Search Memories](/search/overview) - Search your content
 - [List Memories](/list-memories/overview) - Browse stored memories
 - [Update & Delete](/update-delete-memories/overview) - Manage memories
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 5ec94339..22b3e9ff 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -174,7 +174,7 @@
 							},
 							{
 								"group": "Migration Guides",
-								"pages": ["migration/from-mem0"]
+								"pages": ["migration/from-mem0", "migration/from-zep"]
 							},
 							{
 								"group": "Deployment",
diff --git a/apps/docs/intro.mdx b/apps/docs/intro.mdx
index efdcee38..3f6d64a9 100644
--- a/apps/docs/intro.mdx
+++ b/apps/docs/intro.mdx
@@ -58,7 +58,7 @@ Along with the user context, developers can also choose to do a search on the ra
 - Works well with the memory engine
 
 <Info>
-    You can reference the full API reference for the Memory API [here](/api-reference/manage-documents/add-document).
+    You can reference the full API reference for the Memory API in the API Reference tab.
 </Info>
 
 
diff --git a/apps/docs/memory-api/creation/adding-memories.mdx b/apps/docs/memory-api/creation/adding-memories.mdx
index 9b34b3bb..a8837e3c 100644
--- a/apps/docs/memory-api/creation/adding-memories.mdx
+++ b/apps/docs/memory-api/creation/adding-memories.mdx
@@ -373,4 +373,4 @@ requests.patch(
 
 ## Next Steps
 
-Explore more advanced features in our [API Reference](/api-reference/manage-memories/add-memory)
+Explore more advanced features in our API Reference tab.
diff --git a/apps/docs/memory-api/introduction.mdx b/apps/docs/memory-api/introduction.mdx
index 8ff4547e..ca4fa705 100644
--- a/apps/docs/memory-api/introduction.mdx
+++ b/apps/docs/memory-api/introduction.mdx
@@ -31,7 +31,7 @@ Check out the following resources to get started:
   <Card title="Quickstart" icon="zap" href="/memory-api/overview">
     Get started in 5 minutes
   </Card>
-  <Card title="API Reference" icon="unplug" href="/api-reference">
+  <Card title="API Reference" icon="unplug">
     Learn more about the API
   </Card>
   <Card title="Use Cases" icon="brain" href="/overview/use-cases">
diff --git a/apps/docs/memory-api/overview.mdx b/apps/docs/memory-api/overview.mdx
index 33771e2c..c201f157 100644
--- a/apps/docs/memory-api/overview.mdx
+++ b/apps/docs/memory-api/overview.mdx
@@ -81,7 +81,7 @@ client.memory.add(
 
 This will add a new memory to your supermemory account.
 
-Try it out in the [API Playground](/api-reference/manage-memories/add-memory).
+Try it out in the API Reference tab.
 
 ## Content Processing
 
@@ -132,7 +132,7 @@ client.search.execute(
 
 </CodeGroup>
 
-Try it out in the [API Playground](/api-reference/search-memories/search-memories).
+Try it out in the API Reference tab.
 
 You can do a lot more with supermemory, and we will walk through everything you need to.
 
diff --git a/apps/docs/memory-api/searching/searching-memories.mdx b/apps/docs/memory-api/searching/searching-memories.mdx
index 517b835d..6e5f3454 100644
--- a/apps/docs/memory-api/searching/searching-memories.mdx
+++ b/apps/docs/memory-api/searching/searching-memories.mdx
@@ -178,4 +178,4 @@ Forgotten memories are memories that have been explicitly forgotten using the fo
 
 ## Next Steps
 
-Explore more advanced features in our [API Reference](/api-reference/search-memories/search-memories).
+Explore more advanced features in our API Reference tab.
diff --git a/apps/docs/memory-api/track-progress.mdx b/apps/docs/memory-api/track-progress.mdx
index 1d02cc0d..e14d7739 100644
--- a/apps/docs/memory-api/track-progress.mdx
+++ b/apps/docs/memory-api/track-progress.mdx
@@ -154,7 +154,7 @@ curl -X GET "https://api.supermemory.ai/v3/documents/doc_abc123" \
 }
 ```
 
-For more comprehensive information on the get documents by ID endpoint, refer to the [API reference.](/api-reference/manage-documents/get-document)
+For more comprehensive information on the get documents by ID endpoint, refer to the API Reference tab.
 
 ## Status Values
 
diff --git a/apps/docs/migration/from-zep.mdx b/apps/docs/migration/from-zep.mdx
new file mode 100644
index 00000000..a109a157
--- /dev/null
+++ b/apps/docs/migration/from-zep.mdx
@@ -0,0 +1,372 @@
+---
+title: "Migrating from Zep to Supermemory"
+description: "Quick guide to migrate from Zep to Supermemory"
+sidebarTitle: "From Zep"
+---
+
+## Key Differences
+
+| Zep AI | Supermemory |
+|--------|-------------|
+| Sessions & Messages | Documents & Container Tags |
+| `session.create()` | Use `containerTags` parameter |
+| `memory.add(session_id, ...)` | `add({containerTag: [...]})` |
+| `memory.search(session_id, {text: ...})` | `search.execute({q: ..., containerTags: [...]})` |
+
+## Installation
+
+<CodeGroup>
+
+```bash Python
+pip install supermemory
+```
+
+```bash TypeScript
+npm install supermemory
+```
+
+</CodeGroup>
+
+<CodeGroup>
+
+```python Python
+from supermemory import Supermemory
+client = Supermemory(api_key="your-api-key")
+```
+
+```typescript TypeScript
+import { Supermemory } from "supermemory";
+const client = new Supermemory({ apiKey: "your-api-key" });
+```
+
+</CodeGroup>
+
+## API Mapping
+
+### Session Management
+
+<CodeGroup>
+
+```python Zep AI
+session = client.session.create(
+    session_id="user_123",
+    user_id="user_123"
+)
+```
+
+```python Supermemory
+# No explicit session creation - use containerTag
+containerTag = ["user_123"]
+```
+
+</CodeGroup>
+
+### Adding Memories
+
+<CodeGroup>
+
+```python Zep AI
+client.memory.add(
+    session_id="user_123",
+    memory={"content": "User prefers dark mode"}
+)
+```
+
+```python Supermemory
+client.add({
+    "content": "User prefers dark mode",
+    "containerTag": ["user_123"]
+})
+```
+
+</CodeGroup>
+
+### Searching
+
+<CodeGroup>
+
+```python Zep AI
+results = client.memory.search(
+    session_id="user_123",
+    search_payload={"text": "preferences", "limit": 5}
+)
+```
+
+```python Supermemory
+results = client.search.execute({
+    "q": "preferences",
+    "containerTag": ["user_123"],
+    "limit": 5
+})
+```
+
+</CodeGroup>
+
+### Getting All Memories
+
+<CodeGroup>
+
+```python Zep AI
+memories = client.memory.get(session_id="user_123")
+```
+
+```python Supermemory
+documents = client.memories.list({
+    "containerTag": ["user_123"],
+    "limit": 100
+})
+```
+
+</CodeGroup>
+
+## Migration Steps
+
+1. **Replace client initialization** - Use Supermemory client instead of Zep
+2. **Map sessions to container tags** - Replace `session_id="user_123"` with `containerTag: ["user_123"]`
+3. **Update method calls** - Use `add()` and `search.execute()` instead of `memory.add()` and `memory.search()`
+4. **Change search parameter** - Use `q` instead of `text`
+5. **Handle async processing** - Documents process asynchronously (status: `queued` → `done`)
+
+## Complete Example
+
+<CodeGroup>
+
+```python Zep AI
+from zep_python import ZepClient
+
+client = ZepClient(api_key="...")
+session = client.session.create(session_id="user_123", user_id="user_123")
+
+client.memory.add("user_123", {
+    "content": "I love Python",
+    "role": "user"
+})
+
+results = client.memory.search("user_123", {
+    "text": "programming",
+    "limit": 3
+})
+```
+
+```python Supermemory
+from supermemory import Supermemory
+
+client = Supermemory(api_key="...")
+containerTag = ["user_123"]
+
+client.add({
+    "content": "I love Python",
+    "containerTag": containerTag,
+    "metadata": {"role": "user"}
+})
+
+results = client.search.execute({
+    "q": "programming",
+    "containerTag": containerTag,
+    "limit": 3
+})
+```
+
+</CodeGroup>
+
+## Important Notes
+
+- **No session creation needed** - Just use `containerTag` in requests
+- **Messages are documents** - Store with `metadata.role` and `metadata.type`
+- **Async processing** - Documents may take a moment to be searchable
+- **Response structure** - Supermemory returns chunks with scores, not direct memory content
+
+## Migrating Existing Data
+
+### Quick Migration (All-in-One)
+
+Complete migration in one script:
+
+<CodeGroup>
+
+```typescript TypeScript
+import { ZepClient } from "@getzep/zep-js";
+import { Supermemory } from "supermemory";
+
+// Initialize clients
+const zep = new ZepClient({ apiKey: "your_zep_api_key" });
+const supermemory = new Supermemory({ apiKey: "your_supermemory_api_key" });
+
+// Export from Zep and import to Supermemory
+const sessionIds = ["session_1", "session_2"]; // Add your session IDs
+
+for (const sessionId of sessionIds) {
+  const memory = await zep.memory.get(sessionId);
+  const memories = memory?.memories || [];
+
+  for (const mem of memories) {
+    if (mem.content) {
+      await supermemory.add({
+        content: mem.content,
+        containerTag: [`session_${sessionId}`, `user_${memory.user_id || "unknown"}`],
+        metadata: {
+          role: mem.role,
+          type: "message",
+          original_uuid: mem.uuid,
+          ...mem.metadata
+        }
+      });
+      console.log(`✅ Imported: ${mem.content.substring(0, 50)}...`);
+    }
+  }
+}
+
+console.log("Migration complete!");
+```
+
+```python Python
+from zep_python import ZepClient
+from supermemory import Supermemory
+
+# Initialize clients
+zep = ZepClient(api_key="your_zep_api_key")
+supermemory = Supermemory(api_key="your_supermemory_api_key")
+
+# Export from Zep and import to Supermemory
+session_ids = ["session_1", "session_2"]  # Add your session IDs
+
+for session_id in session_ids:
+    memory = zep.memory.get(session_id)
+    memories = memory.memories if memory else []
+
+    for mem in memories:
+        if mem.content:
+            supermemory.add({
+                "content": mem.content,
+                "containerTag": [f"session_{session_id}", f"user_{memory.user_id or 'unknown'}"],
+                "metadata": {
+                    "role": mem.role,
+                    "type": "message",
+                    "original_uuid": mem.uuid,
+                    **(mem.metadata or {})
+                }
+            })
+            print(f"✅ Imported: {mem.content[:50]}...")
+
+print("Migration complete!")
+```
+
+</CodeGroup>
+
+### Full Migration Script
+
+For a complete migration script with error handling, verification, and progress tracking, copy this TypeScript script:
+
+```typescript
+import { ZepClient } from "@getzep/zep-js";
+import { Supermemory } from "supermemory";
+import * as dotenv from "dotenv";
+import * as fs from "fs";
+
+dotenv.config();
+
+interface MigrationStats {
+  imported: number;
+  failed: number;
+  skipped: number;
+}
+
+async function migrateFromZep(
+  zepApiKey: string,
+  supermemoryApiKey: string,
+  sessionIds: string[]
+) {
+  const zep = new ZepClient({ apiKey: zepApiKey });
+  const supermemory = new Supermemory({ apiKey: supermemoryApiKey });
+
+  const stats: MigrationStats = { imported: 0, failed: 0, skipped: 0 };
+  const exportedData: any = {};
+
+  console.log("🔄 Starting migration...");
+
+  // Export from Zep
+  for (const sessionId of sessionIds) {
+    try {
+      const session = await zep.session.get(sessionId);
+      const memory = await zep.memory.get(sessionId);
+      const memories = memory?.memories || [];
+
+      exportedData[sessionId] = {
+        session: { session_id: sessionId, user_id: session?.user_id },
+        memories: memories.map((m: any) => ({
+          content: m.content,
+          role: m.role,
+          metadata: m.metadata,
+          uuid: m.uuid,
+        })),
+      };
+
+      console.log(`✅ Exported ${memories.length} memories from ${sessionId}`);
+    } catch (error: any) {
+      console.log(`❌ Error exporting ${sessionId}: ${error.message}`);
+    }
+  }
+
+  // Save backup
+  const backupFile = `zep_export_${Date.now()}.json`;
+  fs.writeFileSync(backupFile, JSON.stringify(exportedData, null, 2));
+  console.log(`💾 Backup saved to: ${backupFile}`);
+
+  // Import to Supermemory
+  let totalMemories = 0;
+  for (const [sessionId, data] of Object.entries(exportedData) as any) {
+    const containerTag = ["imported_from_zep", `session_${sessionId}`];
+    if (data.session.user_id) {
+      containerTag.push(`user_${data.session.user_id}`);
+    }
+
+    for (const memory of data.memories) {
+      totalMemories++;
+      try {
+        if (!memory.content?.trim()) {
+          stats.skipped++;
+          continue;
+        }
+
+        await supermemory.add({
+          content: memory.content,
+          containerTag: containerTag,
+          metadata: {
+            source: "zep_migration",
+            role: memory.role,
+            type: "message",
+            original_uuid: memory.uuid,
+            ...memory.metadata,
+          },
+        });
+
+        stats.imported++;
+        console.log(`✅ [${stats.imported}/${totalMemories}] Imported`);
+      } catch (error: any) {
+        stats.failed++;
+        console.log(`❌ Failed: ${error.message}`);
+      }
+    }
+  }
+
+  console.log("\n📊 Migration Summary:");
+  console.log(`✅ Imported: ${stats.imported}`);
+  console.log(`⚠️  Skipped: ${stats.skipped}`);
+  console.log(`❌ Failed: ${stats.failed}`);
+}
+
+// Usage
+const sessionIds = ["session_1", "session_2"]; // Add your session IDs
+migrateFromZep(
+  process.env.ZEP_API_KEY!,
+  process.env.SUPERMEMORY_API_KEY!,
+  sessionIds
+).catch(console.error);
+```
+
+
+## Resources
+
+- [Supermemory SDKs](/memory-api/sdks/overview)
+- [API Reference](/memory-api/overview)
+- [Search Documentation](/search/overview)
diff --git a/apps/docs/n8n.mdx b/apps/docs/n8n.mdx
index d3f50bd5..f68b1f7f 100644
--- a/apps/docs/n8n.mdx
+++ b/apps/docs/n8n.mdx
@@ -50,7 +50,7 @@ Follow these steps to build a workflow that captures and stores your Gmail messa
 
 1. **Add an HTTP Request node** after the Gmail Trigger
 2. **Method**: `POST`
-3. **URL**: [`https://api.supermemory.ai/v3/documents`](/api-reference/manage-documents/add-document)
+3. **URL**: `https://api.supermemory.ai/v3/documents`
 4. Select your auth credentials you created with the Supermemory API Key.
 
 #### Step 3: Format Email Data for Supermemory
@@ -89,4 +89,4 @@ If you want to process attachments:
 3. Check the execution to ensure the email was captured
 4. Verify in Supermemory that the email appears in search results
 
-Refer to the [API reference](/api-reference/manage-documents/add-document) to learn more about other supermemory API endpoints.
\ No newline at end of file
+Refer to the API Reference tab to learn more about other supermemory API endpoints.
\ No newline at end of file
diff --git a/apps/docs/search/overview.mdx b/apps/docs/search/overview.mdx
index 575d87b5..3f888b02 100644
--- a/apps/docs/search/overview.mdx
+++ b/apps/docs/search/overview.mdx
@@ -369,7 +369,7 @@ curl -X GET "https://api.supermemory.ai/v3/documents/{YOUR-DOCUMENT-ID}" \
 </CodeGroup>
 
 <Note>
-This endpoint returns the complete document with all fields including content, metadata, containerTags, summary, and processing status. For more details, see the [API reference](/api-reference/manage-documents/get-document).
+This endpoint returns the complete document with all fields including content, metadata, containerTags, summary, and processing status. For more details, see the API Reference tab.
 </Note>
 
 ## Search Flow Architecture
diff --git a/apps/docs/zapier.mdx b/apps/docs/zapier.mdx
index d1e48b40..d7398ab4 100644
--- a/apps/docs/zapier.mdx
+++ b/apps/docs/zapier.mdx
@@ -7,7 +7,7 @@ description: "Learn how to use the code block to integrate supermemory with  Zap
 With Supermemory you can now easily add memory to your Zapier workflow steps. Here's how:
 
 ## Prerequisites
-- A Supermemory API Key. Get yours [here](console.supermemory.ai)
+- A Supermemory API Key. Get yours [here](https://console.supermemory.ai)
 
 ## Step-by-step tutorial
 
@@ -30,7 +30,7 @@ For this tutorial, we're building a simple flow that adds incoming emails in Gma
         ![](/images/map-content-to-gmail.png)
     </Step>
     <Step title="Integrate Supermemory">
-        Since we're ingesting data here, we'll use the [add documents endpoint.](/api-reference/manage-documents/add-document)
+        Since we're ingesting data here, we'll use the add documents endpoint.
 
         Add the following code block:
         
@@ -61,4 +61,4 @@ For this tutorial, we're building a simple flow that adds incoming emails in Gma
 </Note>
 
 
-You can perform other operations like search, filtering, user profiles, etc., by using other Supermemory API endpoints which can be found in our [API Reference.](api-reference/search/search-memory-entries)
\ No newline at end of file
+You can perform other operations like search, filtering, user profiles, etc., by using other Supermemory API endpoints which can be found in our API Reference tab.
\ No newline at end of file