docs: apply review fixes to the drift audit

Match plugin behaviour to the hook and proxy code, fix the strict TypeScript and pyright failures in edited samples, and correct the install, ChatGPT and Mem0 lines flagged in review.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

apps/docs/connectors/onedrive.mdx

@@ -60,7 +60,8 @@ connector = client.connectors.create(
 )
 
 # Send the user to Microsoft to authorize
-print(f"Redirect to: {connector.authorization.url}")
+if connector.authorization:
+    print(f"Redirect to: {connector.authorization.url}")
 # Output: Redirect to: https://api.supermemory.ai/v3/connections/auth/redirect?state=...
 ```
 

apps/docs/install.md

@@ -44,7 +44,7 @@ export SUPERMEMORY_API_KEY="sm_..."
 
 ## STEP 3: CANONICAL API SURFACE (use these, nothing else)
 
-- Auth header: `Authorization: Bearer $SUPERMEMORY_API_KEY` — the only supported auth header
+- Auth header: `Authorization: Bearer $SUPERMEMORY_API_KEY` (recommended; `x-api-key` and `x-supermemory-api-key` still work but are deprecated)
 - Write content: `POST https://api.supermemory.ai/ns/{namespace}/document`
 - Upload a file: `POST https://api.supermemory.ai/ns/{namespace}/document/file`
 - Search: `POST https://api.supermemory.ai/ns/{namespace}/search`
