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. You can define your own at the organization level, add more at the space (container tag) level, or get AI-generated suggestions — all covered below.

Reading buckets

Requesting bucketed profiles

Pass include: ["buckets"] to /v4/profile to return bucket-organized memories, and optionally buckets to limit the response to specific keys. include also lets you skip sections you don’t need — ["buckets"] alone omits static and dynamic.

fetch
cURL

const res = await fetch("https://api.supermemory.ai/v4/profile", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    containerTag: "user_123",
    include: ["buckets"],
    buckets: ["preferences", "goals"]   // optional — omit for all buckets
  })
});

const { profile } = await res.json();
console.log(profile.buckets.preferences);
console.log(profile.buckets.goals);

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

Response:

{
  "profile": {
    "buckets": {
      "preferences": [
        "[Summary] Prefers concise, technical answers and dark-mode tooling",
        "[Recent] Switched their editor to Zed"
      ],
      "goals": [
        "[Recent] Wants to ship the billing revamp this quarter"
      ]
    }
  }
}

[Recent] and [Summary] labels. To keep profiles dense, an entity’s older memories are periodically aggregated into a short synthesis. Entries prefixed [Summary] are that aggregated context; entries prefixed [Recent] were ingested since the last aggregation and aren’t summarized yet. The dynamic section uses the same [Recent] prefix (plus a [YYYY-MM-DD] date). Strip the prefixes if you only want raw text, or keep them to signal recency to your model.

List bucket definitions

To see which buckets are configured for a container tag (org buckets merged with any space-level additions), call /v4/profile/buckets:

fetch
cURL

const res = await fetch("https://api.supermemory.ai/v4/profile/buckets", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ containerTag: "user_123" })
});

const { buckets } = await res.json();
// [{ key: "preferences", description: "..." }, ...]

curl -X POST "https://api.supermemory.ai/v4/profile/buckets" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"containerTag": "user_123"}'

Response:

{
  "buckets": [
    {
      "key": "preferences",
      "description": "Explicit first-person preferences the person directly stated."
    }
  ]
}

Field	Type	Description
`buckets[].key`	string	Stable slug, also stored on each memory. Lowercase alphanumeric with `-`/`_`, 1–64 chars
`buckets[].description`	string	What belongs in the bucket — guides the ingestion classifier

This endpoint requires only that the caller belongs to the org — any role, and any API key (scoped keys included) can read bucket definitions.

Creating and configuring buckets

Bucket definitions live at two levels: organization (the default set every container tag gets) and space (per-container-tag additions). Both are configured through the settings API — there’s no console-only path; these are regular authenticated endpoints.

Writing buckets requires an admin or owner role in the org, and a full-access API key — project/container-tag-scoped keys cannot call these endpoints and will get a 403. Reading buckets (the endpoints above) has no such restriction.

Organization-level buckets

PATCH /v3/settings sets the org’s bucket list. The profileBuckets array replaces the entire stored list — it’s not a merge, so always send the full set you want.

fetch
cURL

const res = await fetch("https://api.supermemory.ai/v3/settings", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    profileBuckets: [
      { key: "work", description: "Professional role, employer, projects, and work-related decisions." },
      { key: "health", description: "Physical and mental wellbeing, habits, and health-related goals." }
    ]
  })
});

const { updated } = await res.json();

curl -X PATCH "https://api.supermemory.ai/v3/settings" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileBuckets": [
      { "key": "work", "description": "Professional role, employer, projects, and work-related decisions." },
      { "key": "health", "description": "Physical and mental wellbeing, habits, and health-related goals." }
    ]
  }'

Response:

{
  "orgId": "org_abc123xyz",
  "orgSlug": "acme-inc",
  "updated": {
    "profileBuckets": [
      { "key": "work", "description": "Professional role, employer, projects, and work-related decisions." },
      { "key": "health", "description": "Physical and mental wellbeing, habits, and health-related goals." }
    ]
    // ...other org settings fields
  }
}

GET /v3/settings returns the current org settings, including profileBuckets, without changing anything.

Space (container tag) buckets

