graphite-app · Oct 6, 2026 · Oct 6, 2026
diff --git a/apps/docs/agents-and-mcp.mdx b/apps/docs/agents-and-mcp.mdx
@@ -36,14 +36,14 @@ npx supermemory help --all
 Also available for smoke tests against your key: `add`, `search`, `profile`, `docs`, `tags`, `config`, `whoami`. Auth via first-run credentials or `SUPERMEMORY_API_KEY`.
 
 ```bash
-npx supermemory add "User prefers TypeScript" --tag user_123
-npx supermemory search "language preference" --tag user_123
-npx supermemory profile --tag user_123
+npx supermemory add "User prefers TypeScript" --namespace user_123
+npx supermemory search "language preference" --namespace user_123
+npx supermemory profile --namespace user_123
 ```
 
 ## Skill
 
-Install the official skill so the agent uses the real endpoints, auth, and `containerTag` rules instead of hallucinating APIs:
+Install the official skill so the agent uses the real endpoints, auth, and `namespace` rules instead of hallucinating APIs:
 
 ```bash
 npx skills add https://github.com/supermemoryai/skills --skill supermemory
@@ -175,10 +175,11 @@ https://supermemory.ai/docs/mcp
 You are integrating Supermemory into my app.
 
 - Use the supermemory-docs MCP (or https://supermemory.ai/docs/llms.txt) before inventing endpoints.
-- Prefer `npx supermemory setup` / the supermemory skill for correct auth, containerTag, and SDK usage.
-- Canonical writes: POST /v3/documents · search: POST /v4/search · profile: POST /v4/profile
+- 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 containerTag (singular) on write and search
+- 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 }
 - For demos use dreaming: "instant" when memories must be ready right after status done
 ```
 
@@ -195,26 +196,26 @@ Note: You can always reference the documentation by using the **supermemory-docs
 CANONICAL API SURFACE (use these, nothing else):
 
 - Auth header: `Authorization: Bearer $SUPERMEMORY_API_KEY` — the only supported auth header
-- Write content:     POST https://api.supermemory.ai/v3/documents
-- Search:            POST https://api.supermemory.ai/v4/search
-- Profile + search:  POST https://api.supermemory.ai/v4/profile
-- Settings:          PATCH https://api.supermemory.ai/v3/settings
-- Scoping:           `containerTag` (singular string) in the JSON body — never in a header
-- SDK:               `client.add()`, `client.search()`, `client.profile()`
+- Write content:     POST https://api.supermemory.ai/ns/{namespace}/document
+- Search:            POST https://api.supermemory.ai/ns/{namespace}/search
+- Profile:           POST https://api.supermemory.ai/ns/{namespace}/profile
+- Org settings:      PATCH https://api.supermemory.ai/organization
+- Scoping:           one `namespace` in the URL path — never in the body or a header
+- SDK:               `import { Supermemory } from "supermemory"`; `supermemory.add(namespace, { content, id?, metadata? })`, `supermemory.search(namespace, { query })`, `supermemory.profile(namespace)`
 
 DO NOT USE — deprecated, undocumented, or fabricated:
 
-- Endpoints:  /v1/anything, /v3/memories, /v3/search   (use /v3/documents and /v4/search)
+- Endpoints:  /v1/anything, /v3/documents, /v3/search, /v4/search, /v4/profile, /v4/memories   (use /ns/{namespace}/...)
 - Headers:    x-supermemory-api-key, x-api-key, x-sm-user-id (for API auth)
-- Body keys:  containerTags (plural) on writes as the only scope, userId, spaces
-- Mixing:     `rerank` and `rewriteQuery` on /v4/search only — never on /v3/search
+- Body keys:  containerTag, containerTags, customId (use `id`), entityContext (use `supportingContext`), filterByMetadata (use `group`), documentDate (use `date`), q (use `query`), filters (use `filter`), userId, spaces
+- SDK:        `client.add({ containerTag })`, `client.search.execute`, `client.memories.*`, `client.profile({ q })`
 
-SCOPING IS LOAD-BEARING. Every write and every search MUST include `containerTag`.
+SCOPING IS LOAD-BEARING. Every write and every search MUST name one namespace in the path.
 
 Prefer for tutorials:
-- Ingest conversations with customId + dreaming: "instant" when you need memories immediately
-- Wait until document status is done before search
-- search with searchMode: "documents" for RAG, search (+ relatedMemories) for the graph, profile for always-on context
+- Ingest conversations with a stable `id` + dreaming: "instant" when you need memories immediately
+- Wait until document system.status is done before search
+- search with searchMode: "chunks" for RAG, searchMode: "memories" (+ include.related) for the graph, profile for always-on context
 
 STEP 1: Ask what I'm building, integration style (AI SDK / OpenAI / Direct SDK / API), data model (user/org/both), profiles yes/no.
 STEP 2: Install supermemory (npm/pip), set SUPERMEMORY_API_KEY from https://console.supermemory.ai

