Profile buckets

Buckets are custom topical categories for a profile — an axis that sits alongside static and dynamic. Where static/dynamic split facts by how long-lived they are, buckets group them by subject (e.g. preferences, goals, work). As content is ingested, a classifier assigns each memory to the buckets it matches, so you can pull just the slice of context a given surface needs.

New to buckets? Read the conceptual overview first — this page is the API reference for reading, creating, and managing them.

Every org starts with a built-in preferences bucket that is always present — buckets you define at the organization level, or add per namespace (what v3/v4 called a container tag), are added alongside it. All covered below.

Reading buckets

Requesting bucketed profiles

supermemory.profile returns buckets next to static and dynamic. Omit buckets in the request to get every effective bucket, or pass up to 50 names to narrow only the bucket section.

TypeScript
cURL

const { profile } = await supermemory.profile("user_123", { // optional — omit for all buckets
  buckets: ["preferences", "goals"],
});

console.log(profile.buckets.preferences.map((m) => m.memory));
console.log(profile.buckets.goals.map((m) => m.memory));

curl -X POST "https://api.supermemory.ai/ns/user_123/profile" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "buckets": ["preferences", "goals"] }'

Response:

{
  "profile": {
    "static": [],
    "dynamic": [],
    "buckets": {
      "preferences": [
        { "id": "mem_2", "memory": "Switched their editor to Zed" },
        { "id": "aggregated_0_1760000000000", "memory": "Tooling and style: Prefers concise, technical answers and dark-mode tooling" }
      ],
      "goals": [
        { "id": "mem_3", "memory": "Wants to ship the billing revamp this quarter" }
      ]
    }
  }
}

Summaries vs. individual memories. To keep profiles dense, once a bucket grows large enough its older memories are periodically aggregated into a short synthesis. Synthesized entries have an id starting with aggregated_ and don’t map to a single memory; entries with a regular memory ID were ingested since the last aggregation and aren’t summarized yet. v5 returns plain text — the [Recent]/[Summary] prefixes from v4 are not included, so use the aggregated_ ID prefix to tell summaries apart. Individual dynamic entries still start with a [YYYY-MM-DD] date.

List bucket definitions

To see which buckets are configured for a namespace (org buckets merged with any namespace-level additions), call profiles.getBuckets:

TypeScript
cURL

const { buckets } = await supermemory.profiles.getBuckets("user_123");
// { preferences: "Explicit first-person preferences...", work: "..." }

curl "https://api.supermemory.ai/ns/user_123/profile/buckets" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Response:

{
  "buckets": {
    "preferences": "Explicit first-person preferences the person directly stated."
  }
}

Field	Type	Description
`buckets`	object	Map of bucket name to description. The name is a stable slug, also stored on each memory. Lowercase alphanumeric with `-`/`_`, 1–64 chars
`buckets[name]`	string	What belongs in the bucket — guides the ingestion classifier

Creating and configuring buckets

Bucket definitions live at two levels: organization (the default set every namespace gets) and namespace (per-namespace additions). Namespace buckets are managed through profiles.setBuckets and profiles.deleteBuckets.

Namespace buckets

setBuckets sends 1 to 50 name-to-description entries. Existing namespace names are updated, new names are added, and omitted namespace buckets remain unchanged. These are add-only on top of org buckets — a namespace always keeps every org bucket. Sending a name the org already defines returns 409, and if an org bucket is added later with the same name as a namespace bucket, the org’s definition wins in the merged, effective set used at ingestion and read time.

TypeScript
cURL

await supermemory.profiles.setBuckets("user_alex", {
  buckets: {
    work: "Professional role, employer, projects, and work-related decisions.",
    trip_planning: "Upcoming trip details specific to this user.",
  },
});

curl -X PUT "https://api.supermemory.ai/ns/user_alex/profile/buckets" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "buckets": {
      "work": "Professional role, employer, projects, and work-related decisions.",
      "trip_planning": "Upcoming trip details specific to this user."
    }
  }'

Delete namespace buckets

TypeScript
cURL

await supermemory.profiles.deleteBuckets("user_alex", {
  buckets: ["trip_planning"],
});

curl -X DELETE "https://api.supermemory.ai/ns/user_alex/profile/buckets" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "buckets": ["trip_planning"] }'

Organization-owned buckets appear in the effective getBuckets response but cannot be changed or removed through namespace setBuckets or deleteBuckets calls. Organization-level buckets are managed in the console, not through the v5 API.

