Supermemory MCP

https://github.com/supermemoryai/supermemory-mcp
Admin
Supermemory MCP is a universal memory system that enables users to carry their memories across...
Tokens:24,649
Snippets:167
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Route usage of Welcome component

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/welcome.tsx.md

Usage example from the owning route (app/routes/home.tsx) showing how to render the Welcome component with loader data.

```tsx
import { Welcome } from "../welcome/welcome"

export default function Home({ loaderData }: Route.ComponentProps) {
    return (
        <Welcome
            message={loaderData.message}
            userId={loaderData.userId}
            initialMemories={loaderData.memories}
        />
    )
}
```

--------------------------------

### Error-handling example (transport not initialized)

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Documents the only throw path in the source: posting to /<userId>/messages before any SSE connection is opened results in a 500 error with body 'Transport not initialized'.

```ts
// POST /<userId>/messages before any SSE connection was opened
// -> server.onError returns HTTP 500 with body "Transport not initialized"
```

--------------------------------

### Session restore example

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Session restore pattern as used in the restore case. Reads the Cookie header, gets the session, sets the userId, and returns a success response with a Set-Cookie header that expires in the year 9999.

```ts
const cookies = request.headers.get("Cookie")
const session = await getSession(cookies)
session.set("userId", postedUserId)
return data(
    { success: true, message: "Session restored successfully", userId, memories },
    { headers: { "Set-Cookie": await commitSession(session, { expires: new Date("9999-12-31") }) } },
)
```

--------------------------------

### Memory Limit Error Handling

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Error-handling example matching the source (`/add` guard) that returns a 400 response when the memory limit is exceeded.

```ts
if (memories.length > 2000) {
    return c.json<ToolResponseType>(
        [{ type: "text", text: "Memory limit of 2000 memories exceeded" }],
        400,
    )
}
```

--------------------------------

### Loader function for home route

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Handles incoming GET requests, reads the session from cookies, and either returns existing memories for a returning user or creates a new anonymous session with a nanoid and sets a long-lived cookie.

```TypeScript
export async function loader({ request, context }: Route.LoaderArgs) {
    const cookies = request.headers.get("Cookie")
    const session = await getSession(cookies)

    const supermemory = new Supermemory({
        apiKey: context.cloudflare.env.SUPERMEMORY_API_KEY,
    })

    if (session.has("userId")) {
        const userId = session.get("userId")!
        const memories = (
            await supermemory.memories.list({
                limit: "2000",
                containerTags: [userId]
            })
        ).memories
        console.log("memories", memories)
        return data({
            message: "Welcome back!",
            userId,
            memories,
        })
    }

    session.set("userId", nanoid())
    const userId = session.get("userId")!

    return data(
        {
            message: "Welcome to Supermemory MCP!",
            userId,
            memories: [],
        },
        {
            headers: {
                "Set-Cookie": await commitSession(session, {
                    expires: new Date("9999-12-31"),
                }),
            },
        },
    )
}
```

--------------------------------

### GET /:userId/sse

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

The GET /:userId/sse endpoint opens an SSE stream for a user, used for MCP communication. It is part of the MyDurableObject's fetch method and is mounted on the Hono server with basePath "/:userId".

```APIDOC
## GET /:userId/sse

### Description
Opens a Server-Sent Events (SSE) stream for the specified user. This endpoint is part of the MCP wire protocol and is served by the MyDurableObject's fetch method.

### Method
GET

### Endpoint
/:userId/sse

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user ID extracted from the first path segment.

### Response
#### Success Response (200)
- **body** (stream) - SSE stream for MCP communication.

### Error Handling
- If the userId is missing, the middleware returns HTTP 400 with body "User ID is required".
- Any errors are caught by the onError handler, logged, and returned as HTTP 500 with the error message as the body.
```

--------------------------------

### GET /<userId>/sse

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/endpoints.md

Opens an SSE stream for MCP communication. The client connects to this endpoint to receive MCP messages from the server.

```APIDOC
## GET /<userId>/sse

### Description
Opens an SSE stream for MCP communication. The client connects to this endpoint to receive MCP messages from the server.

### Method
GET

### Endpoint
GET /<userId>/sse

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user identifier, extracted from the first path segment.

#### Query Parameters
- **sessionId** (string) - Optional - The Durable Object ID used to select the Durable Object on the first hop.

### Response
#### Success Response (200)
- **Content-Type**: text/event-stream
- **Body**: SSE stream produced by `streamSSE(c, handler)`. The stream is used to deliver MCP messages.

#### Error Responses
- **400**: `{ "error": "User ID is required" }` if the userId path parameter is missing.
- **500**: `err.message` as body on any later error.

### Notes
- No authentication required.
- CORS preflight: `cors({ origin: "*", credentials: true })`.
- After a successful stream, the client posts MCP messages to `POST /<userId>/messages`, whose response is delivered back over this stream.
```

