Migrate Supermemory v3/v4 to v5 - supermemory

Migrate with an agent

Paste this into Claude Code, Cursor, or Codex. It fetches this guide as markdown and rewrites every legacy call.

Migrate this repository from Supermemory v3/v4 to v5. Fetch https://supermemory.ai/docs/migration/api-v5.md and follow it exactly. First write a checklist of every legacy call site, then migrate them one by one and tick each off. Stop and report any operation that has no v5 replacement instead of inventing one.

Migrate by hand

This is a breaking API migration. Do not change only the URL: fields moved, search defaults changed, response envelopes changed, and some legacy operations have no v5 replacement.

The API base URL and bearer keys do not change. v5 application routes are unversioned; /v5/reference is the interactive v5 reference, not an API path prefix.

Recommended migration process

Inventory every legacy call

Search for /v3/, /v4/, containerTag, containerTags, customId, entityContext, filterByMetadata, filters, and legacy SDK methods.

Resolve one namespace per request

Move the legacy containerTag into /ns/{namespace}. Never infer scope from a document or memory ID, and never send multiple namespaces to one v5 request.

Translate requests by domain

Apply ingestion, updates, content management, search, profiles, forgetting, namespaces, organization, and filter changes independently.

Update response readers

Migrate envelopes, includes, pagination, profile buckets, system fields, and partial-error handling before switching traffic.

Verify legacy and v5 side by side

Follow the verification and rollout guide. Compare identity and behavior—not raw JSON ordering—and set changed defaults explicitly during rollout.

Cut over one domain at a time

Switch traffic, monitor failures and semantic drift, then remove legacy compatibility code only after that domain passes verification.

Endpoint map

Legacy	v5
`POST /v3/documents`	`POST /ns/{namespace}/document`
`POST /v3/documents/batch`	`POST /ns/{namespace}/document/batch`
`POST /v3/documents/file`	`POST /ns/{namespace}/document/file`
`GET/PATCH /v3/documents/{id}`	`GET/PATCH /ns/{namespace}/document/{id}`
Single or bulk document delete	`DELETE /ns/{namespace}/document`
Legacy document or memory lists	`POST /ns/{namespace}/list/{type}`
`POST /v3/search` or `/v4/search`	`POST /ns/{namespace}/search`
`POST /v4/profile`	`POST /ns/{namespace}/profile`
`POST /v4/profile/buckets`	`GET /ns/{namespace}/profile/buckets`
Legacy memory forget routes	`DELETE /ns/{namespace}/memories...`
Container-tag settings and lifecycle	`/namespaces` and `/ns/{namespace}`
`GET/PATCH /v3/settings`	`GET/PATCH /organization`

SDKs, tools and the CLI

Check which client you call the API through before you translate requests. Not every client supports v5 yet.

Client	v5 support	What to do
TypeScript SDK (`supermemory` on npm)	`5.0.0-rc.5` and later	Install `supermemory@rc` and follow the SDK changes below. Release candidates before `rc.5` still use the v3/v4 surface.
Python SDK (`supermemory` on PyPI)	Not yet	The 3.x SDK calls v3/v4. Call v5 over HTTP as shown in this guide, or keep the SDK on v3/v4 until a v5 release ships.
`@supermemory/tools` (AI SDK, OpenAI and agent integrations)	Not yet	These call v3/v4 (`/v4/profile`, `/v4/conversations`). No change needed today.
CLI (`npx supermemory`) and `supermemory local`	Unchanged	The CLI calls v3/v4 directly and keeps working. No change needed.

TypeScript SDK changes

The v5 SDK scopes every content call to one namespace and moves the payload under body:

import Supermemory from "supermemory";

const client = new Supermemory(); // reads SUPERMEMORY_API_KEY, as before

// v4
await client.add({ content: "Alex prefers morning meetings.", containerTag: "user_alex" });

// v5
await client.add({
  namespace: "user_alex",
  body: { content: "Alex prefers morning meetings." },
});

