# Supermemory Modules: Complete Guide to the Turbo Monorepo Architecture

> Explore the Supermemory Modules and understand the Turbo Monorepo architecture. Discover applications, shared packages, and SDKs powering Supermemory.

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

---

**Supermemory organizes its codebase into twelve distinct modules within a Turborepo monorepo structure: three applications (`apps/web`, `apps/mcp`, `apps/browser-extension`), four shared infrastructure packages (`packages/lib`, `packages/validation`, `packages/ui`, `packages/memory-graph`), and five language-specific SDKs (`packages/ai-sdk`, `packages/tools`, `packages/openai-sdk-python`, `packages/agent-framework-python`, `packages/pipecat-sdk-python`).**

The **Supermemory** codebase is structured as a **Turbo monorepo**, enabling independent builds, linting, and type-checking across packages while sharing a common TypeScript configuration (`@total-typescript/tsconfig`). Each top-level directory represents a logical module with distinct responsibilities, from the Next.js web interface to Python agent frameworks and MCP servers.

## Application Modules

The `apps/` directory contains three deployable units that serve as the primary entry points for user interaction and external integration.

### Web Application (`apps/web`)

The **Next.js web application** powers the Supermemory UI and handles routing, authentication, and client-side data fetching. Located at `apps/web`, this module consumes the shared library components and provides the main interface for users to manage their memories.

### MCP Server (`apps/mcp`)

The **Model-Context-Protocol (MCP) server** is a lightweight Cloudflare Worker providing `/v4` endpoints that agents use to fetch memory profiles. This module acts as the bridge between external AI agents and the Supermemory backend, validating payloads using schemas from `packages/validation`.

### Browser Extension (`apps/browser-extension`)

Built with **WXT**, the browser extension (`apps/browser-extension`) allows users to capture content directly from web pages and push it into Supermemory without leaving their browser. It integrates with the same API client used by the web application.

## Core Shared Infrastructure

Four packages provide the foundational utilities, types, and components used across the entire platform.

### TypeScript Library (`packages/lib`)

The **core TypeScript library** contains essential utilities shared by all front-end code. Key files include:

- **[`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts)** – Centralized, type-safe HTTP client (`$fetch`) used by the UI and SDKs
- **[`packages/lib/auth.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/auth.ts)** – Authentication helpers and session management
- **[`packages/lib/auth-context.tsx`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/auth-context.tsx)** – React context providers for authentication state
- **[`packages/lib/similarity.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/similarity.ts)** – Vector similarity utilities for memory matching

### Validation Schemas (`packages/validation`)

This module contains **Zod schema definitions** ([`packages/validation/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts)) that guarantee type-safe communication between the UI, MCP server, and external SDKs. Every public API endpoint has its request and response shapes strictly defined here.

### UI Component System (`packages/ui`)

Located at `packages/ui`, this package provides reusable components (tables, tabs, tooltips) that enforce a consistent design system across the web app without coupling components to business logic.

### Knowledge Graph Visualization (`packages/memory-graph`)

The **memory-graph** package (`packages/memory-graph`) visualizes the knowledge graph where nodes represent memories and edges represent relationships. This is consumed internally by the web UI to render relationship diagrams.

## AI SDKs and Developer Tools

Five packages provide language-specific tooling for integrating Supermemory into AI agents and applications.

### JavaScript AI SDK (`packages/ai-sdk`)

The official **JavaScript/TypeScript SDK** (`packages/ai-sdk`) exposes a convenient `supermemoryTools` factory and type-safe API definitions. It serves as a single entry point for JavaScript developers, re-exporting functionality from `packages/tools` with standardized interfaces.

### Memory Tools (`packages/tools`)

**Supermemory Tools** (`packages/tools`) provide ready-made memory utilities for the AI-SDK, OpenAI SDK, and Mastra agents:

- **`searchMemoriesTool`** and **`addMemoryTool`** for memory operations
- **`withSupermemory`** middleware that injects retrieved memories into LLM prompts

```typescript
import { supermemoryTools } from "@supermemory/tools/ai-sdk";

const tools = supermemoryTools(process.env.SUPERMEMORY_API_KEY!, {
  containerTags: ["user_123"],
});

const { searchMemories, addMemory } = tools;
const hits = await searchMemories({ informationToGet: "project deadline", limit: 3 });
await addMemory({ memory: "Project X deadline is 2026-04-01" });

```

### Python OpenAI SDK (`packages/openai-sdk-python`)

This Python wrapper mirrors the JavaScript SDK for OpenAI-compatible runtimes, offering `search_memories`, `add_memory` functions and middleware for the `openai` Python client.

