Migrating from Zep to Supermemory

Key differences

Zep AI	Supermemory
Sessions & Messages	Documents & Container Tags
`session.create()`	Use `containerTag` parameter
`memory.add(session_id, ...)`	`add({containerTag: "..."})`
`memory.search(session_id, {text: ...})`	`search.execute({q: ..., containerTag: "..."})`

Installation

pip install supermemory

npm install supermemory

from supermemory import Supermemory
client = Supermemory(api_key="your-api-key")

import { Supermemory } from "supermemory";
const client = new Supermemory({ apiKey: "your-api-key" });

API mapping

Session management

session = client.session.create(
    session_id="user_123",
    user_id="user_123"
)

# No explicit session creation - use containerTag
containerTag = "user_123"

Adding memories

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

client.add({
    "content": "User prefers dark mode",
    "containerTag": "user_123"
})

Searching

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

results = client.search.execute({
    "q": "preferences",
    "containerTag": "user_123",
    "limit": 5
})

Getting all memories

memories = client.memory.get(session_id="user_123")

documents = client.documents.list({
    "containerTags": ["user_123"],
    "limit": 100
})

Migration steps

Replace client initialization - Use Supermemory client instead of Zep
Map sessions to container tags - Replace session_id="user_123" with containerTag: "user_123"
Update method calls - Use add() and search.execute() instead of memory.add() and memory.search()
Change search parameter - Use q instead of text
Handle async processing - Documents process asynchronously (status: queued → done)

Complete example

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
})

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
})

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:

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!");

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}: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!")

Full migration script

For a complete migration script with error handling, verification, and progress tracking, copy this TypeScript script:

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 containerTag = `imported_from_zep:session:${sessionId}`;
    if (data.session.user_id) {
      containerTag += `: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);

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Key differences

Installation

API mapping

Session management

Adding memories

Searching

Getting all memories

Migration steps

Complete example

Important notes

Migrating existing data

Quick migration (all-in-one)

Full migration script

Resources

​Key differences

​Installation

​API mapping

​Session management

​Adding memories

​Searching

​Getting all memories

​Migration steps

​Complete example

​Important notes

​Migrating existing data

​Quick migration (all-in-one)

​Full migration script

​Resources

Key differences

Installation

API mapping

Session management

Adding memories

Searching

Getting all memories

Migration steps

Complete example

Important notes

Migrating existing data

Quick migration (all-in-one)

Full migration script

Resources