mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
e47336737e
## Stack context This is the second PR in the V5 documentation stack, on top of the versioned API reference. ## What and why Add an agent-oriented V3/V4 to V5 migration guide covering document ingestion and updates, content management, search, profiles, forgetting, namespaces, organization settings, typed filters, and rollout verification. Shared snippets keep the comprehensive guide and focused topic pages consistent. ```mermaid flowchart LR Legacy[Legacy integration inventory] --> Mapping[Domain migration guidance] Mapping --> V5[V5 requests and response readers] V5 --> Verify[Side-by-side verification and rollout] ``` ## Validation - Verified all 11 migration navigation entries resolve to authored pages. - Verified all imports across 23 migration and snippet files resolve. - `git diff --check` passed. - Mintlify build validation passed against the local generated V5 OpenAPI snapshot. ## Impact Documentation only. The guide explicitly covers changed defaults, removed operations, partial failures, namespace isolation, and rollback-oriented side-by-side testing.
59 lines
2.6 KiB
Text
59 lines
2.6 KiB
Text
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 preserve input order and surface partial failures.
|
|
- Metadata-only updates leave source content unchanged.
|
|
- Accepted writes are polled until processing reaches a terminal state.
|
|
|
|
### Compare reads and recall
|
|
|
|
- Document attachments are absent when omitted and empty arrays when requested without results.
|
|
- Unified list responses populate only the selected resource array.
|
|
- 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
|
|
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.
|
|
- Unchanged connector routes retain their documented `/v3` paths.
|
|
- 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.
|