How supermemoryai/supermemory works
Purpose and Scope
This monorepo packages Supermemory’s AI memory/context platform for consumers: MCP access, agent-framework integrations, graph visualization, playgrounds, docs, and shared client UI/validation. The hosted/local memory engine described in the README is an external API/runtime dependency rather than implementation present in this tree.
Primary Entry Points
• MCP server: apps/mcp/src/server/index.ts starts the protocol-facing service; apps/mcp/src/server/server.ts assembles server capabilities. It is deployed/configured as a Cloudflare Worker via apps/mcp/wrangler.jsonc.
• Published integration packages: TypeScript exports begin in packages/tools/src/index.ts, packages/ai-sdk/src/index.ts, and React graph exports in packages/memory-graph/src/index.tsx.
• Consumer/demo apps: Next.js applications expose interactive SDK and graph experiences through apps/sdk-playground/src/app/page.tsx and apps/memory-graph-playground/src/app/page.tsx.
MCP Gateway and Tenant Boundary
apps/mcp/src/server/auth/index.ts authenticates requests and apps/mcp/src/server/auth/rbac.ts applies role/scope permissions. Space selection and persisted protocol state are handled by apps/mcp/src/server/space.ts, apps/mcp/src/server/space-state.ts, and apps/mcp/src/server/legacy-protocol-state.ts.
The active space/container-tag is the central isolation boundary: tools act under selected space state, while container tags organize project/user memory. The MCP client adapter at apps/mcp/src/server/client/index.ts is the boundary to the Supermemory backend API.
Memory, Search, and Ingestion Tool Surface
The MCP server registers its agent-callable operations through apps/mcp/src/server/tools/index.ts. Core flows are:
• save/capture memory: apps/mcp/src/server/tools/save-memory.ts, apps/mcp/src/server/tools/add-memory.ts;
• retrieve context: apps/mcp/src/server/tools/search-memory.ts, apps/mcp/src/server/tools/get-profile.ts, apps/mcp/src/server/tools/list-memories.ts;
• document/file ingestion: apps/mcp/src/server/tools/prepare-file-upload.ts, apps/mcp/src/server/tools/upload-file.ts, apps/mcp/src/server/tools/get-document.ts;
• graph retrieval: apps/mcp/src/server/tools/fetch-graph-data.ts, apps/mcp/src/server/tools/memory-graph.ts.
Tool input/output contracts are centralized in apps/mcp/src/server/tools/types.ts and apps/mcp/src/server/tools/output-schemas.ts, separating protocol presentation from backend requests.
MCP Widget Experience
The MCP server exposes resources/prompts for interactive host clients through apps/mcp/src/server/resources/widget.ts and apps/mcp/src/server/prompts/context.ts. The embedded React widget begins at apps/mcp/src/widget/main.tsx; apps/mcp/src/widget/McpAppProvider.tsx bridges host context and tool/view state. It renders scoped-space selection, memory save/upload flows, and graph views in apps/mcp/src/widget/views/Picker.tsx, apps/mcp/src/widget/views/Save.tsx, and apps/mcp/src/widget/views/Graph.tsx.
Integration Layer
packages/tools is the main cross-framework adapter layer. Its shared memory API client/context construction is in packages/tools/src/shared/memory-client.ts and packages/tools/src/shared/memory-context.ts; wrappers adapt this behavior to Vercel AI SDK, OpenAI, Mastra, and VoltAgent under packages/tools/src/ai-sdk.ts, packages/tools/src/openai/middleware.ts, and packages/tools/src/mastra/wrapper.ts. Separate Python packages provide analogous integrations, including packages/openai-sdk-python/src/supermemory_openai/middleware.py and packages/agent-framework-python/src/supermemory_agent_framework/context_provider.py.
Graph Rendering and Supporting Apps
packages/memory-graph is a reusable browser-side graph renderer: data acquisition is isolated in packages/memory-graph/src/hooks/use-graph-data.ts, while canvas simulation/rendering live in packages/memory-graph/src/canvas/simulation.ts and packages/memory-graph/src/canvas/renderer.ts. The Next.js graph playground proxies backend graph/tag calls via apps/memory-graph-playground/src/app/api/graph/route.ts and apps/memory-graph-playground/src/app/api/container-tags/route.ts.
Material runtimes are TypeScript/React, Next.js, Vite, Cloudflare Workers/Wrangler, and Python integration packages. External services include the Supermemory API, MCP-capable AI hosts, and optional model/embedding providers documented for local deployment.
Main entry points: server.ts Server assembly · index.ts Tool registry · index.tsx Memory graph package · memory-client.ts Shared memory client
Components 23
MCP Gateway
Cloudflare Worker protocol service.
- MCP Worker entry
apps/mcp/src/server/index.ts - Server assembly · Registers protocol capabilities and tools.
apps/mcp/src/server/server.ts - Auth and RBAC · Authenticates callers and enforces roles/scopes.
apps/mcp/src/server/auth/index.ts - Selected space state · Scopes operations to the active space/container tag.
apps/mcp/src/server/space-state.ts - Tool registry · Agent-callable memory, search, ingestion, and graph operations.
apps/mcp/src/server/tools/index.ts - Tool contracts · Central input/output protocol contracts.
apps/mcp/src/server/tools/types.ts - Supermemory client · Boundary to the external memory backend.
apps/mcp/src/server/client/index.ts - Widget resources · Exposes interactive resources and context prompts.
apps/mcp/src/server/resources/widget.ts
MCP Widget
Embedded interactive host UI.
- Widget entry
apps/mcp/src/widget/main.tsx - Host context bridge · Connects host context with tool and view state.
apps/mcp/src/widget/McpAppProvider.tsx - Picker, save, graph views · Scoped selection, capture/upload, and graph interaction.
apps/mcp/src/widget/views/Graph.tsx
Integration Packages
Published TypeScript and Python adapters.
- Tools package · Cross-framework integration entry point.
packages/tools/src/index.ts - Shared memory client · Builds memory API clients and context.
packages/tools/src/shared/memory-client.ts - Framework wrappers · Adapters for AI SDK, OpenAI, Mastra, and VoltAgent.
packages/tools/src/ai-sdk.ts - Python integrations · OpenAI middleware and agent-framework context providers.
packages/openai-sdk-python/src/supermemory_openai/middleware.py
Graph UI
Reusable renderer and Next.js demo.
- Memory graph package · Reusable browser graph renderer.
packages/memory-graph/src/index.tsx - Graph data hook · Isolates graph data acquisition.
packages/memory-graph/src/hooks/use-graph-data.ts - Canvas renderer · Simulation and canvas rendering.
packages/memory-graph/src/canvas/renderer.ts - Graph playground · Interactive consumer graph experience.
apps/memory-graph-playground/src/app/page.tsx - Graph API proxy · Proxies backend graph and tag requests.
apps/memory-graph-playground/src/app/api/graph/route.ts
Other components
- SDK playground · Interactive SDK consumer experience.
apps/sdk-playground/src/app/page.tsx - Supermemory API · Hosted or local memory engine outside this repository.
- MCP AI hosts
Connections 23
- MCP AI hosts → MCP Worker entry: MCP requests
- MCP Worker entry → Server assembly: starts
- Server assembly → Auth and RBAC: authenticates
- Server assembly → Selected space state: loads scope
- Server assembly → Tool registry: registers
- Tool registry → Tool contracts: validates with
- Tool registry → Selected space state: acts within
- Tool registry → Supermemory client: calls
- Supermemory client → Supermemory API: API requests
- Server assembly → Widget resources: serves
- Widget resources → Widget entry: embeds
- Widget entry → Host context bridge: initializes
- Host context bridge → Picker, save, graph views: drives
- Tools package → Shared memory client: exports
- Framework wrappers → Shared memory client: uses
- Shared memory client → Supermemory API: API requests
- Python integrations → Supermemory API: API requests
- Memory graph package → Graph data hook: acquires data
- Memory graph package → Canvas renderer: renders via
- Graph playground → Memory graph package: uses
- Graph playground → Graph API proxy: requests graph data
- Graph API proxy → Supermemory API: proxies
- SDK playground → Tools package: demonstrates