Migrations

Migrate from Mem0

Map Mem0 users and memories to Zep users, threads, and graphs

This guide maps common Mem0 operations to Zep. Review the current Mem0 API before you export data because Mem0 can change its data model.

Zep stores agent memory in a Context Graph. A user graph combines a user’s chat messages and business data.

Contact [email protected] before a large migration that needs higher API limits.

Map the data models

Use one Zep user for each application user. Use one Zep thread for each conversation.

Add ordered chat messages with thread.add_messages. Add text or JSON business data with graph.add.

Zep extracts entities and temporal facts from both data sources. Facts include validity timestamps when the source data supplies them.

Map common operations

Mem0 operationZep Python methodNotes
Add conversation messagesclient.thread.add_messages(thread_id=..., messages=[...])Create the user and thread first. Preserve message order.
Add a business recordclient.graph.add(user_id=..., type="json", data=...)Serialize JSON data to a string. Use type="text" for text.
Retrieve context for a conversationclient.thread.get_user_context(thread_id=...)Returns an assembled Context Block in .context.
Search a user’s graphclient.graph.search(user_id=..., query=..., scope="auto")Use another scope when you need one result type.
List graph nodesclient.graph.node.get_by_user_id(user_id=...)Supports pagination and filters.
List graph edgesclient.graph.edge.get_by_user_id(user_id=...)Each edge contains a temporal fact.
Delete an episodeclient.graph.episode.delete(uuid_=...)Deletion also removes data derived only from that episode.

Do not translate each Mem0 memory into a Zep fact. Ingest the source messages or records so Zep can build the graph.

Migration procedure

  1. Install a Zep SDK and create an API key.
  2. Export users, conversation messages, and business records from Mem0.
  3. Create a Zep user for each application user.
  4. Create a Zep thread for each conversation.
  5. Add conversation messages in chronological order.
  6. Add business records to each user’s graph.
  7. Poll each returned task until ingestion reaches a terminal state.
  8. Compare retrieval results for a representative set of user questions.

Use zep-ingest or the Batch API for large imports. Follow Prepare data for ingestion so each record has a timestamp, a stable identity, and a single destination graph.

Retrieval after migration

Use thread.get_user_context when the current conversation supplies the query. The method returns a Context Block that can include all supported context types.

Use graph.search when your application supplies a query or needs a specific result type. Start with scope="auto" unless you need nodes, edges, episodes, observations, or thread summaries separately.

Treat all retrieved content as untrusted model input. Follow memory security best practices when you send it to a model.