supermemoryai/supermemory

Overview

Supermemory is a hosted memory API. You send it content and conversations, and you get back extracted memories, a per-user “profile” (stable facts plus recent context) and hybrid search over memories and documents. Readers should know one thing first: the memory engine is not in this repository. Extraction, contradiction handling, forgetting, embeddings, connectors and search all run behind api.supermemory.ai (/v3/documents, /v4/search, /v4/profile, /v4/conversations). The project’s own self-hosting docs say the downloadable local server “is built from a separate, non-public codebase” (overview.mdx).

So the open-source repo is the client side of that product. It contains the remote MCP server (a Cloudflare Worker with an embedded React widget), the @supermemory/tools middleware for the Vercel AI SDK, OpenAI SDK, Mastra and VoltAgent, Python integrations (OpenAI Agents, Pipecat, LiveKit, Cartesia, Agent Framework), a memory-graph visualisation component, a Raycast extension, an agent skill, the docs site, and a small Next.js app that is now mostly a redirect page to the console. Anything this review says about internals is limited to that client code. Claims about how memories are extracted or ranked cannot be checked from here.

Architecture

flowchart LR
  H["MCP host (Claude, ChatGPT, Cursor)"] --> W["MCP Worker: Hono /mcp"]
  W --> AUTH["validateApiKey / OAuth"]
  W --> SRV["createSupermemoryServer"]
  SRV --> T["Tools, prompts, widget resource"]
  SRV --> DO["SpaceState Durable Object"]
  T --> CL["SupermemoryClient (supermemory SDK)"]
  APP["Your app: AI SDK / OpenAI / Mastra"] --> MW["withSupermemory middleware"]
  MW --> API["Hosted API (closed source)"]
  CL --> API
  PY["Python integrations"] --> API

Component	Path	Role
MCP Worker entry	apps/mcp/src/server/index.ts	Hono app: OAuth metadata, bearer auth, /mcp handler, direct file-upload proxy
MCP server factory	apps/mcp/src/server/server.ts	Builds an McpServer per request and registers tools, resources, the widget and the context prompt
Tools	apps/mcp/src/server/tools/	search_memory, get_profile, add_memory, save-memory, guided-save, list/get documents and memories, spaces, graph, uploads
API client	apps/mcp/src/server/client/index.ts	Wraps the supermemory SDK; container-tag defaulting, forget, search, profile
Space state	apps/mcp/src/server/space-state.ts	Durable Object holding the active space per actor and one-shot upload sessions
RBAC	apps/mcp/src/server/auth/rbac.ts	Read/write permission per container tag from the session
Widget	apps/mcp/src/widget/	React app served as an MCP UI resource (memory browser, graph, save flows)
Framework middleware	packages/tools/src/	withSupermemory for AI SDK, OpenAI, Mastra, VoltAgent; Claude memory-tool adapter
Python integrations	packages/*-python/	Same idea for Python agent frameworks
Graph UI	packages/memory-graph/	Canvas visualisation of documents, memories and version links

How a request flows

Two paths matter: an MCP host calling a tool, and an app using the middleware.

MCP search_memory:

1. Authenticate. handleMcpRequest reads the bearer token and resolves it as an API key or OAuth token against the API. It returns 503 with Retry-After on a transient auth-backend failure and 401 otherwise (index.ts).
2. Build the server. createSupermemoryServer makes a fresh McpServer for this actor. It looks up the actor’s SpaceState Durable Object, and container-tag resolution falls back to sm_project_default (server.ts).
3. Call the API. The tool calls SupermemoryClient.search, which forwards q, limit, threshold and the tag to client.search.memories with searchMode: "hybrid". Ranking happens entirely on the server (client/index.ts).

AI SDK withSupermemory(model, { containerTag, customId }):

1. Before the model call. transformParamsWithMemory takes the last user message and calls buildMemoriesText. The result is cached per turn and injected into the system prompt (middleware.ts). In the default profile mode no query text is sent. query and full modes send the last user message (memory-client.ts).
2. Fetch context. supermemoryProfileSearch POSTs to /v4/profile with include: ["static", "dynamic"] and an optional q (memory-client.ts).
3. After the response. With addMemory: "always" (the default), saveMemoryAfterResponse sends the whole turn to /v4/conversations under customId. The server extracts memories from it (middleware.ts, vercel/index.ts).

Key components

MCP server

There are sixteen tools, registered in one place (tools/index.ts). Writes go through client.add and come back as queued, which shows that ingestion is asynchronous on the server. forgetMemory first tries an exact-content forget. On a 404 it searches with a 0.85 similarity threshold and forgets the closest memory hit, never a chunk (client/index.ts). The context prompt builds a compact block: the active space, up to 8 stable and 8 recent profile facts, and recently active spaces (context.ts).

Spaces and access

A “space” is a container tag. SpaceState stores the actor’s active tag and handles short-lived upload sessions. It stores only a hash of each upload token, deletes the session on first use, and expires it with an alarm (space-state.ts). effectiveContainerTagAccess gives write by default, falls back to per-tag membership for restricted sessions, and downgrades to read for read-scoped or out-of-scope tags (rbac.ts). Enforcement still happens at the API. This code only decides what the widget offers.

Memory model (as seen by clients)

The shared types show what the API returns. Memories carry version, isLatest, parent and root ids, isForgotten, isStatic and isInference, and documents can have forgetAfter. So versioning, temporal forgetting and inferred memories exist server-side. The client neither implements nor configures them.

Extending it

• Your own app. Use the supermemory SDK directly, or wrap a model with withSupermemory (mode: profile | query | full, addMemory: always | never, custom prompt template).
• Agents with tools. supermemoryTools and the OpenAI function-calling tools expose search and add as model-callable tools. A Claude memory-tool adapter maps Anthropic’s memory tool onto Supermemory documents.
• MCP. Add a file in apps/mcp/src/server/tools/ and register it in registerAllTools. The widget resource and structured-content output schemas are in resources/ and tools/output-schemas.ts.

Running it

• Hosted. Get an API key from the console and point any SDK or the MCP URL at the hosted service. Connectors (Drive, Notion, Gmail, OneDrive) and MCP are hosted features.
• MCP Worker yourself. bun run build then wrangler deploy in apps/mcp. The only bindings are the two Durable Objects and API_URL (wrangler.jsonc). It still needs a Supermemory API behind it.
• Local engine. npx supermemory local downloads a closed-source single binary that serves the same API on port 6767 with an embedded graph store, local bge-base-en-v1.5 embeddings and your own LLM key. It is free within a “lite” licence. The docs list connectors and the Supermemory MCP as platform-only.

Strengths and caveats

• Strength: easy adoption. One middleware wrap or one MCP URL gives an app per-user profile context plus automatic conversation capture. The profile endpoint avoids writing retrieval prompts yourself.
• Strength: polished MCP surface. OAuth discovery, a UI widget, space selection, RBAC-aware writes and direct file uploads through single-use tokens are more complete than most memory MCPs.
• Caveat: the core is not open. Extraction, conflict handling, decay and ranking cannot be inspected or changed. The “open-source memory engine” framing does not match this repository.
• Caveat: vendor dependency. Every path ends at the Supermemory API, either hosted or the closed local binary, so data residency and pricing are the vendor’s terms.
• Caveat: limited tuning. Client-side knobs are the container tag, the mode, a similarity threshold and the prompt template. Anything deeper needs the API’s own settings.

Sources: code at ac21804, deepwiki-open wiki (12 pages), OpenDeepWiki wiki (38 pages), verified Q&A.