diff --git a/apps/docs/api-reference/container-tags.mdx b/apps/docs/api-reference/container-tags.mdx
@@ -5,6 +5,10 @@ description: "Settings, merge and delete for multi-tenant containers."
 icon: "/icons/hugeicons/book-open-01.svg"
 ---
 
+<Note>
+v5 calls these **namespaces**. Same values. New integrations should use [v5 namespaces](/v5/api-reference/namespaces).
+</Note>
+
 `containerTag` is the primary multi-tenant key (user id, workspace id, etc.). These endpoints manage settings and lifecycle for a tag.
 
 | Endpoint | Use when |

diff --git a/apps/docs/authentication.mdx b/apps/docs/authentication.mdx
@@ -1,6 +1,6 @@
 ---
 title: "API keys & auth"
-description: "Org API keys, container-scoped keys, and connector branding."
+description: "Org API keys, namespace-scoped keys, and connector branding."
 sidebarTitle: "API keys"
 icon: "/icons/hugeicons/key-01.svg"
 ---
@@ -16,17 +16,17 @@ Include your key in all requests:
 <CodeGroup>
 
 ```bash cURL
-curl https://api.supermemory.ai/v3/search \
+curl -X POST https://api.supermemory.ai/ns/user_123/search \
   --header 'Authorization: Bearer YOUR_API_KEY' \
   --header 'Content-Type: application/json' \
-  -d '{"q": "hello"}'
+  -d '{"query": "hello"}'
 ```
 
 
 ```typescript TypeScript
-import Supermemory from "supermemory";
+import { Supermemory } from "supermemory";
 
-const client = new Supermemory({ apiKey: "YOUR_API_KEY" });
+const supermemory = new Supermemory({ apiKey: "YOUR_API_KEY" });
 ```
 
 
@@ -42,32 +42,26 @@ client = Supermemory(api_key="YOUR_API_KEY")
 
 ## Connector branding
 
-When users connect external services (Google Drive, Notion, OneDrive), they see a "Log in to **Supermemory**" prompt by default. You can replace this with your own app name by providing your own OAuth credentials via the settings endpoint.
-
-```typescript
-await client.settings.update({
-  googleDriveCustomKeyEnabled: true,
-  googleDriveClientId: "your-client-id.apps.googleusercontent.com",
-  googleDriveClientSecret: "your-client-secret"
-});
-```
+When users connect external services (Google Drive, Notion, OneDrive), they see a "Log in to **Supermemory**" prompt by default. You can replace this with your own app name by providing your own OAuth credentials.
 
 This works for Google Drive, Notion, and OneDrive. See the full setup in [Customization](/concepts/customization).
 
 ---
 
 ## Scoped API keys
 
-Scoped keys are restricted to one or more `containerTag`s. They can only access documents and search within those containers — use them to give a client, session, or tenant limited access without shipping your org master key.
+Scoped keys are restricted to one namespace (what v3/v4 called a container tag). They can only access documents and search within that namespace — use them to give a client, session, or tenant limited access without shipping your org master key.
 
-Pairs with [container tags](/concepts/container-tags) for multi-tenant isolation.
+Pairs with [namespaces](/concepts/container-tags) for multi-tenant isolation.
 
 **Allowed endpoints:** `/v3/documents`, `/v3/memories`, `/v4/memories`, `/v3/search`, `/v4/search`, `/v4/profile`
 
 Scoped keys **cannot** read billing, manage org settings, or mint further keys.
 
 ### Create a scoped key
 
+The scoped-key endpoint still takes the namespace in a field named `containerTag`.
+
 ```bash
 curl https://api.supermemory.ai/v3/auth/scoped-key \
   --request POST \
@@ -84,7 +78,7 @@ curl https://api.supermemory.ai/v3/auth/scoped-key \
 
 | Parameter | Required | Default | Description |
 | --- | --- | --- | --- |
-| `containerTag` | Yes | — | Alphanumeric, hyphens, underscores, colons, dots |
+| `containerTag` | Yes | — | The namespace to scope the key to. Alphanumeric, hyphens, underscores, colons, dots |
 | `name` | No | `scoped_{containerTag}` | Display name for the key |
 | `expiresInDays` | No | — | 1–365 days |
 | `rateLimitMax` | No | `500` | Max requests per window (1–10,000) |
@@ -103,11 +97,11 @@ curl https://api.supermemory.ai/v3/auth/scoped-key \
 }
 ```
 
-Use the returned key like a normal API key — it just will not work outside its container scope.
+Use the returned key like a normal API key — it just will not work outside its namespace.
 
 ### Disable a scoped key
 
-Revoke with the `id` from creation. Subsequent requests get `401`. Memories and container tags are **not** deleted.
+Revoke with the `id` from creation. Subsequent requests get `401`. Memories and namespaces are **not** deleted.
 
 ```bash
 curl https://api.supermemory.ai/v3/auth/scoped-key/KEY_ID \