mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-27 06:15:15 +00:00
8452a00434
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)
107 lines
3.6 KiB
Text
107 lines
3.6 KiB
Text
v5 returns a maintained profile directly and gives profile bucket definitions their own namespace-scoped resource.
|
|
|
|
### Remove search behavior from profile calls
|
|
|
|
<CodeGroup>
|
|
```bash Legacy
|
|
POST /v4/profile
|
|
{"containerTag":"user_1","q":"work preferences","threshold":0.6,"include":["static","dynamic","buckets"]}
|
|
```
|
|
|
|
```bash v5
|
|
POST /ns/user_1/profile
|
|
{"filter":{"field":"region","operator":"eq","value":"us-west"},"buckets":["work"]}
|
|
```
|
|
</CodeGroup>
|
|
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
<CodeGroup>
|
|
```bash Legacy
|
|
POST /v4/profile/buckets
|
|
{"containerTag":"user_1"}
|
|
```
|
|
|
|
```bash v5
|
|
GET /ns/user_1/profile/buckets
|
|
```
|
|
</CodeGroup>
|
|
|
|
The response changes from key/description objects to a map:
|
|
|
|
```json
|
|
{"buckets":{"work":"Professional preferences and ongoing work"}}
|
|
```
|
|
|
|
### Add or edit namespace buckets
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
<CodeGroup>
|
|
```ts Legacy
|
|
const profile = await client.profile({ containerTag: "user_1", q: "work preferences" })
|
|
const buckets = await client.profile.buckets({ containerTag: "user_1" })
|
|
```
|
|
|
|
```ts v5
|
|
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"],
|
|
})
|
|
```
|
|
</CodeGroup>
|
|
|
|
`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.
|