supermemory/apps/docs/migration/from-zep.mdx

---
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 & Namespaces |
| `session.create()` | Use the `namespace` parameter |
| `memory.add(session_id, ...)` | `client.add(namespace, { content })` |
| `memory.search(session_id, {text: ...})` | `client.search(namespace, { query })` |

## 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"
)
```

```typescript Supermemory
// No explicit session creation, use a namespace
const namespace = "user_123";
```

</CodeGroup>

### Adding memories

<CodeGroup>

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

```typescript Supermemory
await client.add("user_123", {
  content: "User prefers dark mode",
});
```

</CodeGroup>

### Searching

<CodeGroup>

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

```typescript Supermemory
const { results } = await client.search("user_123", {
  query: "preferences",
  limit: 5,
});
```

</CodeGroup>

### Getting all memories

<CodeGroup>

```python Zep AI
memories = client.memory.get(session_id="user_123")
```

```typescript Supermemory
const { documents } = await client.list("user_123", "documents", {
  limit: 100,
});
```

</CodeGroup>

## Migration steps

1. **Replace client initialization** - Use Supermemory client instead of Zep
2. **Map sessions to namespaces** - Replace `session_id="user_123"` with `namespace: "user_123"`
3. **Update method calls** - Use `add()` and `search()` instead of `memory.add()` and `memory.search()`
4. **Change search parameter** - Use `query` 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
})
```

```typescript Supermemory
import { Supermemory } from "supermemory";

const client = new Supermemory({ apiKey: "..." });
const namespace = "user_123";

await client.add(namespace, {
  content: "I love Python",
  metadata: { role: "user" },
});

const { results } = await client.search(namespace, {
  query: "programming",
  limit: 3,
});
```

</CodeGroup>

## Important notes

- **No session creation needed** - Just pass `namespace` on each call
- **Messages are documents** - Store with `metadata.role` and `metadata.type`
- **Async processing** - Documents may take a moment to be searchable. Pass `dreaming: "instant"` on `add` when you need memories right away
- **Response structure** - `search` returns `results`, each with a `memory` or `chunk` and a `similarity` score

## 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(`session:${sessionId}:user:${memory.user_id || "unknown"}`, {
        content: mem.content,
        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(
                f"session:{session_id}:user:{memory.user_id or 'unknown'}",
                content=mem.content,
                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) {
    let namespace = `imported_from_zep:session:${sessionId}`;
    if (data.session.user_id) {
      namespace += `:user:${data.session.user_id}`;
    }

    for (const memory of data.memories) {
      totalMemories++;
      try {
        if (!memory.content?.trim()) {
          stats.skipped++;
          continue;
        }

        await supermemory.add(namespace, {
          content: memory.content,
          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](/api-reference/overview)
- [Search Documentation](/recall/search)