--------------------------------

### POST /<userId>/messages

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/endpoints.md

Delivers MCP JSON-RPC messages to the server. The request body is the MCP message payload, and the response is delivered back over the SSE stream opened via `GET /<userId>/sse`.

```APIDOC
## POST /<userId>/messages

### Description
Delivers MCP JSON-RPC messages to the server. The request body is the MCP message payload, and the response is delivered back over the SSE stream opened via `GET /<userId>/sse`.

### Method
POST

### Endpoint
POST /<userId>/messages

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user identifier, extracted from the first path segment.

#### Query Parameters
- **sessionId** (string) - Optional - The Durable Object ID used to select the Durable Object on the first hop.

#### Request Body
- **MCP JSON-RPC message** (object) - Required - The MCP message payload consumed by `SSEHonoTransport.handlePostMessage(c)`. JSON framing is handled by the external `muppet/streaming` package.

### Response
#### Success Response (200)
- **Content-Type**: text/plain; charset=utf-8
- **Body**: `ok`

#### Error Responses
- **400**: `{ "error": "User ID is required" }` if the userId path parameter is missing.
- **500**: `err.message` as body via `onError`. Notably, `"Transport not initialized"` is thrown when `c.env.transport` is unset (no prior `GET /sse` on this DO instance).

### Notes
- No authentication required.
- CORS preflight: `cors({ origin: "*", credentials: true })`.
```

--------------------------------

### POST /

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/endpoints.md

Documentation for the POST / endpoint that handles memory console actions.

```APIDOC
## POST /

### Description
Handles memory console actions (fetch, delete, update, restore) via a React Router index route action. Consumed through `useFetcher().submit(formData, { method: "post", action: "/?index" })`.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body (multipart/form-data)
- **userId** (string) - Required - Session identity / Supermemory container tag; missing → 400
- **action** (string) - Required - One of `fetch`, `delete`, `update`, `restore`; anything else → 400
- **memoryId** (string) - Required for `delete` and `update` - Target memory; missing → 400
- **content** (string) - Required for `update` - Replacement memory content

### Request Example
```
userId=user123&action=fetch
```

### Response
#### Success Response (200)
- **fetch**: `{ success: true, memories: MemoryListResponse.Memory[] }`
- **delete**: `{ success: true, message: "Memory deleted successfully", memories: [...] }`
- **update**: `{ success: true, message: "Memory updated successfully", memories: [...] }`
- **restore**: `{ success: true, message: "Session restored successfully", userId, memories }` + `Set-Cookie` (expires `9999-12-31`)

#### Response Example
```
{
  "success": true,
  "memories": []
}
```

#### Error Responses
- **400**: Missing `userId` ("User ID is required"), missing `memoryId` ("Memory ID is required"), invalid `action` ("Invalid action type")
- **500**: SDK failure ("Error deleting memory: <msg>", "Error updating memory: <msg>"), or outer catch ("Failed to process memory action")

Error body: `{ error: string }`
```

--------------------------------

### Issue first-time session with commitSession

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/session-cookies.server.ts.md

Shows how to create a new session for a first-time user, set the userId, and commit the session in a Set-Cookie header with an expiration date far in the future.

```ts
import { getSession, commitSession } from "~/session-cookies.server"

const cookies = request.headers.get("Cookie")
const session = await getSession(cookies)
session.set("userId", nanoid())

return data(
    { message: "Welcome to Supermemory MCP!", userId, memories: [] },
    {
        headers: {
            "Set-Cookie": await commitSession(session, {
                expires: new Date("9999-12-31"),
            }),
        },
    },
)
```

--------------------------------

### Initialize Supermemory client and list memories

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Initialization pattern used by both the loader and action. Creates a Supermemory instance with the API key from the environment and lists memories with a limit of 2000 and container tags for the user.

```ts
import { Supermemory } from "supermemory"

const supermemory = new Supermemory({
    apiKey: context.cloudflare.env.SUPERMEMORY_API_KEY,
})
const { memories } = await supermemory.memories.list({
    limit: "2000",
    containerTags: [userId],
})
```

--------------------------------

### Welcome component imports and props

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/welcome.tsx.md

Imports and function signature for the Welcome component. The component receives a greeting message, an anonymous user id, and initial memories loaded by the route loader.

```ts
import type { MemoryListResponse } from "@supermemory/sdk/resources/memory.mjs"
import { useCallback, useEffect, useState } from "react"
import { useFetcher } from "react-router"
import logoMark from "./logomark.svg"

export function Welcome({
    message,
    userId,
    initialMemories,
}: {
    message: string
    userId: string
    initialMemories: MemoryListResponse.Memory[]
}) {
```

--------------------------------

