diff --git a/apps/docs/agents-and-mcp.mdx b/apps/docs/agents-and-mcp.mdx index d59488064..4a1a42900 100644 --- 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 index 1208ad94a..8189313de 100644 --- 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. - - 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). - + Check out the NPM page for more details diff --git a/apps/docs/integrations/mastra.mdx b/apps/docs/integrations/mastra.mdx index 0bb06e868..c52d019da 100644 --- 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. - - 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). - + Check out the NPM page for more details diff --git a/apps/docs/integrations/openai.mdx b/apps/docs/integrations/openai.mdx index 4c25e8479..aed5d07ef 100644 --- 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 - - 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). - + **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 index c7087d2ac..3a905b4ae 100644 --- 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. - - 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). - + 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 index 57fc77b2c..ff0cba9db 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-document-updates.mdx b/apps/docs/migration/api-v5-document-updates.mdx index 148f2779d..bd2beff47 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-document-writes.mdx b/apps/docs/migration/api-v5-document-writes.mdx index 6a8b55209..8ae1a0738 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-filters.mdx b/apps/docs/migration/api-v5-filters.mdx index 288847f5a..a8721b9d4 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-memory-forgetting.mdx b/apps/docs/migration/api-v5-memory-forgetting.mdx index 3ddde55ab..8be282553 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-organization.mdx b/apps/docs/migration/api-v5-organization.mdx index 54a1f91dc..a3a13ad18 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-profiles.mdx b/apps/docs/migration/api-v5-profiles.mdx index 5ec5e16b7..720733ba9 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx index 355a72f6b..dcccbfe72 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-rollout.mdx b/apps/docs/migration/api-v5-rollout.mdx index a90d005bd..974c77613 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/api-v5-settings.mdx b/apps/docs/migration/api-v5-settings.mdx index a90305a19..0bf590fb4 100644 --- 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"; + + ## Migration details diff --git a/apps/docs/migration/tools-v3-upgrade.mdx b/apps/docs/migration/tools-v3-upgrade.mdx index 3b91fffdb..b1df53981 100644 --- 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"; + + + `@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 index eecb94b62..506a8ecfe 100644 --- 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: + +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. ``` + diff --git a/apps/docs/snippets/migrate-cli.mdx b/apps/docs/snippets/migrate-cli.mdx new file mode 100644 index 000000000..c0fde1692 --- /dev/null +++ b/apps/docs/snippets/migrate-cli.mdx @@ -0,0 +1,3 @@ + +On {legacy}? Run `npx supermemory@latest migrate`, or read the {guideLabel}. + diff --git a/apps/docs/v5/api-reference/namespaces.mdx b/apps/docs/v5/api-reference/namespaces.mdx index cfbd9313f..2bfbd9dcc 100644 --- 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"; + Namespaces were called **container tags** (`containerTag`) in v3 and v4. Same values, nothing moved. + + | 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 index d1f2babd1..bd6b9beec 100644 --- 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 ``` + + 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