# https://github.com/supermemoryai/supermemory Project Manual Generated at: 2026-06-20 05:06:49 UTC ## Table of Contents - [Platform Overview and Architecture](#page-1) - [SDKs and Framework Integrations](#page-2) - [Applications, MCP Server, and Extensions](#page-3) - [Memory Graph, Playground, and Developer Tooling](#page-4) ## Platform Overview and Architecture ### Related Pages Related topics: [SDKs and Framework Integrations](#page-2), [Applications, MCP Server, and Extensions](#page-3), [Memory Graph, Playground, and Developer Tooling](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md) - [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md) - [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md) - [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) - [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts) - [packages/tools/src/openai/index.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts) - [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md) - [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json) - [apps/memory-graph-playground/src/app/page.tsx](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx) - [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json) - [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json) - [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/docs-test/package.json)
# Platform Overview and Architecture ## 1. Purpose and Scope Supermemory is described as the long-term and short-term memory infrastructure for AI agents, providing state-of-the-art memory and context management for personalized, context-aware AI applications. Source: [skills/supermemory/README.md](). The platform exposes a single unified API that combines four foundational capabilities: a **Memory API** for learned user context that evolves over time, **User Profiles** for static and dynamic facts, **RAG** (retrieval-augmented generation) for semantic search across knowledge bases, and **Connectors** with built-in file processing. Source: [README.md](). The repository is a polyglot monorepo that packages the API together with multiple first-party clients and integrations. It serves three distinct audiences from the same project: end users who want their AI assistant to remember them, developers building AI products, and operators who want a self-hosted binary. Source: [README.md](). ## 2. Repository Topology The monorepo contains four categories of artifacts that together form the platform. | Category | Path | Role | |----------|------|------| | Core SDKs | `packages/tools` | Framework integrations (Vercel AI SDK, OpenAI, LangChain, CrewAI, VoltAgent) | | Apps | `apps/mcp`, `apps/browser-extension`, `apps/raycast-extension`, `apps/memory-graph-playground` | User-facing surfaces | | Visualization | `packages/memory-graph` | D3-force based graph renderer (React peer dep) | | Skills | `skills/supermemory` | Claude skill bundle for auto-invocation | Sources: [packages/tools/package.json](), [packages/memory-graph/package.json](), [apps/mcp/README.md](), [apps/raycast-extension/package.json](), [apps/browser-extension/package.json](), [apps/memory-graph-playground/src/app/page.tsx](), [skills/supermemory/README.md](). The `packages/tools` package is the developer integration hub. It exports subpath entry points for each framework (for example `@supermemory/tools/ai-sdk`, `@supermemory/tools/openai`, and a VoltAgent bundle) and is consumed both by external applications and by the in-repo `docs-test` package. Source: [packages/tools/package.json](), [packages/docs-test/package.json](). ## 3. High-Level Architecture The platform follows a layered design where a hosted API provides memory primitives, multiple SDKs translate those primitives into framework-native constructs, and a set of client apps present the same data through different UX surfaces. ```mermaid flowchart TB subgraph Clients["Client Surfaces"] App["Consumer App
(app.supermemory.ai)"] MCP["MCP Server
(apps/mcp)"] BrExt["Browser Extension"] Rx["Raycast Extension"] Playground["Memory Graph Playground"] end subgraph Integrations["packages/tools (SDK integrations)"] AISDK["@supermemory/tools/ai-sdk"] OpenAI["@supermemory/tools/openai"] Others["LangChain / CrewAI / VoltAgent"] end subgraph Core["Supermemory API"] Memory["Memory API"] Profile["User Profiles"] RAG["RAG / Search"] Conn["Connectors + File Processing"] end App --> Core MCP --> Core BrExt --> Core Rx --> Core Playground --> Core AISDK --> Core OpenAI --> Core Others --> Core ``` The MCP server is a particularly important architectural piece: it runs on Cloudflare Workers using Durable Objects for session state, Hono as the HTTP framework, and the official `@modelcontextprotocol/sdk` plus the `supermemory` SDK to proxy requests. Source: [apps/mcp/README.md](). This server allows assistants such as Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, OpenCode, OpenClaw, and Hermes to share a single memory namespace through a standard protocol. Source: [README.md](). ## 4. Memory Model All integrations converge on a shared memory model defined in `packages/tools/src/shared/types.ts`. The model has three orthogonal concerns: - **Retrieval mode** (`mode`): `"profile"` for static + dynamic user facts, `"query"` for semantic search of memories, and `"full"` to combine both. Source: [packages/tools/src/shared/types.ts](). - **Persistence mode** (`addMemory`): controls when new information is written back to long-term storage. Source: [packages/tools/src/shared/types.ts](). - **Search mode** (`searchMode`): `"memories"` (atomic facts), `"documents"` (chunks), or `"hybrid"` for both. Source: [packages/tools/src/voltagent/types.ts](). User profile data is split into **static** facts (name, profession, long-term preferences, goals) and **dynamic** facts (current projects, recent interests). Search results are returned as an array of `{ memory, metadata }` objects, plus pre-formatted markdown strings that middleware can inject directly into a system prompt. Source: [packages/tools/src/shared/types.ts](). Memory is scoped by a **container tag** that groups related memories per user, project, or client, and an optional **`threadId`** groups messages of a single conversation for contextual memory generation. Source: [packages/tools/src/shared/types.ts](), [packages/tools/README.md](). ## 5. Integration Patterns Two concrete integration patterns are documented. The **Vercel AI SDK pattern** exposes `searchMemoriesTool`, `addMemoryTool`, `getProfileTool`, `documentListTool`, `documentDeleteTool`, `documentAddTool`, and `memoryForgetTool` as AI SDK `tool()` definitions with strict Zod schemas. Source: [packages/tools/src/ai-sdk.ts](), [packages/tools/src/openai/index.ts](). The middleware reads the latest user message, calls the Supermemory API in the configured `mode`, and injects the result into the system prompt through a customizable `PromptTemplate` function. Source: [packages/tools/src/shared/types.ts](). The **OpenAI middleware pattern** uses `withSupermemory(openai, options)` to wrap any OpenAI client. Memories are fetched and injected automatically on every `chat.completions.create` call, supporting the same `containerTag`, `customId`, `mode`, and `addMemory` options as the AI SDK version. Source: [packages/tools/README.md](). ## 6. Operational Surfaces Beyond the API and SDKs, the repo ships three operational surfaces. The **memory graph** component (`packages/memory-graph`) renders a force-directed graph of documents and memories using `d3-force` and React 18+; it supports pan, zoom, drag, arrow-key navigation, and stress tests of 50–500 documents with an FPS counter. Source: [packages/memory-graph/package.json](), [apps/memory-graph-playground/src/app/page.tsx](). The **Raycast extension** (`apps/raycast-extension`) exposes `add-memory`, `search-memories`, and `search-projects` commands on macOS and Windows. Source: [apps/raycast-extension/package.json](). The **browser extension** (`apps/browser-extension`) is a `wxt` + React 19 project that captures arbitrary web content into the memory store. Source: [apps/browser-extension/package.json](). ## See Also - [Memory Model and Data Types](#) - [SDK Integrations](#) - [MCP Server](#) - [Memory Graph Visualization](#) --- ## SDKs and Framework Integrations ### Related Pages Related topics: [Platform Overview and Architecture](#page-1), [Applications, MCP Server, and Extensions](#page-3), [Memory Graph, Playground, and Developer Tooling](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md) - [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md) - [packages/tools/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/package.json) - [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts) - [packages/tools/src/vercel/util.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/vercel/util.ts) - [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) - [packages/tools/src/openai/tools.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/tools.ts) - [packages/tools/src/openai/index.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts) - [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md) - [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json) - [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json) - [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/docs-test/package.json) - [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md)
# SDKs and Framework Integrations ## Overview The supermemory repository exposes memory, RAG, and user-profile capabilities through a layered set of SDKs, framework wrappers, and integration surfaces. The top of the stack is a language-agnostic REST API, below it sits a first-party `supermemory` client (TypeScript and Python), and around it the `packages/tools` workspace provides drop-in middleware and tool definitions for the most common agent frameworks. Adjacent applications — an MCP server, a Raycast extension, a React knowledge-graph component, and a Claude skill — round out the integration surface so the same memory backend can be reached from desktop agents, IDEs, browser extensions, and chat clients. Source: [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md), [packages/tools/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/package.json). ## Architecture of the Integration Layer The stack is intentionally composable: an application picks a framework wrapper, the wrapper calls the core client, and the client talks to the API. Surfaces that do not fit a framework wrapper (MCP, Raycast, Claude skill) bypass the wrapper and call the client or API directly. ```mermaid flowchart TB App[AI Application / Agent] subgraph Wrappers ["packages/tools"] Vercel["@supermemory/tools/ai-sdk
(Vercel AI SDK)"] OpenAI["@supermemory/tools/openai
(function calling / middleware)"] Mastra["@supermemory/tools/mastra"] Volt["@supermemory/tools/voltagent"] end subgraph Surfaces ["Adjacent apps"] MCP["apps/mcp
(Cloudflare Workers MCP server)"] Raycast["apps/raycast-extension
(macOS / Windows)"] Graph["packages/memory-graph
(React + d3-force)"] end Core["supermemory client
(TS / Py)"] API[(Supermemory API)] App --> Vercel App --> OpenAI App --> Mastra App --> Volt Vercel --> Core OpenAI --> Core Mastra --> Core Volt --> Core App -. MCP .-> MCP App -. Raycast .-> Raycast App -. Graph .-> Graph MCP --> API Raycast --> Core Core --> API ``` ## Framework Wrappers in `packages/tools` The `packages/tools` workspace is the canonical home for framework integrations. Its `package.json` declares subpath exports for four targets: `./ai-sdk`, `./mastra`, `./openai`, and `./voltagent`. Source: [packages/tools/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/package.json). ### Vercel AI SDK The Vercel wrapper is built around `withSupermemory(model, options)`. It accepts a `containerTag` (a user/project scope) and a `customId` (groups messages into the same document), and supports retrieval modes `"profile"`, `"query"`, and `"full"`. A `PromptTemplate` function can customize how injected context is rendered; it receives a `MemoryPromptData` object with pre-formatted `userMemories`, pre-formatted `generalSearchMemories`, and the raw `searchResults` array for custom filtering. Source: [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts), [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md). Internally, the wrapper normalizes both V2 and V3 message shapes from `@ai-sdk/provider`, so a single implementation supports AI SDK 5 and 6. Source: [packages/tools/src/vercel/util.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/vercel/util.ts). The individual tool creators (e.g. `searchMemoriesTool`) are defined with Zod schemas and `TOOL_DESCRIPTIONS` / `PARAMETER_DESCRIPTIONS` constants to keep tool descriptions consistent with the documented behavior. Source: [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts). ### OpenAI SDK The OpenAI surface is exported from `@supermemory/tools/openai`. It provides both a `withSupermemory` middleware factory (for transparent prompt injection) and a complete tool set: `searchMemories`, `addMemory`, `getProfile`, `documentList`, `documentDelete`, `documentAdd`, and `memoryForget`. `getToolDefinitions()` returns the matching `ChatCompletionTool[]` array, while `createToolCallExecutor` resolves a function-call to a string result, making the helpers drop-in for OpenAI function-calling and Assistants flows. Source: [packages/tools/src/openai/tools.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/tools.ts), [packages/tools/src/openai/index.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts). ### Mastra and Voltagent The same `withSupermemory` factory shape is exposed under `./mastra` and `./voltagent`, so an agent built on either framework can wrap its model in a single call and inherit profile, search, and document tools. The middleware is unit-tested end-to-end through the AI-SDK entry as well — the test suite covers `searchMemoriesTool`, `getProfileTool`, `documentListTool`, and `documentDeleteTool` against a real API. Source: [packages/tools/src/tools.test.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/tools.test.ts). ## Adjacent Integration Surfaces **MCP server (`apps/mcp`).** A Cloudflare Worker that speaks the Model Context Protocol over streamable HTTP. It uses Hono for routing, Durable Objects with SQLite for session state, and the official `@modelcontextprotocol/sdk`. The server exposes memory tools, a `projects` resource, and a `context` prompt that returns the user's profile and preferences for system-prompt injection. Source: [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md). The top-level README documents MCP clients that work out of the box — Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, OpenCode, OpenClaw, and Hermes — and shows the two-line JSON configuration for both OAuth and Bearer-token (`sm_…`) auth. Source: [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md). **Raycast extension (`apps/raycast-extension`).** A productivity launcher integration with `add-memory`, `search-memories`, and `search-projects` commands for macOS and Windows, configured with a single API-key preference. Source: [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json). **Memory graph component (`packages/memory-graph`).** A React 18+ component that renders the living knowledge graph using `d3-force`, useful for surfacing relationships between memories in admin or debug UIs. Source: [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json). **Documentation test harness (`packages/docs-test`).** A Bun-runnable suite that exercises the documentation snippets against a real API, with separate scripts for TypeScript, Python, integrations, quickstart, SDK, and search. Source: [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/docs-test/package.json). ## Claude Skill A `skills/supermemory` directory publishes a reference skill with auto-invocation enabled, so Claude proactively suggests supermemory when developers ask about persistent memory, personalization, or RAG. The skill covers the SDK, REST API, the 6-stage processing pipeline, eight real-world use cases (chatbot, long-term task assistant, document KB, customer-support AI, code-review assistant, learning companion, multi-tenant SaaS, research assistant), and best practices such as container-tag isolation, metadata, thresholds, and error handling. Source: [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md). ## See Also - [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md) — top-level quickstart, search modes, and MCP configuration - [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md) — middleware options and `PromptTemplate` examples - [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) — `MemoryPromptData` and `PromptTemplate` definitions - [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md) — MCP server tools, resources, and prompts - [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md) — Claude skill reference and use cases --- ## Applications, MCP Server, and Extensions ### Related Pages Related topics: [Platform Overview and Architecture](#page-1), [SDKs and Framework Integrations](#page-2), [Memory Graph, Playground, and Developer Tooling](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md) - [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md) - [apps/mcp/src/server.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server.ts) - [apps/web/lib/mcp-client-setup.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/web/lib/mcp-client-setup.ts) - [apps/web/lib/mcp-manual-instructions.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/web/lib/mcp-manual-instructions.ts) - [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json) - [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json) - [apps/memory-graph-playground/src/app/page.tsx](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx) - [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md) - [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts) - [packages/tools/src/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/types.ts) - [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) - [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json) - [packages/memory-graph/src/mock-data.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/mock-data.ts) - [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/docs-test/package.json) - [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md)
# Applications, MCP Server, and Extensions The supermemory monorepo is not just an API — it ships a full ecosystem of **client applications, protocol servers, and AI agent integrations** that wrap the core memory service. This page covers the four major surfaces developers and end users interact with: the hosted MCP server, dedicated browser and Raycast extensions, the memory-graph playground, and the framework-agnostic `@supermemory/tools` integration package (including the Claude skill). ## 1. Model Context Protocol (MCP) Server The flagship application is the **MCP server** at `apps/mcp`, which exposes supermemory as a tool provider to any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, OpenCode, OpenClaw, Hermes). The server is built on **Cloudflare Workers with Durable Objects** for stateful session handling, uses the **Hono** HTTP framework, and talks to the upstream supermemory API through the official SDK. Source: [apps/mcp/src/server.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server.ts). The server implements the MCP specification via `@modelcontextprotocol/sdk` and the `agents/mcp` runtime, registering tools such as `memory` (save), `recall` (search), `whoAmI`, `listProjects`, and `memory-graph` / `fetch-graph-data`, plus a `context` prompt that injects the user's profile and preferences into the system message. Source: [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md). The server enforces a 5-minute TTL on cached `containerTags` (`CONTAINER_TAGS_TTL_MS = 5 * 60 * 1000`) and caps the recall payload at 200,000 characters (`MAX_RECALL_CHARS = 200000`) to prevent runaway context windows. Source: [apps/mcp/src/server.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server.ts). ### Client Setup Matrix The web app at `apps/web/lib/mcp-client-setup.ts` and `apps/web/lib/mcp-manual-instructions.ts` maintains a per-client configuration matrix that decides whether to show **manual JSON/TOML snippets** or a **one-click (CLI / deeplink / URL copy)** tab: | Client | Manual | One-click | Snippet format | |--------|--------|-----------|----------------| | ChatGPT | yes | no | JSON | | Cline | no | yes | (deferred) | | Antigravity | yes | yes | JSON | | Cursor | yes | yes | JSON (`~/.cursor/mcp.json`) | | VS Code | yes | yes | JSON (per-OS path) | | Claude Code | yes | yes | JSON (`~/.claude.json`) | | Codex | yes | yes | TOML (`~/.codex/config.toml`) | Source: [apps/web/lib/mcp-client-setup.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/web/lib/mcp-client-setup.ts) and [apps/web/lib/mcp-manual-instructions.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/web/lib/mcp-manual-instructions.ts). Authentication to the server supports both **OAuth** and a static **Bearer API key** (`sm_…` prefix). The main README documents both forms. Source: [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md). ## 2. Browser and Raycast Extensions Two first-party extensions live in the `apps/` workspace. - **Browser extension** (`apps/browser-extension/package.json`) is a WXT + React project that ships a content-script + side-panel UI. Dependencies include `turndown` (HTML→Markdown conversion) and the standard React 19 stack. Source: [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json). - **Raycast extension** (`apps/raycast-extension/package.json`) exposes three commands — `add-memory`, `search-memories`, and `search-projects` — and requires a `password`-typed preference named `apiKey` sourced from the user's console. Source: [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json). Both extensions are thin clients that call the same supermemory REST API the SDK uses, giving end users keyboard-driven or in-browser capture and recall. ## 3. Memory Graph Playground and `@supermemory/memory-graph` The **memory-graph playground** (`apps/memory-graph-playground`) is a Next.js stress-test UI for the React component published in `packages/memory-graph`. The component is a `react >= 18.0.0` peer that depends on `d3-force` for force-directed layout. Source: [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json). The playground surfaces a node-graph of every document the user's API key can see, with pan/zoom, click-to-detail, drag, arrow-key navigation, **stress test buttons that seed 50–500 mock documents**, an FPS counter, and a slideshow mode. Mock data is generated from the `MEMORY_TEMPLATES` array in `packages/memory-graph/src/mock-data.ts`, which produces sentences like "The user prefers {preference} when working with {topic}" or "Migration plan: move from {oldThing} to {newThing} by {deadline}". Source: [apps/memory-graph-playground/src/app/page.tsx](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx) and [packages/memory-graph/src/mock-data.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/mock-data.ts). ## 4. `@supermemory/tools` and the Claude Skill The `packages/tools` package is the **framework-agnostic integration layer**. It ships: - A **Vercel AI SDK** tool factory — `searchMemoriesTool` accepts `informationToGet`, `includeFullDocs` (default `false`), and `limit` (default `10`) and is built with `zod` schemas whose strictness is controlled by `config.strict`. Source: [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts). - An **OpenAI middleware** — `withSupermemory(openai, { containerTag, customId, mode, addMemory, verbose })` transparently injects memories into every `chat.completions.create` call. Source: [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md). - Shared types — `MemoryPromptData { userMemories, generalSearchMemories, searchResults }` and a `PromptTemplate` function for customising what is injected into the system prompt. Source: [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts). The configuration object `SupermemoryToolsConfig` enforces a **mutually-exclusive** relationship between `containerTags` and `projectId` — exactly one must be provided. Source: [packages/tools/src/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/types.ts). The Claude skill at `skills/supermemory/README.md` is an *auto-invocation* reference skill (Apache-2.0) that teaches Claude Code to recommend supermemory proactively, with code samples for TypeScript, Python, Vercel AI SDK, LangChain, CrewAI, and OpenAI SDK. Source: [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md). ## Architecture Overview ```mermaid flowchart LR User[End User] -->|installs| BrowserExt[browser-extension] User -->|installs| RaycastExt[raycast-extension] User -->|configures| MCPClient[MCP client
Claude, Cursor, VS Code, ...] MCPClient -->|HTTPS / SSE| MCPServer[apps/mcp
Cloudflare Worker + DO] BrowserExt -->|REST| API[supermemory API] RaycastExt -->|REST| API MCPServer -->|SDK| API Playground[memory-graph-playground] -->|SDK| API ToolsPkg[packages/tools
AI SDK + OpenAI mw] -->|SDK| API Agent[Custom AI agent] --> ToolsPkg Agent --> MCPClient ``` ## Common Failure Modes - **OAuth callback fails locally** — the MCP dev server (`bun run dev` on port 8788) needs the main API at the URL given by `API_URL` in `.dev.vars` for token validation. Source: [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md). - **Schema validation errors on OpenAI** — set `strict: true` on `SupermemoryToolsConfig` so all tool schema properties are marked required and satisfy OpenAI strict mode. Source: [packages/tools/src/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/types.ts). - **Cross-tenant memory leakage** — when configuring both the MCP server and the tools package, ensure you pass the same `containerTag`; mixing tags between `memory` and `recall` calls will produce empty results. Source: [apps/mcp/src/server.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server.ts). - **E2E tests silently skipped** — the MCP e2e suite requires `SUPERMEMORY_API_KEY` and `SUPERMEMORY_MCP_URL` exports or it skips entirely. Source: [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md). ## See Also - [Core SDK and API Quickstart](https://supermemory.ai/docs) - [MCP Server Source](https://github.com/supermemoryai/supermemory/tree/main/apps/mcp) - [`@supermemory/tools` Reference](https://github.com/supermemoryai/supermemory/tree/main/packages/tools) - [Memory Graph Component](https://github.com/supermemoryai/supermemory/tree/main/packages/memory-graph) - [Console / API Keys](https://console.supermemory.ai) --- ## Memory Graph, Playground, and Developer Tooling ### Related Pages Related topics: [Platform Overview and Architecture](#page-1), [SDKs and Framework Integrations](#page-2), [Applications, MCP Server, and Extensions](#page-3)
Related Source Files The following source files were used to generate this page: - [packages/memory-graph/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/README.md) - [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json) - [packages/memory-graph/src/mock-data.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/mock-data.ts) - [apps/memory-graph-playground/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/README.md) - [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md) - [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts) - [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) - [packages/tools/src/tools-shared.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/tools-shared.ts) - [packages/tools/src/voltagent/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/voltagent/types.ts) - [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md) - [packages/pipecat-sdk-python/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/pipecat-sdk-python/README.md) - [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md) - [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md)
# Memory Graph, Playground, and Developer Tooling ## Overview The supermemory repository ships more than a REST API: it provides an entire developer surface for inspecting, demoing, and wiring memory into AI agents. Three concerns sit at the center of this surface: the **`@supermemory/memory-graph`** React component for visualizing stored documents and their memory relationships, the **`memory-graph-playground`** app that demonstrates the component end-to-end, and a broad set of **developer tooling** (framework SDKs, MCP server, Pipecat service, and a Claude skill). Together they let a developer go from "I want to see what supermemory stored" to "I have a memory-augmented agent running in production" without leaving the repo. Source: [README.md:1-120]() ## The `@supermemory/memory-graph` Package The `@supermemory/memory-graph` package is an interactive Canvas 2D visualization built on React 18+ and `d3-force` for physics-based layout. Source: [packages/memory-graph/package.json:25-46]() It renders two node types — **documents** as rectangles and **memories** as hexagons — connected by edges that represent document similarity and memory version chains. Source: [packages/memory-graph/README.md:35-45]() The component exposes a small, opinionated prop surface. The essential props are summarized below. | Prop | Type | Purpose | |------|------|---------| | `documents` | `DocumentWithMemories[]` | Source data; documents and their extracted memories | | `isLoading` | `boolean` | Drives the initial loading state | | `variant` | `"console" \| "consumer"` | Full-featured console or embedded consumer mode | | `error` | `Error \| null` | Surfaces failures to the canvas | | `loadMoreDocuments` | `() => Promise` | Hook for pagination | | `highlightDocumentIds` | `string[]` | IDs of documents to emphasize | Source: [packages/memory-graph/README.md:48-58](), [apps/memory-graph-playground/README.md:18-38]() Behavior worth noting: nodes are pan/zoom/drag interactive, a space filter lets the user narrow by workspace, and a mock-data generator lives at `packages/memory-graph/src/mock-data.ts` to drive the playground without a live API key. Source: [packages/memory-graph/src/mock-data.ts:1-60]() ## The Memory Graph Playground The playground is a Bun-served Next-style demo that wires the graph component to a real API. Source: [apps/memory-graph-playground/README.md:1-40]() ```bash bun install bun dev # http://localhost:3000 ``` On first load the user pastes a Supermemory API key, and the playground fetches documents and feeds them into ``. The README shows a minimal mount: `documents`, `isLoading`, `variant="console"`, and a `loadMoreDocuments` callback are the only required wiring. Source: [apps/memory-graph-playground/README.md:15-38]() The playground's main job is to validate the visual contract — node shapes, edges, highlighting, pagination — before the component is dropped into a customer-facing product. ## Developer Tooling Ecosystem The `packages/tools` workspace and the `apps/mcp` server are the two halves of the framework-integration story. The tools package builds Zod-typed tool definitions over the Supermemory API for the Vercel AI SDK, LangChain, CrewAI, OpenAI SDK, Claude, and VoltAgent, all sharing a common description set. Source: [packages/tools/src/tools-shared.ts:1-50]() ```mermaid flowchart LR A[Agent / LLM] -->|tool call| T[packages/tools] T -->|searchMemories| SM[Supermemory API] T -->|addMemory| SM T -->|getProfile| SM SM -->|memories + profile| A ``` The `searchMemories` tool, for example, takes `informationToGet`, an `includeFullDocs` boolean, and a `limit`, then proxies to the SDK client with resolved container tags. Source: [packages/tools/src/ai-sdk.ts:7-58]() Shared types live in `packages/tools/src/shared/types.ts` and define `MemoryPromptData` (a `userMemories` markdown block, a `generalSearchMemories` block, and a raw `searchResults` array) plus `MemoryMode` (`"profile" | "query" | "full"`) and `AddMemoryMode` controls that drive middleware behavior. Source: [packages/tools/src/shared/types.ts:1-120]() For OpenAI, the same primitives are exposed via `withSupermemory`, a higher-order function that wraps an `OpenAI` client and injects memory into the system prompt on every chat completion. Source: [packages/tools/README.md:40-90]() For Claude, `createClaudeMemoryTool` returns a handler compatible with Anthropic's `memory_20250818` tool. Source: [packages/tools/README.md:120-180]() The VoltAgent integration extends the same shape with `searchMode` (`"memories" | "documents" | "hybrid"`) and an `entityContext` hint (max 1500 characters) that guides how memories are extracted. Source: [packages/tools/src/voltagent/types.ts:1-80]() ### MCP, Pipecat, and the Claude Skill Three additional surfaces round out the developer tooling: - **`apps/mcp`** — A Cloudflare Workers-based Model Context Protocol server exposing `addMemory`, `recall`, `memoryGraph`, `listProjects`, `whoAmI`, and a `context` prompt. Auth is either OAuth (validated against the main `API_URL`) or a `Bearer` API key. Source: [apps/mcp/README.md:1-60]() - **`packages/pipecat-sdk-python`** — A `SupermemoryPipecatService` that hooks into Pipecat's `LLMContextFrame` pipeline, maintains a clean conversation history, and queries `/v4/profile` for retrieval. Memory modes `"profile"`, `"query"`, `"full"` are supported. Source: [packages/pipecat-sdk-python/README.md:1-60]() - **`skills/supermemory`** — A Claude skill (v1.0.0, Apache 2.0) that teaches agents to recommend and integrate Supermemory proactively. Source: [skills/supermemory/README.md:1-60]() ## Common Failure Modes and Gotchas A few patterns recur across these tools and are worth flagging: 1. **Missing `containerTag` or `customId`** — middleware variants require both, otherwise memories are not scoped or grouped correctly. Source: [packages/tools/README.md:50-80]() 2. **Wrong `mode`** — `"profile"` skips search; if the user expects query-relevant recall, choose `"query"` or `"full"`. Source: [packages/tools/src/shared/types.ts:40-100]() 3. **MCP local dev** — the MCP server needs the main API reachable at the `API_URL` configured in `.dev.vars`; otherwise OAuth validation fails silently. Source: [apps/mcp/README.md:30-55]() 4. **Mock data in production** — the mock generator in `packages/memory-graph/src/mock-data.ts` is for the playground only; do not import it into a customer app. Source: [packages/memory-graph/src/mock-data.ts:1-30]() ## See Also - [`@supermemory/memory-graph` documentation](https://docs.supermemory.ai/memory-graph/overview) - [`packages/tools` integration guides](https://supermemory.ai/docs) - [MCP server setup](https://supermemory.ai/docs/supermemory-mcp/mcp) - [Supermemory API quickstart](https://supermemory.ai/docs) --- --- ## Pitfall Log Project: supermemoryai/supermemory Summary: Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification. ## 1. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/supermemoryai/supermemory ## 2. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/supermemoryai/supermemory ## 3. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/supermemoryai/supermemory ## 4. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/supermemoryai/supermemory ## 5. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/supermemoryai/supermemory ## 6. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/supermemoryai/supermemory