v4	v5
`client.search.memories({ q, containerTag })`	`client.search({ namespace, body: { query } })`
`client.profile({ containerTag, q })`	`client.profile({ namespace })`, plus `client.search` in parallel if you need results
`client.documents.list(...)`, `client.memories.list(...)`	`client.list({ namespace, type })`
`client.containerTags.*`	`client.namespaces.*`
`client.settings.{get, update}`	`client.organization.{get, update}`
Errors per status (`RateLimitError`, …)	One `SupermemoryError`; branch on `statusCode`
Retries on by default	Retries are opt-in through `retryConfig`
`timeout`	`timeoutMs`

The v5 SDK drops methods that have no v5 endpoint: connections, conversations.add, settings.{reset, suggestBuckets}, containerTags.{merge, mergeStatus}, memories.{add, updateMemory}, and documents.{listProcessing, chunks, fileUrl, search}. Stay on supermemory@4 for those calls. The full method map is in the SDK’s migration guide.

Document ingestion

v5 moves document scope into the URL and keeps repeated caller IDs attached to one evolving document.

Rename common fields

Legacy	v5	Location
`containerTag`	`{namespace}`	Path
`customId`	`id`	JSON body
`entityContext`	`supportingContext`	JSON/form body
`filterByMetadata`	`group`	JSON/form body
`documentDate`	`date`	JSON/form body
`taskType`, `dreaming`	unchanged	Query string

Add or append one document

POST /v3/documents
{"content":"new turn","customId":"conv_1","containerTag":"user_1"}

POST /ns/user_1/document?dreaming=dynamic
{"content":"new turn","id":"conv_1"}

The response remains an acceptance result with id and status. Repeating the v5 request with id: "conv_1" adds or diffs the new content into that document; it does not silently replace the canonical source.

Batch ingestion

{"documents":["first","second"],"containerTag":"user_1"}

{"documents":[{"content":"first","id":"doc_1"},{"content":"second","id":"doc_2"}]}

Send the v5 body to POST /ns/user_1/document/batch. The array accepts 1–600 document objects. Namespace, taskType, and processing mode apply to the request; document content, ID, context, metadata, grouping, and date stay per item. Batch results preserve input order. Inspect success, failed, and every item in results; a batch can contain successful and failed items together.

File ingestion

Replace POST /v3/documents/file with POST /ns/{namespace}/document/file. Continue using multipart/form-data:

Part	Encoding
`file`	Binary file
`supportingContext`, `date`	Plain strings
`metadata`, `group`	JSON-encoded strings
`fileType`, `mimeType`	Query parameters when inference is insufficient

The API acknowledges the file after durable acceptance. Extraction, indexing, and memory formation continue asynchronously; poll the document rather than assuming the first response means processing is complete.

Processing choices

taskType=memory extracts long-term memories; taskType=superrag indexes source context without memory generation.
dreaming=dynamic (default) groups related documents into coherent memory units.
dreaming=instant processes each document independently and bills one extra operation per document.

Verification

Ingest text, a public URL, and a file, then wait for each document to finish processing.
Repeat a caller-defined ID and confirm append/diff behavior instead of replacement.
Submit a mixed-success batch and verify result order and per-item errors.
Confirm metadata and grouping remain filterable after processing.

Document updates

v5 makes the difference between adding new information and replacing the canonical source explicit.

Choose the correct write

Intent	Operation	Content behavior
Add information to a stable caller ID	`POST /ns/{namespace}/document`	Append/diff
Replace text or URL content	`PATCH /ns/{namespace}/document/{id}`	Replace and reprocess
Update only supporting fields	Same `PATCH` without `content`	Canonical content unchanged
Replace a source file and its user metadata	`POST /ns/{namespace}/document/file/{id}`	Full replacement and reprocess
Partially update a file or its supporting fields	`PATCH /ns/{namespace}/document/file/{id}`	Omitted fields remain unchanged

Update text or URL content

