Migrating from Mem0 to Supermemory: A Production Playbook

Switching memory providers is not a package rename. The APIs may look similar, but the isolation model, memory lifecycle, retrieval scores, and ingestion behavior are different enough that a blind copy creates quiet data loss.

This guide covers Mem0 Platform v3 to Supermemory. If you self-host Mem0 Open Source, start by documenting the vector store, graph store, model providers, and persistence layers in your deployment. A managed-platform export cannot represent that whole system.

If you are still deciding whether to switch, read why Scira moved from Mem0 to Supermemory first. This article starts after that decision: how to move production data and traffic without making the migration irreversible.

What changes in a Mem0 migration?

The central design change is identity. Mem0 can scope memories across user_id, agent_id, app_id, and run_id. Supermemory uses one containerTag as the isolation boundary, then metadata for additional filtering and provenance.

Mem0 Platform	Supermemory	Migration consequence
user_id, agent_id, app_id, run_id	one containerTag plus metadata	define a deterministic namespace before importing
add messages or files to an entity scope	ingest raw content with containerTag and optional customId	preserve conversation identity and choose one update strategy
extracted memory record	direct memory creation or raw document ingestion	import existing facts directly; ingest new source content normally
query, entity filters, top_k, and score	q, containerTag, search mode, limit, and similarity	rewrite the adapter and retune thresholds
update or delete a memory	versioned update or soft forget	decide how application lifecycle actions should translate

Do not start the backfill until that mapping is explicit. A migration script can move every record successfully and still break tenant isolation if the namespace is wrong.

Is this guide right for your setup?

Proceed when every memory read and write can be mapped to a stable user, tenant, project, or agent boundary.

Pause for architecture work when:

• queries depend on several Mem0 entity dimensions at once
• the application expects to search across arbitrary tenants
• nested metadata drives authorization or retrieval behavior
• exact graph topology must be preserved
• deletes must be permanent at the moment the application requests them

Supermemory searches one containerTag at a time. That is useful isolation, but it means the tag must represent the boundary your authorization model already enforces. Graph edges and provider-specific ranking scores are not portable data formats.

What should you inventory first?

Create a written inventory before touching production:

1. Record the Mem0 SDK and API versions in use.
2. Enumerate every user, agent, app, and run scope that owns memories.
3. Choose one canonical scope order for export and deduplicate globally by Mem0 memory ID before counting records.
4. Separate raw conversations and documents from already-extracted memory facts.
5. Inspect metadata for nested objects that will need flattening or serialization.
6. Capture a golden set of real queries, expected facts, current ranks, empty-result rate, error rate, and p50/p95 latency.

That last step gives the migration an acceptance test. Without a baseline, “the import completed” becomes a substitute for “the product still remembers correctly.”

Mem0's get_all endpoint requires at least one entity filter, returns paginated results, and accepts at most 200 records per page. Overlapping user, agent, app, and run queries can return the same memory more than once, so write each source ID to the snapshot once. The response also exposes the run dimension as session_id; normalize it back to your application's run_id field before mapping metadata.

How should Mem0 IDs map to container tags?

Choose a deterministic rule and use it everywhere. Common patterns include:

• user:{user_id} for a single-tenant consumer application
• org:{org_id}:user:{user_id} for user memory inside an enterprise tenant
• agent:{agent_id} for an agent-owned knowledge base
• app:{app_id}:user:{user_id} when the same person must remain isolated across products

Store dimensions that do not define access as flat metadata, such as mem0_agent_id, mem0_app_id, and mem0_run_id. Current v4 container tags allow up to 100 characters using letters, numbers, underscores, colons, and hyphens. If a source ID falls outside ^[a-zA-Z0-9_:-]+$, sanitize or hash it and persist the mapping. Never derive the tag differently in the importer and the live request path.

Treat containerTag as an authorization boundary, not a convenient label. Test it with adversarial queries before cutover.

How do you export Mem0 without losing information?

For a canonical backfill, paginate Mem0's memory-list endpoint using the scope order you chose, deduplicate globally by memory ID, and write the raw records to immutable JSONL. Preserve:

• the memory text and source ID
• user, agent, app, and run identifiers
• categories and metadata
• creation, update, and expiration timestamps
• lifecycle state needed by the application

Mem0 also provides structured memory exports. Those exports are useful when you intentionally want to transform memories into a schema, such as a profile. They are not automatically a one-to-one database dump because the requested schema and export instructions can reshape the result.

If you use the export job, poll until it reports completion and download it promptly. Keep the raw source snapshot even after the new provider is live. It is the only reliable starting point for rollback or a corrected re-import.

How should existing memories be imported?

Already-extracted facts should use Supermemory's direct memory creation endpoint. Raw conversations, files, and URLs should use the normal ingestion pipeline instead.

For every imported fact, send:

• the Mem0 memory value as content
• the mapped containerTag
• source: mem0 in metadata
• the original Mem0 ID and entity IDs
• original timestamps and categories as flat or serialized metadata
• an expiration value only when the source policy requires it