```python
from supermemory_sdk import SupermemoryClient

client = SupermemoryClient(api_key="YOUR_SUPERMEMORY_API_KEY")
result = client.search_memories(
    information_to_get="favorite coffee",
    limit=5,
)
print(result)

```

### Python Agent Framework (`packages/agent-framework-python`)

A lightweight framework for building agents that automatically use Supermemory as a knowledge source. The middleware ([`packages/agent-framework-python/src/supermemory_agent_framework/middleware.py`](https://github.com/supermemoryai/supermemory/blob/main/packages/agent-framework-python/src/supermemory_agent_framework/middleware.py)) enriches agent contexts with retrieved memories.

```python
from supermemory_agent_framework import SupermemoryMiddleware

middleware = SupermemoryMiddleware(api_key="YOUR_SUPERMEMORY_API_KEY")
await middleware.add_memory("User mentioned they love espresso")

```

### Pipecat Voice Integration (`packages/pipecat-sdk-python`)

This integration layer connects the **Pipecat voice-assistant framework** to Supermemory, enabling voice agents to query and store memories during conversational interactions.

## Module Interactions and Data Flow

The modules interact through a coordinated pipeline orchestrated by **Turbo** (see [`turbo.json`](https://github.com/supermemoryai/supermemory/blob/main/turbo.json) at the repository root):

1. The **frontend** (`apps/web`) imports `$fetch` and auth helpers from `packages/lib` for type-safe API communication.

2. API calls hit the Supermemory backend (hosted on Cloudflare Workers), which validates payloads using **`packages/validation`** schemas.

3. The backend runs a content-processing pipeline (extraction → chunking → embedding → indexing) and builds a knowledge graph stored in the **memory-graph** system.

4. Agents written in JavaScript or Python use the **SDK modules** (`packages/ai-sdk`, `packages/openai-sdk-python`, `packages/agent-framework-python`), which call the same HTTP endpoints via the shared [`api.ts`](https://github.com/supermemoryai/supermemory/blob/main/api.ts) client.

5. When LLM requests are made, middleware (`withSupermemory` in `packages/tools` or Python equivalents) fetches relevant memories, formats them into system prompts, and optionally writes user utterances back as new memories.

This architecture allows swapping UI libraries, replacing agent frameworks, or adding new language bindings without modifying the core ingestion pipeline.

## Summary

- **Supermemory** uses a **Turborepo** structure with twelve modules organized under `apps/` and `packages/`.
- **Application modules** include the Next.js web app (`apps/web`), MCP server (`apps/mcp`), and browser extension (`apps/browser-extension`).
- **Shared infrastructure** comprises `packages/lib` (core utilities), `packages/validation` (Zod schemas), `packages/ui` (components), and `packages/memory-graph` (visualization).
- **SDK modules** support both JavaScript (`packages/ai-sdk`, `packages/tools`) and Python (`packages/openai-sdk-python`, `packages/agent-framework-python`, `packages/pipecat-sdk-python`) ecosystems.
- All modules share a central API client ([`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts)) and validation schemas, ensuring type safety across language boundaries.

## Frequently Asked Questions

### What is the difference between `packages/ai-sdk` and `packages/tools`?

The **`packages/tools`** module contains the raw memory tool implementations (`searchMemoriesTool`, `addMemoryTool`) and middleware logic, while **`packages/ai-sdk`** provides a convenient, unified entry point and factory functions that wrap these tools for specific AI SDKs (like Vercel's AI SDK or Mastra). Think of `packages/tools` as the engine and `packages/ai-sdk` as the driver's interface.

### How does the MCP server relate to the other modules?

The **MCP server** (`apps/mcp`) functions as a specialized Cloudflare Worker that exposes memory endpoints via the Model Context Protocol. Unlike the web app which serves human users, the MCP server is designed for agent-to-agent communication. It uses the same `packages/validation` schemas and backend storage as the web application, ensuring consistency across human and agent interfaces.

### Can I use Supermemory with Python-based LLM frameworks?

Yes. The **`packages/openai-sdk-python`** module provides a direct Python client, while **`packages/agent-framework-python`** offers higher-level middleware for auto-injecting memories into agent prompts. Additionally, **`packages/pipecat-sdk-python`** enables voice-specific Python agents to query and store memories during real-time conversations.

### Where is the type-safe API client defined, and which modules use it?

The **`$fetch` client** is defined in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts) and serves as the centralized HTTP client for the entire platform. It is imported by `apps/web` for frontend requests, consumed by the JavaScript SDKs in `packages/ai-sdk`, and referenced as the contract that Python SDKs mirror. This ensures all API consumers share identical type definitions via `packages/validation`.