PATCH /v3/documents/doc_1
{"content":"corrected source","metadata":{"revision":2}}

PATCH /ns/user_1/document/doc_1?dreaming=dynamic
{"content":"corrected source","metadata":{"revision":2}}

The v5 body accepts any non-empty subset of content, supportingContext, metadata, group, or date. Supplying content makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing.

Replace a file-backed document

POST /ns/user_1/document/file/doc_1?dreaming=dynamic
Content-Type: multipart/form-data

file=@corrected.pdf
metadata={"revision":2}

POST requires file and replaces the canonical source plus user-controlled metadata, grouping, context, and date. Omitted supporting fields are cleared. Use it when the submitted request is the complete new representation of the file-backed document.

Partially update a file-backed document

PATCH /ns/user_1/document/file/doc_1?dreaming=dynamic
Content-Type: multipart/form-data

metadata={"reviewed":true}

PATCH changes only supplied fields. Include file to replace the source while retaining omitted supporting fields, or omit file for metadata-, group-, context-, or date-only changes. metadata and group are JSON-encoded strings; supportingContext and date are plain strings.

There is no public v5 PUT /ns/{namespace}/document/file/{id} operation. Use POST for a complete replacement and PATCH for a partial update.

IDs and scope

The path id may be the Supermemory document ID or your caller-defined ID. It is resolved only inside {namespace}; an ID from another namespace is not a cross-namespace update mechanism.

Processing and conflicts

Content or file replacement is accepted before downstream processing completes. A document still processing, a namespace conflict, or a conflicting internal file path can return 409; retry only after the conflicting operation reaches a terminal state.

Verification

Patch metadata alone and confirm document content and derived facts remain intact.
Patch content and confirm the new source is canonical after processing.
Replace a file with POST and confirm omitted user metadata is cleared.
Patch a file-backed document and confirm omitted fields remain unchanged.
Attempt the same ID in another namespace and confirm the update is rejected or not found.

Content management

v5 retrieves, lists, and removes content within one explicit namespace.

Retrieve a document and its derived context

GET /v3/documents/{id}
GET /v3/documents/{id}/chunks

GET /ns/{namespace}/document/{id}?include=chunks,memories

Pass include as a comma-separated list to return chunks, memories, or both. Keys you omit are absent; requested keys with no results are empty arrays. Lifecycle fields move under system:

{"system":{"status":"done","createdAt":"...","updatedAt":"..."}}

List documents, chunks, or memories

POST /v3/documents/list
POST /v4/memories/list

POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
{}

Set type to documents, chunks, or memories. Pagination and sorting move to the query string; the body contains only optional filter. Every response contains documents, chunks, memories, and pagination. Only the selected resource array is populated. Replace legacy memories assumptions in document-list callers with documents.

Delete documents

DELETE /v3/documents/{id}
DELETE /v3/documents/bulk

DELETE /ns/{namespace}/document
{"ids":["doc_1","external_id_2"]}

The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both deletedCount and per-ID errors; HTTP success can include partial failures.

Forget memories

Legacy intent	v5 operation
Forget exact IDs	`DELETE /ns/{namespace}/memories` with `{ "ids": [...] }`
Find memories by meaning	`DELETE /ns/{namespace}/memories/semantic` with `{ "query": "...", "dryRun": true }`

Both return { count, matches, errors }. For drift-free semantic deletion, preview with dryRun: true, review the IDs, then submit them to the exact-ID endpoint. See memory forgetting for the complete dry-run, approval, response, and audit workflow.

Verification

Assert requested empty includes are [], while omitted includes are absent.
Paginate each resource type until currentPage >= totalPages; unselected arrays stay empty.
Verify chunk rows contain their parent documentId.
Exercise partial document-delete failures and semantic dry runs.
Verify IDs cannot read, list, or delete content outside their namespace.

Search

v5 searches one namespace, defaults to hybrid recall, and takes every option in one typed JSON body. Search has no query-string parameters.

Request mapping

