graphite-app · Oct 6, 2026 · Oct 6, 2026
diff --git a/apps/docs/api-reference/overview.mdx b/apps/docs/api-reference/overview.mdx
@@ -4,6 +4,10 @@ description: "Interactive reference for the Supermemory HTTP API: ingest, search
 icon: "/icons/hugeicons/plug-socket.svg"
 ---
 
+<Warning>
+This is the legacy v3/v4 reference. v3 and v4 are deprecated and will be shut down on **December 31, 2026**. Move to [v5](/v5/api-reference/overview) before then. The [migration guide](/migration/api-v5) maps every legacy call to its v5 equivalent.
+</Warning>
+
 This is the **contract-level** reference for Supermemory: methods, paths, parameters, and the playground.
 
 For narrative guides (when to use what, patterns, SDKs), start with the [Quickstart](/quickstart) and [Using supermemory](/ingestion/add-memories).

diff --git a/apps/docs/docs.json b/apps/docs/docs.json
@@ -1,5 +1,9 @@
 {
 	"$schema": "https://mintlify.com/docs.json",
+	"banner": {
+		"content": "**v3 and v4 are deprecated and will be shut down on December 31, 2026.** Move to v5 before then. [Read the migration guide](/migration/api-v5).",
+		"dismissible": true
+	},
 	"api": {
 		"examples": {
 			"defaults": "required",
@@ -247,6 +251,23 @@
 							{
 								"group": "Migration guides",
 								"pages": [
+									{
+										"group": "Supermemory API upgrades",
+										"icon": "arrow-up-right",
+										"pages": [
+											"migration/api-v5",
+											"migration/api-v5-document-writes",
+											"migration/api-v5-document-updates",
+											"migration/api-v5-document-reads",
+											"migration/api-v5-recall",
+											"migration/api-v5-profiles",
+											"migration/api-v5-memory-forgetting",
+											"migration/api-v5-settings",
+											"migration/api-v5-organization",
+											"migration/api-v5-filters",
+											"migration/api-v5-rollout"
+										]
+									},
 									{
 										"group": "From another provider",
 										"icon": "/icons/hugeicons/delivery-truck-01.svg",
@@ -293,7 +314,7 @@
 						"icon": "/icons/hugeicons/plug-socket.svg",
 						"versions": [
 							{
-								"version": "Legacy (V3, V4)",
+								"version": "Legacy (v3, v4)",
 								"openapi": "https://api.supermemory.ai/v4/openapi",
 								"pages": [
 									"api-reference/overview",
@@ -391,7 +412,7 @@
 								]
 							},
 							{
-								"version": "Latest (V5)",
+								"version": "Latest (v5)",
 								"default": true,
 								"openapi": {
 									"source": "https://api.supermemory.ai/v5/openapi",

diff --git a/apps/docs/migration/api-v5-document-reads.mdx b/apps/docs/migration/api-v5-document-reads.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate content management to v5"
+description: "Upgrade document retrieval, resource lists, and document or memory deletion"
+sidebarTitle: "Content management"
+---
+
+import ContentManagement from "/snippets/api-v5-content-management.mdx";
+
+## Migration details
+
+<ContentManagement />
diff --git a/apps/docs/migration/api-v5-document-updates.mdx b/apps/docs/migration/api-v5-document-updates.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate document and file updates to v5"
+description: "Choose append, replacement, or metadata-only updates deliberately"
+sidebarTitle: "Document updates"
+---
+
+import DocumentUpdates from "/snippets/api-v5-document-updates.mdx";
+
+## Migration details
+
+<DocumentUpdates />
diff --git a/apps/docs/migration/api-v5-document-writes.mdx b/apps/docs/migration/api-v5-document-writes.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate document ingestion to v5"
+description: "Upgrade single, batch, and file ingestion without changing append behavior"
+sidebarTitle: "Document ingestion"
+---
+
+import DocumentIngestion from "/snippets/api-v5-document-ingestion.mdx";
+
+## Migration details
+
+<DocumentIngestion />
diff --git a/apps/docs/migration/api-v5-filters.mdx b/apps/docs/migration/api-v5-filters.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate metadata filters to v5"
+description: "Convert legacy Query filters into strict, type-safe v5 filter expressions"
+sidebarTitle: "Typed filters"
+---
+
+import Filters from "/snippets/api-v5-filters.mdx";
+
+## Migration details
+
+<Filters />
diff --git a/apps/docs/migration/api-v5-memory-forgetting.mdx b/apps/docs/migration/api-v5-memory-forgetting.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate memory forgetting to v5"
+description: "Replace legacy exact and semantic forgetting with one response contract"
+sidebarTitle: "Memory forgetting"
+---
+
+import MemoryForgetting from "/snippets/api-v5-memory-forgetting.mdx";
+
+## Migration details
+
+<MemoryForgetting />
diff --git a/apps/docs/migration/api-v5-organization.mdx b/apps/docs/migration/api-v5-organization.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate organization settings to v5"
+description: "Reduce organization settings to shared context and namespace count"
+sidebarTitle: "Organization settings"
+---
+
+import Organization from "/snippets/api-v5-organization.mdx";
+
+## Migration details
+
+<Organization />
diff --git a/apps/docs/migration/api-v5-profiles.mdx b/apps/docs/migration/api-v5-profiles.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate profiles and buckets to v5"
+description: "Separate profile retrieval from search and manage namespace-owned buckets"
+sidebarTitle: "Profiles and buckets"
+---
+
+import Profiles from "/snippets/api-v5-profiles.mdx";
+
+## Migration details
+
+<Profiles />
diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate search to v5"
+description: "Upgrade search modes, filters, attachments, defaults, and response readers"
+sidebarTitle: "Search"
+---
+
+import Search from "/snippets/api-v5-search.mdx";
+
+## Migration details
+
+<Search />
diff --git a/apps/docs/migration/api-v5-rollout.mdx b/apps/docs/migration/api-v5-rollout.mdx
@@ -0,0 +1,11 @@
+---
+title: "Verify and roll out a v5 migration"
+description: "Prove behavioral parity, detect intentional differences, and cut over safely"
+sidebarTitle: "Verification and rollout"
+---
+
+import Rollout from "/snippets/api-v5-rollout.mdx";
+
+## Migration details
+
+<Rollout />
diff --git a/apps/docs/migration/api-v5-settings.mdx b/apps/docs/migration/api-v5-settings.mdx
@@ -0,0 +1,11 @@
+---
+title: "Migrate container tags to namespaces"
+description: "Upgrade namespace discovery, settings, deletion, and moves"
+sidebarTitle: "Namespaces"
+---
+
+import Namespaces from "/snippets/api-v5-namespaces.mdx";
+
+## Migration details
+
+<Namespaces />
diff --git a/apps/docs/migration/api-v5.mdx b/apps/docs/migration/api-v5.mdx
@@ -0,0 +1,71 @@
+---
+title: "Migrate Supermemory v3/v4 to v5"
+description: "Upgrade legacy API calls to the namespace-scoped v5 API"
+sidebarTitle: "Legacy API to v5"
+icon: "arrow-up-right"
+---
+
+import AgentPrompt from "/snippets/api-v5-agent-prompt.mdx";
+import Overview from "/snippets/api-v5-overview.mdx";
+import DocumentIngestion from "/snippets/api-v5-document-ingestion.mdx";
+import DocumentUpdates from "/snippets/api-v5-document-updates.mdx";
+import ContentManagement from "/snippets/api-v5-content-management.mdx";
+import Search from "/snippets/api-v5-search.mdx";
+import Profiles from "/snippets/api-v5-profiles.mdx";
+import MemoryForgetting from "/snippets/api-v5-memory-forgetting.mdx";
+import Namespaces from "/snippets/api-v5-namespaces.mdx";
+import Organization from "/snippets/api-v5-organization.mdx";
+import Filters from "/snippets/api-v5-filters.mdx";
+import Rollout from "/snippets/api-v5-rollout.mdx";
+import Sdks from "/snippets/api-v5-sdks.mdx";
+import Completion from "/snippets/api-v5-completion.mdx";
+
+<AgentPrompt />
+
+<Overview />
+
+## SDKs, tools and the CLI
+
+<Sdks />
+
+## Document ingestion
+
+<DocumentIngestion />
+
+## Document updates
+
+<DocumentUpdates />
+
+## Content management
+
+<ContentManagement />
+
+## Search
+
+<Search />
+
+## Profiles and buckets
+
+<Profiles />
+
+## Memory forgetting
+
+<MemoryForgetting />
+
+## Namespaces
+
+<Namespaces />
+
+## Organization settings
+
+<Organization />
+
+## Typed filters
+
+<Filters />
+
+## Verification and rollout
+
+<Rollout />
+
+<Completion />
diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -6,7 +6,7 @@
   "portless": { "name": "docs.dev.supermemory", "script": "dev:app", "appPort": 3003 },
   "scripts": {
     "dev": "portless",
-    "dev:app": "bunx mintlify@latest dev --no-open --port 3003"
+    "dev:app": "bash scripts/dev.sh"
   },
   "devDependencies": {
     "@types/bun": "latest",

diff --git a/apps/docs/scripts/dev.sh b/apps/docs/scripts/dev.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+docs_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+docs_port="${PORT:-3003}"
+mintlify_args=(dev --no-open --port "$docs_port")
+
+printf -v docs_dir_escaped "%q" "$docs_dir"
+printf -v mintlify_args_escaped " %q" "${mintlify_args[@]}"
+
+# Run outside the monorepo so npx does not pick up Mintlify's Bun-installed
+# dependency tree, which is incompatible with its Node-based schema compiler.
+cd /tmp
+exec npx --yes \
+  --package node@22 \
+  --package mintlify@latest \
+  --call "cd $docs_dir_escaped && mintlify$mintlify_args_escaped"
diff --git a/apps/docs/snippets/api-v5-agent-prompt.mdx b/apps/docs/snippets/api-v5-agent-prompt.mdx
@@ -0,0 +1,7 @@
+## Migrate with an agent
+
+Paste this into Claude Code, Cursor, or Codex. It fetches this guide as markdown and rewrites every legacy call.
+
+```text
+Migrate this repository from Supermemory v3/v4 to v5. Fetch https://supermemory.ai/docs/migration/api-v5.md and follow it exactly. First write a checklist of every legacy call site, then migrate them one by one and tick each off. Stop and report any operation that has no v5 replacement instead of inventing one.
+```
diff --git a/apps/docs/snippets/api-v5-completion.mdx b/apps/docs/snippets/api-v5-completion.mdx
@@ -0,0 +1,9 @@
+## Operations without a direct replacement
+
+- Direct memory creation and version updates: ingest or replace a source document instead.
+- Organization bucket suggestion and organization reset: not part of the v5 public surface.
+- Connector routes that still use `/v3`: unchanged; do not rewrite them.
+- Conversation ingestion (`/v4/conversations`): not part of the v5 public surface. Send the transcript as a document instead.
+- Container-tag merges: not part of the v5 public surface.
+
+Use the [v5 reference](https://api.supermemory.ai/v5/reference) for the stable v5 API. [`/reference`](https://api.supermemory.ai/reference) always points to the latest public version.
diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx
@@ -0,0 +1,73 @@
+v5 retrieves, lists, and removes content within one explicit namespace.
+
+### Retrieve a document and its derived context
+
+<CodeGroup>
+```bash Legacy
+GET /v3/documents/{id}
+GET /v3/documents/{id}/chunks
+```
+
+```bash v5
+GET /ns/{namespace}/document/{id}?attach=chunks&attach=memories
+```
+</CodeGroup>
+
+Repeat `attach` to include chunks, memories, or both. Omitted attachment keys are absent; requested attachments with no results are empty arrays. Lifecycle fields move under `system`:
+
+```json
+{"system":{"status":"done","createdAt":"...","updatedAt":"..."}}
+```
+
+### List documents, chunks, or memories
+
+<CodeGroup>
+```bash Legacy
+POST /v3/documents/list
+POST /v4/memories/list
+```
+
+```bash v5
+POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
+{}
+```
+</CodeGroup>
+
+Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string; the body contains only optional `filter`.
+
+Every response contains `documents`, `chunks`, `memories`, and `pagination`. Only the selected resource array is populated. Replace legacy `memories` assumptions in document-list callers with `documents`.
+
+### Delete documents
+
+<CodeGroup>
+```bash Legacy
+DELETE /v3/documents/{id}
+DELETE /v3/documents/bulk
+```
+
+```bash v5
+DELETE /ns/{namespace}/document
+{"ids":["doc_1","external_id_2"]}
+```
+</CodeGroup>
+
+The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `deletedCount` and per-ID `errors`; HTTP success can include partial failures.
+
+### Forget memories
+
+| Legacy intent | v5 operation |
+| --- | --- |
+| Forget exact IDs | `DELETE /ns/{namespace}/memories` with `{ "ids": [...] }` |
+| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` with `{ "query": "...", "dryRun": true }` |
+
+Both return `{ count, matches, errors }`. For drift-free semantic deletion, preview with `dryRun: true`, review the IDs, then submit them to the exact-ID endpoint.
+
+See [memory forgetting](./api-v5-memory-forgetting) for the complete dry-run, approval, response, and audit workflow.
+
+### Verification
+
+- Assert requested empty attachments are `[]`, while omitted attachments are absent.
+- Paginate each resource type until `currentPage >= totalPages`; unselected arrays stay empty.
+- Verify chunk rows contain their parent `documentId`.
+- Exercise partial document-delete failures and semantic dry runs.
+- Verify IDs cannot read, list, or delete content outside their namespace.