A Composable Memory Stack Starts with Interface Contracts

A memory stack becomes replaceable when its components agree on explicit inputs, outputs, identity, and failure behavior. Putting storage, retrieval, ranking, and context assembly in separate files is not enough. Hidden assumptions about IDs, scores, and update timing can make a supposedly modular system expensive to change.

Define what crosses each boundary

An ingestion result should identify the accepted source, revision, scope, and processing state. A retrieval result should include evidence, provenance, access scope, and enough version information to detect stale material. Context assembly should receive readable evidence rather than database-specific objects.

Avoid passing raw provider scores into a universal threshold without understanding their meaning. Similarity scores from different models or indexes are not automatically comparable. Preserve the original score for diagnosis and evaluate any normalization you introduce.

Keep lifecycle behavior explicit

Replacement is hardest when deletion, corrections, and retries are implicit. Specify whether updating a source replaces the prior revision, appends a revision, or creates a separate record. Define how derived memories become outdated and how consumers learn that processing has completed.

A component that accepts writes immediately but indexes them asynchronously needs a readiness contract. A reader should not interpret “not searchable yet” as “no information exists.” Decide how the application handles that interval.

Test a replacement through the public boundary

Build fixtures for repeated writes, changed permissions, deleted evidence, an empty result, and a provider timeout. Run the same fixtures against each implementation. If tests require internal database tables, they are probably checking one implementation rather than the interchange contract.

Then replay representative questions and compare evidence and answers. Passing a schema test does not prove the replacement returns useful context. Keep a rollback path that includes the index version and source mapping, not just a package version.

Choose modularity where change is plausible

A small application may benefit from one managed service and a narrow adapter. A mature system with unusual ranking needs may justify separate stages. Each additional boundary adds operational work, so build it around a credible replacement or ownership need.

The component migration guide turns these contracts into a rollout plan. To evaluate a managed boundary, review Supermemory's search interface and map its results and failure cases to your application's contract before adding an adapter.