graphite-app · Oct 6, 2026 · Oct 6, 2026
diff --git a/apps/docs/agents-and-mcp.mdx b/apps/docs/agents-and-mcp.mdx
@@ -31,9 +31,10 @@ npx supermemory setup --prompt     # print integration prompt only
 npx supermemory setup --json       # machine-readable output
 npx supermemory help --json        # agent-readable command catalog
 npx supermemory help --all
+npx supermemory migrate            # move a v3/v4 project to v5 with your agent
 ```
 
-Also available for smoke tests against your key: `add`, `search`, `profile`, `docs`, `tags`, `config`, `whoami`. Auth via first-run credentials or `SUPERMEMORY_API_KEY`.
+Also available for smoke tests against your key: `add`, `search`, `profile`, `docs`, `namespaces`, `config`, `whoami`. Auth via first-run credentials or `SUPERMEMORY_API_KEY`.
 
 ```bash
 npx supermemory add "User prefers TypeScript" --namespace user_123
@@ -181,6 +182,7 @@ You are integrating Supermemory into my app.
 - Always scope with one namespace in the URL path on write and search; there is no namespace field in the body
 - SDK: import { Supermemory } from "supermemory"; version 5 or later; the namespace is the first argument: client.add(namespace, { content }), client.search(namespace, { query })
 - For demos use dreaming: "instant" when memories must be ready right after status done
