Replace One Memory Component Without Losing the Contract

Replacing an embedding model, retrieval service, or memory store requires more than moving data. Preserve identity, scope, source revisions, lifecycle behavior, and the application's interpretation of results. A successful migration produces useful answers and predictable corrections, not just a matching record count.

Inventory the dependency you are changing

List the interfaces used by writers, background jobs, readers, deletion handlers, and support tools. Include assumptions that are not in the API schema: when writes become searchable, whether filters are mandatory, and whether result scores drive a cutoff.

Choose one boundary to replace. Changing the embedding model, chunking, source parser, and ranking policy together makes it difficult to explain disagreements. If several changes are necessary, record them as separate evaluation dimensions.

Build a mapping before moving records

Keep a mapping from original source IDs and revisions to destination records. Preserve tenant and user scopes from trusted application state. Where the destination creates derived memories, track the source relationship rather than expecting record counts to match exactly.

Define how updates arriving during the migration are handled. Options include a short write pause, a replayable event log, or controlled dual writes. Each has tradeoffs; dual writes need reconciliation when only one destination succeeds.

Shadow reads before switching answers

Run representative queries against both systems while the current system still serves users. Compare evidence relevance, currentness, permissions, and answer quality. Do not use the old answer as unquestioned ground truth: it may contain the problem the migration is intended to fix.

Include corrected and deleted sources, empty results, and delayed ingestion. Sample disagreements manually and classify them. A new system returning fewer results may be better if it excludes stale or unauthorized material.

Define rollback at the data boundary

Specify what happens to writes made after cutover. A rollback that changes only the read endpoint can lose access to new information. Keep reconciliation and replay available until the migration window closes.

The interface-contract guide provides the acceptance boundary. If Supermemory is a candidate destination, create an isolated evaluation project and migrate a representative subset before committing the full collection.