Main Components of Supermemory's Architecture: A Deep Dive into the Turbo-Powered Monorepo

Supermemory is built as a Turbo-powered monorepo that separates concerns into five logical layers: a Next.js frontend, Hono API endpoints, an MCP server for LLM integration, shared TypeScript packages, and browser extensions, all communicating through a typed API client.

The supermemoryai/supermemory repository implements a modular, type-safe architecture designed to handle memory storage, retrieval, and visualization across multiple interfaces. Understanding the main components of Supermemory's architecture reveals how the system maintains consistency between its web UI, programmatic API, and LLM-facing tools while maximizing code reuse through shared packages.

The Five-Layer Architecture

Supermemory organizes its codebase into distinct logical layers that handle specific responsibilities. This separation ensures that business logic remains centralized while allowing multiple entry points—web, API, and LLM agents—to interact with the same underlying data.

Frontend (Next.js Web UI)

The user-facing layer lives in apps/web and implements a Next.js React application that handles memory creation, search, and visualization. According to the source code in apps/web/next.config.ts, the frontend configures custom rewrites, redirects, and Sentry integration for error tracking.

State management relies on React Query combined with custom stores located in apps/web/stores/*. UI components—including the interactive Memory Graph visualization—reside under apps/web/components/*, providing a seamless interface for navigating connected memories.

API Layer (Hono and Zod Validation)

The HTTP interface exposes CRUD operations for memories, projects, connections, and analytics through Hono routes located in apps/web/app/api/*. Every endpoint validates requests using Zod schemas centralized in packages/validation/api.ts, ensuring type safety from the network boundary inward.

Authentication middleware in packages/lib/auth.ts implements Better-Auth to protect endpoints. The API layer communicates with a PostgreSQL database via Drizzle ORM, persisting the domain models that both the web UI and MCP server manipulate.

MCP Server (Model Context Protocol)

The Model Context Protocol implementation in apps/mcp/src/server.ts exposes Supermemory's functionality to LLMs through a standardized tool interface. This lightweight server registers tools like memory, recall, listProjects, and whoAmI, allowing external AI agents to read and write memories programmatically.

The MCP server utilizes the @modelcontextprotocol/sdk/server/mcp package to create an McpServer instance. Critically, it shares the same SupermemoryClient SDK defined in apps/mcp/src/client.ts that the web frontend uses, ensuring consistent behavior regardless of entry point.

Shared Packages

Reusable libraries occupy the packages/ directory and prevent code duplication across applications:

• packages/lib/api.ts: Provides a typed $fetch wrapper around the Supermemory backend, used by both the web UI and MCP tools.
• packages/memory-graph: Supplies the force-directed canvas visualization, styling, and data hooks (hooks/use-graph-data.ts, hooks/use-graph-api.ts) that power the interactive memory graph.
• packages/validation: Centralizes Zod schemas used by the API layer, MCP server, and frontend forms.
• packages/ai-sdk: Contains wrappers that expose AI-specific tool helpers for third-party LLM integrations.

Extensions and Integrations

Optional entry points extend Supermemory's reach beyond the web interface. The browser extension code in apps/browser-extension/* captures content from Chrome or Edge and communicates with the same $fetch client used by the main application. Additional integrations in packages/ai-sdk/* provide wrappers for external AI SDKs, allowing other applications to embed Supermemory capabilities.

How the Components Interact

The architecture maintains strict boundaries while enabling fluid data flow between layers. When a user creates a memory through the web interface, the frontend invokes the typed $fetch client from packages/lib/api.ts, which sends a validated request to the Hono API endpoints in apps/web/app/api/*. The API stores the data in PostgreSQL via Drizzle ORM and returns a typed response.

When an LLM agent accesses Supermemory through the MCP layer, the server in apps/mcp/src/server.ts invokes the same SupermemoryClient SDK that the frontend uses. This design ensures that business logic remains centralized in the shared packages while multiple interfaces—web, API, and LLM—consume identical functionality.

Key Implementation Examples

Using the Typed API Client

The $fetch utility in packages/lib/api.ts provides type-safe network requests used throughout the monorepo:

import { $fetch } from "packages/lib/api";

// Create a new memory
const result = await $fetch("@post/documents", {
  json: { content: "Remember to buy milk tomorrow" },
});

console.log("Created memory ID:", result.data.id);

Registering MCP Tools

The MCP server exposes capabilities to LLMs through a declarative registration pattern in apps/mcp/src/server.ts:

import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";

const mcp = new McpServer({ name: "supermemory", version: "4.0.0" });

const helloSchema = z.object({ name: z.string().optional() });

mcp.registerTool(
  "sayHello",
  { description: "Return a friendly greeting", inputSchema: helloSchema },
  async (args) => ({
    content: [{ type: "text", text: `Hello, ${args?.name ?? "friend"}!` }],
  })
);

Rendering the Memory Graph

The visualization layer exposes a React component that consumes the shared graph logic:

import { MemoryGraph } from "packages/memory-graph/src/components/memory-graph";

export default function GraphPage() {
  return (
    <div style={{ width: "100%", height: "800px" }}>
      <MemoryGraph containerTag="my_project" />
    </div>
  );
}

Summary

• Turbo-powered monorepo: Codebase organized into apps/ (deployable units) and packages/ (shared libraries) for maximum reuse.
• Type-safe API layer: Hono routes in apps/web/app/api/* use Zod schemas from packages/validation/api.ts and Better-Auth middleware from packages/lib/auth.ts.
• Dual interface design: Both humans (via Next.js) and LLMs (via MCP) access the same data through the SupermemoryClient SDK.
• Centralized business logic: The $fetch client in packages/lib/api.ts and validation schemas ensure consistency across all entry points.
• Modular visualization: The memory graph lives in packages/memory-graph and integrates into both the web UI and MCP resources.

Frequently Asked Questions

What is the Model Context Protocol (MCP) in Supermemory?

The Model Context Protocol (MCP) is an implementation in apps/mcp/src/server.ts that exposes Supermemory's functionality as tools that LLM agents can invoke. It registers specific capabilities like memory (create), recall (search), and listProjects (read) using the official MCP SDK, allowing AI systems to read from and write to the user's memory store through a standardized interface.

How does Supermemory ensure type safety across the monorepo?

Type safety is enforced through Zod schemas centralized in packages/validation/api.ts that validate all API requests and responses. The $fetch client in packages/lib/api.ts provides a typed wrapper around HTTP calls, ensuring that both the frontend and MCP server receive correctly shaped data. This shared validation layer prevents runtime errors across TypeScript applications.

What database does Supermemory use for persistence?

Supermemory uses PostgreSQL as its primary datastore, accessed through Drizzle ORM within the API layer. The Drizzle configuration and schema definitions handle migrations and type-safe database queries, while the connection details are configured in the Next.js application environment.

How do the browser extensions communicate with the main application?

Browser extensions located in apps/browser-extension/* communicate with the core Supermemory backend using the same typed $fetch client defined in packages/lib/api.ts. This ensures that extension actions—such as capturing web content—follow the same validation rules and authentication flows as the main web application, maintaining consistency across all client implementations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}