Legacy	v5
`containerTag`	`/ns/{namespace}`
body `q`	body `query`
body `limit`	body `limit`
`searchMode: "documents"`	`searchMode: "chunks"`
omitted search mode	`searchMode: "hybrid"`
`filters`	singular `filter`
`include.documents` or `.summaries`	`include.documents`
`include.relatedMemories`	`include.related`
`include.forgottenMemories`	`include.forgotten`
`rerank: true` / `aggregate: true`	`rerank: "order"` / `"aggregate"`

POST /v4/search
{"q":"What did the user decide?","containerTag":"user_1","limit":10,"searchMode":"memories"}

POST /ns/user_1/search
{"query":"What did the user decide?","limit":10,"searchMode":"memories","threshold":0.6,"rewriteQuery":false}

Changed defaults

Setting	v4	v5
Search mode	`memories`	`hybrid`
Similarity threshold	`0.6`	`0.3`
Reranking	Disabled	`rerank: "none"`
Query rewriting	Disabled	`false`

Set mode and threshold explicitly while comparing versions. After parity testing, remove them only if you want the broader v5 hybrid defaults.

Search modes

Mode	Returns
`memories`	Formed memories only
`chunks`	Source chunks only
`hybrid`	Both result types in one ranked list

Legacy include.chunks has no v5 equivalent. Choose chunks or hybrid instead.

Included context and ranking

include is an object of booleans in the body, e.g. "include": {"documents": true, "related": true}. Each flag defaults to false.

include.documents adds the most relevant source document to each result.
include.related adds parent, child, and sibling memories.
include.forgotten lets forgotten and expired memories appear in results, including as primary results.
rerank accepts none, order, or aggregate; rewriteQuery controls retrieval-oriented query rewriting.

Response mapping

Legacy reader	v5 reader
Result array	`results`
Timing	`searchTime`
Source expansion	`result.included.document`
Related context	`result.included.related.{parents,children,siblings}`
Lifecycle fields	`result.system`

Each primary result contains either memory, chunk, or both only if the contract allows it. Branch on field presence rather than assuming one result shape.

Verification

Compare IDs using explicit v4-equivalent defaults, then test v5 hybrid behavior separately.
Cover all three modes, thresholds at 0 and 1, each rerank option, and query rewriting.
Cover every include alone and in combination, including empty results.
Verify filters, namespace isolation, result limits, and invalid body/query placement.

Profiles and buckets

v5 returns a maintained profile directly and gives profile bucket definitions their own namespace-scoped resource.

Remove search behavior from profile calls

POST /v4/profile
{"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":{}}

POST /ns/user_1/profile
{"filter":{"field":"region","operator":"eq","value":"us-west"},"buckets":["work"]}

Remove legacy q, threshold, and include. If the caller needs query-ranked results, issue a separate v5 search request. Move containerTag to the path and rename filters to singular filter.

Read the v5 profile shape

{
  "profile": {
    "static": ["The user works in design"],
    "dynamic": ["The user is preparing a launch"],
    "buckets": { "work": ["Prefers concise project updates"] }
  }
}

static and dynamic are always returned and cannot be disabled. Omit buckets in the request to return every effective custom bucket; pass up to 50 names to narrow only the bucket section.

Read bucket definitions

POST /v4/profile/buckets
{"containerTag":"user_1"}

GET /ns/user_1/profile/buckets

The response changes from key/description objects to a map:

{"buckets":{"work":"Professional preferences and ongoing work"}}

Add or edit namespace buckets

PUT /ns/user_1/profile/buckets
{"buckets":{"work":"Professional preferences and ongoing work"}}

Send one to 50 name-to-description entries. Existing namespace names are updated, new names are added, and omitted namespace buckets remain unchanged.

Delete namespace buckets

DELETE /ns/user_1/profile/buckets
{"buckets":["work"]}

Names must be unique. Organization-owned buckets can appear in the effective GET response but cannot be changed or removed through namespace PUT or DELETE calls.

