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

> Learn how to add new features to Supermemory by forking the repo, creating a branch, implementing changes with Zod validation, and testing locally before submitting a pull request. A full developer guide.

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

---

**Adding new features to Supermemory requires forking the repository, creating a feature branch, implementing changes with proper Zod validation in [`packages/validation/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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/*`.

```bash

# Clone your fork

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

# Install monorepo dependencies

bun install

```

Reference the root [`package.json`](https://github.com/supermemoryai/supermemory/blob/main/package.json) for available scripts, including `dev`, `build`, and quality checks as documented in [`CLAUDE.md`](https://github.com/supermemoryai/supermemory/blob/main/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.

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts). This centralizes type validation and enables automatic type inference across the monorepo.

For example, to add a tag endpoint:

```typescript
// 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`](https://github.com/supermemoryai/supermemory/blob/main/packages/lib/api.ts) to include the new endpoint. The `$fetch` client uses these schemas for type-safe HTTP requests.

```typescript
// 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.

```typescript
// 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`](https://github.com/supermemoryai/supermemory/blob/main/package.json) and documented in the Development Workflow section of [`CLAUDE.md`](https://github.com/supermemoryai/supermemory/blob/main/CLAUDE.md).

```bash

# 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:

```bash
bun test packages/tools

```

## Submit Your Pull Request

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

```bash
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`](https://github.com/supermemoryai/supermemory/blob/main/.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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts) when adding API endpoints
- **Register routes** in [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/validation/api.ts), then import these types into [`packages/lib/api.ts`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/.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.