## What
The Supermemory API now serves the session endpoint unversioned at `/session` (supermemoryai/mono#3626). `sm_` API-key validation in the MCP worker calls `/session` instead of `/v3/session`. One-line code change.
- `apps/mcp/src/server/auth/index.ts`: `fetchSession` requests `/session`.
- `apps/mcp/src/server/auth/index.test.ts`: asserts the new URL and that a refused key makes exactly one request.
- `apps/mcp/src/shared/types.ts`: comment updated.
## Deploy order
This worker depends on the API serving `/session`. **Deploy mono#3626 first.** Until then, production answers `/session` with 404 for full keys and 403 for scoped keys (the scope allowlist is checked before routing), and every `sm_` key would be rejected.
No fallback to `/v3/session` on purpose: the only "old server" in scope is that deploy window, and a failed-request fallback would blur 403/404 semantics for a case merge ordering already covers.
## Verification
- `bun run check-types`, `vitest run src` (29/29).
- Against the API with mono#3626 running: full key → `/session` 200 valid; scoped key → `/session` 200 valid; bad key → `/session` 401 rejected, single call.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Why
The document operations guide did not describe how to retrieve extracted text from a v5 document list, and the migration guide incorrectly said the list `include` object was for memories only.
## What changed
- Document `include.content`, its `false` default, and a cURL request for uploaded files in the same section pattern as the surrounding guide.
- Explain that list content is the last published extracted text, including the behavior before first publication and during failed replacement.
- Correct the v5 migration and reference overview copy.
```mermaid
flowchart LR
A[Document operations guide] --> B[include.content request]
B --> C[Published extracted text in list response]
```
## Validation
- Compared the guide and migration snippet with adjacent v5 docs for format and terminology.
- `git diff --check` — passed.
- `python3 -m json.tool apps/docs/docs.json` — passed.
Related API PR: https://github.com/supermemoryai/mono/pull/3606
The written docs should publish with or after the API change. The generated v5 reference reads the deployed OpenAPI source, so it updates when that source is available and the docs site refreshes.
forget_memory called the semantic forget-matching endpoint (two LLM calls plus a widening loop) to pick one memory, so most calls hit the 30s timeout since the v5 move. It now takes ids from search_memory and forgets them with the exact-ID endpoint (~0.5s on prod).
- Text-only calls forget only an exact text match; otherwise nothing is deleted and the closest memories come back with their IDs.
- Legacy add_memory action=forget keeps working through the same path.
Fixes billing, analytics, security and legacy reference pages.
- **Operations.** `rewriteQuery`, rerank/aggregate and forget-matching each bill one operation.
- **Profile metering.** v5 profile is documented as 1 search query per call.
- **Analytics:**
- The errors response shape is fixed.
- Usage `byKey` includes `tokensUsed`, and the log `output` example has the right shape.
- The 90-day range limit doesn't exist.
- **Smaller fixes:**
- Only 2 billing endpoints need an admin.
- The `credits` response shape.
- The 2FA gate is in the feature table.
- The security page points to the one-call namespace delete for data erasure.
- Container-tag merge takes several sources.
- A stale "after API deploy" note is removed.
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)
Fixes self-hosting docs to match the `supermemory-server` binary.
- **Ingest example.** `?dreaming=instant` was in the URL in the quickstart; it's now in the body.
- **Startup.** The banner example is accurate. The plaintext `env` file is legacy: it's moved into the encrypted `env.enc` and then deleted.
- **Providers:**
- The provider order is OpenAI → Anthropic → Gemini → Vertex → Groq → Workers AI.
- PDF extraction needs `GEMINI_API_KEY` (Vertex doesn't help).
- URL ingestion uses Firecrawl and needs `FIRECRAWL_API_KEY`.
- **Smaller fixes:**
- The SDK option is `baseUrl`.
- Documented the environment switches the binary honors.
- Embedding defaults are corrected.
- Removed the claim that the hosted platform uses the same embedding stack.
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)
Fixes connector docs.
- **`authorization.url` examples.** They now show the URL the API actually returns (`/v3/connections/auth/redirect?state=…`), not provider URLs.
- **Broken examples:**
- TS `connectors.create` examples were missing commas.
- Python dicts now use the SDK's snake_case keys.
- `connector.createdAt` → `connector.system.createdAt`.
- The list default `limit` is 10.
- **Pending connectors.** They are visible through get (`pending_authorization`), just not in list.
- **Gmail:**
- It needs the Max plan.
- Nothing syncs until labels are picked.
- The watch covers the selected labels, not just INBOX.
- `from` filters use `contains`.
- **Smaller fixes:**
- The OAuth redirect-URI troubleshooting.
- Notion property metadata keys.
- Picker error codes.
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)
Fixes namespace, auth and SDK-shape docs.
- **Namespace move example deleted instead.** It sent `moveTo` in a JSON body on `DELETE /ns/{namespace}`. The route only reads `moveTo` from the query string and ignores the body, so following the docs permanently deleted the namespace. It now uses `?moveTo=`, and the overview warns about this.
- **SDK call shape.** URL values are positional (`namespace` first), followed by one options object; the docs described one object with `body`. Python 5.0.0 is the v5 client, so "no v5 Python SDK" is gone.
- **Scoped keys** (`authentication.mdx`):
- The allowed-endpoints list now includes the `/ns/*` routes; all legacy routes are kept.
- `containerTags` (several namespaces) is documented.
- Namespace names don't allow dots.
- **Key permissions.** Read/write applies to the whole key; only restricted members have per-namespace permissions.
- **Smaller fixes:**
- The move response has no `success` field.
- `namespaceCount` only matches the namespace list for an unrestricted key.
- `setup --json` does nothing.
- The agent prompt's ban on `memories.*` now covers only the calls v5 removed.
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)
Fixes v5 ingestion and document-operation docs.
- **Query params return `400`.** `dreaming`, `fileType` and `mimeType` were documented as query params; they are JSON body or multipart form fields.
- **Errors.** Out-of-balance quota is `402`, not `429`; `429` is only rate limiting. Added the `409` returned during a namespace merge.
- **Statuses.** There is no `processing` status. The real ones are queued, extracting, chunking, embedding, done and failed; treat anything else as in progress.
- **`group` on updates.** `group` is ingestion-side: it picks which existing memories serve as context while content is processed. Changing it only takes effect on re-ingestion, so it's sent with `content`/`file`. The "group-only PATCH" claims are removed from the migration doc.
- **Lists, deletes and forget:**
- Valid `sort` values per type, a `limit` max of 100, and `include.forgotten`.
- Deletes skip documents that are still processing.
- Forget-matching has a 100-match cap and a 2000-character `query` limit.
- **Failed documents stay `failed`.** The docs said they're deleted after 2 minutes. They actually stay `failed`, and resending the same `id` reprocesses them.
- **Smaller fixes:**
- Metadata allows `string[]`.
- The batch response field is `count`.
- `audio` is a valid `fileType`.
- Chunk overlap is 200 characters.
- URL extraction no longer claims Markdowner.
- Search examples no longer index the response object as an array.
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)
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)
Fixes v5 search and recall docs that didn't match the API.
- **Options in the URL.** Search examples passed `searchMode`/`limit` as query params, and ingest examples passed `dreaming`/`taskType` the same way. v5 rejects every query param on these routes with `400`. They now go in the JSON body (quickstart, rules, super-rag, recall/search).
- **`include`, not `attach`.** Renamed the search option. Its `forgotten` flag also admits forgotten memories into the main results, not just related context.
- **Search response.** Added the required `isInference`. `metadata` is always an object, and `system.createdAt` is optional.
- **Search add-ons are billed.** `rewriteQuery` and `rerank` each bill one extra operation; the docs said "no extra cost".
- **Removed claims that don't match current behavior:**
- inferred memories being down-weighted in search;
- AST code chunking via `code-chunk` (super-rag now describes how chunking actually works);
- a 64-character metadata key limit.
- **Smaller fixes:**
- The namespace is the SDK's first argument; the docs called it a top-level key.
- "No v5 Python SDK" was stale.
- Memory review: `total` semantics, the internal review stamp, and the missing 403.
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)
Bundles 10 community fixes for the Python wrappers, each commit kept with its original author. Ships supermemory-openai-sdk 1.0.10, supermemory-cartesia 0.1.5 and supermemory-pipecat 0.1.5.
- openai-sdk-python: shared OpenAI clients no longer leak memories across tenants (#1503), memory search fails open instead of crashing the chat (#1288), the requests fallback runs off the event loop (#1660), get_profile works for users with no memories (#1759).
- cartesia: the wrapped agent runs exactly once per event (#1280, #1670), plain-string and chunk-only search results are kept (#1683, #1693).
- pipecat: memory text stays literal when replacing the injected block (#1647), `InputParams` is exported from the package root (#1575).
- #1503 was hand-ported onto main's newer middleware. #1751 is left out: the v5 agent-framework migration (#1786) appends to the conversation document by design.
Co-Authored-By: abhinav7x94 <204053250+abhinav7x94@users.noreply.github.com>
Co-Authored-By: shamAnimates <145093437+shamAnimates@users.noreply.github.com>
Co-Authored-By: aloktripathi1 <142301030+aloktripathi1@users.noreply.github.com>
Co-Authored-By: Cintu07 <178455858+Cintu07@users.noreply.github.com>
Co-Authored-By: Atharvsinh-codez <201381760+Atharvsinh-codez@users.noreply.github.com>
Co-Authored-By: abhay-codes07 <182421137+abhay-codes07@users.noreply.github.com>
Co-Authored-By: nkootstra <545768+nkootstra@users.noreply.github.com>
Co-Authored-By: Agnik47 <140933190+Agnik47@users.noreply.github.com>
Community fixes for the docs-test runner.
- Python examples run on Windows: the runner picks `.venv/Scripts/python.exe` and reports a missing venv as a failed test (#1487).
- TypeScript examples exit 1 when `main()` rejects, so broken examples no longer count as passed (#1495).
Co-Authored-By: abhinav7x94 <204053250+abhinav7x94@users.noreply.github.com>
Community docs fixes, checked against the self-hosted server source.
- CONTRIBUTING.md: setup steps and project structure match the repo (#1745).
- README: link the self-hosting quickstart (#1713).
- Self-hosting: database snapshot behavior (#1687) and embedding env vars, local model dimensions and the v0.0.6 upgrade lock (#1659), trimmed to what the code does.
- Docs sidebar: hover and selected state CSS from #1784, without the duplicated bold icon set.
- `SUPERMEMORY_DATA_DIR` now defaults to `~/.supermemory` (server-v0.0.9).
Co-Authored-By: Agnik47 <140933190+Agnik47@users.noreply.github.com>
Co-Authored-By: Fullstop000 <fullstop1005@gmail.com>
Co-Authored-By: Adityakk9031 <143548997+Adityakk9031@users.noreply.github.com>
Co-Authored-By: parthivdzns <parthiv.des@gmail.com>
Docs for supermemoryai/mono#3519: v5 document reads and list items now return `system.dreamingStatus` (`"dreaming" | "done"`), the signal for when a document's memories are ready, separate from `system.status`.
- Migration guide (content-management snippet): the field, why it differs from `status`, and the move from v3's top-level `dreamingStatus`.
- Document operations: a "Memory generation status" section, plus the field in the get, list, and processing-queue examples.
- One-line pointers in the SDK mapping table, batch ingest, and quickstart.
Draft until mono#3519 is deployed and the v5 SDK is regenerated: `supermemory@5.0.1` doesn't type `system.dreamingStatus` yet, so the new TS examples won't compile before then. The endpoint reference pages come from the live v5 spec and update on their own.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
#1665 renamed getDocument, listSpaces, listDocuments, listMemories and whoAmI to snake_case with no aliases. Clients with a cached tool list (ChatGPT, Codex, Claude) still call the old names and fail 100% of the time (~2k errors from ~300 users in the last 10 days, per PostHog). The old names are now registered again with the same handler and a "Deprecated alias" description. They stay listed because ChatGPT rejects calls to tools missing from tools/list.
New shared snippet with the npx supermemory@latest migrate command, placed on the tools 3.0 guide, the four integration pages, the API reference overview and namespaces page, the ten migration sub pages, and the agents page. The migration guide keeps the command first and folds the paste-in prompt into an accordion; the --prompt variant is gone from the examples.
The Copy prompt button on the docs home still handed agents the v3/v4 prompt with containerTag and /v3/documents, and the hero code samples used the old call shape. Both now match the console's v5 onboarding prompt and the shipped SDKs, with install hints for the stable 5.x releases and a pointer to the migration guide. The agents page starter prompt drops the rc.5 { namespace, body } description.
Docs for supermemoryai/mono#3420: `GET /namespaces` returns `{namespaces, pagination}` (newest first, `limit` up to 100), and the SDK note now describes `namespaces.list()` and both delete outcomes (`status: "deleted"` / `"queued"`) correctly. Also rewrites the memory GET and batch-result descriptions so they no longer refer to other endpoints.
Rewrites 339 TypeScript calls across 50 pages from the rc.5 `method({ namespace, body })` form to the shipped `method(namespace, { ... })` form, and aligns field names with the live v5 spec: `attach` to `include`, `authUrl` to `authorization`, `lastSync` to `latestRun`, `deletedCount` to `count`, and the paginated `namespaces.list()`.
Renames container tags to namespaces across concepts, connectors, integrations and snippets. The namespace pages keep container tag in the description, search keywords and a rename note so old searches still land, and the v3 reference page points at v5.
The migration guide's SDK table now covers both 5.0.0 SDKs, and the SDK integration page uses the real client options (`baseUrl`, `timeoutInSeconds`, `maxRetries`) and error classes.
Docs for supermemoryai/mono#3421: ingest `taskType`/`dreaming` move into the JSON body (form fields on file routes, alongside `fileType`/`mimeType`); namespace delete takes `moveTo` as a query param and rejects a body. Adds a "where parameters live" rule to the migration overview.
Every integration (AI SDK, OpenAI, Mastra, VoltAgent, Claude memory) now calls v5 through `supermemory@5`. The config takes one `namespace` instead of `containerTags` or `projectId`, and `withSupermemory` takes `namespace` and `id` instead of `containerTag` and `customId`. No aliases. With no config the tools still use `sm_project_default`.
Conversations are stored as one document per conversation keyed by `id` instead of `/v4/conversations`. `memoryForget` drops `reason`; forgetting by text previews with `forgetMatching` and then forgets exact matches by id. Claude memory marks its files with `metadata.source` instead of a second tag. Search keeps the 2.x defaults so results do not shift.
`packages/ai-sdk` is removed: npm already deprecates it in favor of `@supermemory/tools/ai-sdk`, so its CI steps and playground wiring go too. `apps/sdk-playground` moves to the new tools API and v5 routes, including its Python server.
Tested against production: add, search, profile, list and delete. 112 unit tests pass; type errors drop from 148 to 141, none new. The `supermemory` dependency pins the rc until 5.0.0 is published.