### Supermemory Client Initialization and Usage

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Basic initialization of a Supermemory client inside a Worker handler, including listing memories, adding a memory, and executing a search.

```ts
import { Supermemory } from "supermemory"

const supermemory = new Supermemory({
    apiKey: env.SUPERMEMORY_API_KEY,
})
const { memories } = await supermemory.memories.list({
    containerTags: [userId],
})
await supermemory.memories.add({
    content: "prefers TypeScript over Java",
    containerTags: [userId],
})
const response = await supermemory.search.execute({
    q: "what do I prefer?",
    containerTags: [userId],
})
```

--------------------------------

### fetch method implementation

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Overrides the fetch method to handle incoming requests. Extracts userId from the URL path, lazily creates the SSE transport, sets up a Hono server with basePath and middleware, and returns the server's fetch response.

```ts
override async fetch(request: Request) {
    const url = new URL(request.url)
    const userId = url.pathname.split("/")[1] // Get userId from path
    if (!this.transport) {
        this.transport = new SSEHonoTransport(
            `/${userId}/messages`,
            this.ctx.id.toString(),
        )
    }
    const server = new Hono<{
        Bindings: Env & { transport: SSEHonoTransport }
        Variables: { userId: string }
    }>()
        .basePath("/:userId")
        .use(async (c, next) => { /* 400 "User ID is required"; c.set("userId", userId) */ })
        .use(cors({ origin: "*", credentials: true }))

    server.get("/sse", /* streamSSE + bridge + muppet */)
    server.post("/messages", /* transport.handlePostMessage */)
    server.onError((err, c) => { console.error(err); return c.body(err.message, 500) })

    return server.fetch(request, { ...this.env, transport: this.transport })
}
```

--------------------------------

### POST /search route (searchSupermemory tool)

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Defines the POST /search endpoint that invokes the searchSupermemory MCP tool. Expects a JSON body with informationToGet, calls supermemory.search.execute, and returns a ToolResponseType with joined chunk contents.

```ts
app.post(
    "/search",
    describeTool({
        name: "searchSupermemory",
        description:
            "Search user memories and patterns. Run when explicitly asked or when context about user's past choices would be helpful. ...",
    }),
    mValidator(
        "json",
        z.object({
            informationToGet: z.string(),
        }),
    ),
    async (c) => {
        const { informationToGet } = c.req.valid("json")
        console.log("SEARCHING WITH USER ID", userId)
        const response = await supermemory.search.execute({
            q: informationToGet,
            containerTags: [userId],
        })
        return c.json<ToolResponseType>([
            { type: "text", text: `${response.results.map((r) =>
                r.chunks.map((c) => c.content).join("\n\n"),
            )}` },
        ])
    },
)
```

--------------------------------

### createSuperMemory(userId, env) factory

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Creates a Supermemory client and returns the module-level Hono app with three routes registered. The function has no return annotation; it returns `app`. Routes are registered on the shared module-level `app` constant, so each call re-registers them. `Supermemory` is from the `supermemory ^3.0.0-alpha.14` package. Source: `workers/app.ts` lines 39–156.

```ts
function createSuperMemory(userId: string, env: Env) {
    const supermemory = new Supermemory({
        apiKey: env.SUPERMEMORY_API_KEY,
    })
    // ... registers app.post("/supermemory-prompt" | "/add" | "/search") on
    // the module-level `const app = new Hono<AppType>()` ...
    return app
}
```

--------------------------------

### Composing the Layout

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Shows how a consumer composes the exported Layout shell by wrapping the App component.

```tsx
<Layout>
    <App />
</Layout>
```

--------------------------------

### meta() function for home route

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Returns the React Router meta descriptor array configuring page title, description, social media images, apple touch icons, favicons, web manifest, and theme color.

```typescript
export function meta() {
    return [
        { title: "Supermemory MCP" },
        { name: "description", content: "Universal Memory MCP" },
        // og image
        { name: "og:image", content: "/og-image.png" },
        { name: "twitter:card", content: "summary_large_image" },
        { name: "twitter:image", content: "/og-image.png" },
        // apple touch icons
        { tagName: "link", rel: "apple-touch-icon", sizes: "57x57", href: "/icons/apple-icon-57x57.png" },
        // ... sizes 60, 72, 76, 114, 120, 144, 152, 180 ...
        // favicons
        { tagName: "link", rel: "icon", type: "image/png", sizes: "192x192", href: "/icons/android-icon-192x192.png" },
        { tagName: "link", rel: "icon", type: "image/png", sizes: "32x32", href: "/icons/favicon-32x32.png" },
        { tagName: "link", rel: "icon", type: "image/png", sizes: "96x96", href: "/icons/favicon-96x96.png" },
        { tagName: "link", rel: "icon", type: "image/png", sizes: "16x16", href: "/icons/favicon-16x16.png" },
        { tagName: "link", rel: "manifest", href: "/icons/manifest.json" },
        { name: "msapplication-TileColor", content: "#ffffff" },
        { name: "msapplication-TileImage", content: "/icons/ms-icon-144x144.png" },
        { name: "theme-color", content: "#ffffff" },
    ]
}
```

