How supermemoryai/supermemory-mcp works
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: app.ts Worker entry · routes.ts Routes · root.tsx App shell · entry.server.tsx SSR entry
Components 16
Browser
User-facing experience in the browser
- Browser · Client-side navigation and hydrated UI
Cloudflare Worker
Edge HTTP handling and server rendering
- Worker entry · Cloudflare Worker HTTP entrypoint
workers/app.ts - SSR entry · Server render pipeline for initial HTML
app/entry.server.tsx
App UI
Route structure and shared page composition
State and External
Cookie state, branding assets, and external API dependency
- Session cookies · Lightweight onboarding and session persistence
app/session-cookies.server.ts - Supermemory API · External service used by the app
- API key · Self-host authentication/configuration secret
- Public assets · Icons, manifest, and preview image assets
public/icons/manifest.json
Build
Tooling that bundles and deploys the worker app
- Vite build · Frontend and worker bundle build
vite.config.ts - Router config · React Router build/runtime configuration
react-router.config.ts - Worker config · Cloudflare Worker deployment configuration
wrangler.jsonc - TS configs · TypeScript and worker typing configuration
tsconfig.json
Connections 18
- 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