+- Already on Supermemory v3/v4? Run `npx supermemory@latest migrate` instead of rewriting calls by hand
 ```
 
 ### Integrate prompt (optional)

diff --git a/apps/docs/integrations/ai-sdk.mdx b/apps/docs/integrations/ai-sdk.mdx
@@ -5,11 +5,11 @@ description: "Use Supermemory with Vercel AI SDK for seamless memory management"
 icon: "/icons/hugeicons/triangle.svg"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
 The Supermemory AI SDK provides native integration with Vercel's AI SDK through two approaches: **User Profiles** for automatic personalization and **Memory Tools** for agent-based interactions.
 
-<Note>
-  Upgrading from 2.x? 3.0 moves to the v5 API and one `namespace` per config. See the [3.0 upgrade guide](/migration/tools-v3-upgrade).
-</Note>
+<MigrateCli legacy="@supermemory/tools 2.x" guideHref="/migration/tools-v3-upgrade" guideLabel="3.0 upgrade guide" />
 
 <Card title="@supermemory/tools on npm" icon="/icons/hugeicons/package.svg" href="https://www.npmjs.com/package/@supermemory/tools">
     Check out the NPM page for more details

diff --git a/apps/docs/integrations/mastra.mdx b/apps/docs/integrations/mastra.mdx
@@ -5,11 +5,11 @@ description: "Add persistent memory to Mastra AI agents with Supermemory process
 icon: "/images/mastra-icon.svg"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
 Integrate Supermemory with [Mastra](https://mastra.ai) to give your AI agents persistent memory. Use the `withSupermemory` wrapper for zero-config setup or processors for fine-grained control.
 
-<Note>
-  Upgrading from 2.x? 3.0 moves to the v5 API and one `namespace` per config. See the [3.0 upgrade guide](/migration/tools-v3-upgrade).
-</Note>
+<MigrateCli legacy="@supermemory/tools 2.x" guideHref="/migration/tools-v3-upgrade" guideLabel="3.0 upgrade guide" />
 
 <Card title="@supermemory/tools on npm" icon="/icons/hugeicons/package.svg" href="https://www.npmjs.com/package/@supermemory/tools">
     Check out the NPM page for more details

diff --git a/apps/docs/integrations/openai.mdx b/apps/docs/integrations/openai.mdx
@@ -5,14 +5,14 @@ description: "Memory tools for OpenAI function calling with Supermemory integrat
 icon: "/images/openai.svg"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
 Add memory capabilities to the official OpenAI SDKs using Supermemory. Two approaches available:
 
 1. **`withSupermemory` wrapper** - Automatic memory injection into system prompts (zero-config)
 2. **Function calling tools** - Explicit tool calls for search/add memory operations
 
-<Note>
-  Upgrading from 2.x? 3.0 moves to the v5 API and one `namespace` per config. See the [3.0 upgrade guide](/migration/tools-v3-upgrade).
-</Note>
+<MigrateCli legacy="@supermemory/tools 2.x" guideHref="/migration/tools-v3-upgrade" guideLabel="3.0 upgrade guide" />
 
 <Tip>
 **New to Supermemory?** Start with `withSupermemory` for the simplest integration. It automatically injects relevant memories into your prompts.

diff --git a/apps/docs/integrations/voltagent.mdx b/apps/docs/integrations/voltagent.mdx
@@ -5,11 +5,11 @@ description: "Integrate Supermemory with VoltAgent for long-term memory in AI ag
 icon: "/icons/hugeicons/flash.svg"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
 Supermemory integrates with [VoltAgent](https://github.com/VoltAgent/voltagent), providing long-term memory capabilities for AI agents. Your VoltAgent applications will remember past conversations and provide personalized responses based on user history.
 
-<Note>
-  Upgrading from 2.x? 3.0 moves to the v5 API and one `namespace` per config. See the [3.0 upgrade guide](/migration/tools-v3-upgrade).
-</Note>
+<MigrateCli legacy="@supermemory/tools 2.x" guideHref="/migration/tools-v3-upgrade" guideLabel="3.0 upgrade guide" />
 
 <Card title="@supermemory/tools on npm" icon="/icons/hugeicons/package.svg" href="https://www.npmjs.com/package/@supermemory/tools">
     Check out the NPM page for more details

diff --git a/apps/docs/migration/api-v5-document-reads.mdx b/apps/docs/migration/api-v5-document-reads.mdx
@@ -4,8 +4,11 @@ description: "Upgrade document retrieval, resource lists, and document or memory
 sidebarTitle: "Content management"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import ContentManagement from "/snippets/api-v5-content-management.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <ContentManagement />
diff --git a/apps/docs/migration/api-v5-document-updates.mdx b/apps/docs/migration/api-v5-document-updates.mdx
@@ -4,8 +4,11 @@ description: "Choose append, replacement, or metadata-only updates deliberately"
 sidebarTitle: "Document updates"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import DocumentUpdates from "/snippets/api-v5-document-updates.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <DocumentUpdates />
diff --git a/apps/docs/migration/api-v5-document-writes.mdx b/apps/docs/migration/api-v5-document-writes.mdx
@@ -4,8 +4,11 @@ description: "Upgrade single, batch, and file ingestion without changing append
 sidebarTitle: "Document ingestion"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import DocumentIngestion from "/snippets/api-v5-document-ingestion.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <DocumentIngestion />
diff --git a/apps/docs/migration/api-v5-filters.mdx b/apps/docs/migration/api-v5-filters.mdx
@@ -4,8 +4,11 @@ description: "Convert legacy Query filters into strict, type-safe v5 filter expr
 sidebarTitle: "Typed filters"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import Filters from "/snippets/api-v5-filters.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <Filters />
diff --git a/apps/docs/migration/api-v5-memory-forgetting.mdx b/apps/docs/migration/api-v5-memory-forgetting.mdx
@@ -4,8 +4,11 @@ description: "Replace legacy exact and semantic forgetting with one response con
 sidebarTitle: "Memory forgetting"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import MemoryForgetting from "/snippets/api-v5-memory-forgetting.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <MemoryForgetting />
diff --git a/apps/docs/migration/api-v5-organization.mdx b/apps/docs/migration/api-v5-organization.mdx
@@ -4,8 +4,11 @@ description: "Reduce organization settings to shared context and namespace count
 sidebarTitle: "Organization settings"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import Organization from "/snippets/api-v5-organization.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <Organization />
diff --git a/apps/docs/migration/api-v5-profiles.mdx b/apps/docs/migration/api-v5-profiles.mdx
@@ -4,8 +4,11 @@ description: "Separate profile retrieval from search and manage namespace-owned
 sidebarTitle: "Profiles and buckets"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import Profiles from "/snippets/api-v5-profiles.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <Profiles />
diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx
@@ -4,8 +4,11 @@ description: "Upgrade search modes, filters, included context, defaults, and res
 sidebarTitle: "Search"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import Search from "/snippets/api-v5-search.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <Search />
diff --git a/apps/docs/migration/api-v5-rollout.mdx b/apps/docs/migration/api-v5-rollout.mdx
@@ -4,8 +4,11 @@ description: "Prove behavioral parity, detect intentional differences, and cut o
 sidebarTitle: "Verification and rollout"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import Rollout from "/snippets/api-v5-rollout.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <Rollout />
diff --git a/apps/docs/migration/api-v5-settings.mdx b/apps/docs/migration/api-v5-settings.mdx
@@ -4,8 +4,11 @@ description: "Upgrade namespace discovery, settings, deletion, and moves"
 sidebarTitle: "Namespaces"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
 import Namespaces from "/snippets/api-v5-namespaces.mdx";
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="full v5 migration guide" />
+
 ## Migration details
 
 <Namespaces />
diff --git a/apps/docs/migration/tools-v3-upgrade.mdx b/apps/docs/migration/tools-v3-upgrade.mdx
@@ -5,6 +5,10 @@ sidebarTitle: "Tools: 2.x → 3.0"
 keywords: ["containerTags", "projectId", "customId", "namespace", "tools"]
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
+<MigrateCli legacy="@supermemory/tools 2.x" guideHref="/migration/api-v5" guideLabel="v5 migration guide" />
+
 `@supermemory/tools` 3.0 moves every integration (Vercel AI SDK, OpenAI, Mastra, VoltAgent, Claude memory) to the [v5 API](/migration/api-v5) through `supermemory@5`. The names changed to match: a **namespace** is what 2.x called a container tag.
 
 ```bash

