How to Set Up Supermemory Locally: Complete Developer Guide

To set up Supermemory locally, install Bun ≥1.2.17, clone the supermemoryai/supermemory repository, run bun install, configure your .env.local file, and execute bun run dev to launch the Next.js web UI on port 3000 and the MCP server on port 8788.

Setting up Supermemory on your local machine is straightforward thanks to its Turbo-powered monorepo structure. This guide walks you through the complete process to set up Supermemory locally, from installing dependencies to verifying your installation with working API calls against the processing pipeline.

Prerequisites

Before you begin, ensure your system meets these requirements:

• Bun ≥1.2.17 — The package manager and task runner used throughout the monorepo. Install with:

  curl https://bun.sh/install | bash

• Git — Required to clone the repository.

• Node.js ≥20 (optional) — Some tooling may fall back to Node, though Bun bundles its own runtime. Install via bun install node if needed.

Clone and Install

Clone the repository and install all workspace dependencies:

git clone https://github.com/supermemoryai/supermemory.git
cd supermemory
bun install

The bun install command reads the lockfile and sets up every package under packages/ along with the applications in apps/web, apps/mcp, and apps/memory-graph-playground. This single command prepares the entire Turbo monorepo workspace for development.

Configure Environment Variables

Supermemory requires specific API keys and configuration values to function. The repository includes a template you can copy:

cp .env.example .env.local

Edit .env.local and add your credentials:

• SUPERMEMORY_API_KEY — Your API key from the Supermemory console
• CLOUDFLARE_ACCOUNT_ID — Required if deploying to Cloudflare Workers
• CLOUDFLARE_API_TOKEN — Required for Cloudflare deployments
• API_URL — Optional override (defaults to http://localhost:8787)

The .env.local file is intentionally ignored by Git, ensuring you never commit secrets to version control.

Optional Local Development Proxy

When running the UI locally, the web application sends API requests to http://localhost:8787. If you need to bypass authentication cookie handling during local development, modify apps/web/proxy.ts:

if (url.hostname === "localhost") {
  return NextResponse.next();   // skip auth cookie handling locally
}

This conditional bypass allows seamless communication between the Next.js frontend and the local API server without auth cookie conflicts.

Start the Development Server

From the repository root, run the Turbo-provided development script:

bun run dev

This single command orchestrates three services simultaneously:

1. Web UI — Next.js application running at http://localhost:3000
2. MCP Server — Cloudflare Workers dev server running at http://localhost:8788
3. Memory-Graph Playground — Available within the web UI for visualizing knowledge graphs

The bun run dev command leverages the monorepo configuration to start all components in parallel, connecting the client applications to the processing pipeline.

Verify Your Local Installation

Open your browser and navigate to http://localhost:3000. You should see the Supermemory landing page with a "Sign in" button powered by Better-Auth.

To verify full functionality:

1. Sign in (or configure a test API key in .env.local)
2. Upload a PDF or text content via the UI
3. Observe the content flowing through the processing pipeline (queued → extracting → chunking → embedding → indexing)
4. Check the Memory Graph visualization in the sidebar to see semantic relationships

If you encounter "API key not working" errors, verify that SUPERMEMORY_API_KEY is correctly set in .env.local and that the API server is reachable at http://localhost:8787.

Test with TypeScript and Python SDKs

Once running locally, test your instance using the official SDKs.

TypeScript SDK Example

The TypeScript SDK is implemented in packages/ai-sdk/src/tools.ts. Use it to add memories and retrieve dynamic profiles:

import { Supermemory } from "supermemory";

const client = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY,
});

async function demo() {
  // Store a new memory
  await client.add({
    content: "User prefers dark mode and TypeScript",
    containerTag: "user_123",
  });

  // Retrieve the dynamic profile + recent memories
  const { profile, searchResults } = await client.profile({
    containerTag: "user_123",
    q: "What does the user prefer?",
  });

  console.log("Static profile:", profile.static);
  console.log("Dynamic context:", profile.dynamic);
  console.log("Search hits:", searchResults?.results ?? []);
}

demo();

Python SDK Example

The Python SDK provides equivalent functionality with the same API surface:

import os
from supermemory import Supermemory

client = Supermemory(api_key=os.getenv("SUPERMEMORY_API_KEY"))

# Add a memory

client.add(
    content="User prefers dark mode and TypeScript",
    container_tag="user_123",
)

# Pull the user profile

result = client.profile(container_tag="user_123", q="What does the user prefer?")
print("Static:", result["profile"]["static"])
print("Dynamic:", result["profile"]["dynamic"])

Both SDKs communicate with the REST endpoints defined in apps/api, orchestrating the extraction → chunking → embedding → graph indexing pipeline that transforms content into semantic memories.

Understanding the Local Architecture

When you set up Supermemory locally, you are running three logical layers simultaneously:

• Client Applications — Located in apps/web, apps/mcp, and apps/memory-graph-playground, providing the Next.js UI, Model Context Protocol server, and interactive graph visualization.

• API & Processing Pipeline — The apps/api directory (integrated into the web app) exposes REST endpoints at /v3/documents, /v3/search, and /v3/profile. These endpoints manage the pipeline that converts uploaded content into knowledge graph entries.

• Shared Packages — The packages/* directory contains validation schemas in packages/validation/api.ts, UI components, and the core AI SDK tools.

The processing pipeline runs in reverse during queries: requests are embedded, similar vectors are retrieved from the graph, relationships are expanded, and results are merged with dynamically generated user profiles.

Summary

• Install Bun ≥1.2.17 and Git before attempting to set up Supermemory locally
• Run bun install from the repository root to install all monorepo dependencies across apps/ and packages/
• Copy .env.example to .env.local and configure your SUPERMEMORY_API_KEY and optional Cloudflare credentials
• Execute bun run dev to start all services simultaneously via Turbo
• Access the web UI at http://localhost:3000 and the MCP server at http://localhost:8788
• Verify functionality by uploading content and querying via the TypeScript or Python SDKs

Frequently Asked Questions

What is the minimum Bun version required to set up Supermemory locally?

You need Bun version 1.2.17 or higher. The monorepo relies on specific workspace features and lockfile handling introduced in recent Bun releases. Earlier versions may fail to resolve dependencies correctly or execute the Turbo scripts.

Why does Supermemory use different ports for the web UI and API?

The web UI runs on Next.js default port 3000, while the API server listens on port 8787 (the Cloudflare Workers dev server default). The MCP server runs on port 8788. During local development, apps/web/proxy.ts routes requests between these services, allowing the frontend to communicate with the backend processing pipeline.

Can I modify the proxy behavior for custom local setups?

Yes. If you run the API on a non-standard port (for example, within Docker), edit apps/web/proxy.ts to adjust the conditional routing logic. The source file contains a localhost bypass pattern using NextResponse.next() that you can adapt to your specific network configuration.

What environment variables are required in .env.local?

At minimum, you need SUPERMEMORY_API_KEY for API authentication. If you plan to deploy or test Cloudflare Workers functionality locally, you must also provide CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN. The API_URL variable is optional and defaults to http://localhost:8787 for local development.

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