mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-02 02:11:20 +00:00
c6fd728981
## What and why Add an agent-oriented V3/V4 to V5 migration guide covering document ingestion and updates, content management, search, profiles, memory forgetting, namespaces, organization settings, typed filters, and rollout verification. Shared snippets keep the comprehensive guide and the focused topic pages consistent, following the existing `/snippets/*.mdx` import convention used elsewhere in the docs. ```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] ``` ## Grounding Every old-vs-new claim traces to code in this repository: - `packages/validation/api.ts` - `SearchRequestSchema`, `Searchv4RequestSchema`, `ListMemoriesQuerySchema`, `MemoryUpdateSchema`, `BulkDeleteMemoriesSchema`, `ContainerTagListTypeSchema`, `SearchFiltersSchema`. - `packages/validation/schemas.ts` - `MemoryEntrySchema`, `OrganizationSettingsSchema`, `MemoryRelationEnum`. - `packages/tools/src/shared/memory-client.ts` and `packages/tools/src/shared/types.ts` - the `/v4/profile` request and `profile.static` / `profile.dynamic` / `profile.buckets` reader. - `apps/mcp/src/server/client/index.ts` - live `/v3/container-tags/list`, `/v4/memories/list`, and `/v3/documents/file` call sites. ## Notable findings documented - `SearchFiltersSchema` is `z.array(z.unknown())` behind a `// TODO: Improve filter schema` comment, so legacy conditions were never validated at the edge. The typed-filter page documents the mechanical conversion and calls out the numeric-string-to-JSON-number trap that a straight rename would miss. - `OrganizationSettingsSchema` carries connector credentials that are absent from the public V5 `/organization` response; the page warns against reading them from `GET /v3/settings`. - Operations with no V5 replacement are listed explicitly rather than given invented substitutes. ## Validation - `docs.json` parses as JSON; all 11 new nav entries resolve to authored pages, and every pre-existing nav entry still resolves. - All 12 snippet imports and every relative/absolute link across the 23 new files resolve to real targets. - Fences, braces, and JSX component tags balance across all new files; frontmatter parses as YAML. - `git diff --check` passes. ## Impact Documentation only. No runtime, schema, or SDK behavior changes.
93 lines
3 KiB
Text
93 lines
3 KiB
Text
Forgetting in V5 acts on a single namespace, and an exact-ID request and a
|
|
semantic request come back in the same result envelope.
|
|
|
|
### Choose exact or semantic forgetting
|
|
|
|
| Intent | V5 operation |
|
|
| --- | --- |
|
|
| Forget reviewed memory IDs | `DELETE /ns/{namespace}/memories` |
|
|
| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` |
|
|
|
|
The legacy API split these across two differently shaped endpoints:
|
|
`DELETE /v4/memories` (identify by `id` **or** exact `content`, plus a `reason`)
|
|
and `POST /v4/memories/forget-matching` (semantic `query` or explicit `ids`, with
|
|
`dryRun`, `threshold`, and `maxForget`). V5 normalizes both onto one response
|
|
contract.
|
|
|
|
### Forget exact IDs
|
|
|
|
```bash
|
|
DELETE /ns/user_1/memories
|
|
Content-Type: application/json
|
|
|
|
{"ids":["mem_1","mem_2"]}
|
|
```
|
|
|
|
The count runs from **1** to **500** IDs. Your successes arrive under `matches`;
|
|
anything missing or ineligible lands in `errors`. A 2xx status therefore does not
|
|
prove that every ID you named was actually forgotten.
|
|
|
|
### Preview a semantic request
|
|
|
|
```bash
|
|
DELETE /ns/user_1/memories/semantic
|
|
Content-Type: application/json
|
|
|
|
{"query":"outdated home address","dryRun":true}
|
|
```
|
|
|
|
With `dryRun: true` the request only selects — memory state is left **untouched**.
|
|
With `dryRun: false` it removes whatever the selection resolves to at the moment
|
|
the request runs.
|
|
|
|
### Avoid selection drift
|
|
|
|
```text
|
|
semantic request with dryRun: true
|
|
|
|
|
v
|
|
review matches[].id
|
|
|
|
|
v
|
|
exact DELETE with reviewed IDs
|
|
```
|
|
|
|
Use this workflow whenever a human or a policy must approve the exact set.
|
|
Re-running the semantic request with `dryRun: false` can select a **different**
|
|
set if memories changed after the preview.
|
|
|
|
<Warning>
|
|
Do not assume the semantic endpoint is idempotent with respect to your earlier
|
|
preview. The legacy `forget-matching` route had the same property, but the
|
|
legacy docs described the two-step preview flow as optional; in V5 it is the
|
|
recommended path for any deletion a reviewer has to sign off on.
|
|
</Warning>
|
|
|
|
### Read the normalized response
|
|
|
|
```json
|
|
{
|
|
"count": 1,
|
|
"matches": [{ "id": "mem_1", "memory": "Old address" }],
|
|
"errors": [{ "id": "mem_2", "error": "Memory not found" }]
|
|
}
|
|
```
|
|
|
|
The value of `count` is by definition the length of `matches`. Dry-run and
|
|
applied semantic requests share this shape, so the response body on its own will
|
|
not reveal which mode produced it — record the mode next to your audit entry.
|
|
|
|
### Removed memory-write routes
|
|
|
|
V5 offers nothing in place of direct V4 memory creation or version updates. Feed
|
|
source material in through the document routes and rewrite the canonical document
|
|
whenever the underlying facts change.
|
|
|
|
### Verification
|
|
|
|
- Try ID sets that are all-success, partially successful, duplicated, unknown,
|
|
and drawn from across namespaces.
|
|
- A dry run should leave every matched memory recallable.
|
|
- Forget the reviewed IDs exactly, then check that ordinary recall no longer
|
|
surfaces them.
|
|
- Log the request mode alongside the audit trail for semantic operations.
|