--------------------------------

### POST /supermemory-prompt MCP prompt route

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Registers the MCP prompt route `POST /supermemory-prompt`. `describePrompt` declares the prompt; `completion` returns three suggestion strings. The handler responds with `PromptResponseType` (from `muppet`): an array of chat-message objects. The `text` value instructs the model to proactively use Supermemory tools. Full text: `workers/app.ts` lines 54–67.

```ts
app.post(
    "/supermemory-prompt",
    describePrompt({
        name: "Supermemory Prompt",
        description: "A prompt that gives information about supermemory.",
        completion: ({ name, value }) => [
            "supermemory",
            "memory",
            "supermemory api",
        ],
    }),
    (c) => {
        return c.json<PromptResponseType>([
            {
                role: "user",
                content: {
                    type: "text",
                    text: "IMPORTANT: You MUST use Supermemory tools proactively ...",
                },
            },
        ])
    },
)
```

--------------------------------

### POST /add MCP tool addToSupermemory route

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Registers the MCP tool route `POST /add` for `addToSupermemory`. Validates JSON body with `mValidator` expecting `{ thingToRemember: string }`. Returns `ToolResponseType` (from `muppet`) with success or error messages; errors return status 400 with "User ID is required" or "Memory limit of 2000 memories exceeded". Backend calls: `supermemory.memories.list({ containerTags: [userId] })` and `supermemory.memories.add({ content, containerTags })`. Source: `workers/app.ts` lines 69–119.

```ts
app.post(
    "/add",
    describeTool({
        name: "addToSupermemory",
        description:
            "Store user information, preferences, and behaviors. Run on explicit commands ('remember this') ...",
    }),
    mValidator(
        "json",
        z.object({
            thingToRemember: z.string(),
        }),
    ),
    async (c) => {
        const { thingToRemember } = c.req.valid("json")
        if (!userId) {
            return c.json<ToolResponseType>(
                [{ type: "text", text: "User ID is required" }],
                400,
            )
        }
        const { memories } = await supermemory.memories.list({
            containerTags: [userId],
        })
        if (memories.length > 2000) {
            return c.json<ToolResponseType>(
                [{ type: "text", text: "Memory limit of 2000 memories exceeded" }],
                400,
            )
        }
        await supermemory.memories.add({
            content: thingToRemember,
            containerTags: [userId],
        })
        return c.json<ToolResponseType>([
            { type: "text", text: "Memory added successfully" },
        ])
    },
)
```

--------------------------------

### Error handling for 404

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Shows how to use isRouteErrorResponse to check for a 404 error and render a specific message. This is equivalent consumer-side logic for the ErrorBoundary.

```ts
import { isRouteErrorResponse } from "react-router"

if (isRouteErrorResponse(error) && error.status === 404) {
    // -> ErrorBoundary renders "404 / The requested page could not be found."
}
```

--------------------------------

### Module-level constants for MCP clients and URL

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/welcome.tsx.md

Module-level constants: selectedClient defaults to "claude", clients lists supported MCP clients, and currentUrl is the deployed origin used to build the MCP URL.

```ts
const [selectedClient, setSelectedClient] = useState<string>("claude")
const clients = [
    "claude",
    "cursor",
    "cline",
    "roo-cline",
    "windsurf",
    "witsy",
    "enconvo",
]
const currentUrl = "https://mcp.supermemory.ai"
```

--------------------------------

### fetchMemories fetcher call pattern

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/welcome.tsx.md

Realistic useFetcher call pattern to fetch memories by submitting FormData with userId and action "fetch" to the /?index action.

```ts
const formData = new FormData()
formData.append("userId", userId)
formData.append("action", "fetch")
fetcher.submit(formData, {
    method: "post",
    action: "/?index",
})
```

--------------------------------

### Return ToolResponseType JSON from /add and /search handlers

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Returns JSON responses typed as ToolResponseType, including success and error variants with status 400 when user ID is missing.

```TypeScript
c.json<ToolResponseType>([{ type: "text", text: "Memory added successfully" }])
// and error variants, status 400:
c.json<ToolResponseType>([{ type: "text", text: "User ID is required" }], 400)
```

--------------------------------

### Import RouteConfig and index from @react-router/dev/routes

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/routes.ts.md

Imports the RouteConfig type and index helper from the React Router dev routes package.

```ts
import { type RouteConfig, index } from "@react-router/dev/routes"
```

--------------------------------

