diff --git a/apps/docs/agents-and-mcp.mdx b/apps/docs/agents-and-mcp.mdx index d5948806..4a1a4290 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 1208ad94..8189313d 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 0bb06e86..c52d019d 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 4c25e847..aed5d07e 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 c7087d2a..3a905b4a 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 57fc77b2..ff0cba9d 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 148f2779..bd2beff4 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 6a8b5520..8ae1a073 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 288847f5..a8721b9d 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 3ddde55a..8be28255 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 54a1f91d..a3a13ad1 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 5ec5e16b..720733ba 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 355a72f6..dcccbfe7 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 a90d005b..974c7761 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 a90305a1..0bf590fb 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 3b91fffd..b1df5398 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 eecb94b6..506a8ecf 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 00000000..c0fde169 --- /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 cfbd9313..2bfbd9dc 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 d1f2babd..bd6b9bee 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