How to Contribute to the Supermemory Project: Complete Monorepo Guide

You can contribute to the Supermemory project by forking the repository, installing dependencies with Bun, configuring your environment variables, and submitting pull requests that pass the format-lint, type-check, and build validation pipeline.

Supermemory is a Turbo-powered monorepo delivering an AI-enhanced knowledge-graph API, a Next.js web front-end, and multi-language SDKs. Whether you specialize in frontend UI, backend API development, or AI tooling, understanding the architecture and contributing workflow will help you submit meaningful pull requests that improve the platform's document processing and semantic search capabilities.

Understand the Supermemory Architecture

Before you contribute to the Supermemory project, you must understand its three-layer architecture. The system separates client interactions from heavy processing and vector storage, enabling scalable AI-powered knowledge management.

The Three-Layer System

The codebase is organized into distinct architectural layers:

• Client Layer – Your application or the web UI sends REST requests to endpoints like /v3/documents and /v4/search
• API & Processing Pipeline – Cloudflare Workers running Hono accept uploads, validate requests, and queue content through extraction, chunking, and embedding stages
• Knowledge-Graph Store – Combines vector indexing (HNSW) with graph database relationships (Updates, Extends, Derives) to power semantic search

The entry point for the API layer is located at apps/mcp/src/server.ts, where the Hono server routes incoming requests to the appropriate handlers.

Content Processing Pipeline

Every document uploaded to Supermemory traverses a six-stage processing pipeline defined in the architecture documentation. When you contribute to the core engine, you will likely interact with one of these stages:

1. Queued – Content type detection and metadata validation via Zod schemas in packages/validation/
2. Extracting – PDF parsing, OCR, and transcription services
3. Chunking – Semantic boundary detection with context overlap
4. Embedding – Vector generation (typically 1536-dimensional) handled by packages/ai-sdk/
5. Indexing – Graph edge creation linking related memories
6. Done – Final persistence making the memory searchable

Repository Structure Overview

The Supermemory monorepo uses Turborepo for task orchestration. You must understand this layout to navigate the codebase effectively:

supermemory/
├── apps/
│   ├── web/                 # Next.js 19 front-end (React, Tailwind)

│   ├── mcp/                 # Model Context Protocol server (Hono/Workers)

│   └── browser-extension/   # WXT-based Chrome/Edge extension

├── packages/
│   ├── lib/                 # Shared utilities, auth, API client

│   ├── ai-sdk/              # Core AI SDK (embeddings, LLM tools)

│   ├── validation/          # Zod schemas for request validation

│   └── openai-sdk-python/   # Python wrapper for OpenAI integration

├── turbo.json                # Monorepo task runner configuration

└── biome.json                # Unified lint and format rules

Key configuration files include turbo.json for pipeline definitions and biome.json for code quality standards that all contributions must satisfy.

Setting Up Your Development Environment

To contribute to the Supermemory project, you must use Bun as your package manager and JavaScript runtime. The project does not support npm or yarn for development workflows.

Run these commands from the repository root:

# Install all dependencies across the monorepo

bun install

# Configure environment variables

cp .env.example .env.local

# Start the development stack (web, MCP, and extension)

bun run dev

The bun run dev command launches the full stack simultaneously, enabling you to test integration between the Next.js frontend and Cloudflare Workers backend on your local machine.

Contribution Workflow and Guidelines

Supermemory follows a standard GitHub flow with strict quality gates. Before submitting your contribution, ensure your changes pass the automated validation pipeline.

Follow these steps:

1. Fork and clone the repository to your GitHub account
2. Create a feature branch using the naming convention feature/your-feature or fix/bug-description
3. Make atomic commits with clear messages describing the architectural change
4. Run quality checks before pushing:
   • bun run format-lint – Enforces Biome formatting and linting rules
   • bun run check-types – Validates TypeScript across all packages
   • bun run build – Ensures production builds succeed
5. Open a Pull Request using the template with prefixes like feat: or fix: in the title

All contribution standards are documented in CONTRIBUTING.md at the repository root, which includes detailed environment setup instructions and PR review criteria.

Where to Contribute: Key Areas

Depending on your expertise, you can contribute to the Supermemory project across several domains:

Frontend Development (apps/web/)

Typical tasks: Building new pages with Next.js 19, improving React component accessibility, fixing UI bugs, or enhancing the Tailwind-based design system.

