diff --git a/apps/docs/agents-and-mcp.mdx b/apps/docs/agents-and-mcp.mdx index b0f73162..d5948806 100644 --- a/apps/docs/agents-and-mcp.mdx +++ b/apps/docs/agents-and-mcp.mdx @@ -178,8 +178,8 @@ You are integrating Supermemory into my app. - Prefer `npx supermemory setup` / the supermemory skill for correct auth, namespace, and SDK usage. - Canonical writes: POST /ns/{namespace}/document · search: POST /ns/{namespace}/search · profile: POST /ns/{namespace}/profile - Auth: Authorization: Bearer $SUPERMEMORY_API_KEY only -- Always scope with one namespace in the URL path on write and search (never containerTag in the body) -- SDK: import { Supermemory } from "supermemory"; every call takes { namespace, ...queryParams, body } +- 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 ``` diff --git a/apps/docs/integrations/ai-sdk.mdx b/apps/docs/integrations/ai-sdk.mdx index a67e248b..1208ad94 100644 --- a/apps/docs/integrations/ai-sdk.mdx +++ b/apps/docs/integrations/ai-sdk.mdx @@ -8,7 +8,7 @@ icon: "/icons/hugeicons/triangle.svg" 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. - Migrating to v2 from 1.4.x? Check the [migration guide](/migration/tools-v2-upgrade). + 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). diff --git a/apps/docs/integrations/mastra.mdx b/apps/docs/integrations/mastra.mdx index ea192b0d..0bb06e86 100644 --- a/apps/docs/integrations/mastra.mdx +++ b/apps/docs/integrations/mastra.mdx @@ -8,7 +8,7 @@ icon: "/images/mastra-icon.svg" 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. - Migrating to v2 from 1.4.x? Check the [migration guide](/migration/tools-v2-upgrade). + 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). diff --git a/apps/docs/integrations/openai.mdx b/apps/docs/integrations/openai.mdx index fe23e3fa..4c25e847 100644 --- a/apps/docs/integrations/openai.mdx +++ b/apps/docs/integrations/openai.mdx @@ -11,7 +11,7 @@ Add memory capabilities to the official OpenAI SDKs using Supermemory. Two appro 2. **Function calling tools** - Explicit tool calls for search/add memory operations - Migrating to v2 from 1.4.x? Check the [migration guide](/migration/tools-v2-upgrade). + 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). diff --git a/apps/docs/integrations/voltagent.mdx b/apps/docs/integrations/voltagent.mdx index 796a4a47..c7087d2a 100644 --- a/apps/docs/integrations/voltagent.mdx +++ b/apps/docs/integrations/voltagent.mdx @@ -8,7 +8,7 @@ icon: "/icons/hugeicons/flash.svg" 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. - Migrating to v2 from 1.4.x? Check the [migration guide](/migration/tools-v2-upgrade). + 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). diff --git a/apps/docs/snippets/agent-prompt.jsx b/apps/docs/snippets/agent-prompt.jsx index 08b90bf5..5e42eb4d 100644 --- a/apps/docs/snippets/agent-prompt.jsx +++ b/apps/docs/snippets/agent-prompt.jsx @@ -1,2 +1,71 @@ -export const AGENT_PROMPT = - '# You are onboarding this project to Supermemory\n\nSupermemory is a memory API for AI apps and agents: ingest conversations, documents, files, and URLs; get semantic search, extracted facts, and per-user profiles back. Every call is scoped to one containerTag, with strict isolation between tags.\n\n## What you can call\n\n| Operation | Endpoint | Use when |\n|---|---|---|\n| Add content | POST /v3/documents | Ingest conversations, documents, files, URLs |\n| Search memories | POST /v4/search | Find extracted facts with graph context |\n| Search documents | POST /v3/search | Find raw chunks for RAG grounding |\n| Get profile | POST /v4/profile | Static + dynamic context for a user |\n| List documents | POST /v3/documents/list | Paginate and filter ingested content |\n| Forget memory | DELETE /v4/memories | Soft-delete one fact; JSON body with containerTag plus id or exact content |\n| Forget matching | POST /v4/memories/forget-matching | Soft-delete every fact matching a query or an ids list; dryRun previews first |\n\nTwo processing modes: taskType "memory" (full pipeline: facts, profile, graph — for conversations and personal context) and taskType "superrag" (chunk/embed only, 5x cheaper — for reference material). Search returns memories, documents, or hybrid via searchMode.\n\nFull API reference for agents: https://docs.supermemory.ai/llms.txt\n\nNow work the steps below in order. Do not skip ahead. Stop where a step says to.\n\n## Step 1 — Credentials\n\nAPI key env var: SUPERMEMORY_API_KEY (never hardcode it, never print it back).\n\nKey for this project: YOUR_SUPERMEMORY_API_KEY\n\nIf that reads YOUR_SUPERMEMORY_API_KEY, ask the user to create a key at https://console.supermemory.ai/keys, export it as SUPERMEMORY_API_KEY, and tell you when it is set. Wait for confirmation.\n\n## Step 2 — Install the docs MCP server, then brief the user\n\nAdd this MCP server to your client (public, no auth): https://supermemory.ai/docs/mcp\n\nIt serves search over the full Supermemory docs plus a skill resource with integration rules. Verify it works by searching it for "container tag rules" and confirming a real result returns. Prefer its answers over prior knowledge for anything Supermemory-specific.\n\nThen give the user a short rundown of what Supermemory can do for THIS project, using the table above.\n\n## Step 3 — Scan this repo for integration points\n\nIf this directory has application source, read enough to understand it, then map findings against this table. Cite exact files and lines. If the repo is empty or docs-only, say so and skip to Step 5.\n\n| Code pattern | Replace / augment with |\n|---|---|\n| Chat or agent loop with no memory between sessions | Add each exchange (taskType "memory"), search before the model answers |\n| Full conversation history stuffed into the prompt | Retrieved context from POST /v4/search instead of replaying everything |\n| Homegrown embeddings pipeline (pgvector, pinecone, chroma) | POST /v3/documents + POST /v3/search, no pipeline to maintain |\n| RAG over files or docs sites | Ingest with taskType "superrag", search with searchMode "documents" |\n| Per-user preferences or personalization tables | POST /v4/profile |\n| Multi-tenant SaaS serving many end users | One containerTag per end user (user_123); never share or cross-query tags |\n\n## Step 4 — Propose, then get approval before touching code\n\nPresent findings as a numbered list: file + line range, the endpoint(s) involved, one line on why it is an improvement. Ask which to implement. Do not modify files until the user approves specific items.\n\nWhen implementing, use the official SDK (supermemory on npm and PyPI). The client reads SUPERMEMORY_API_KEY from the environment:\n\n import Supermemory from "supermemory"\n const client = new Supermemory()\n\nContainer tag rules, non-negotiable: singular containerTag (the plural form is deprecated), one tag per end user or project, format ^[a-zA-Z0-9_:-]+$, no cross-tag queries. First write with a new tag creates it.\n\n## Step 5 — Suggest uses tailored to this project\n\nOnly if Step 3 found no application code: propose 3-5 concrete places in the user\'s stack where a memory layer would save effort, each tied to a specific endpoint from the table. Propose, do not build.' +export const AGENT_PROMPT = `# You are onboarding this project to Supermemory + +Supermemory is a memory API for AI apps and agents: ingest conversations, documents, files, and URLs; get semantic search, extracted facts, and per-user profiles back. Every call is scoped to one namespace in the URL (/ns/{namespace}/...), with strict isolation between namespaces. + +## What you can call + +| Operation | Endpoint | Use when | +|---|---|---| +| Add content | POST /ns/{namespace}/document | Ingest conversations, documents, files, URLs | +| Search | POST /ns/{namespace}/search | searchMode memories (facts), chunks (raw text for RAG) or hybrid | +| Get profile | POST /ns/{namespace}/profile | Static + dynamic context for a user | +| List | POST /ns/{namespace}/list/{documents|chunks|memories} | Paginate and filter ingested content | +| Forget memories | DELETE /ns/{namespace}/memories | Soft-delete facts by id | +| Forget matching | DELETE /ns/{namespace}/memories/semantic | Soft-delete every fact matching a query; dryRun previews first | + +Two processing modes: taskType "memory" (full pipeline: facts, profile, graph; for conversations and personal context) and taskType "superrag" (chunk/embed only, 5x cheaper; for reference material). Search returns memories, chunks, or hybrid via searchMode. + +Full API reference for agents: https://supermemory.ai/docs/llms.txt +Migrating code that still uses /v3, /v4 or containerTag: https://supermemory.ai/docs/migration/api-v5 + +Now work the steps below in order. Do not skip ahead. Stop where a step says to. + +## Step 1: Credentials + +API key env var: SUPERMEMORY_API_KEY (never hardcode it, never print it back). + +Key for this project: YOUR_SUPERMEMORY_API_KEY + +If that reads YOUR_SUPERMEMORY_API_KEY, ask the user to create a key at https://console.supermemory.ai/keys, export it as SUPERMEMORY_API_KEY, and tell you when it is set. Wait for confirmation. + +## Step 2: Install the docs MCP server, then brief the user + +Add this MCP server to your client (public, no auth): https://supermemory.ai/docs/mcp + +It serves search over the full Supermemory docs plus a skill resource with integration rules. Verify it works by searching it for "namespace rules" and confirming a real result returns. Prefer its answers over prior knowledge for anything Supermemory-specific. + +Then give the user a short rundown of what Supermemory can do for THIS project, using the table above. + +## Step 3: Scan this repo for integration points + +If this directory has application source, read enough to understand it, then map findings against this table. Cite exact files and lines. If the repo is empty or docs-only, say so and skip to Step 5. + +| Code pattern | Replace / augment with | +|---|---| +| Chat or agent loop with no memory between sessions | Add each exchange (taskType "memory"), search before the model answers | +| Full conversation history stuffed into the prompt | Retrieved context from POST /ns/{namespace}/search instead of replaying everything | +| Homegrown embeddings pipeline (pgvector, pinecone, chroma) | POST /ns/{namespace}/document + search with searchMode chunks, no pipeline to maintain | +| RAG over files or docs sites | Ingest with taskType "superrag", search with searchMode "chunks" | +| Per-user preferences or personalization tables | POST /ns/{namespace}/profile | +| Multi-tenant SaaS serving many end users | One namespace per end user (user_123); never share or cross-query namespaces | + +## Step 4: Propose, then get approval before touching code + +Present findings as a numbered list: file + line range, the endpoint(s) involved, one line on why it is an improvement. Ask which to implement. Do not modify files until the user approves specific items. + +When implementing, use the official SDK, version 5 or later: npm install supermemory, or pip install supermemory. Older releases call v3/v4 and do not have these methods, so an existing dependency is not enough; check the installed version. The client reads SUPERMEMORY_API_KEY from the environment: + + import { Supermemory } from "supermemory" + const client = new Supermemory() + await client.add("user_123", { content: "..." }) + const { results } = await client.search("user_123", { query: "..." }) + +Namespace rules, non-negotiable: the namespace is the first argument of every SDK call (the URL path in raw HTTP), one namespace per end user or project, format ^[a-zA-Z0-9_:-]+$, no cross-namespace queries. The first write to a new namespace creates it. + +## Step 4a: Use the integration package when one fits + +Check the project's dependencies before writing code. If package.json has ai or @ai-sdk/*, use @supermemory/tools/ai-sdk (withSupermemory(model, { namespace, id }), or supermemoryTools for model-decided calls). openai: @supermemory/tools/openai. @mastra/core: @supermemory/tools/mastra. @voltagent/core: @supermemory/tools/voltagent. @anthropic-ai/sdk: @supermemory/tools/claude-memory. Python with openai: supermemory-openai-sdk. These scope every call to the namespace and handle recall and save around each model call; npm install @supermemory/tools. Anything else uses the SDK directly as below. Already on Supermemory v3/v4? Run npx supermemory@latest migrate instead. + +## Step 5: Suggest uses tailored to this project + +Only if Step 3 found no application code: propose 3-5 concrete places in the user's stack where a memory layer would save effort, each tied to a specific endpoint from the table. Propose, do not build.` diff --git a/apps/docs/snippets/api-v5-agent-prompt.mdx b/apps/docs/snippets/api-v5-agent-prompt.mdx index 348b83ff..eecb94b6 100644 --- a/apps/docs/snippets/api-v5-agent-prompt.mdx +++ b/apps/docs/snippets/api-v5-agent-prompt.mdx @@ -1,6 +1,14 @@ ## Migrate with an agent -Paste this into Claude Code, Cursor, or Codex. It fetches this guide as markdown and rewrites every legacy call. +The quickest path is one command in your project root. It scans the repo for v3/v4 usage, reads your Supermemory packages and AI SDK, builds a migration prompt for this project, and launches your coding agent with it: + +```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: ```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/hero-samples.jsx b/apps/docs/snippets/hero-samples.jsx index bbf90bd2..1df5ce6e 100644 --- a/apps/docs/snippets/hero-samples.jsx +++ b/apps/docs/snippets/hero-samples.jsx @@ -1,8 +1,54 @@ -export const HERO_TS = - 'import Supermemory from "supermemory";\n\nconst client = new Supermemory();\n\n// March\nawait client.add({\n content: "I work at Google on the Maps team.",\n containerTag: "user_4f8a",\n});\n\n// June\nawait client.add({\n content: "Big news: I just started at Stripe!",\n containerTag: "user_4f8a",\n});\n\n// Later: what does your agent know about this user?\nconst { profile } = await client.profile({ containerTag: "user_4f8a" });\n\nconsole.log(profile.static);\n// \u2192 ["Now works at Stripe."]' +export const HERO_TS = `import { Supermemory } from "supermemory"; -export const HERO_PY = - 'from supermemory import Supermemory\n\nclient = Supermemory()\n\n# March\nclient.add(\n content="I work at Google on the Maps team.",\n container_tag="user_4f8a",\n)\n\n# June\nclient.add(\n content="Big news: I just started at Stripe!",\n container_tag="user_4f8a",\n)\n\n# Later: what does your agent know about this user?\nprofile = client.profile(container_tag="user_4f8a").profile\n\nprint(profile.static)\n# \u2192 ["Now works at Stripe."]' +const client = new Supermemory(); -export const HERO_CURL = - '# March\ncurl https://api.supermemory.ai/v3/documents \\\n -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \\\n -H "Content-Type: application/json" \\\n -d \'{"content": "I work at Google on the Maps team.", "containerTag": "user_4f8a"}\'\n\n# June\ncurl https://api.supermemory.ai/v3/documents \\\n -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \\\n -H "Content-Type: application/json" \\\n -d \'{"content": "Big news: I just started at Stripe!", "containerTag": "user_4f8a"}\'\n\n# Later: what does your agent know about this user?\ncurl https://api.supermemory.ai/v4/profile \\\n -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \\\n -H "Content-Type: application/json" \\\n -d \'{"containerTag": "user_4f8a"}\'\n# \u2192 {"profile": {"static": ["Now works at Stripe."], "dynamic": []}}' +// March +await client.add("user_4f8a", { + content: "I work at Google on the Maps team.", +}); + +// June +await client.add("user_4f8a", { + content: "Big news: I just started at Stripe!", +}); + +// Later: what does your agent know about this user? +const { profile } = await client.profile("user_4f8a"); + +console.log(profile.static.map((m) => m.memory)); +// \u2192 ["Now works at Stripe."]` + +export const HERO_PY = `from supermemory import Supermemory + +client = Supermemory() + +# March +client.add("user_4f8a", content="I work at Google on the Maps team.") + +# June +client.add("user_4f8a", content="Big news: I just started at Stripe!") + +# Later: what does your agent know about this user? +profile = client.profile("user_4f8a").profile + +print([m.memory for m in profile.static]) +# \u2192 ["Now works at Stripe."]` + +export const HERO_CURL = `# March +curl https://api.supermemory.ai/ns/user_4f8a/document \\ + -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \\ + -H "Content-Type: application/json" \\ + -d '{"content": "I work at Google on the Maps team."}' + +# June +curl https://api.supermemory.ai/ns/user_4f8a/document \\ + -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \\ + -H "Content-Type: application/json" \\ + -d '{"content": "Big news: I just started at Stripe!"}' + +# Later: what does your agent know about this user? +curl -X POST https://api.supermemory.ai/ns/user_4f8a/profile \\ + -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \\ + -H "Content-Type: application/json" \\ + -d '{}' +# \u2192 {"profile": {"static": [{"id": "mem_1", "memory": "Now works at Stripe."}], "dynamic": []}}`