Migrating from Zep to Cognee

Migration steps

1. 1

   Export your graph from Zep

   Use Zep's graph API to pull the nodes, edges, and episodes for each user or group graph you want to keep and save them as JSON. The Cognee adapter expects the shape Zep's graph endpoints return (nodes, edges, episodes), and accepts a single dict or a file path.

   import json
   from zep_cloud.client import Zep
   
   client = Zep(api_key="...")
   graph_id = "alice"
   
   export = {
       "nodes": client.graph.node.get_by_user_id(graph_id),
       "edges": client.graph.edge.get_by_user_id(graph_id),
       "episodes": client.graph.episode.get_by_user_id(graph_id),
   }
   
   with open("zep_graph_export.json", "w") as f:
       json.dump(export, f, default=str)

2. 2

   Install Cognee

   pip install cognee, set LLM_API_KEY, and optionally configure production storage through environment variables. The embedded defaults are enough to test the import.

   pip install cognee
   export LLM_API_KEY="..."

3. 3

   Import with ZepSource in hybrid mode

   hybrid is the default for Zep exports: Cognee maps Zep's entity and fact nodes straight into its graph (no LLM calls) and also runs its own extraction over the episodes, so nothing Zep knew is lost and the graph gains Cognee's structure on top.

   import asyncio
   import cognee
   from cognee.migration import ZepSource
   
   async def main():
       await cognee.remember(
           ZepSource("zep_graph_export.json", mode="hybrid"),
           dataset_name="alice_memory",
       )
   
   asyncio.run(main())

4. 4

   Verify with temporal and graph queries

   TEMPORAL search answers time-scoped questions; GRAPH_COMPLETION answers relational ones. Compare a handful of answers against what Zep returned before you cut over.

   from cognee import SearchType
   
   await cognee.search(
       "What was Alice's role before she moved teams?",
       query_type=SearchType.TEMPORAL,
       datasets=["alice_memory"],
   )

5. 5

   Reconnect your agents

   Swap Zep's memory.add and graph.search calls for cognee.remember and cognee.recall in Python, or use the TypeScript client and the Cognee MCP server for Claude Code, Cursor, and other MCP clients. Run both systems side by side until the answers agree.

Because Zep already extracted entities and facts, preserve mode gives you a faithful copy with zero LLM cost, hybrid (the default for ZepSource) adds Cognee's own extraction on top, and re-derive discards Zep's graph and rebuilds from the episodes only. Use preserve to validate the export shape, then hybrid for the real import.

The import adapters live in cognee.migration and are documented at docs.cognee.ai. If your export does not match the shape the adapter expects, open an issue on GitHub with a redacted sample.