# supermemoryai/supermemory architecture

> Architecture diagram of the GitHub repository supermemoryai/supermemory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supermemoryai/supermemory
- Repository: https://github.com/supermemoryai/supermemory

## Overview

#### 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: [`apps/mcp/src/server/server.ts`](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/server.ts) (Server assembly), [`apps/mcp/src/server/tools/index.ts`](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/tools/index.ts) (Tool registry), [`packages/memory-graph/src/index.tsx`](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/index.tsx) (Memory graph package), [`packages/tools/src/shared/memory-client.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/memory-client.ts) (Shared memory client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Gateway"]
  node_mcp_entry{{"MCP Worker entry<br/>TypeScript service<br/>[index.ts]"}}
  node_mcp_server["Server assembly<br/>MCP server<br/>[server.ts]"]
  node_auth["Auth and RBAC<br/>access control<br/>[index.ts]"]
  node_space_state[("Selected space state<br/>tenant boundary<br/>[space-state.ts]")]
  node_mcp_tools["Tool registry<br/>MCP tools<br/>[index.ts]"]
  node_tool_contracts["Tool contracts<br/>schemas<br/>[types.ts]"]
  node_backend_client["Supermemory client<br/>API adapter<br/>[index.ts]"]
  node_widget_resources["Widget resources<br/>MCP resources<br/>[widget.ts]"]
end

subgraph group_widget["MCP Widget"]
  node_widget_entry["Widget entry<br/>React app<br/>[main.tsx]"]
  node_widget_provider["Host context bridge<br/>React provider<br/>[McpAppProvider.tsx]"]
  node_widget_views["Picker, save, graph views<br/>React views<br/>[Graph.tsx]"]
end

subgraph group_integrations["Integration Packages"]
  node_tools_package["Tools package<br/>TypeScript exports<br/>[index.ts]"]
  node_shared_memory_client["Shared memory client<br/>integration core<br/>[memory-client.ts]"]
  node_framework_wrappers["Framework wrappers<br/>AI adapters<br/>[ai-sdk.ts]"]
  node_python_integrations["Python integrations<br/>Python adapters<br/>[middleware.py]"]
end

subgraph group_graph["Graph UI"]
  node_graph_package["Memory graph package<br/>React exports<br/>[index.tsx]"]
  node_graph_data["Graph data hook<br/>React hook<br/>[use-graph-data.ts]"]
  node_graph_canvas["Canvas renderer<br/>visualization engine<br/>[renderer.ts]"]
  node_graph_playground["Graph playground<br/>Next.js app<br/>[page.tsx]"]
  node_graph_api_proxy["Graph API proxy<br/>Next.js route<br/>[route.ts]"]
end

node_sdk_playground["SDK playground<br/>Next.js app<br/>[page.tsx]"]
node_supermemory_api(("Supermemory API<br/>external service"))
node_mcp_hosts(("MCP AI hosts<br/>external clients"))

node_mcp_hosts -->|"MCP requests"| node_mcp_entry
node_mcp_entry -->|"starts"| node_mcp_server
node_mcp_server -->|"authenticates"| node_auth
node_mcp_server -->|"loads scope"| node_space_state
node_mcp_server -->|"registers"| node_mcp_tools
node_mcp_tools -->|"validates with"| node_tool_contracts
node_mcp_tools -->|"acts within"| node_space_state
node_mcp_tools -->|"calls"| node_backend_client
node_backend_client -->|"API requests"| node_supermemory_api
node_mcp_server -->|"serves"| node_widget_resources
node_widget_resources -->|"embeds"| node_widget_entry
node_widget_entry -->|"initializes"| node_widget_provider
node_widget_provider -->|"drives"| node_widget_views
node_tools_package -->|"exports"| node_shared_memory_client
node_framework_wrappers -->|"uses"| node_shared_memory_client
node_shared_memory_client -->|"API requests"| node_supermemory_api
node_python_integrations -->|"API requests"| node_supermemory_api
node_graph_package -->|"acquires data"| node_graph_data
node_graph_package -->|"renders via"| node_graph_canvas
node_graph_playground -->|"uses"| node_graph_package
node_graph_playground -->|"requests graph data"| node_graph_api_proxy
node_graph_api_proxy -->|"proxies"| node_supermemory_api
node_sdk_playground -->|"demonstrates"| node_tools_package

