Migrating from Zep to Supermemory

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

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 a namespace
const namespace = "user_123";

Adding memories

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

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

Searching

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

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

Getting all memories

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

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

Migration steps

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

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

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:

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

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

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

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