diff --git a/apps/docs/snippets/api-v5-agent-prompt.mdx b/apps/docs/snippets/api-v5-agent-prompt.mdx
@@ -5,11 +5,12 @@ The quickest path is one command in your project root. It scans the repo for v3/
 ```bash
 npx supermemory@latest migrate            # pick your agent interactively
 npx supermemory@latest migrate --agent codex
-npx supermemory@latest migrate --prompt   # print the prompt instead
 ```
 
-Prefer to paste a prompt yourself? This one fetches the guide as markdown and rewrites every legacy call:
+<Accordion title="No Node or no coding agent? Paste this prompt instead">
+This prompt fetches the 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. First write a checklist in your reply, not as a file in the repository, of every legacy call site and of every Supermemory-specific name in this codebase: containerTag, containerTags, customId, entityContext, filterByMetadata, filters, including option names, config keys, environment variables and tests. Migrate them one by one and tick each off. Rename those names to the v5 ones (namespace, id, supportingContext, group, filter) with no aliases. A document belongs to exactly one namespace in v5, so a containerTags array becomes one namespace. If an operation has no v5 replacement, do not invent one: keep going, and list it at the end with the alternative the guide suggests.
 ```
+</Accordion>
diff --git a/apps/docs/snippets/migrate-cli.mdx b/apps/docs/snippets/migrate-cli.mdx
@@ -0,0 +1,3 @@
+<Tip>
+On {legacy}? Run `npx supermemory@latest migrate`, or read the <a href={guideHref}>{guideLabel}</a>.
+</Tip>
diff --git a/apps/docs/v5/api-reference/namespaces.mdx b/apps/docs/v5/api-reference/namespaces.mdx
@@ -6,10 +6,14 @@ icon: "/icons/hugeicons/book-open-01.svg"
 keywords: ["container tag", "container tags", "containerTag", "namespace"]
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
 <Note>
 Namespaces were called **container tags** (`containerTag`) in v3 and v4. Same values, nothing moved.
 </Note>
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="v5 migration guide" />
+
 | Operation | Purpose |
 | --- | --- |
 | `GET /namespaces` | Discover namespaces and see their memory footprint |

diff --git a/apps/docs/v5/api-reference/overview.mdx b/apps/docs/v5/api-reference/overview.mdx
@@ -5,6 +5,8 @@ description: "Documents, search, profiles, lists, memories, namespaces, and orga
 icon: "/icons/hugeicons/plug-socket.svg"
 ---
 
+import MigrateCli from "/snippets/migrate-cli.mdx";
+
 v5 makes namespace scope explicit in the URL and consolidates overlapping legacy operations.
 
 ```text
@@ -18,6 +20,8 @@ https://api.supermemory.ai
   /organization
 ```
 
+<MigrateCli legacy="v3 or v4" guideHref="/migration/api-v5" guideLabel="v5 migration guide" />
+
 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.
 
 ## Install the TypeScript SDK