Merge branch 'main' of https://github.com/supermemoryai/supermemory

4 files changed, 223 insertions, 88 deletions

diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 2bbfdc0a..82dfb629 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -173,6 +173,10 @@
 								"pages": ["n8n", "zapier"]
 							},
 							{
+								"group": "Supermemory MCP",
+								"pages": ["mcp", "supermemory-mcp/setup"]
+							},
+							{
 								"group": "Migration Guides",
 								"pages": ["migration/from-mem0", "migration/from-zep"]
 							},
diff --git a/apps/docs/mcp.mdx b/apps/docs/mcp.mdx
new file mode 100644
index 00000000..c1690dbf
--- /dev/null
+++ b/apps/docs/mcp.mdx
@@ -0,0 +1,110 @@
+---
+title: "Overview"
+description: "Give your AI assistants persistent memory with the Model Context Protocol"
+---
+
+Supermemory MCP Server 4.0 gives AI assistants (Claude, Cursor, Windsurf, etc.) persistent memory across conversations. Built on Cloudflare Workers with Durable Objects for scalable, persistent connections.
+
+## Quick Install
+
+```bash
+npx -y install-mcp@latest https://mcp.supermemory.ai/mcp --client claude --oauth=yes
+```
+
+Replace `claude` with your MCP client: `cursor`, `windsurf`, `vscode`, etc.
+
+## Manual Configuration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp"
+    }
+  }
+}
+```
+
+The server uses **OAuth** by default. Your client will discover the authorization server via `/.well-known/oauth-protected-resource` and prompt you to authenticate.
+
+### API Key Authentication (Alternative)
+
+If you prefer API keys over OAuth, get one from [app.supermemory.ai](https://app.supermemory.ai) and pass it in the `Authorization` header:
+
+```json
+{
+  "mcpServers": {
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer sm_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+API keys start with `sm_` and skip OAuth when provided.
+
+### Project Scoping
+
+Scope all operations to a specific project with `x-sm-project`:
+
+```json
+{
+  "mcpServers": {
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp",
+      "headers": {
+        "x-sm-project": "your-project-id"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `memory`
+
+Save or forget information about the user.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | Yes | The memory content to save or forget |
+| `action` | `"save"` \| `"forget"` | No | Default: `"save"` |
+| `containerTag` | string | No | Project tag to scope the memory |
+
+### `recall`
+
+Search memories and get user profile.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search query to find relevant memories |
+| `includeProfile` | boolean | No | Include user profile summary. Default: `true` |
+| `containerTag` | string | No | Project tag to scope the search |
+
+### `whoAmI`
+
+Get the current logged-in user's information. Returns `{ userId, email, name, client, sessionId }`.
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `supermemory://profile` | User profile with stable preferences and recent activity |
+| `supermemory://projects` | List of available memory projects |
+
+## Prompts
+
+| Name | Description |
+|------|-------------|
+| `context` | User profile and preferences for system context injection |
+
+<Card title="MCP Server Source Code" icon="github" href="https://github.com/supermemoryai/supermemory/tree/main/apps/mcp">
+  View the open-source implementation
+</Card>
+
diff --git a/apps/docs/supermemory-mcp/introduction.mdx b/apps/docs/supermemory-mcp/introduction.mdx
index 0ee96b45..2e6f3826 100644
--- a/apps/docs/supermemory-mcp/introduction.mdx
+++ b/apps/docs/supermemory-mcp/introduction.mdx
@@ -1,74 +1,60 @@
 ---
-title: 'About supermemory MCP'
-description: 'Carry your memories with you, using supermemory MCP'
+title: 'About Supermemory MCP'
+description: 'Give your AI assistants persistent memory with the Model Context Protocol'
 ---
 
-supermemory MCP is a lightweight **consumer-facing** component that allows you to carry your memories with you across any AI platform. It serves as a universal memory layer that enables Large Language Models (LLMs) to maintain persistent context and memories across different applications and sessions, solving the fundamental limitation of AI assistants forgetting everything between conversations.
+Supermemory MCP Server 4.0 is a lightweight component that gives AI assistants persistent memory across conversations. It serves as a universal memory layer enabling Large Language Models (LLMs) to maintain context and memories across different applications and sessions, solving the fundamental limitation of AI assistants forgetting everything between conversations.
 
-## What supermemory MCP is and how it works
-
-**supermemory MCP** functions as an open-source, universal memory system that bridges the gap between isolated AI applications through the Model Context Protocol (MCP). It operates as a **meta MCP server** that creates individual server instances for each user, providing seamless memory persistence across any MCP-compatible LLM client including ChatGPT, Claude, Windsurf, Cursor, and VS Code.
-
-The system works by running as an MCP server that communicates with MCP-compatible clients, storing and retrieving contextual information through the robust supermemory API infrastructure. When users interact with any connected AI application, the system automatically captures relevant information and makes it available to all other connected platforms through **semantic search and intelligent retrieval**.
-
-
-It is also a great example of how you can use supermemory to build your own consumer-facing applications.
-<Card title="supermemory MCP code" icon="github" href="https://github.com/supermemoryai/supermemory-mcp">
-    Code behind the scenes
+<Card title="Quick Start" icon="rocket" href="/mcp">
+  Jump to installation and setup
 </Card>
 
+## What Supermemory MCP Does
 
-### Key consumer benefits
-
-- **No login requirements**: Access granted via unique, private URLs that serve as both identifier and API key
-- **Completely free**: Fully functional hosted service available at no cost
-- **One-command setup**: Single CLI installation: `npx install-mcp [URL] --client [CLIENT]`
-- **Universal compatibility**: Works seamlessly across multiple LLM clients and platforms
+**Supermemory MCP** functions as a universal memory system that bridges AI applications through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It operates as an **MCP server** that communicates with MCP-compatible clients, storing and retrieving contextual information through the Supermemory API infrastructure.
 
+When users interact with any connected AI application, the system captures relevant information and makes it available across all other connected platforms through **semantic search and intelligent retrieval**.
 
-### Core workflow process
+### Supported Platforms
 
-1. User interacts with any MCP-compatible AI client 
-2. The client connects to supermemory MCP server via a unique, private URL
-3. During conversations, relevant information is stored using the `addToSupermemory` action
-4. When context is needed, the `searchSupermemory` action retrieves relevant memories
-5. The AI assistant accesses this persistent context regardless of which platform is being used
+- **Claude Desktop** - Direct MCP protocol support
+- **Cursor IDE** - Global MCP server configuration via `~/.cursor/mcp.json`
+- **Windsurf** - Seamless integration for AI-powered development
+- **VS Code** - Compatible with AI coding extensions
+- **Cline/Roo-Cline** - Full MCP protocol support
+- **Any MCP-compatible application** - Universal compatibility through standard protocol
 
-## Building applications with supermemory
+### Key Features
 
-supermemory MCP demonstrates building consumer applications with supermemory through its **API-first architecture**. The system acts as a "customer" of the underlying supermemory API infrastructure, showcasing how developers can leverage the platform to create their own memory-enabled applications.
+- **OAuth Authentication** - Secure login through Supermemory accounts
+- **API Key Support** - Alternative authentication for automation and CI/CD
+- **Persistent Memory** - Save and recall information across sessions
+- **User Profiles** - Auto-generated profiles from stored memories
+- **Project Scoping** - Organize memories by project with `x-sm-project` header
 
-### Supported platforms
+## Core Workflow
 
-- **Claude Desktop**: Direct SSE connection support
-- **Cursor IDE**: Global MCP server configuration via `~/.cursor/mcp.json`
-- **Windsurf**: Seamless integration for AI-powered development
-- **VS Code**: Compatible with various AI coding extensions
-- **Cline/Roo-Cline**: Full MCP protocol support
-- **Any MCP-compatible application**: Universal compatibility through standard protocol implementation
+1. User interacts with any MCP-compatible AI client
+2. The client connects to `https://mcp.supermemory.ai/mcp`
+3. OAuth flow authenticates the user (or API key validates directly)
+4. During conversations, relevant information is stored using the `memory` tool
+5. When context is needed, the `recall` tool retrieves relevant memories
+6. The AI assistant accesses this persistent context regardless of which platform is being used
 
-## Security and privacy considerations
+## Security and Privacy
 
-### Security model
+### Authentication Model
 
-- **URL-based authentication**: Random URLs serve as access keys, eliminating traditional login complexity
-- **Session isolation**: Complete user data separation through unique URL paths
-- **Self-hosting option**: Full control over data and infrastructure for privacy-conscious users
-- **No authentication overhead**: Simplified access without traditional username/password systems
+- **OAuth by default** - Secure authentication through Supermemory accounts
+- **API key alternative** - Keys start with `sm_` for programmatic access
+- **Session isolation** - Complete user data separation per account
 
-### Privacy features
+### Privacy Features
 
-- **Data isolation**: User memories completely separated by unique URLs
-- **Local control option**: Self-hosting capability for enterprise or sensitive use cases
-- **Secure infrastructure**: Built on Cloudflare's enterprise-grade security platform
+- **Data isolation** - User memories completely separated by account
+- **Secure infrastructure** - Built on Cloudflare's enterprise-grade platform
+- **Open source** - Full transparency into how your data is handled
 
-## Future developments and ecosystem
-
-The project represents a **breakthrough in AI memory portability**, with ongoing developments including:
-
-- **Infinite Chat API**: Enhanced inline memory management with conversation history
-- **Expanded client support**: More MCP clients adding SSE connection capabilities
-- **Enterprise features**: Advanced security and compliance options for business use
-- **Integration expansion**: Potential connections to Google Drive, Notion, OneDrive, and other productivity platforms
-
-supermemory MCP successfully demonstrates how to build compelling consumer-facing applications using supermemory's infrastructure, achieving massive adoption through exceptional user experience design combined with robust technical architecture. Its success validates the market demand for universal AI memory solutions and provides a compelling template for developers building their own memory-enabled applications.
\ No newline at end of file
+<Card title="Source Code" icon="github" href="https://github.com/supermemoryai/supermemory/tree/main/apps/mcp">
+  View the open-source implementation
+</Card>
diff --git a/apps/docs/supermemory-mcp/setup.mdx b/apps/docs/supermemory-mcp/setup.mdx
index 23f17967..647c07f5 100644
--- a/apps/docs/supermemory-mcp/setup.mdx
+++ b/apps/docs/supermemory-mcp/setup.mdx
@@ -1,67 +1,102 @@
 ---
-title: 'Setup and usage'
-description: 'How to set up and use supermemory MCP'
+title: 'Setup and Usage'
+description: 'How to set up and use Supermemory MCP Server 4.0'
 ---
 
-### Hosted setup (recommended)
+## Quick Install (Recommended)
 
-1. **Visit** https://mcp.supermemory.ai
-2. **Receive** automatically generated unique URL (e.g., `https://mcp.supermemory.ai/TN-IKxAcDdHWTJkMhtGLF/sse`)
-3. **Select** your MCP client from the dropdown menu
-4. **Copy** the generated installation command
-5. **Run** the command: `npx install-mcp [YOUR_URL] --client [CLIENT_NAME]`
+```bash
+npx -y install-mcp@latest https://mcp.supermemory.ai/mcp --client claude --oauth=yes
+```
+
+Replace `claude` with your MCP client: `cursor`, `windsurf`, `vscode`, etc.
+
+## Manual Configuration
 
-Or follow the client configuration example below.
+Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):
 
-### Self-hosted configuration
+```json
+{
+  "mcpServers": {
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp"
+    }
+  }
+}
+```
 
-For users requiring complete data control:
+The server uses **OAuth authentication** by default. Your MCP client will automatically discover the authorization server via `/.well-known/oauth-protected-resource` and prompt you to authenticate.
 
-1. **Obtain API key** from https://console.supermemory.ai
-2. **Create `.env` file** with `SUPERMEMORY_API_KEY=your_key`
-3. **Clone repository**: `git clone https://github.com/supermemoryai/supermemory-mcp.git`
-4. **Configure MCP client** to connect to local server instance
+## API Key Authentication (Alternative)
 
-### Client configuration example
+If you prefer to use an API key instead of OAuth, get one from [app.supermemory.ai](https://app.supermemory.ai) and pass it in the `Authorization` header:
 
-1. For Clients that support `url` configuration:
 ```json
 {
   "mcpServers": {
     "supermemory": {
-      "transport": "sse",
-      "url": "https://mcp.supermemory.ai/[USER_ID]/sse"
+      "url": "https://mcp.supermemory.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer sm_your_api_key_here"
+      }
     }
   }
 }
 ```
 
-2. Using `supergateway` with `npx`:
+API keys start with `sm_` and are automatically detected. When an API key is provided, OAuth authentication is skipped.
+
+## Project Scoping (Optional)
+
+To scope all operations to a specific project, add the `x-sm-project` header:
+
 ```json
 {
-    "command": "npx",
-    "args": ["-y", "supergateway", "--sse", "YOUR_URL"]
+  "mcpServers": {
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp",
+      "headers": {
+        "x-sm-project": "your-project-id"
+      }
+    }
+  }
 }
 ```
 
-3. Using `supergateway` with `docker`:
+This keeps memories organized by project, useful when working on multiple codebases or contexts.
+
+## Client-Specific Setup
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
-The equivalent MCP command would be:
 ```json
 {
   "mcpServers": {
-    "supermachineExampleDocker": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "supercorp/supergateway",
-        "--sse",
-        "YOUR_SUPERMEMORY_URL"
-      ]
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp"
     }
   }
 }
 ```
 
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "supermemory": {
+      "url": "https://mcp.supermemory.ai/mcp"
+    }
+  }
+}
+```
+
+Or use the one-click install button at [app.supermemory.ai](https://app.supermemory.ai).
+
+### Windsurf / VS Code
+
+Configuration varies by extension. Generally, add the server URL (`https://mcp.supermemory.ai/mcp`) to your MCP settings.
\ No newline at end of file