Migrate profiles and buckets to v5

On v3 or v4? Run npx supermemory@latest migrate, or read the full v5 migration guide.

Migration details

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":["static","dynamic","buckets"]}

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": [{ "id": "mem_1", "memory": "The user works in design" }],
    "dynamic": [{ "id": "mem_2", "memory": "[2026-10-01] The user is preparing a launch" }],
    "buckets": {
      "preferences": [],
      "work": [{ "id": "mem_3", "memory": "Prefers concise project updates" }]
    }
  }
}

static and dynamic are always returned and cannot be disabled. Omit buckets in the request to return every effective bucket, including the built-in preferences bucket; pass up to 50 names to narrow only the bucket section. Entries change from v4 strings to { id, memory } objects, and the v4 [Recent]/[Summary] text prefixes are dropped. Synthesized summaries of older memories now carry an id starting with aggregated_; individual dynamic entries keep their [YYYY-MM-DD] date prefix.

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 — naming one returns 409. The built-in preferences bucket always stays in the effective set; DELETE only removes namespace-owned buckets.

With the SDK

const profile = await client.profile({ containerTag: "user_1", q: "work preferences" })
const buckets = await client.profile.buckets({ containerTag: "user_1" })

const { profile } = await supermemory.profile("user_1", {
  buckets: ["work"],
})

const buckets = await supermemory.profiles.getBuckets("user_1")

await supermemory.profiles.setBuckets("user_1", {
  buckets: { work: "Professional preferences and ongoing work" },
})

await supermemory.profiles.deleteBuckets("user_1", {
  buckets: ["work"],
})

supermemory.profile(namespace, options?) takes no query. The options object is optional and accepts only filter and buckets. Read profile.static, profile.dynamic, and profile.buckets[name] as arrays of { id, memory }.

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.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Migration details

Remove search behavior from profile calls

Read the v5 profile shape

Read bucket definitions

Add or edit namespace buckets

Delete namespace buckets

With the SDK

Verification

​Migration details

​Remove search behavior from profile calls

​Read the v5 profile shape

​Read bucket definitions

​Add or edit namespace buckets

​Delete namespace buckets

​With the SDK

​Verification

Migration details

Remove search behavior from profile calls

Read the v5 profile shape

Read bucket definitions

Add or edit namespace buckets

Delete namespace buckets

With the SDK

Verification