Migrating graph memory without flattening episodes and time

July 15, 2026Guides13 min read

A Zep or Graphiti migration plan that keeps source exports, maps facts and temporal state deliberately, and evaluates downstream decisions.

A graph-memory export is not one list of memories. It may contain raw episodes, entities, fact edges, temporal validity, summaries, communities, embeddings, namespaces, and a prompt-ready context block. Copying only the rendered context preserves what one query saw and discards the structure needed to correct or rebuild it.

A safe migration identifies which source artifacts are authoritative, which graph artifacts are derived, and which behavior the destination must reproduce for the application.

The short version

Freeze the deployed Zep or Graphiti contract and export raw episodes before changing anything.
Map episodes, facts, entities, time, and namespaces separately.
Import already-derived facts deterministically; do not flatten them into one context string.
Keep provenance from every destination record back to source episodes.
Rebuild derived projections only from retained evidence.
Compare downstream decisions, history, deletion, and failure behavior—not byte-identical prompts.

Inventory the graph you actually use

Record service and SDK versions, storage backend, group or user identifiers, custom entity and edge types, extraction instructions, search recipes, rerankers, context templates, and deletion behavior. Capture the requests the application makes, not every feature the source product offers.

Graphiti models ingestion events as episodes and associates extracted entities and fact edges with them. Zep adds managed user, thread, retrieval, and governance surfaces. A production integration may use only message ingestion and a context block, or it may query nodes, edges, episodes, and filters directly. Those are different migration projects.

Separate source and derived artifacts

Source artifact	Likely authority	Destination treatment
Episode body and reference time	Original ingestion evidence	Preserve as source or replay input with provenance
Entity node	Resolved identity derived from episodes	Map only if the application depends on stable entity identity
Fact edge	Derived relationship plus temporal state	Import as a scoped fact with all supporting episode links
Summary or community	Rebuildable synthesis	Keep as optional view, never sole evidence
Rendered context block	Query-time presentation	Use for comparison, not migration authority
Embedding or rank score	Model-specific projection	Rebuild under the destination index

Preserve episodes before facts

An extracted fact may not appear word-for-word in a message or business record. Its trust comes from the association back to one or more episodes. Preserve the episode content, source description, reference time, group or user identity, metadata, and the associations supporting each fact.

When multiple episodes reaffirm or invalidate one relationship, retain the full association set. Copying only the first source breaks later deletion, access filtering, and explanations of why the fact changed.

Map temporal fields by meaning

Graphiti fact edges may carry creation, validity, invalidation, and expiry information. FishMem records expose event time, validity range, system history, and supersession. Field names are less important than the questions they answer.

When did the source event occur?
When did the relationship become true?
When did it stop being true?
When did the source system learn or change it?
Which new record superseded the old one?

Leave unknown values empty. Do not substitute export time for event time or infer a precise interval from a vague historical statement.

Map namespaces before entities

Graphiti group_id, Zep user graphs, and FishMem project/user/agent/run scopes all partition data, but their authorization meanings can differ. Decide which destination namespace owns the data and which structural IDs are safe retrieval filters.

Run adversarial tests with similar entity names in different source groups. Entity deduplication must never cross a security boundary merely because semantic matching says two nodes look alike.

Choose a fact import strategy

Episode replay

Re-ingest episodes and allow FishMem inference to derive new records. This tests a new extraction policy, but results will not be a lossless migration of the source graph.

Fact preservation

Import exported fact content with inference disabled, preserve temporal fields and episode provenance, and rebuild destination indexes. This best preserves the source system's conclusions.

Hybrid migration

Preserve high-value facts deterministically while retaining episodes for citation and future controlled reprocessing. Run any new inference into a separate evaluation namespace until differences are understood.

Do not mix these strategies silently. The migration ledger should record which path produced every destination record.

Rebuild projections from evidence

Entity associations, semantic indexes, full-text indexes, profiles, and prompt-ready summaries are useful but model- and implementation-specific. Rebuild them under the destination system and compare their behavior. Preserve the original export until the new projections survive the observation window.

If the application depends on a custom ontology, map it explicitly. A generic relationship string may retain human meaning while losing typed query behavior. Conversely, importing every source node type into the destination may reproduce complexity the product never used.

Compare decisions, not context bytes

Build trace cases for:

current facts after a contradiction;
point-in-time historical questions;
multi-hop relationships;
source-scoped retrieval;
entity aliases and merges;
episode deletion with shared facts;
namespace isolation;
abstention when evidence is absent;
latency and token budget under realistic graph size.

Compare required evidence and the downstream answer. Different ranking or formatting is acceptable when it leads to the same supported decision within the agreed budget.

Deletion is the hardest integrity test

If one episode is deleted, determine which facts, entities, summaries, and indexes should change. A fact supported by two episodes should retain the remaining association. A fact supported only by the deleted episode may need removal or invalidation. The destination must not leave a derived claim with no inspectable source.

Run deletion during the dual-read phase, not after cutover. It exposes whether the migration preserved provenance as a live relationship or merely copied source IDs into metadata.

A staged migration plan

Freeze source versions and export episodes, graph artifacts, schemas, and configuration.
Create the source-to-destination mapping and migration ledger.
Import a small isolated graph and reconcile counts, hashes, time, and associations.
Rebuild retrieval projections and run a redacted trace set.
Shadow production queries and compare decisions.
Canary one source group or user cohort with independent rollback.
Test update, contradiction, episode deletion, export, and restore.
Expand only when quality, isolation, latency, and operational gates hold.

What compatibility means here

FishMem is not affiliated with Zep or Graphiti and does not claim SDK or context-block compatibility. A successful migration preserves the application decisions and evidence you selected, not every internal graph implementation detail.