### AppType Type Definition

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Defines the Hono generics for the module-level app, which is created as `const app = new Hono<AppType>()`.

```ts
type AppType = {
    Bindings: Env
}
```

--------------------------------

### Import dependencies and declare React Router AppLoadContext

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Imports the dependencies for the Worker entry module: Cloudflare Durable Object, Supermemory client, Hono and CORS, muppet types and helpers, SSE transport, React Router request handler, and Zod. Also augments the React Router AppLoadContext with the Cloudflare bindings (env and ctx).

```ts
import { DurableObject } from "cloudflare:workers"
import { Supermemory } from "supermemory"
import { Hono } from "hono"
import { cors } from "hono/cors"
import {
    type PromptResponseType,
    type Resource,
    type ToolResponseType,
    bridge,
    describePrompt,
    describeTool,
    mValidator,
    muppet,
} from "muppet"
import { SSEHonoTransport, streamSSE } from "muppet/streaming"
import { createRequestHandler } from "react-router"
import { z } from "zod"

declare module "react-router" {
    export interface AppLoadContext {
        cloudflare: {
            env: Env
            ctx: ExecutionContext
        }
    }
}
```

--------------------------------

### POST /search

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

The POST /search endpoint is an MCP tool named searchSupermemory that searches user memories and patterns. It accepts an informationToGet string in the request body and returns a ToolResponseType with the search results concatenated.

```APIDOC
## POST /search

### Description
Searches user memories and patterns. Run when explicitly asked or when context about user's past choices would be helpful.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **informationToGet** (string) - Required - The information to search for in the user's memories.

### Request Example
{
  "informationToGet": "What did I eat for breakfast?"
}

### Response
#### Success Response (200)
- **type** (string) - Always "text"
- **text** (string) - The concatenated content of all chunks from the search results, joined with "\n\n".

#### Response Example
{
  "type": "text",
  "text": "I had eggs and toast.\n\nI also had coffee."
}
```

--------------------------------

### Imports for home.tsx route

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Imports the Supermemory SDK, nanoid, React Router utilities, session cookie helpers, and the Welcome component. Also imports the generated Route types from './+types/home'.

```typescript
import { Supermemory } from "supermemory"
import { nanoid } from "nanoid"
import { data, type AppLoadContext } from "react-router"
import { commitSession, getSession } from "~/session-cookies.server"
import { Welcome } from "../welcome/welcome"
import type { Route } from "./+types/home"
```

--------------------------------

### Return PromptResponseType JSON from /supermemory-prompt handler

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Returns a JSON response typed as PromptResponseType, containing a user message that instructs the model to use Supermemory tools proactively.

```TypeScript
return c.json<PromptResponseType>([
    {
        role: "user",
        content: {
            type: "text",
            text: "IMPORTANT: You MUST use Supermemory tools proactively ...",
        },
    },
])
```

--------------------------------

### Import PromptResponseType from muppet

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Imports PromptResponseType and other types from the external muppet package in workers/app.ts.

```TypeScript
import { type PromptResponseType, type Resource, type ToolResponseType, ... } from "muppet"
```

--------------------------------

### Imports for root layout

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Imports React Router components and types for the root layout, including Links, Meta, Outlet, Scripts, ScrollRestoration, isRouteErrorResponse, the Route type, and the app's CSS.

```ts
import {
    Links,
    Meta,
    Outlet,
    Scripts,
    ScrollRestoration,
    isRouteErrorResponse,
} from "react-router"

import type { Route } from "./+types/root"
import "./app.css"
```

--------------------------------

### Indirect usage of MY_DO binding

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Shows how Cloudflare resolves stubs from the MY_DO binding, as documented in configuration.md. The DO is never constructed directly by user code.

```ts
// Cloudflare resolves stubs from the MY_DO binding (wrangler.jsonc):
const stub = env.MY_DO.get(env.MY_DO.idFromString(sessionId))
await stub.fetch(request) // GET /<userId>/sse or POST /<userId>/messages
```

--------------------------------

### Error handling for memory deletion

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Error handling pattern as used in the delete case. The SDK call is wrapped in a try-catch, and the error message is surfaced in the response with a 500 status.

```ts
try {
    await supermemory.memories.delete(memoryId)
} catch (error: unknown) {
    return data(
        { error: `Error deleting memory: ${error instanceof Error ? error.message : String(error)}` },
        { status: 500 },
    )
}
```

--------------------------------

### Import SSEHonoTransport and streamSSE from muppet/streaming

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Used to import the SSEHonoTransport class and streamSSE function for streaming transport. Observable usage includes constructing SSEHonoTransport with a user-specific path and context ID, then connecting with a stream and handling post messages.

```typescript
import { SSEHonoTransport, streamSSE } from "muppet/streaming"
```

