mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-26 06:04:08 +00:00
docs(api): keep the default preferences bucket and drop v4 profile labels in v5 docs (#1809)
Fixes v5 profile and bucket docs.
- **The default `preferences` bucket can't be replaced.** It's always part of the effective set. Custom buckets are added alongside it, `deleteBuckets` can't remove it, and defining a bucket named `preferences` only overrides its description.
- **No `[Summary]`/`[Recent]` labels in v5.** Only v4 adds them. Summaries are now told apart by an `aggregated_` id, and individual `dynamic` entries keep their `[YYYY-MM-DD]` date. Example responses are updated, and the migration snippet calls out the change.
- **Name clashes.** A namespace bucket with an org bucket's name returns `409`; the docs said the org's definition silently wins.
- **Smaller fixes:**
- `filterPrompt` → `organizationalContext`.
- An invalid `organization.update` example (stray `},`).
- OAuth redirect URIs now use `/v3/connections/auth/callback/{provider}`.
- The v4 `include` example in the migration snippet.
- Broken anchors and links.
Checked against the current API and the published SDKs (TS 5.0.1, Python 5.0.0). Legacy v3/v4 docs are unchanged apart from factual fixes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
sohamd22
parent
ca89d161cc
commit
8452a00434
6 changed files with 37 additions and 27 deletions
|
|
@ -27,7 +27,6 @@ await supermemory.organization.update({
|
|||
- Outdated brand materials (pre-2024)
|
||||
- Internal discussions about brand changes
|
||||
- Competitor analysis docs`,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
|
|
@ -103,6 +102,10 @@ Supporting context persists on the namespace and combines with the org-level org
|
|||
|
||||
---
|
||||
|
||||
<Note>
|
||||
The Chunk size and Connector branding sections below use the legacy settings resource. Their `client.settings.update(...)` examples require a legacy SDK that exposes `settings`; SDK 5.x users should call `PATCH /v3/settings` directly with an org admin or owner credential. These options are not fields on the v5 organization resource.
|
||||
</Note>
|
||||
|
||||
## Chunk size
|
||||
|
||||
Control how documents are split into searchable pieces. Smaller chunks = more precise retrieval but less context per result.
|
||||
|
|
@ -133,7 +136,7 @@ Show "Log in to **YourApp**" instead of "Log in to Supermemory" when users conne
|
|||
<AccordionGroup>
|
||||
<Accordion title="Google Drive">
|
||||
1. Create OAuth credentials in [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Redirect URI: `https://api.supermemory.ai/v3/connections/google-drive/callback`
|
||||
2. Redirect URI: `https://api.supermemory.ai/v3/connections/auth/callback/google-drive`
|
||||
|
||||
```typescript
|
||||
await client.settings.update({
|
||||
|
|
@ -145,7 +148,7 @@ Show "Log in to **YourApp**" instead of "Log in to Supermemory" when users conne
|
|||
</Accordion>
|
||||
<Accordion title="Notion">
|
||||
1. Create integration at [Notion Developers](https://developers.notion.com/)
|
||||
2. Redirect URI: `https://api.supermemory.ai/v3/connections/notion/callback`
|
||||
2. Redirect URI: `https://api.supermemory.ai/v3/connections/auth/callback/notion`
|
||||
|
||||
```typescript
|
||||
await client.settings.update({
|
||||
|
|
@ -157,7 +160,7 @@ Show "Log in to **YourApp**" instead of "Log in to Supermemory" when users conne
|
|||
</Accordion>
|
||||
<Accordion title="OneDrive">
|
||||
1. Register app in [Azure Portal](https://portal.azure.com/)
|
||||
2. Redirect URI: `https://api.supermemory.ai/v3/connections/onedrive/callback`
|
||||
2. Redirect URI: `https://api.supermemory.ai/v3/connections/auth/callback/onedrive`
|
||||
|
||||
```typescript
|
||||
await client.settings.update({
|
||||
|
|
|
|||
|
|
@ -94,7 +94,7 @@ Recent context and temporary states:
|
|||
|
||||
Static and dynamic split facts by how long-lived they are. **Buckets** split them by *topic* — a third, independent axis you define, like `preferences`, `goals`, or `work`. As content is ingested, a classifier sorts each fact into the buckets it matches.
|
||||
|
||||
Every org starts with a default `preferences` bucket. Add your own in console settings at the organization level, or per namespace with `supermemory.profiles.setBuckets()` — namespace buckets are add-only, so a namespace always keeps every org-level bucket.
|
||||
Every org starts with a default `preferences` bucket, which is always present — custom buckets are added alongside it, never in place of it. Add your own in console settings at the organization level, or per namespace with `supermemory.profiles.setBuckets()` — namespace buckets are add-only, so a namespace always keeps every org-level bucket.
|
||||
|
||||
```typescript
|
||||
// Define a namespace-level bucket (name → description)
|
||||
|
|
@ -110,7 +110,7 @@ console.log(profile.buckets.preferences); // [{ id, memory }, ...]
|
|||
console.log(profile.buckets.goals);
|
||||
```
|
||||
|
||||
Bucket descriptions steer the classifier, so a precise description ("explicit first-person preferences only, exclude inferred traits") produces cleaner buckets than a vague one. Buckets are separate from [`filterPrompt`](/concepts/customization), which controls what gets ingested at all — buckets only organize facts that already made it into the profile.
|
||||
Bucket descriptions steer the classifier, so a precise description ("explicit first-person preferences only, exclude inferred traits") produces cleaner buckets than a vague one. Buckets are separate from [`organizationalContext`](/concepts/customization#organizational-context) (called `filterPrompt` in v3/v4), which steers what gets extracted at all — buckets only organize facts that already made it into the profile.
|
||||
|
||||
<Card title="Profile Buckets reference" icon="/icons/hugeicons/tag-01.svg" href="/user-profiles/buckets">
|
||||
Request bucketed profiles, create buckets at the org or namespace level, and see validation limits.
|
||||
|
|
|
|||
|
|
@ -62,16 +62,18 @@ Profiles are built automatically as you [ingest content](/ingestion/add-memories
|
|||
{ "id": "mem_3", "memory": "User prefers dark mode interfaces" }
|
||||
],
|
||||
"dynamic": [
|
||||
{ "id": "mem_4", "memory": "User is working on Project Alpha" },
|
||||
{ "id": "mem_5", "memory": "User recently started learning Rust" },
|
||||
{ "id": "mem_6", "memory": "User is debugging authentication issues" }
|
||||
{ "id": "mem_4", "memory": "[2026-10-02] User is working on Project Alpha" },
|
||||
{ "id": "mem_5", "memory": "[2026-10-05] User recently started learning Rust" },
|
||||
{ "id": "mem_6", "memory": "[2026-10-09] User is debugging authentication issues" }
|
||||
],
|
||||
"buckets": {}
|
||||
"buckets": {
|
||||
"preferences": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`static` and `dynamic` are always returned. Each entry is `{ id, memory }`; the `id` is the memory ID, so you can [forget](/recall/memory-operations#forget-memories) a profile entry directly.
|
||||
`static`, `dynamic`, and `buckets` are always returned. Omitting the request's `buckets` returns every effective bucket, including the built-in `preferences` bucket; specifying names returns only those buckets, and an empty list returns an empty bucket section. Each entry is `{ id, memory }`; the `id` is the memory ID, so you can [forget](/recall/memory-operations#forget-memories) a profile entry directly. The exception is synthesized summaries of older memories, whose `id` starts with `aggregated_` — they don't map to a single memory. Individual `dynamic` entries start with a `[YYYY-MM-DD]` date.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -123,7 +125,7 @@ The v5 profile call takes no query. When you also need query-ranked memories, ru
|
|||
|
||||
## Parameters
|
||||
|
||||
`namespace` is a top-level key (URL path). `body` is optional and accepts only `filter` and `buckets`.
|
||||
`namespace` is the first argument (URL path). The options object is optional and accepts only `filter` and `buckets`.
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ v5 returns a maintained profile directly and gives profile bucket definitions th
|
|||
<CodeGroup>
|
||||
```bash Legacy
|
||||
POST /v4/profile
|
||||
{"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":{}}
|
||||
{"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":["static","dynamic","buckets"]}
|
||||
```
|
||||
|
||||
```bash v5
|
||||
|
|
@ -22,13 +22,18 @@ Remove legacy `q`, `threshold`, and `include`. If the caller needs query-ranked
|
|||
{
|
||||
"profile": {
|
||||
"static": [{ "id": "mem_1", "memory": "The user works in design" }],
|
||||
"dynamic": [{ "id": "mem_2", "memory": "The user is preparing a launch" }],
|
||||
"buckets": { "work": [{ "id": "mem_3", "memory": "Prefers concise project updates" }] }
|
||||
"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 custom bucket; pass up to 50 names to narrow only the bucket section.
|
||||
`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
|
||||
|
||||
|
|
@ -65,7 +70,7 @@ 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.
|
||||
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
|
||||
|
||||
|
|
@ -92,7 +97,7 @@ await supermemory.profiles.deleteBuckets("user_1", {
|
|||
```
|
||||
</CodeGroup>
|
||||
|
||||
`supermemory.profile` takes no query. `body` is optional and accepts only `filter` and `buckets`. Read `profile.static`, `profile.dynamic`, and `profile.buckets[name]` as arrays of `{ id, memory }`.
|
||||
`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
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Buckets are **custom topical categories** for a profile — an axis that sits al
|
|||
New to buckets? Read the [conceptual overview](/concepts/user-profiles#buckets) first — this page is the API reference for reading, creating, and managing them.
|
||||
</Tip>
|
||||
|
||||
Every org starts with a built-in `preferences` bucket. You can define your own at the organization level, and add more per namespace (what v3/v4 called a container tag) — all covered below.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -50,11 +50,11 @@ Every org starts with a built-in `preferences` bucket. You can define your own a
|
|||
"dynamic": [],
|
||||
"buckets": {
|
||||
"preferences": [
|
||||
{ "id": "mem_1", "memory": "[Summary] Prefers concise, technical answers and dark-mode tooling" },
|
||||
{ "id": "mem_2", "memory": "[Recent] Switched their editor to Zed" }
|
||||
{ "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": "[Recent] Wants to ship the billing revamp this quarter" }
|
||||
{ "id": "mem_3", "memory": "Wants to ship the billing revamp this quarter" }
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -62,7 +62,7 @@ Every org starts with a built-in `preferences` bucket. You can define your own a
|
|||
```
|
||||
|
||||
<Note>
|
||||
**`[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.
|
||||
**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.
|
||||
</Note>
|
||||
|
||||
### List bucket definitions
|
||||
|
|
@ -106,7 +106,7 @@ Bucket definitions live at two levels: **organization** (the default set every n
|
|||
|
||||
### 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, and if a namespace bucket's name collides with an org bucket, the org's definition wins in the merged, effective set used at ingestion and read time.
|
||||
`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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="TypeScript">
|
||||
|
|
@ -179,7 +179,7 @@ If you'd rather start from a template than write descriptions from scratch, thes
|
|||
|
||||
### Default bucket
|
||||
|
||||
If neither the org nor the namespace 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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -203,7 +203,7 @@ Bucket descriptions steer classification. A precise description ("Explicit first
|
|||
|
||||
### Instructions
|
||||
|
||||
Bucket descriptions only steer classification *within* a bucket — they don't tell the model anything about the namespace itself. For that, set [`supportingContext`](/concepts/customization#entity-context) 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.
|
||||
Bucket descriptions only steer classification *within* a bucket — they don't tell the model anything about the namespace itself. For that, set [`supportingContext`](/concepts/customization#supporting-context) 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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="TypeScript">
|
||||
|
|
|
|||
|
|
@ -36,4 +36,4 @@ curl -X PUT "https://api.supermemory.ai/ns/user_1/profile/buckets" \
|
|||
|
||||
Profiles always contain static and dynamic sections, giving applications both durable knowledge and fresh context without composing them manually. Organization-owned buckets may be inherited but cannot be changed through namespace bucket endpoints.
|
||||
|
||||
See [profile migration](/migration/api-v5-recall).
|
||||
See [profile migration](/migration/api-v5-profiles).
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue