# supermemoryai/supermemory-mcp architecture

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

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

## Overview

1. **What this repo is**
   - This is the public-facing Supermemory MCP app: a lightweight web experience for installation, onboarding, and self-host setup, not a large backend system.
   - The architecture is intentionally thin: most behavior lives in the UI, with a small edge/server layer for rendering and cookie-backed state.

2. **Primary runtime boundary**
   - The app is designed to run on **Cloudflare Workers**.
   - `workers/app.ts`, `wrangler.jsonc`, and `worker-configuration.d.ts` indicate the production entrypoint is a worker-based HTTP handler, not a traditional Node server.

3. **Request/response flow**
   - Incoming requests hit the Cloudflare Worker.
   - The worker delegates to the **React Router SSR stack** to match routes and render HTML on the server.
   - The initial HTML is then hydrated in the browser, with client-side navigation handled by React Router.

4. **Routing and page composition**
   - `app/routes.ts` defines the route structure.
   - `app/routes/home.tsx` appears to be the main landing/home route.
   - `app/welcome/welcome.tsx` suggests a dedicated onboarding/welcome experience, likely used for first-run guidance or install instructions.

5. **Shared app shell**
   - `app/root.tsx` is the top-level layout/root component that wraps all routes.
   - `app/app.css` provides global styling across the entire UI.
   - `app/entry.server.tsx` is the server-render entry used to produce the initial HTML payload.

6. **Server-side state**
   - `app/session-cookies.server.ts` is the main state boundary in the repo.
   - It likely stores lightweight session/onboarding state in cookies rather than using a database.
   - That makes the app effectively stateless at the infrastructure level, aside from client cookies and environment configuration.

7. **External system integration**
   - The repo’s core domain is the **Supermemory API**.
   - The README says self-hosting requires `SUPERMEMORY_API_KEY`, which means the app depends on an external API key-backed service rather than owning its own data store.
   - The console at `console.supermemory.ai` is part of the deployment/setup flow for self-hosted usage.

8. **Static and browser-facing assets**
   - `public/icons/*` contains manifest/browser config assets for browser install/branding.
   - `public/og-image.png` (referenced in the README) is used for preview/demo presentation.
   - These assets support the product/site layer, not core application logic.

9. **Build and deployment tooling**
   - `vite.config.ts`, `react-router.config.ts`, and the TypeScript configs show a Vite + React Router build pipeline.
   - The app is likely built once and deployed as a Cloudflare Worker bundle.
   - There is no separate service tier or database service in this repo, which keeps the architecture to: browser UI + edge SSR + external Supermemory API.

10. **Architectural summary**
   - The main diagram should show four boundaries: **browser**, **Cloudflare Worker/SSR app**, **cookie-based session state**, and **Supermemory API / self-host API key**.
   - Everything else in the repo supports that flow: routing, root layout, welcome/home views, and static branding assets.