click node_mcp_entry "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/index.ts"
click node_mcp_server "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/server.ts"
click node_auth "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/auth/index.ts"
click node_space_state "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/space-state.ts"
click node_mcp_tools "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/tools/index.ts"
click node_tool_contracts "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/tools/types.ts"
click node_backend_client "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/client/index.ts"
click node_widget_resources "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/resources/widget.ts"
click node_widget_entry "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/widget/main.tsx"
click node_widget_provider "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/widget/McpAppProvider.tsx"
click node_widget_views "https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/widget/views/Graph.tsx"
click node_tools_package "https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/index.ts"
click node_shared_memory_client "https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/memory-client.ts"
click node_framework_wrappers "https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts"
click node_python_integrations "https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/src/supermemory_openai/middleware.py"
click node_graph_package "https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/index.tsx"
click node_graph_data "https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/hooks/use-graph-data.ts"
click node_graph_canvas "https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/canvas/renderer.ts"
click node_graph_playground "https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx"
click node_graph_api_proxy "https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/api/graph/route.ts"
click node_sdk_playground "https://github.com/supermemoryai/supermemory/blob/main/apps/sdk-playground/src/app/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_entry,node_mcp_server,node_auth,node_space_state,node_mcp_tools,node_tool_contracts,node_backend_client,node_widget_resources toneBlue
class node_widget_entry,node_widget_provider,node_widget_views toneAmber
class node_tools_package,node_shared_memory_client,node_framework_wrappers,node_python_integrations toneMint
class node_graph_package,node_graph_data,node_graph_canvas,node_graph_playground,node_graph_api_proxy toneRose
class node_sdk_playground,node_supermemory_api,node_mcp_hosts toneNeutral
```

## Components

### MCP Gateway

Cloudflare Worker protocol service.

- [MCP Worker entry](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/index.ts): TypeScript service · `apps/mcp/src/server/index.ts`
- [Server assembly](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/server.ts): MCP server · Registers protocol capabilities and tools. · `apps/mcp/src/server/server.ts`
- [Auth and RBAC](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/auth/index.ts): access control · Authenticates callers and enforces roles/scopes. · `apps/mcp/src/server/auth/index.ts`
- [Selected space state](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/space-state.ts): tenant boundary · Scopes operations to the active space/container tag. · `apps/mcp/src/server/space-state.ts`
- [Tool registry](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/tools/index.ts): MCP tools · Agent-callable memory, search, ingestion, and graph operations. · `apps/mcp/src/server/tools/index.ts`
- [Tool contracts](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/tools/types.ts): schemas · Central input/output protocol contracts. · `apps/mcp/src/server/tools/types.ts`
- [Supermemory client](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/client/index.ts): API adapter · Boundary to the external memory backend. · `apps/mcp/src/server/client/index.ts`
- [Widget resources](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server/resources/widget.ts): MCP resources · Exposes interactive resources and context prompts. · `apps/mcp/src/server/resources/widget.ts`

### MCP Widget

Embedded interactive host UI.

- [Widget entry](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/widget/main.tsx): React app · `apps/mcp/src/widget/main.tsx`
- [Host context bridge](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/widget/McpAppProvider.tsx): React provider · Connects host context with tool and view state. · `apps/mcp/src/widget/McpAppProvider.tsx`
- [Picker, save, graph views](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/widget/views/Graph.tsx): React views · Scoped selection, capture/upload, and graph interaction. · `apps/mcp/src/widget/views/Graph.tsx`

### Integration Packages

Published TypeScript and Python adapters.

- [Tools package](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/index.ts): TypeScript exports · Cross-framework integration entry point. · `packages/tools/src/index.ts`
- [Shared memory client](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/memory-client.ts): integration core · Builds memory API clients and context. · `packages/tools/src/shared/memory-client.ts`
- [Framework wrappers](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts): AI adapters · Adapters for AI SDK, OpenAI, Mastra, and VoltAgent. · `packages/tools/src/ai-sdk.ts`
- [Python integrations](https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/src/supermemory_openai/middleware.py): Python adapters · 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](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/index.tsx): React exports · Reusable browser graph renderer. · `packages/memory-graph/src/index.tsx`
- [Graph data hook](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/hooks/use-graph-data.ts): React hook · Isolates graph data acquisition. · `packages/memory-graph/src/hooks/use-graph-data.ts`
- [Canvas renderer](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/canvas/renderer.ts): visualization engine · Simulation and canvas rendering. · `packages/memory-graph/src/canvas/renderer.ts`
- [Graph playground](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx): Next.js app · Interactive consumer graph experience. · `apps/memory-graph-playground/src/app/page.tsx`
- [Graph API proxy](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/api/graph/route.ts): Next.js route · Proxies backend graph and tag requests. · `apps/memory-graph-playground/src/app/api/graph/route.ts`

### Other components

- [SDK playground](https://github.com/supermemoryai/supermemory/blob/main/apps/sdk-playground/src/app/page.tsx): Next.js app · Interactive SDK consumer experience. · `apps/sdk-playground/src/app/page.tsx`
- **Supermemory API**: external service · Hosted or local memory engine outside this repository.
- **MCP AI hosts**: external clients

## Connections

- 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
