How to Add New Features to Supermemory: A Complete Developer Guide

Adding new features to Supermemory requires forking the repository, creating a feature branch, implementing changes with proper Zod validation in packages/validation/api.ts, writing tests in packages/tools/test/, and passing local checks including bun run format-lint and bun run check-types before submitting a pull request.

Contributing to the Supermemory open-source project follows a structured workflow designed to maintain code quality across its Turborepo architecture. This guide explains the complete process to add new features to Supermemory, covering environment setup, validation patterns, and submission requirements. Following these steps ensures your TypeScript code integrates cleanly with the existing Next.js application and shared library packages.

Fork and Set Up Your Development Environment

Begin by creating a personal fork of the repository and cloning it locally. The project uses Bun as its package manager, so install dependencies from the repository root to pull in all shared packages across apps/* and packages/*.

# Clone your fork

git clone https://github.com/your-username/supermemory.git
cd supermemory

# Install monorepo dependencies

bun install

Reference the root package.json for available scripts, including dev, build, and quality checks as documented in CLAUDE.md.

Create a Feature Branch

Follow the branch naming convention to keep the repository organized. Use feature/your-feature-name for new functionality or fix/description for bug fixes.

git checkout -b feature/your-feature-name

Implement Your Feature

Place new source files in the appropriate package directory, such as packages/lib for shared utilities, packages/tools for CLI utilities, or apps/web for frontend features.

Update Validation Schemas

If your feature exposes a new API endpoint, extend the Zod schemas in packages/validation/api.ts. This centralizes type validation and enables automatic type inference across the monorepo.

For example, to add a tag endpoint:

// packages/validation/api.ts
import { z } from "zod";

export const AddTagSchema = z.object({
  tag: z.string().min(1).max(30),
  containerTag: z.string(),
});

export const TagResponseSchema = z.object({
  id: z.string(),
  tag: z.string(),
  createdAt: z.string().datetime(),
});

Register the API Route

Update the API client in packages/lib/api.ts to include the new endpoint. The $fetch client uses these schemas for type-safe HTTP requests.

// packages/lib/api.ts
export const $fetch = createFetch({
  baseURL: `${process.env.NEXT_PUBLIC_BACKEND_URL ?? "https://api.supermemory.ai"}/v3`,
  credentials: "include",
  retry: { attempts: 3, delay: 100, type: "linear" },
  schema: apiSchema,
});

// New helper for the tag endpoint
export const addTag = (input: z.infer<typeof AddTagSchema>) =>
  $fetch.post("@post/tags", { input });

Write Tests for New Features

Create unit or integration tests under the corresponding package's test/ folder. For API features, place tests in packages/tools/test/ using Bun's test runner.

// packages/tools/test/add-tag.test.ts
import { describe, it, expect } from "bun:test";
import { addTag } from "@repo/lib/api";

describe("Tag API", () => {
  it("creates a new tag", async () => {
    const res = await addTag({ tag: "important", containerTag: "proj_123" });
    expect(res).toHaveProperty("id");
    expect(res.tag).toBe("important");
  });
});

Validate Your Changes Locally

Before committing, run the quality assurance scripts defined in the root package.json and documented in the Development Workflow section of CLAUDE.md.

# Format and lint with Biome

bun run format-lint

# TypeScript type-checking across the monorepo

bun run check-types

# Verify functionality in development

bun run dev

Execute the test suite to ensure your changes don't break existing functionality:

bun test packages/tools

Submit Your Pull Request

Commit your changes using conventional commit messages (feat:, fix:) and push to your fork.

git commit -m "feat: add tag endpoint with validation"
git push origin feature/your-feature-name

Open a pull request targeting the upstream main branch. The CI pipeline defined in .github/workflows/ci.yml automatically runs lint, type-check, build, and test steps on your PR.

Address reviewer feedback by updating code and tests, then pushing additional commits. Once all checks pass and at least one reviewer approves, your contribution can be merged into the main branch.

Summary

• Fork and clone the repository, then run bun install to set up the monorepo environment
• Create feature branches using the feature/name convention to organize your work
• Extend validation schemas in packages/validation/api.ts when adding API endpoints
• Register routes in packages/lib/api.ts using the type-safe $fetch client
• Write tests in packages/tools/test/ or the appropriate package's test directory
• Run local checks with bun run format-lint and bun run check-types before submitting
• Target the main branch with conventional commit messages and clear PR descriptions

Frequently Asked Questions

Where do I place new source code when adding features to Supermemory?

Place new source files in the appropriate package directory based on functionality. Use packages/lib for shared utilities, packages/tools for CLI utilities, apps/web for Next.js frontend code, and packages/validation for Zod schemas. This monorepo structure keeps concerns separated and enables efficient builds.

What validation library does Supermemory use for API endpoints?

Supermemory uses Zod for schema validation. Define request and response schemas in packages/validation/api.ts, then import these types into packages/lib/api.ts when registering new $fetch routes. This ensures end-to-end type safety from the backend to the frontend API client.

Which test runner does the Supermemory project use?

The project uses Bun's built-in test runner (bun:test). Write tests in TypeScript files under the test/ directory of the relevant package, such as packages/tools/test/add-tag.test.ts. Run tests with bun test <package-name> to validate your changes locally.

What happens after I submit a pull request to Supermemory?

After submission, the CI pipeline in .github/workflows/ci.yml automatically executes formatting checks, TypeScript validation, builds, and tests. Reviewers will examine your code for adherence to project standards. Once approved and all checks pass, maintainers merge your branch into main, triggering the release pipeline.

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