--------------------------------

### Export default route config array with index route

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/routes.ts.md

Exports the default route configuration array, containing a single index route for 'routes/home.tsx', typed with satisfies RouteConfig.

```ts
export default [index("routes/home.tsx")] satisfies RouteConfig
```

--------------------------------

### react-router.config.ts configuration

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/configuration.md

Configures React Router with SSR enabled and several unstable future flags for Vite environment API, dependency optimization, and route module splitting.

```TypeScript
export default {
    ssr: true,
    future: {
        unstable_viteEnvironmentApi: true,
        unstable_optimizeDeps: true,
        unstable_splitRouteModules: true,
    },
} satisfies Config
```

--------------------------------

### Import MemoryListResponse type from @supermemory/sdk

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Imports the MemoryListResponse type for use in type annotations. Observable usage includes defining initialMemories as MemoryListResponse.Memory[] and accessing memory properties like id, title, and summary.

```typescript
import type { MemoryListResponse } from "@supermemory/sdk/resources/memory.mjs"
```

--------------------------------

### Export session helpers

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/session-cookies.server.ts.md

Re-exports the session helpers created by createCookieSessionStorage. This is the public interface for other modules to use.

```ts
export { getSession, commitSession, destroySession }
```

--------------------------------

### links function for Google Fonts

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Exports the links function that returns preconnect hints for Google Fonts and a stylesheet link for the Space Grotesk font (weights 300-700).

```ts
export const links: Route.LinksFunction = () => [
    { rel: "preconnect", href: "https://fonts.googleapis.com" },
    {
        rel: "preconnect",
        href: "https://fonts.gstatic.com",
        crossOrigin: "anonymous",
    },
    {
        rel: "stylesheet",
        href: "https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300..700&display=swap",
    },
]
```

--------------------------------

### Cloudflare Env interface declaration (worker-configuration.d.ts)

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Generated by `wrangler types` (header: `Generated by Wrangler ... hash: bac47ddfd12d22e9196880962c11c32e`). Declares the Cloudflare Env interface with SUPERMEMORY_API_KEY, AUTH_SECRET, and MY_DO fields, plus an alias Env extending Cloudflare.Env. Used by workers/app.ts and app/routes/home.tsx.

```typescript
declare namespace Cloudflare {
	interface Env {
		SUPERMEMORY_API_KEY: string;
		AUTH_SECRET: string;
		MY_DO: DurableObjectNamespace<import("./workers/app").MyDurableObject>;
	}
}
interface Env extends Cloudflare.Env {}
```

--------------------------------

### Module augmentation of react-router's AppLoadContext

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Adds a `cloudflare` property with `env` and `ctx` to every React Router `AppLoadContext`. Consumers like `app/routes/home.tsx` read `context.cloudflare.env.SUPERMEMORY_API_KEY` from `loader`/`action`; `app/root.tsx`'s `ErrorBoundary` and `app/entry.server.tsx`'s `handleRequest` receive it as the load context. Source: `workers/app.ts` lines 18–25.

```ts
declare module "react-router" {
    export interface AppLoadContext {
        cloudflare: {
            env: Env
            ctx: ExecutionContext
        }
    }
}
```

--------------------------------

### Action handler for memory operations (TypeScript)

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

Handles multipart form data for memory actions. Requires `userId` and `action` fields; returns 400 errors for missing fields or invalid action type, 500 on SDK errors. Uses `Supermemory` with API key from context and returns React Router `data` responses.

```typescript
export async function action({
    request,
    context,
}: {
    request: Request
    context: AppLoadContext
}) {
    const formData = await request.formData()
    const userId = formData.get("userId") as string
    const actionType = formData.get("action") as string

    if (!userId) {
        return data({ error: "User ID is required" }, { status: 400 })
    }

    const supermemory = new Supermemory({
        apiKey: context.cloudflare.env.SUPERMEMORY_API_KEY,
    })

    try {
        switch (actionType) {
            case "fetch":   // list memories
            case "delete":  // requires form field memoryId
            case "update":  // requires form fields memoryId + content
            case "restore": // re-issue session cookie for the posted userId
            default:        // 400 { error: "Invalid action type" }
        }
    } catch (error) {
        console.error("Error processing memory action:", error)
        return data({ error: "Failed to process memory action" }, { status: 500 })
    }
}
```

--------------------------------

### Error handling: check session presence

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/session-cookies.server.ts.md

Shows a consumer checking if the session has a userId before use, treating the user as anonymous if not present and assigning a new userId.

```ts
const session = await getSession(request.headers.get("Cookie"))
if (!session.has("userId")) {
    // treat as anonymous: assign a new userId via session.set("userId", nanoid())
    // and commitSession(...) in the Set-Cookie header
}
```

--------------------------------

### Error handling for failed memory operation

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/welcome.tsx.md