Starter presets

If you’d rather start from a template than write descriptions from scratch, these are the same presets available in the console UI:

Name	Description
`preferences`	Stated likes, dislikes, and personal settings choices — food, media, tools, aesthetics, and other expressed tastes.
`interests`	Topics, hobbies, and domains the person is curious about or actively follows, even if not yet a firm preference.
`goals`	Short- and long-term objectives, aspirations, and things the person wants to achieve or work toward.
`work`	Professional context: current role, employer, projects, colleagues, career trajectory, and work-related decisions.
`relationships`	People in the person’s life — family, friends, colleagues, partners — and the nature of those connections.
`health`	Physical and mental wellbeing: conditions, habits, medications, fitness routines, and health-related goals.
`skills`	Competencies, expertise areas, tools mastered, and things the person is actively learning.
`finances`	Financial habits, spending patterns, savings goals, income context, and money-related decisions.
`education`	Academic background, current courses, learning goals, and educational achievements.
`travel`	Places visited, travel preferences, upcoming trips, and destinations the person wants to visit.
`values`	Core beliefs, ethical stances, principles, and things that matter most to the person.
`projects`	Personal and professional side projects, creative endeavors, and things being built outside of primary work.

Default bucket

Every namespace has a built-in preferences bucket, scoped tightly to explicit first-person statements (“prefers X over Y”, “always uses W”) — not inferred traits or general observations. It is always part of the effective set: configuring your own buckets adds to it rather than replacing it, and deleteBuckets can’t remove it. Defining a bucket named preferences only overrides its description; an empty description falls back to the built-in one.

Validation & limits

Rule	Detail
Name format	Lowercase alphanumeric, starting with a letter/digit, may contain `-`/`_`. 1–64 chars
Reserved names	`static` and `dynamic` can’t be used as bucket names
Max buckets	50 per request — applies separately to an org’s list and to each namespace’s list
Duplicate names	Rejected within a single request
Description	Up to 2,000 chars

Bucket descriptions steer classification. A precise description (“Explicit first-person preferences only — exclude inferred traits”) yields cleaner buckets than a vague one.

Configure

Instructions

Bucket descriptions only steer classification within a bucket — they don’t tell the model anything about the namespace itself. For that, set supportingContext on the namespace: a free-text field that’s appended alongside the org-level organizationalContext into the same prompt the extraction/classification step uses, so it shapes bucket assignment too, not just fact extraction.

TypeScript
cURL

await supermemory.namespaces.update("user_alex", {
  supportingContext: "This namespace belongs to a solo founder juggling sales, hiring, and product.",
});

curl -X PATCH "https://api.supermemory.ai/ns/user_alex" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "supportingContext": "This namespace belongs to a solo founder juggling sales, hiring, and product."
  }'

Field	Type	Limit
`supportingContext`	string \| null	Up to 1,500 characters. Pass `null` to clear

supportingContext is per-namespace, so use it for context specific to that user/namespace (who they are, what the namespace is for) — use org-level organizationalContext for guidance that should apply everywhere. Both are combined into the same prompt, so keep them complementary rather than redundant.

You can also set supportingContext inline when adding content, via supportingContext in the body of supermemory.add — useful if you don’t want a separate namespace call.

Model selection

The model behind extraction and bucket classification isn’t configurable through the API on supermemory Cloud — it’s managed for you. If you’re self-hosting, you choose the provider and model yourself via environment variables (OPENAI_MODEL and related) — see Self-hosting Configuration.

Next steps

User Profiles — Fetch and use profiles via the API
User Profiles Concept — Static vs dynamic vs buckets
Namespaces — How namespaces work

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Reading buckets

Requesting bucketed profiles

List bucket definitions

Creating and configuring buckets

Namespace buckets

Delete namespace buckets

Starter presets

Default bucket

Validation & limits

Configure

Instructions

Model selection

Next steps

​Reading buckets

​Requesting bucketed profiles

​List bucket definitions

​Creating and configuring buckets

​Namespace buckets

​Delete namespace buckets

​Starter presets

​Default bucket

​Validation & limits

​Configure

​Instructions

​Model selection

​Next steps

Reading buckets

Requesting bucketed profiles

List bucket definitions

Creating and configuring buckets

Namespace buckets

Delete namespace buckets

Starter presets

Default bucket

Validation & limits

Configure

Instructions

Model selection

Next steps