> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify and roll out a v5 migration

> Prove behavioral parity, detect intentional differences, and cut over safely

## 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

| Boundary | Cases |
| - | - |
| Namespace | Correct, missing, unauthorized, cross-namespace ID |
| Pagination | First, middle, final, empty, maximum limit |
| Filters | Every operator, nested AND/OR, invalid type, excessive depth |
| Deletion | All success, partial success, unknown IDs, semantic dry run |
| Settings | Admin, non-admin, null removal, invalid empty value |

### Classify differences

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
same request intent
       |
       +-- same semantic result ------> parity
       +-- documented v5 difference --> update assertion
       +-- undocumented difference ----> block cutover
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.