> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-temp-snowcone-command.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from Zep to Supermemory

> Quick guide to migrate from Zep to Supermemory

## 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 theme={null}
  pip install supermemory
  ```

  ```bash TypeScript theme={null}
  npm install supermemory
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  from supermemory import Supermemory
  client = Supermemory(api_key="your-api-key")
  ```

  ```typescript TypeScript theme={null}
  import { Supermemory } from "supermemory";
  const client = new Supermemory({ apiKey: "your-api-key" });
  ```
</CodeGroup>

## API Mapping

### Session Management

<CodeGroup>
  ```python Zep AI theme={null}
  session = client.session.create(
      session_id="user_123",
      user_id="user_123"
  )
  ```

  ```python Supermemory theme={null}
  # No explicit session creation - use containerTag
  containerTag = ["user_123"]
  ```
</CodeGroup>

### Adding Memories

<CodeGroup>
  ```python Zep AI theme={null}
  client.memory.add(
      session_id="user_123",
      memory={"content": "User prefers dark mode"}
  )
  ```

  ```python Supermemory theme={null}
  client.add({
      "content": "User prefers dark mode",
      "containerTag": ["user_123"]
  })
  ```
</CodeGroup>

### Searching

<CodeGroup>
  ```python Zep AI theme={null}
  results = client.memory.search(
      session_id="user_123",
      search_payload={"text": "preferences", "limit": 5}
  )
  ```

  ```python Supermemory theme={null}
  results = client.search.execute({
      "q": "preferences",
      "containerTag": ["user_123"],
      "limit": 5
  })
  ```
</CodeGroup>

### Getting All Memories

<CodeGroup>
  ```python Zep AI theme={null}
  memories = client.memory.get(session_id="user_123")
  ```

  ```python Supermemory theme={null}
  documents = client.documents.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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
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](/integrations/supermemory-sdk)
* [API Reference](/memory-api/overview)
* [Search Documentation](/search)