mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-10 03:28:14 +00:00
2feccc99fa
Renames v5 `attach` to `include`. GET routes take one comma-separated `include` query param (`?include=chunks,memories`); search takes every option in the JSON body, with `include` as an object of booleans. Also fixes the `forgotten` description: it does let forgotten memories come back as primary results. Pairs with supermemoryai/mono#3410.
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 includes 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.
|