diff --git a/apps/docs/concepts/customization.mdx b/apps/docs/concepts/customization.mdx index 8f43df9b..25c4d8a6 100644 --- a/apps/docs/concepts/customization.mdx +++ b/apps/docs/concepts/customization.mdx @@ -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 --- + +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. + + ## 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 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 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 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({ diff --git a/apps/docs/concepts/user-profiles.mdx b/apps/docs/concepts/user-profiles.mdx index d03dede8..4e09a6f3 100644 --- a/apps/docs/concepts/user-profiles.mdx +++ b/apps/docs/concepts/user-profiles.mdx @@ -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. Request bucketed profiles, create buckets at the org or namespace level, and see validation limits. diff --git a/apps/docs/recall/user-profiles.mdx b/apps/docs/recall/user-profiles.mdx index a953fcb4..413332e0 100644 --- a/apps/docs/recall/user-profiles.mdx +++ b/apps/docs/recall/user-profiles.mdx @@ -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 | |-----------|------|----------|-------------| diff --git a/apps/docs/snippets/api-v5-profiles.mdx b/apps/docs/snippets/api-v5-profiles.mdx index eaa126d3..39440571 100644 --- a/apps/docs/snippets/api-v5-profiles.mdx +++ b/apps/docs/snippets/api-v5-profiles.mdx @@ -5,7 +5,7 @@ v5 returns a maintained profile directly and gives profile bucket definitions th ```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", { ``` -`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 diff --git a/apps/docs/user-profiles/buckets.mdx b/apps/docs/user-profiles/buckets.mdx index 553a5f8b..8fa53e27 100644 --- a/apps/docs/user-profiles/buckets.mdx +++ b/apps/docs/user-profiles/buckets.mdx @@ -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. -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 ``` -**`[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. ### 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. @@ -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. diff --git a/apps/docs/v5/api-reference/profiles.mdx b/apps/docs/v5/api-reference/profiles.mdx index 77bb560e..a99a1e84 100644 --- a/apps/docs/v5/api-reference/profiles.mdx +++ b/apps/docs/v5/api-reference/profiles.mdx @@ -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).