Supermemory creates a new memory ID and timestamp. Maintain a migration ledger from mem0_id to the new ID, checkpoint each successful batch, and make retries skip completed source records. The direct-memory API does not promise that repeating the same request is idempotent.

The direct endpoint accepts batches of 1–100 memories, with each fact limited to 10,000 characters. Metadata values must use the documented scalar or string-array shapes, so flatten or serialize nested Mem0 metadata before sending it. Reject invalid records into a separate file rather than truncating them silently.

Do not claim that importing extracted facts reconstructs Mem0's graph relationships. It preserves the facts and makes them searchable. Graph and profile behavior must be evaluated after import.

How should the live write path change?

Use two write paths deliberately.

For new conversations and source documents, use Supermemory ingestion with a stable customId. Choose whether each update sends the complete conversation or only the delta, then keep that strategy consistent for the same ID.

For exact application-owned facts, use direct memory creation. That avoids sending a fact through document extraction when the application already knows what must be stored.

Document processing is asynchronous. A successful request means the work was accepted, not that every downstream memory is immediately available. With the default dreaming: "dynamic", document status can be done while memory and profile formation is still batching. If the workflow requires memories as soon as processing completes, dreaming: "instant" provides that behavior for an additional operation; otherwise validate document search and memory search separately.

During migration, dual-write new production events to both providers. Keep one system authoritative for reads until the new path passes the full evaluation.

How should the read path change?

The adapter needs more than renamed fields:

• Mem0 query becomes Supermemory q
• entity filters become containerTag plus metadata filters
• choose memories, documents, or hybrid search intentionally
• handle results that may represent a memory or a document chunk
• retune result limits and similarity thresholds

Do not compare Mem0 score directly with Supermemory similarity, and do not copy the same numeric cutoff. Each provider computes and calibrates relevance differently. Tune thresholds against the golden query set captured before migration.

For migration validation, score the retrieved context before the answer model sees it. A fluent model can hide a bad retrieval result by guessing convincingly.

How do you validate before cutover?

Run both systems in parallel and grade the same production-shaped queries.

Measure:

• exact-fact recall and top-k relevance
• stale or contradictory memories
• empty results and unexpected extra results
• tenant isolation and metadata filters
• expiration behavior
• ingestion success and time-to-searchable
• application-observed latency and error rates
• duplicate source IDs after retries

Backfill a small group of containers first. Shadow reads without showing the new response to users. When acceptance criteria pass, move a low-risk cohort behind a feature flag and keep rollback to Mem0 available.

The switching memory infrastructure guide covers the organizational side of this rollout. The technical rule is simpler: do not move all reads and writes on the same day.

Which lifecycle differences need explicit handling?

Operation	Mem0	Supermemory	Decision required
Update	updates a memory record	creates a new memory version	decide whether history should be visible to the application
Remove memory	deletes the memory	soft-forgets the memory while retaining it for explicit forgotten-memory retrieval	do not treat forgetting as an erasure request
Delete source	source-specific removal	permanent document deletion	keep memory IDs and document IDs separate
Expire	remains visible through expiration_date in UTC	forgets at the exact forgetAfter timestamp	either map to next-day 00:00:00Z and test it, or refuse automatic conversion

A Mem0 memory ID is not a Supermemory document ID. Keep resource types explicit in the migration ledger or deletion code will eventually target the wrong thing.

What should the rollback plan contain?

A rollback plan needs four concrete assets:

1. the immutable source snapshot
2. the source-to-destination ID ledger
3. a reversible read and write feature flag
4. an append-only log of writes created after the snapshot

During dual-write, declare which provider is the source of truth. If you roll back, switch reads first, restore the original write path, then replay only the events recorded after the snapshot. Do not delete Mem0 data until the rollback window closes and the team has verified counts, retrieval quality, lifecycle behavior, and tenant isolation.

What is the safest next step?

Migrate one representative tenant, not the easiest tenant and not the largest one. Import its facts, replay its real queries, test updates and forgetting, and measure the engineering work required to keep the system healthy.

Then make the decision from evidence. Read the current Supermemory container-tag model, map your scopes, and keep the first cutover small enough to reverse.

Frequently asked questions

Can I migrate from Mem0 to Supermemory without downtime?

A dual-write and shadow-read rollout can avoid a planned outage, but no migration is automatically zero-downtime. Keep Mem0 serving reads while you backfill and validate Supermemory, then move a small cohort behind a reversible feature flag.

How do Mem0 entity IDs map to Supermemory container tags?

Choose one deterministic container tag as the isolation boundary, such as org:{org_id}:user:{user_id}. Preserve other Mem0 dimensions such as agent_id, app_id, and run_id as flat metadata or encode them into the composite tag when they affect access.

Will Supermemory preserve Mem0 memory IDs and timestamps?

Supermemory creates its own memory IDs and creation timestamps. Preserve the original Mem0 ID and timestamps as metadata and maintain a migration ledger that maps each source ID to its new Supermemory ID.

Does this migration guide apply to Mem0 Open Source?

No. This guide covers the managed Mem0 Platform v3 APIs. Mem0 Open Source can use different vector stores, models, embedders, and persistence layers, so its export and migration plan must match the deployed stack.