Key files include apps/web/pages/**/*.tsx for routing and packages/ui/** for shared component libraries.

API and Worker Development (apps/mcp/)

Typical tasks: Implementing new REST endpoints in the Hono server, improving request validation middleware, or optimizing the Cloudflare Workers execution environment.

The main entry point is apps/mcp/src/server.ts, with route handlers organized in apps/mcp/src/routes/. Authentication middleware resides in packages/lib/auth.middleware.ts.

SDK and Core Library Development (packages/)

Typical tasks: Exposing new AI tools in the TypeScript SDK, wrapping additional Cloudflare AI models, or enhancing the Python OpenAI integration.

Critical packages include packages/ai-sdk/src/tools.ts for embedding abstractions and packages/lib/api.ts for the central API client used across the monorepo.

Core Engine and Validation

Typical tasks: Refining semantic chunking algorithms, implementing embedding cache layers, or optimizing graph indexing in the vector store.

Work in packages/validation/ involves updating Zod schemas in packages/validation/api.ts to enforce API contracts.

Code Examples for Contributors

Adding a New API Endpoint

When contributing to the Supermemory API, you will create Hono routes that validate input with Zod and queue documents for processing:

// apps/mcp/src/routes/documents.ts
import { Router } from 'hono';
import { validateDocument } from '@repo/validation';
import { processDocument } from '@repo/lib';

const router = new Router();

router.post('/v3/documents', async (c) => {
  const body = await c.req.json();
  const parsed = validateDocument(body); // Zod validation
  const docId = await processDocument(parsed); // queues for extraction
  return c.json({ id: docId, status: 'queued' });
});

export default router;

This pattern leverages the shared validation schemas in packages/validation/api.ts and the processing queue logic in packages/lib/api.ts.

Building Frontend Components

Frontend contributions should use the centralized API client and TanStack Query for server state management:

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { uploadDocument } from '@repo/lib/api';

export function UploadButton() {
  const queryClient = useQueryClient();
  const mutation = useMutation(uploadDocument, {
    onSuccess: () => queryClient.invalidateQueries(['documents']),
  });

  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
    if (e.target.files?.[0]) {
      const file = e.target.files[0];
      await mutation.mutateAsync({ file });
    }
  };

  return <input type="file" onChange={handleFile} disabled={mutation.isLoading} />;
}

Reference the API client implementation in packages/lib/api.ts and React Query hooks in packages/hooks/use-onboarding-storage.ts for state management patterns.

Running the Full Development Stack

Verify your changes work across the entire system:

# From the repository root

bun install                 # install all deps

cp .env.example .env.local  # configure env vars

bun run dev                # launches web, mcp, and extension

This command sequence is documented in CONTRIBUTING.md under the development environment setup section.

Summary

• Supermemory is a Turbo monorepo with a Next.js frontend, Cloudflare Workers API, and Python/TypeScript SDKs that you can contribute to via GitHub pull requests
• Architecture follows a three-layer pattern: Client → API Pipeline (Hono/Workers) → Knowledge-Graph Vector Store
• Setup requires Bun exclusively (bun install, bun run dev) and environment configuration via .env.local
• Quality gates include bun run format-lint, bun run check-types, and bun run build which must pass before submitting PRs
• Key contribution areas include the web frontend (apps/web/), MCP API server (apps/mcp/src/server.ts), validation schemas (packages/validation/), and AI SDK tools (packages/ai-sdk/)

Frequently Asked Questions

What package manager does Supermemory use for contributions?

Supermemory exclusively uses Bun for dependency management and script execution. You cannot use npm or yarn to install dependencies or run the development server. The bun install command handles the monorepo's workspace configuration defined in the root package.json.

Do I need Cloudflare credentials to contribute to the API layer?

While you can develop frontend components without Cloudflare credentials, contributing to the API layer in apps/mcp/ requires valid environment variables for Cloudflare Workers and associated AI services. Copy .env.example to .env.local and fill in the required API keys for document processing and embedding generation.

How does the content processing pipeline handle errors?

The pipeline implements stage-specific error handling in packages/lib/api.ts. If extraction fails, the document remains in the Extracting stage with error metadata; if embedding fails, it halts before Indexing. Contributors can enhance retry logic and dead-letter queues in the processing functions to improve reliability.

Where should I add validation for new API endpoints?

All Zod validation schemas belong in packages/validation/api.ts. When you contribute new endpoints to apps/mcp/src/routes/, import the validation functions from @repo/validation rather than defining schemas inline. This ensures type safety across both the frontend and backend packages.

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