Verification

Confirm every profile response contains static, dynamic, and buckets.
Compare omitted buckets with one-name and multi-name narrowing.
Add, edit, and delete a namespace bucket without replacing omitted buckets.
Attempt to mutate an inherited organization bucket and expect the documented error.

Memory forgetting

v5 scopes forgetting to one namespace and returns the same result envelope for exact and semantic requests.

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`

Forget exact IDs

DELETE /ns/user_1/memories
Content-Type: application/json

{"ids":["mem_1","mem_2"]}

Send 1–500 IDs. The response reports successful IDs in matches and missing or ineligible IDs in errors, so HTTP success does not imply every requested ID changed.

Preview a semantic request

DELETE /ns/user_1/memories/semantic
Content-Type: application/json

{"query":"outdated home address","dryRun":true}

dryRun: true performs selection without changing memory state. dryRun: false forgets the memories selected when that request executes.

Avoid selection drift

semantic request with dryRun: true
                |
                v
review matches[].id
                |
                v
exact DELETE with reviewed IDs

Use this workflow when a human or policy must approve the exact set. Re-running the semantic request with dryRun: false can select a different set if memories changed after preview.

Read the normalized response

{
  "count": 1,
  "matches": [{ "id": "mem_1", "memory": "Old address" }],
  "errors": [{ "id": "mem_2", "error": "Memory not found" }]
}

count always equals matches.length. Both dry-run and applied semantic requests use this shape; the payload alone does not replace your record of which mode was sent.

Removed memory-write routes

Direct v4 memory creation and version updates have no v5 replacement. Ingest source material through document routes and update the canonical document when facts change.

Verification

Exercise all-success, partial-success, duplicate, unknown, and cross-namespace ID sets.
Confirm dry runs leave matched memories recallable.
Apply reviewed IDs exactly and confirm normal recall excludes them.
Persist the request mode alongside audit logs for semantic operations.

Namespaces

v5 renames the public isolation boundary from container tag to namespace. Existing values remain valid identifiers; no stored data rename is required.

Endpoint mapping

Legacy	v5
`GET /v3/container-tags/list`	`GET /namespaces`
`GET /v3/container-tags/{tag}`	`GET /ns/{namespace}`
`PATCH /v3/container-tags/{tag}`	`PATCH /ns/{namespace}`
`DELETE /v3/container-tags/{tag}`	`DELETE /ns/{namespace}`
Merge container tags	`DELETE /ns/{source}` with `{ "moveTo": "target" }`

GET /ns is an alias for GET /namespaces. Prefer /namespaces in new integrations.

List namespaces

Each entry now exposes id, namespace, documentCount, memoryCount, nullable description, and system.createdAt/updatedAt. Update readers that still expect containerTag, flat timestamps, or unbounded internal settings.

Read and update settings

PATCH /v3/container-tags/project_alpha
{"entityContext":"Research project for distributed systems"}

PATCH /ns/project_alpha
{"supportingContext":"Research project for distributed systems"}

The public GET and PATCH shapes contain only namespace, supportingContext, and lifecycle timestamps. Profile buckets have their own /profile/buckets resource and are not namespace settings. Send supportingContext: null to remove existing context. Omitting the field entirely is invalid because PATCH requires at least one supported setting.

Permanently delete a namespace

DELETE /ns/project_alpha
{}

With no moveTo, deletion is synchronous and returns 200 with deletedDocumentsCount and deletedMemoriesCount. This removes the namespace and its content.

Move then remove a namespace

DELETE /ns/project_alpha
{"moveTo":"project_archive"}

This returns 202 with status: "queued" and operationId. The destination must differ from the source. Do not treat acceptance as completed migration. Legacy merge can accept multiple sources; v5 moves one source per request. Run multi-source migrations sequentially and record each operation independently.

Verification

Confirm existing container-tag values resolve unchanged as namespace paths.
Compare namespace counts with namespace-scoped document and memory lists.
Verify a permanent delete returns final counts while a move returns 202.
Verify restricted callers cannot read or mutate namespaces outside their scope.
Verify only organization-authorized callers can change settings or lifecycle.

Organization settings

v5 exposes only the organization-wide context needed to guide memory formation. Internal controls and profile bucket mutation are no longer part of this settings resource.

Endpoint mapping

Legacy	v5
`GET /v3/settings`	`GET /organization`
`PATCH /v3/settings`	`PATCH /organization`
`filterPrompt`	`organizationalContext`

Read organization settings

GET /organization

{
  "organizationalContext": "Acme builds security tools for enterprises",
  "namespaceCount": 42
}

Remove readers for legacy settings that are not present in this allowlisted response. namespaceCount is informational and cannot be changed through PATCH.

Update organization context

PATCH /v3/settings
{"filterPrompt":"Acme builds security tools for enterprises"}

PATCH /organization
{"organizationalContext":"Acme builds security tools for enterprises"}

The field is exhaustive: the supplied value replaces the existing context. Send null to remove it. Empty strings are rejected. Organization updates require an organization administrator. Do not silently fall back to namespace context when the caller receives 403.

Removed public operations

Organization profile-bucket mutation is not exposed through organization settings.
Bucket suggestion is not part of v5.
Organization data reset is not part of v5.
Namespace-owned profile buckets are managed through /ns/{namespace}/profile/buckets.

Verification

Compare the v5 context with the legacy filterPrompt before cutover.
Set, replace, and clear organizational context.
Confirm namespaceCount agrees with GET /namespaces for the same credentials.
Verify non-admin callers receive 403 on PATCH.
Confirm removed fields are not required by downstream configuration code.

Typed filters

v5 uses one optional singular filter field for search, profiles, and list operations.

Shape

type Filter =
  | { field: string; operator: "eq" | "neq"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "eq" | "neq"; value: number | boolean }
  | { field: string; operator: "gt" | "gte" | "lt" | "lte"; value: number }
  | { field: string; operator: "contains" | "notContains"; value: string; caseSensitive?: boolean }
  | { field: string; operator: "arrayContains" | "arrayNotContains"; value: string }
  | { operator: "and" | "or"; operands: Filter[] };

Fields may contain letters, numbers, _, ., and -. Expressions allow up to five nested levels and 200 operands per logical group.

Operator mapping

Legacy condition	v5 predicate
`{ key, value }`	`{ field: key, operator: "eq", value }`
`negate: true` equality	`operator: "neq"`
`filterType: "string_contains"`	`operator: "contains"`
contains + `negate: true`	`operator: "notContains"`
`filterType: "array_contains"`	`operator: "arrayContains"`
array contains + `negate: true`	`operator: "arrayNotContains"`
numeric `=` / numeric `=` + `negate: true`	`eq` / `neq` with a JSON number
numeric `>`, `>=`, `<`, `<=`	`gt`, `gte`, `lt`, `lte`
`AND` / `OR` arrays	lowercase `and` / `or` with `operands`
`ignoreCase: true`	`caseSensitive: false`

Before and after

{
  "AND": [
    { "key": "category", "value": "research" },
    { "key": "score", "value": 0.8, "filterType": "numeric", "numericOperator": ">=" }
  ]
}

{
  "operator": "and",
  "operands": [
    { "field": "category", "operator": "eq", "value": "research" },
    { "field": "score", "operator": "gte", "value": 0.8 }
  ]
}

Deterministic conversion

Rename outer filters to filter.
Recursively replace AND/OR objects with { operator, operands }.
Rename key to field.
Convert legacy flags into one explicit operator.
Keep numeric values as JSON numbers rather than numeric strings.
Remove legacy filterType, negate, numericOperator, and ignoreCase keys.

Verification

Compare result IDs for equality, inequality, contains, numeric, array, nested AND, and nested OR fixtures.
Add negative tests: legacy shapes, empty operands, incompatible value types, and unknown keys must return 400.
Confirm omitted filter preserves unfiltered behavior.

Verification and rollout

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

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

Ship v5 request construction behind a per-domain flag.
Dual-read or shadow-call where side effects allow it.
Switch ingestion, content management, search, profiles, then settings independently.
Monitor validation failures, authorization failures, latency, empty-result rate, and processing failures.
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.

Operations without a direct replacement

Direct memory creation and version updates: ingest or replace a source document instead.
Organization bucket suggestion and organization reset: not part of the v5 public surface.
Connector routes that still use /v3: unchanged; do not rewrite them.
Conversation ingestion (/v4/conversations): not part of the v5 public surface. Send the transcript as a document instead.
Container-tag merges: not part of the v5 public surface.

Use the v5 reference for the stable v5 API. /reference always points to the latest public version.

​Migrate with an agent

​Migrate by hand

​Recommended migration process

​Endpoint map

​SDKs, tools and the CLI

​TypeScript SDK changes

​Document ingestion

​Rename common fields

​Add or append one document

​Batch ingestion

​File ingestion

​Processing choices

​Verification

​Document updates

​Choose the correct write

​Update text or URL content

​Replace a file-backed document

​Partially update a file-backed document

​IDs and scope

​Processing and conflicts

​Verification

​Content management

​Retrieve a document and its derived context

​List documents, chunks, or memories

​Delete documents

​Forget memories

​Verification

​Search

​Request mapping

​Changed defaults

​Search modes

​Included context and ranking

​Response mapping

​Verification

​Profiles and buckets

​Remove search behavior from profile calls

​Read the v5 profile shape

​Read bucket definitions

​Add or edit namespace buckets

​Delete namespace buckets

​Verification

​Memory forgetting

​Choose exact or semantic forgetting

​Forget exact IDs

​Preview a semantic request

​Avoid selection drift

​Read the normalized response

​Removed memory-write routes

​Verification

​Namespaces

​Endpoint mapping

​List namespaces

​Read and update settings

​Permanently delete a namespace

​Move then remove a namespace

​Verification

​Organization settings

​Endpoint mapping

​Read organization settings

​Update organization context

​Removed public operations

​Verification

​Typed filters

​Shape

​Operator mapping

​Before and after

​Deterministic conversion

​Verification

​Verification and rollout

​Build deterministic fixtures

​Compare writes

​Compare reads and recall

​Exercise boundaries

​Classify differences

​Cut over by domain

​Completion checklist

​Operations without a direct replacement

Migrate with an agent

Migrate by hand

Recommended migration process

Endpoint map

SDKs, tools and the CLI

TypeScript SDK changes

Document ingestion

Rename common fields

Add or append one document

Batch ingestion

File ingestion

Processing choices

Verification

Document updates

Choose the correct write

Update text or URL content

Replace a file-backed document

Partially update a file-backed document

IDs and scope

Processing and conflicts

Verification

Content management

Retrieve a document and its derived context

List documents, chunks, or memories

Delete documents

Forget memories

Verification

Search

Request mapping

Changed defaults

Search modes

Included context and ranking

Response mapping

Verification

Profiles and buckets

Remove search behavior from profile calls

Read the v5 profile shape

Read bucket definitions

Add or edit namespace buckets

Delete namespace buckets

Verification

Memory forgetting

Choose exact or semantic forgetting

Forget exact IDs

Preview a semantic request

Avoid selection drift

Read the normalized response

Removed memory-write routes

Verification

Namespaces

Endpoint mapping

List namespaces

Read and update settings

Permanently delete a namespace

Move then remove a namespace

Verification

Organization settings

Endpoint mapping

Read organization settings

Update organization context

Removed public operations

Verification

Typed filters

Shape

Operator mapping

Before and after

Deterministic conversion

Verification

Verification and rollout

Build deterministic fixtures

Compare writes

Compare reads and recall

Exercise boundaries

Classify differences

Cut over by domain

Completion checklist

Operations without a direct replacement