Supermemory Modules: Complete Guide to the Turbo Monorepo Architecture

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 – Centralized, type-safe HTTP client ($fetch) used by the UI and SDKs
• packages/lib/auth.ts – Authentication helpers and session management
• packages/lib/auth-context.tsx – React context providers for authentication state
• packages/lib/similarity.ts – Vector similarity utilities for memory matching

Validation Schemas (packages/validation)

This module contains Zod schema definitions (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

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.

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) enriches agent contexts with retrieved memories.

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 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 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) 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 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.

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