Error-side handling of a failed action: when fetcher is idle, updates memories if present, otherwise logs and alerts the error.

```ts
if (fetcher.data && fetcher.state === "idle") {
    if (fetcher.data.memories) setMemories(fetcher.data.memories)
    if (fetcher.data.error) {
        console.error("Error with memory operation:", fetcher.data.error)
        alert(`Operation failed: ${fetcher.data.error}`)
    }
}
```

--------------------------------

### Handle HTTP status payloads (cases 1, 2, 4, 5) with fetcher or tool result

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/errors.md

Use this snippet to handle HTTP status payloads (cases 1, 2, 4, 5) when submitting form data or processing tool call results. It checks for a 400 status and logs the error text from the response body, such as 'Memory limit of 2000 memories exceeded'.

```typescript
const res = await fetcher.submit(formData, { method: "post", action: "/?index" })
// or, for tool calls:
if (toolResult.status === 400) {
    const [item] = toolResult.body // { type: "text", text: "Memory limit of 2000 memories exceeded" }
    console.error(item.text)
}
```

--------------------------------

### Catch Error instances (case 3) with try-catch and fetch

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/errors.md

Use this snippet to catch Error instances (case 3) when making a POST request to the Supermemory MCP API. It checks the response status and logs the error message from the body, such as 'Transport not initialized', or catches network-level failures.

```typescript
try {
    const res = await fetch(`https://mcp.supermemory.ai/${userId}/messages`, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(jsonRpcMessage),
    })
    if (!res.ok) {
        // body carries the thrown error message, e.g. "Transport not initialized"
        console.error(await res.text())
    }
} catch (e) {
    // network-level failure
}
```

--------------------------------

### Layout component

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Exports the Layout component that renders the HTML document with a dark theme, meta tags, Meta and Links slots, and a main element with the children. Includes ScrollRestoration and Scripts in the body.

```tsx
export function Layout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en" className="dark">
            <head>
                <meta charSet="utf-8" />
                <meta
                    name="viewport"
                    content="width=device-width, initial-scale=1"
                />
                <Meta />
                <Links />
            </head>
            <body>
                <main className="grow">{children}</main>
                <ScrollRestoration />
                <Scripts />
            </body>
        </html>
    )
}
```

--------------------------------

### handleRequest: Server-Side Request Handler in entry.server.tsx

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/entry.server.tsx.md

Default export of app/entry.server.tsx, used as the Worker-side SSR request handler. It renders the React Router server context to a readable stream, sets Content-Type to text/html, and waits for all content when the user agent is a bot or SPA mode is active. Streaming errors set the status to 500 and are logged only after the shell has rendered.

```tsx
import { isbot } from "isbot"
import { renderToReadableStream } from "react-dom/server"
import type { AppLoadContext, EntryContext } from "react-router"
import { ServerRouter } from "react-router"

export default async function handleRequest(
    request: Request,
    responseStatusCode: number,
    responseHeaders: Headers,
    routerContext: EntryContext,
    _loadContext: AppLoadContext,
) {
    let shellRendered = false
    const userAgent = request.headers.get("user-agent")

    const body = await renderToReadableStream(
        <ServerRouter context={routerContext} url={request.url} />,
        {
            onError(error: unknown) {
                responseStatusCode = 500
                // Log streaming rendering errors from inside the shell.  Don't log
                // errors encountered during initial shell rendering since they'll
                // reject and get logged in handleDocumentRequest.
                if (shellRendered) {
                    console.error(error)
                }
            },
        },
    )
    shellRendered = true

    // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
    if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
        await body.allReady
    }

    responseHeaders.set("Content-Type", "text/html")
    return new Response(body, {
        headers: responseHeaders,
        status: responseStatusCode,
    })
}
```

--------------------------------

### MyDurableObject class extending DurableObject

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Exported class that extends Cloudflare's DurableObject<Env>. It includes an optional transport property of type SSEHonoTransport and overrides the fetch method to handle requests.

```typescript
export class MyDurableObject extends DurableObject<Env> {
    transport?: SSEHonoTransport
    override async fetch(request: Request) { /* ... */ }
}
```

--------------------------------

### Default App component

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Exports the default App component that renders the React Router Outlet, which displays the matched child route.

```tsx
export default function App() {
    return <Outlet />
}
```

--------------------------------

### Home component default export

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/home-route.tsx.md

The default export of the Home route component. It receives loaderData of type Route.ComponentProps and renders the Welcome component with the message, userId, and initialMemories props.

```tsx
export default function Home({ loaderData }: Route.ComponentProps) {
    return (
        <Welcome
            message={loaderData.message}
            userId={loaderData.userId}
            initialMemories={loaderData.memories}
        />
    )
}
```

--------------------------------

### Cloudflare Worker fetch handler with Durable Object routing

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Default export for a Cloudflare Worker. Routes requests with 'sse' or '/messages' in the path to a Durable Object stub, using '?sessionId=' if provided, otherwise creating a new unique ID. All other requests go to the React Router request handler.

```TypeScript
export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext) {
        const url = new URL(request.url)
        if (
            url.pathname.includes("sse") ||
            url.pathname.endsWith("/messages")
        ) {
            const sessionId = url.searchParams.get("sessionId")
            const namespace = env.MY_DO
            let stub: DurableObjectStub<MyDurableObject>
            if (sessionId) {
                const id = namespace.idFromString(sessionId)
                stub = namespace.get(id) as DurableObjectStub<MyDurableObject>
            } else {
                const id = namespace.newUniqueId()
                stub = namespace.get(id) as DurableObjectStub<MyDurableObject>
            }
            return stub.fetch(request)
        }
        return requestHandler(request, {
            cloudflare: { env, ctx },
        })
    },
}
```

--------------------------------

### MyDurableObject class definition

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

Exported Durable Object class extending DurableObject<Env>. Declares an optional SSEHonoTransport and overrides the fetch method to serve MCP wire endpoints.

```ts
export class MyDurableObject extends DurableObject<Env> {
    transport?: SSEHonoTransport