@@ -312,7 +312,7 @@ await client.search(userId, {
 4. Search modes: 'hybrid' (default), 'memories', or 'chunks'
 5. File extraction is automatic - no config needed
 6. Store conversations after each interaction under a stable `id` per conversation
-7. Processing is async; pass `dreaming: "instant"` only when memories must be ready right after `system.status` is `done` (it bills one extra operation per document)
+7. Processing is async: `system.status` tracks extraction, and memories are ready when `system.dreamingStatus` is `done` (it reads `dreaming` while they are generated). Pass `dreaming: "instant"` only when memories must be generated right away (it bills one extra operation per document)
 
 ## TESTING:
 

apps/docs/integrations/claude-code.mdx

@@ -73,9 +73,9 @@ Once installed, the plugin runs automatically:
 
 - **Session context** — At session start, profile facts for this project are loaded into context.
 - **Direct recall** — Before Claude sees each substantive prompt, the hook searches Supermemory and injects fresh matches. Set `recallDirective` to switch to advisory mode, where Claude decides when to search.
-- **Auto-capture** — When a session ends, new conversation content is saved in the background.
+- **Auto-capture** — After each Claude response (the Stop hook), conversation content added since the last save is captured in the background.
 - **Shared repo memory** — Captures go to one repository container shared with the Codex, OpenCode, and Cursor plugins, tagged with `sm_scope: personal` metadata.
-- **MCP tools** — The hosted Supermemory MCP tools (`search_memory`, `add_memory`, and more) use the same credentials. Read-only tools are approved automatically. For deeper history, Claude can also use the `context-gatherer` agent.
+- **MCP tools** — The hosted Supermemory MCP tools (`search_memory`, `add_memory`, and more) use the same credentials. `search_memory` and the legacy camelCase read tools (`listMemories`, `listDocuments`, `getDocument`, `listSpaces`, `whoAmI`) are approved automatically; other tools, including `list_memories`, `list_documents`, `get_document` and `get_profile`, still ask for approval. For deeper history, Claude can also use the `context-gatherer` agent.
 
 ## Commands
 

apps/docs/integrations/codex.mdx

@@ -64,7 +64,7 @@ Once installed, the plugin runs on every Codex session:
 |------|-------|--------------|
 | `session-start` | `SessionStart` | Loads persistent and recent profile context for the session |
 | `recall` | `UserPromptSubmit` | Searches Supermemory directly for substantive prompts and injects fresh relevant memories |
-| `recall-approve` | `PreToolUse` | Auto-allows read-only Supermemory MCP tools |
+| `recall-approve` | `PreToolUse` | Auto-allows `search_memory` and the legacy camelCase read tools (`listMemories`, `listDocuments`, `getDocument`, `listSpaces`, `whoAmI`); other Supermemory MCP tools still ask |
 | `flush` | `Stop` | Captures completed turns in the background |
 
 - **Recall modes** — Set `recallMode` to `"advisory"` to let the model decide when to search, or `"off"` to disable prompt recall.
@@ -78,7 +78,7 @@ Codex, Claude Code, and OpenCode use one container per repository:
 repo_<project-name>__<remote-hash>
 ```
 
-Automatic captures and explicit saves both go to this container; `sm_scope` metadata keeps personal and project memories distinguishable. The hash comes from the normalized Git remote, so clones and linked worktrees share memory while same-named repositories do not collide. Codex still reads the older `codex_user_*`, `codex_project_*`, and other per-tool containers, so existing memories stay searchable.
+Automatic captures go to this container with `sm_scope: personal` metadata. Explicit saves through the MCP tools are passed to the hosted server unchanged, so they land in your account's active space, not the repository container. The hash comes from the normalized Git remote, so clones and linked worktrees share memory while same-named repositories do not collide. Codex still reads the older `codex_user_*`, `codex_project_*`, and other per-tool containers, so existing memories stay searchable.
 
 Override the container in `~/.codex/supermemory.json` if needed:
 

apps/docs/integrations/mastra.mdx

@@ -364,6 +364,7 @@ const agent = new Agent(withSupermemory(
   {
     id: "my-assistant",
     name: "My Assistant",
+    instructions: "You are a helpful assistant.",
     model: openai("gpt-4o"),
     inputProcessors: [myLoggingProcessor],
     outputProcessors: [myAnalyticsProcessor],

apps/docs/integrations/memory-graph.mdx

@@ -104,7 +104,7 @@ export async function GET() {
   const data = await response.json();
   return NextResponse.json({
     ...data,
-    documents: data.documents.map((doc) => ({
+    documents: data.documents.map((doc: { type: string; memoryEntries: unknown[] }) => ({
       ...doc,
       documentType: doc.type,
       memories: doc.memoryEntries,
@@ -130,7 +130,7 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
   const data = await response.json();
   res.json({
     ...data,
-    documents: data.documents.map((doc) => ({
+    documents: data.documents.map((doc: { type: string; memoryEntries: unknown[] }) => ({
       ...doc,
       documentType: doc.type,
       memories: doc.memoryEntries,
@@ -194,10 +194,11 @@ app.get('/api/graph', async (req, res) => {
 'use client';
 
 import { MemoryGraph } from '@supermemory/memory-graph';
+import type { GraphApiDocument } from '@supermemory/memory-graph';
 import { useCallback, useEffect, useState } from 'react';
 
 export default function PaginatedGraph() {
-  const [documents, setDocuments] = useState([]);
+  const [documents, setDocuments] = useState<GraphApiDocument[]>([]);
   const [page, setPage] = useState(1);
   const [hasMore, setHasMore] = useState(true);
   const [isLoading, setIsLoading] = useState(true);
@@ -205,7 +206,7 @@ export default function PaginatedGraph() {
 
   useEffect(() => { fetchPage(1, false); }, []);
 
-  const fetchPage = async (pageNum, append) => {
+  const fetchPage = async (pageNum: number, append: boolean) => {
     pageNum === 1 ? setIsLoading(true) : setIsLoadingMore(true);
 
     const res = await fetch(`/api/graph?page=${pageNum}&limit=100`);

apps/docs/integrations/openai.mdx

@@ -272,7 +272,7 @@ result = await tools.search_memories(
     information_to_get="user preferences",
     limit=10,
 )
-print(f"Found {result['count']} memories")
+print(f"Found {result.get('count', 0)} memories")
 ```
 
 ```typescript JavaScript
@@ -297,7 +297,8 @@ Store new information in memory:
 result = await tools.add_memory(
     memory="User prefers tea over coffee"
 )
-print(f"Added memory with ID: {result['memory']['id']}")
+memory = result.get("memory") or {}
+print(f"Added memory with ID: {memory.get('id')}")
 ```
 
 ```typescript JavaScript
@@ -566,7 +567,7 @@ SupermemoryTools(
 
 **Methods**
 - `get_tool_definitions()` - Get OpenAI function definitions
-- `search_memories(information_to_get, limit)` - Search user memories (`include_full_docs` is deprecated and ignored)
+- `search_memories(information_to_get, limit=10)` - Search user memories. Pass `limit` by keyword: the second positional parameter is the deprecated, ignored `include_full_docs`
 - `add_memory(memory)` - Add new memory
 - `execute_tool_call(tool_call)` - Execute individual tool call
 

apps/docs/integrations/opencode.mdx

@@ -76,7 +76,7 @@ The installer registers the plugin for both OpenCode V1 (`plugin`) and OpenCode
 
 Once installed, the plugin runs automatically:
 
-- **Context Injection** — On a session's first message, your profile and project knowledge are injected into the agent's context.
+- **Context Injection** — On a session's first message, your profile facts are injected into the agent's context.
 - **Direct Recall** — On every substantive prompt, the plugin searches the current project and injects up to five fresh matches. Set `recallMode` to `"advisory"` to let the agent decide when to search, or `"off"` to disable it.
 - **Automatic Capture** — Completed turns are saved every `captureEveryNTurns` turns (fresh installs use `0`, which saves only at the end), and any remainder is flushed when the session ends or OpenCode shuts down.
 - **Keyword Detection** — Phrases like "remember" or "save this" nudge the agent to save to memory.

apps/docs/migration/from-mem0.mdx

@@ -11,7 +11,7 @@ Migrating from Mem0 to Supermemory is straightforward. This guide walks you thro
 Supermemory offers enhanced capabilities over Mem0:
 - **Knowledge graph** architecture for better context relationships
 - **Multiple content types** (URLs, PDFs, images, videos)
-- **Free plan** with $5 of usage credits every month, then usage-based pricing
+- **Free plan** with $5 of free credits every month; Free orgs upgrade to a paid plan once they run out (top-ups are paid-plan only)
 - **Multiple integration options** (API, MCP, SDKs)
 
 ## Quick migration (all-in-one)

apps/docs/supermemory-mcp/chatgpt-web.mdx

@@ -196,7 +196,7 @@ After approval, ChatGPT returns to the Supermemory MCP plugin page. Select **Try
 
 Supermemory MCP is now ready to use in ChatGPT Web. You can manage or disconnect it later from the [Plugins page](https://chatgpt.com/plugins).
 
-To switch between **Read + Write** and **Read only**, or change which spaces ChatGPT can use, open the [Agents page](https://console.supermemory.ai/agents) in the Supermemory console and choose **Edit access**. Reconnecting from ChatGPT does not show the authorization page again.
+To switch between **Read and write** and **Read only**, or change which spaces ChatGPT can use, open the [Agents page](https://console.supermemory.ai/agents) in the Supermemory console and choose **Edit access**. Reconnecting from ChatGPT does not show the authorization page again.
 
 ## Frequently asked questions