# How to Set Up Supermemory Locally: Complete Developer Guide

> Set up Supermemory locally with this developer guide. Follow simple steps to install, clone the repo, configure, and run the Next.js UI and MCP server today.

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

---

**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:
  
  ```bash
  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:

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

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/apps/web/proxy.ts):

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

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/packages/ai-sdk/src/tools.ts). Use it to add memories and retrieve dynamic profiles:

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

```python
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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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.