PATCH /v3/container-tags/{containerTag} sets a container tag’s own bucket list. These are add-only on top of org buckets — a tag always keeps every org bucket, and if a space bucket’s key collides with an org bucket, the org’s definition wins in the merged, effective set used at ingestion and read time.

fetch
cURL

const res = await fetch("https://api.supermemory.ai/v3/container-tags/user_alex", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    profileBuckets: [
      { key: "trip_planning", description: "Upcoming trip details specific to this user." }
    ]
  })
});

curl -X PATCH "https://api.supermemory.ai/v3/container-tags/user_alex" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileBuckets": [
      { "key": "trip_planning", "description": "Upcoming trip details specific to this user." }
    ]
  }'

Response:

{
  "containerTag": "user_alex",
  "name": "user_alex",
  "entityContext": null,
  "memoryFilesystemPaths": null,
  "profileBuckets": [
    { "key": "trip_planning", "description": "Upcoming trip details specific to this user." }
  ],
  "updatedAt": "2026-07-18T00:00:00.000Z"
}

Like the org endpoint, this replaces the tag’s own bucket list, not the merged/effective set — profileBuckets in the response is only what this space added, not the org buckets it inherits. Call /v4/profile/buckets to see the merged, effective list for a tag.

AI-generated suggestions

POST /v3/settings/suggest-buckets returns 3–6 bucket suggestions tailored to your org, generated from the filterPrompt already configured in your org settings. It doesn’t save anything — pass the results into the PATCH /v3/settings call above to apply them.

fetch
cURL

const res = await fetch("https://api.supermemory.ai/v3/settings/suggest-buckets", {
  method: "POST",
  headers: { "Authorization": `Bearer ${API_KEY}` }
});

const { suggestions } = await res.json();
// [{ key: "customer_support", description: "..." }, ...]

curl -X POST "https://api.supermemory.ai/v3/settings/suggest-buckets" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Requires a filterPrompt already set on your org (via PATCH /v3/settings) — without one, this returns 400 { "error": "No organization context configured..." }, since suggestions are tailored from it.

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:

Key	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

If neither the org nor the space has configured any buckets, ingestion falls back to a single built-in preferences bucket, scoped tightly to explicit first-person statements (“prefers X over Y”, “always uses W”) — not inferred traits or general observations. Configuring your own buckets replaces this default.

Validation & limits

Rule	Detail
Key format	Lowercase alphanumeric, starting with a letter/digit, may contain `-`/`_`. 1–64 chars
Reserved keys	`static` and `dynamic` can’t be used as bucket keys
Max buckets	50 per array — applies separately to an org’s list and to each space’s list
Duplicate keys	Rejected within a single request’s array
Description	Optional, up to 2,000 chars. Defaults to empty if omitted

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 space itself. For that, set entityContext on the container tag: a free-text field that’s appended alongside filterPrompt into the same prompt the extraction/classification step uses, so it shapes bucket assignment too, not just fact extraction. PATCH /v3/container-tags/{containerTag}:

fetch
cURL

await fetch("https://api.supermemory.ai/v3/container-tags/user_alex", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    entityContext: "This tag belongs to a solo founder juggling sales, hiring, and product."
  })
});

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

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

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

You can also set entityContext inline when adding content, via entityContext on POST /v4/memories — useful if you don’t want a separate settings 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
Container Tags — How spaces and container tags work

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Reading buckets

Requesting bucketed profiles

List bucket definitions

Creating and configuring buckets

Organization-level buckets

Space (container tag) buckets

AI-generated suggestions

Starter presets

Default bucket

Validation & limits

Configure

Instructions

Model selection

Next Steps

​Reading buckets

​Requesting bucketed profiles

​List bucket definitions

​Creating and configuring buckets

​Organization-level buckets

​Space (container tag) buckets

​AI-generated suggestions

​Starter presets

​Default bucket

​Validation & limits

​Configure

​Instructions

​Model selection

​Next Steps

Reading buckets

Requesting bucketed profiles

List bucket definitions

Creating and configuring buckets

Organization-level buckets

Space (container tag) buckets

AI-generated suggestions

Starter presets

Default bucket

Validation & limits

Configure

Instructions

Model selection

Next Steps