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

> Explore Supermemory's architecture: a Turbo-powered monorepo featuring Next.js, Hono API, MCP server, shared TS packages, and browser extensions. Understand its five logical layers and typed API client.

- Repository: [supermemory/supermemory](https://github.com/supermemoryai/supermemory)
- Tags: deep-dive
- Published: 2026-03-25

---

**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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts), ensuring type safety from the network boundary inward.

Authentication middleware in [`packages/lib/auth.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/hooks/use-graph-data.ts), [`hooks/use-graph-api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts) provides type-safe network requests used throughout the monorepo:

```typescript
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`](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/src/server.ts):

```typescript
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:

```tsx
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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) and Better-Auth middleware from [`packages/lib/auth.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) that validate all API requests and responses. The `$fetch` client in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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.