Main entry points: [`workers/app.ts`](https://github.com/supermemoryai/supermemory-mcp/blob/master/workers/app.ts) (Worker entry), [`app/routes.ts`](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/routes.ts) (Routes), [`app/root.tsx`](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/root.tsx) (App shell), [`app/entry.server.tsx`](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/entry.server.tsx) (SSR entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser"]
  node_browser(("Browser<br/>runtime"))
end

subgraph group_edge["Cloudflare Worker"]
  node_worker_entry["Worker entry<br/>worker handler<br/>[app.ts]"]
  node_ssr_entry["SSR entry<br/>react-router SSR<br/>[entry.server.tsx]"]
end

subgraph group_app["App UI"]
  node_router["Routes<br/>route map<br/>[routes.ts]"]
  node_root_layout["App shell<br/>root layout<br/>[root.tsx]"]
  node_home_page["Home<br/>landing page<br/>[home.tsx]"]
  node_welcome_page["Welcome<br/>onboarding page<br/>[welcome.tsx]"]
  node_global_css["Styles<br/>global css<br/>[app.css]"]
end

subgraph group_state["State and External"]
  node_session_cookies[("Session cookies<br/>cookie state")]
  node_supermemory_api{{"Supermemory API<br/>external api"}}
  node_api_key{{"API key<br/>env config"}}
  node_public_assets["Public assets<br/>static assets<br/>[manifest.json]"]
end

subgraph group_build["Build"]
  node_vite["Vite build<br/>build pipeline<br/>[vite.config.ts]"]
  node_react_router_cfg["Router config<br/>build config"]
  node_worker_cfg["Worker config<br/>deploy config<br/>[wrangler.jsonc]"]
  node_types_cfg["TS configs<br/>tooling config<br/>[tsconfig.json]"]
end

node_browser -->|"HTTP requests"| node_worker_entry
node_worker_entry -->|"render"| node_ssr_entry
node_ssr_entry -->|"match routes"| node_router
node_router -->|"wraps"| node_root_layout
node_router -->|"home route"| node_home_page
node_router -->|"onboarding route"| node_welcome_page
node_root_layout -->|"styles"| node_global_css
node_worker_entry -->|"reads/writes"| node_session_cookies
node_welcome_page -->|"updates"| node_session_cookies
node_home_page -.->|"uses"| node_supermemory_api
node_worker_entry -->|"env"| node_api_key
node_api_key -->|"authenticates"| node_supermemory_api
node_root_layout -->|"brands"| node_public_assets
node_vite -->|"bundles"| node_worker_entry
node_vite -->|"bundles"| node_ssr_entry
node_react_router_cfg -->|"configures"| node_router
node_worker_cfg -->|"deploys"| node_worker_entry
node_types_cfg -.->|"types"| node_worker_entry

click node_worker_entry "https://github.com/supermemoryai/supermemory-mcp/blob/master/workers/app.ts"
click node_ssr_entry "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/entry.server.tsx"
click node_router "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/routes.ts"
click node_root_layout "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/root.tsx"
click node_home_page "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/routes/home.tsx"
click node_welcome_page "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/welcome/welcome.tsx"
click node_global_css "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/app.css"
click node_session_cookies "https://github.com/supermemoryai/supermemory-mcp/blob/master/app/session-cookies.server.ts"
click node_public_assets "https://github.com/supermemoryai/supermemory-mcp/blob/master/public/icons/manifest.json"
click node_vite "https://github.com/supermemoryai/supermemory-mcp/blob/master/vite.config.ts"
click node_react_router_cfg "https://github.com/supermemoryai/supermemory-mcp/blob/master/react-router.config.ts"
click node_worker_cfg "https://github.com/supermemoryai/supermemory-mcp/blob/master/wrangler.jsonc"
click node_types_cfg "https://github.com/supermemoryai/supermemory-mcp/blob/master/tsconfig.json"

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_browser toneBlue
class node_worker_entry,node_ssr_entry toneAmber
class node_router,node_root_layout,node_home_page,node_welcome_page,node_global_css toneMint
class node_session_cookies,node_supermemory_api,node_api_key,node_public_assets toneRose
class node_vite,node_react_router_cfg,node_worker_cfg,node_types_cfg toneIndigo
```

## Components

### Browser

User-facing experience in the browser

- **Browser**: runtime · Client-side navigation and hydrated UI

### Cloudflare Worker

Edge HTTP handling and server rendering

- [Worker entry](https://github.com/supermemoryai/supermemory-mcp/blob/master/workers/app.ts): worker handler · Cloudflare Worker HTTP entrypoint · `workers/app.ts`
- [SSR entry](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/entry.server.tsx): react-router SSR · Server render pipeline for initial HTML · `app/entry.server.tsx`

### App UI

Route structure and shared page composition

- [Routes](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/routes.ts): route map · Application route definitions · `app/routes.ts`
- [App shell](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/root.tsx): root layout · Shared wrapper for all routes · `app/root.tsx`
- [Home](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/routes/home.tsx): landing page · Main public-facing landing route · `app/routes/home.tsx`
- [Welcome](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/welcome/welcome.tsx): onboarding page · Install and first-run guidance · `app/welcome/welcome.tsx`
- [Styles](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/app.css): global css · Application-wide styling · `app/app.css`

### State and External

Cookie state, branding assets, and external API dependency

- [Session cookies](https://github.com/supermemoryai/supermemory-mcp/blob/master/app/session-cookies.server.ts): cookie state · Lightweight onboarding and session persistence · `app/session-cookies.server.ts`
- **Supermemory API**: external api · External service used by the app
- **API key**: env config · Self-host authentication/configuration secret
- [Public assets](https://github.com/supermemoryai/supermemory-mcp/blob/master/public/icons/manifest.json): static assets · Icons, manifest, and preview image assets · `public/icons/manifest.json`

### Build

Tooling that bundles and deploys the worker app

- [Vite build](https://github.com/supermemoryai/supermemory-mcp/blob/master/vite.config.ts): build pipeline · Frontend and worker bundle build · `vite.config.ts`
- [Router config](https://github.com/supermemoryai/supermemory-mcp/blob/master/react-router.config.ts): build config · React Router build/runtime configuration · `react-router.config.ts`
- [Worker config](https://github.com/supermemoryai/supermemory-mcp/blob/master/wrangler.jsonc): deploy config · Cloudflare Worker deployment configuration · `wrangler.jsonc`
- [TS configs](https://github.com/supermemoryai/supermemory-mcp/blob/master/tsconfig.json): tooling config · TypeScript and worker typing configuration · `tsconfig.json`

## Connections

- Browser → Worker entry: HTTP requests · Users load the app and navigate between routes
- Worker entry → SSR entry: render · Worker delegates to the server rendering pipeline
- SSR entry → Routes: match routes · Server render resolves the active route tree
- Routes → App shell: wraps · All routes compose under the shared app shell
- Routes → Home: home route · Primary landing experience
- Routes → Welcome: onboarding route · First-run or install guidance flow
- App shell → Styles: styles · Shared styling applied across the app
- Worker entry → Session cookies: reads/writes · Worker uses cookie-backed state for lightweight persistence
- Welcome → Session cookies: updates · Onboarding state is stored in cookies
- Home → Supermemory API: uses · Public app integrates with the Supermemory service
- Worker entry → API key: env · Self-host setup supplies the API key
- API key → Supermemory API: authenticates · Key-backed access to the external service
- App shell → Public assets: brands · Browser icons and preview assets support the app shell
- Vite build → Worker entry: bundles · Build pipeline packages the worker entry and app code
- Vite build → SSR entry: bundles · Server render code is part of the build output
- Router config → Routes: configures · Router build/runtime behavior
- Worker config → Worker entry: deploys · Cloudflare deployment targets the worker entry
- TS configs → Worker entry: types · Worker typing and compiler setup