    override async fetch(request: Request) {
        // ...
    }
}
```

--------------------------------

### Create cookie session storage with mcp_secret cookie

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/session-cookies.server.ts.md

Defines the session storage using createCookieSessionStorage from react-router. The cookie is named mcp_secret, signed, httpOnly, secure, and uses AUTH_SECRET as the signing key. The session data type includes userId and flash data includes error.

```ts
import { createCookieSessionStorage } from "react-router"

type SessionData = {
    userId: string
}

type SessionFlashData = {
    error: string
}

const { getSession, commitSession, destroySession } =
    createCookieSessionStorage<SessionData, SessionFlashData>({
        // a Cookie from `createCookie` or the CookieOptions to create one
        cookie: {
            name: "mcp_secret",

            isSigned: true,

            httpOnly: true,
            // Set to expire in year 9999 (effectively never)
            // expires: new Date("9999-12-31"),
            path: "/",
            sameSite: "lax",
            secrets: [process.env.AUTH_SECRET ?? ""],
            secure: true,
        },
    })

export { getSession, commitSession, destroySession }
```

--------------------------------

### POST /:userId/messages

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/workers-app.ts.md

The POST /:userId/messages endpoint delivers a message to the user's MCP session. It is part of the MyDurableObject's fetch method and is mounted on the Hono server with basePath "/:userId".

```APIDOC
## POST /:userId/messages

### Description
Delivers a message to the user's MCP session. This endpoint is part of the MCP wire protocol and is served by the MyDurableObject's fetch method.

### Method
POST

### Endpoint
/:userId/messages

### Parameters
#### Path Parameters
- **userId** (string) - Required - The user ID extracted from the first path segment.

### Request Body
- **message** (object) - Required - The MCP message to deliver.

### Response
#### Success Response (200)
- **body** (object) - The response from the transport.

### Error Handling
- If the userId is missing, the middleware returns HTTP 400 with body "User ID is required".
- If the transport is not initialized, the endpoint throws an error "Transport not initialized", which is caught by the onError handler and returned as HTTP 500 with the error message as the body.
```

--------------------------------

### SessionData and SessionFlashData type definitions

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/types.md

Defines the shape of session data and flash data used with createCookieSessionStorage. SessionData holds a userId string; SessionFlashData holds an error string for flash messages.

```TypeScript
type SessionData = {
    userId: string
}

type SessionFlashData = {
    error: string
}
```

--------------------------------

### ErrorBoundary component

Source: https://github.com/supermemoryai/supermemory-mcp/blob/master/_autodocs/api-reference/root.tsx.md

Exports the ErrorBoundary component that handles route errors. It displays a 404 message for not found routes, an error status text for other route errors, and in development shows the error message and stack trace for non-route errors.

```tsx
export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
    let message = "Oops!"
    let details = "An unexpected error occurred."
    let stack: string | undefined

    if (isRouteErrorResponse(error)) {
        message = error.status === 404 ? "404" : "Error"
        details =
            error.status === 404
                ? "The requested page could not be found."
                : error.statusText || details
    } else if (import.meta.env.DEV && error && error instanceof Error) {
        details = error.message
        stack = error.stack
    }

    return (
        <main className="pt-16 p-4 container mx-auto">
            <h1>{message}</h1>
            <p>{details}</p>
            {stack && (
                <pre className="w-full p-4 overflow-x-auto">
                    <code>{stack}</code>
                </pre>
            )}
        </main>
    )
}
```
Tokens:
Raw