Skip to main content

​
Migration details

Treat migration as a behavioral comparison, not a raw response snapshot update.

​
Build deterministic fixtures

Use an isolated namespace with stable IDs and fixed source content. Include plaintext, URL, file, batch, metadata, grouping, profile facts, related memories, forgotten memories, and empty-result cases. Record each legacy request, v5 request, expected semantic result, and intentional difference. Never compare generated IDs, signed URLs, timing, or JSON object order unless the contract guarantees them.

​
Compare writes

  • Repeated POST appends or diffs; PATCH replaces canonical content.
  • Batch outcomes list accepted documents first, then failures, and surface partial failures; match by ID, not position.
  • Metadata-only updates leave source content unchanged.
  • Accepted writes are polled until processing reaches a terminal state.

​
Compare reads and recall

  • Document includes are absent when omitted and empty arrays when requested without results.
  • Unified list responses populate only the selected resource array.
  • metadata is always an object, {} when empty; it is never null.
  • Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
  • Profiles always contain static, dynamic, and bucket sections.

​
Exercise boundaries

​
Classify differences

Do not normalize away an undocumented difference. Capture the request pair, namespace, IDs, response status, and minimal response fragments needed to reproduce it.

​
Cut over by domain

  1. Ship v5 request construction behind a per-domain flag.
  2. Dual-read or shadow-call where side effects allow it.
  3. Switch ingestion, content management, search, profiles, then settings independently.
  4. Monitor validation failures, authorization failures, latency, empty-result rate, and processing failures.
  5. Retain the legacy path until the observation window passes.

​
Completion checklist

  • No application API call accidentally uses a /v5 prefix.
  • Connector calls use /ns/{namespace}/connectors or supermemory.connectors.*, not /v3/connections.
  • No legacy field aliases or response readers remain.
  • Every changed default is either accepted intentionally or passed explicitly.
  • Rollback restores the previous caller without requiring data repair.