Supermemory MCP Documentation

The Supermemory MCP is implemented as a Cloudflare Worker application that utilizes Durable Objects to manage user-specific sessions.

Core Components:

• Main Worker Entrypoint: Handles standard HTTP requests and routes them to a react-router request handler or a Durable Object stub.
• MyDurableObject: A Durable Object that manages individual user sessions. It hosts a Hono server that provides:
  • SSE (Server-Sent Events): An endpoint (/sse) that uses streamSSE and SSEHonoTransport to establish a connection for the Model Context Protocol (MCP).
  • MCP Bridge: Uses the bridge function from muppet to connect the Supermemory MCP logic to the transport layer.
  • Message Handling: An endpoint (/messages) to handle incoming messages via the transport.
• Supermemory Integration: The MCP logic is encapsulated in a createSuperMemory function which initializes a Supermemory client using an apiKey from the environment variables.

To connect an LLM to the Supermemory MCP, you must establish a connection through the Durable Object's SSE endpoint. The connection follows this pattern:

1. Identify/Create Session: The main worker uses a sessionId from the URL search parameters to retrieve an existing Durable Object or creates a new one using namespace.newUniqueId().
2. Establish SSE Connection: Connect to the /sse endpoint of the Durable Object. This endpoint uses SSEHonoTransport and bridge to facilitate the MCP communication.
3. Message Exchange: Subsequent messages are handled via the /messages endpoint using the established transport.

Example Workflow (Conceptual):

// The Durable Object setup inside the worker:
server.get("/sse", async (c) => {
    const userId = c.get("userId")
    return streamSSE(c, async (stream) => {
        this.transport?.connectWithStream(stream)
        await bridge({
            mcp: muppet(createSuperMemory(userId, c.env), {
                name: "Supermemory MCP",
                version: "1.0.0",
            }),
            transport: c.env.transport,
        })
    })
})

The react-router.config.ts file defines the core configuration for the React Router application, including Server-Side Rendering (SSR) capabilities and experimental Vite-related features.

Key configuration options:

• ssr: A boolean that enables or disables Server-Side Rendering. Set to true to enable SSR.
• future: An object used to opt-in to upcoming, potentially breaking features (unstable flags).
  • unstable_viteEnvironmentApi: Enables the new Vite environment API.
  • unstable_optimizeDeps: Enables optimization of dependencies.
  • unstable_splitRouteModules: Enables splitting route modules for better performance.

import type { Config } from "@react-router/dev/config"

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

The Supermemory MCP exposes specific tools via Hono endpoints to allow LLMs to interact with user memory. These tools are defined using muppet's describeTool and mValidator.

Available Tools:

addToSupermemory

Purpose: Store user information, preferences, and behaviors. It should be used when detecting significant user traits or upon explicit commands like 'remember this'.

• Endpoint: POST /add
• Input Schema: A JSON object containing thingToRemember (string).
• Constraints: Rejects requests if the user already has more than 2000 memories.

searchSupermemory

Purpose: Search user memories and patterns using semantic matching. Use this when the LLM needs context about user's past choices or lacks prior knowledge.

• Endpoint: POST /search
• Input Schema: A JSON object containing informationToGet (string).

Prompt Configuration

There is also a specialized prompt endpoint:

• Endpoint: POST /supermemory-prompt
• Purpose: Provides a system instruction to the LLM, mandating proactive use of Supermemory tools to build a user profile and search for context before answering.