supermemory 开源贡献指南：Monorepo 开发环境搭建、代码规范与提交流程

supermemory 开源贡献指南：Monorepo 开发环境搭建、代码规范与提交流程

【免费下载链接】supermemoryMemory and context engine + app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory

supermemory 是一个面向 AI 时代的记忆层（Memory Layer）与上下文引擎，采用 Bun + Turbo 构建的多包 Monorepo 架构。本篇指南以仓库根目录的 CONTRIBUTING.md 为骨架，结合 package.json、turbo.json、biome.json 及各子应用的真实配置，完整讲解从零搭建本地开发环境、理解仓库结构、遵循代码规范到成功提交 Pull Request 的全过程。读完本文，你将掌握 supermemory 的本地开发工作流、Monorepo 各模块的职责划分，以及一套可立即上手的贡献标准动作。

开发环境准备：前置条件与初始化

前置依赖

在开始之前，请确保本机已安装以下工具：

• Bun（>= 1.2.17）：项目首选包管理器。根目录 package.json 通过packageManager字段锁定为bun@1.3.6，同时engines声明要求Node.js >= 20，用于运行 Next.js 等工具链；
• Git：版本控制，用于 Fork、Clone 与分支管理。

克隆与安装依赖

git clone https://gitcode.com/GitHub_Trending/su/supermemory.git cd supermemory bun install

bun install会依据根目录 package.json 中声明的workspaces（apps/*与packages/*，其中apps/raycast-extension与tools/test/chatapp被排除）一次性安装所有工作区依赖，并生成根目录的bun.lock锁定文件。

配置环境变量

# 复制示例环境文件 cp apps/web/.env.example apps/web/.env.local # 按需编辑：填入 API Key 与数据库 URL

以 Web 应用为例，apps/web/.env.example 定义了三个关键变量：

需要注意的是，浏览器扩展等子应用也有独立的 apps/browser-extension/.env.example，接入不同子应用时请到对应目录下复制环境文件。

启动本地开发服务器：dev:local 与 dev 的区别

推荐方式：bun run dev:local

bun run dev:local

这是官方推荐给 OSS 贡献者的启动方式。根目录 package.json 中该命令映射为turbo run dev:app，由 turbo.json 定义的dev:app任务驱动各子应用并行启动，每个应用监听独立的 localhost 端口：

dev:local模式下，Web 应用通过.env.example中的NEXT_PUBLIC_BACKEND_URL指向公共 APIhttps://api.supermemory.ai。由于是纯 localhost 环境，登录时请使用magic-link / 邮件 OTP方式——Google/GitHub OAuth 的回调无法往返回到 localhost，这一点在 CONTRIBUTING.md 中有明确说明。

内部团队方式：bun run dev

bun run dev（不带:local）会经由 portless 路由，为每个应用分配稳定的*.dev.supermemory.aiHTTPS 域名，实现共享 Cookie 与可用的 OAuth 代理。首次使用需要执行bun run setup:dev（绑定 443 端口并信任本地 CA）。这是内部团队的工作流，OSS 贡献者无需配置。

Monorepo 项目结构

supermemory 是一个使用 Turbo 组织的 Monorepo。CONTRIBUTING.md 给出了整体骨架，结合仓库当前实际布局，完整结构如下：

supermemory/ ├── apps/ # 可独立部署的应用 │ ├── web/ # Next.js Web 主应用（React 19 + Tailwind） │ ├── browser-extension/ # 浏览器扩展（WXT 框架） │ ├── docs/ # 文档站（Mintlify） │ ├── mcp/ # MCP Server（Cloudflare Worker + Hono） │ ├── memory-graph-playground/ # 记忆图谱交互式 Playground │ ├── raycast-extension/ # Raycast 扩展 │ └── sdk-playground/ # SDK 演示应用 ├── packages/ # 共享包 │ ├── ui/ # 共享 UI 组件（Radix + shadcn 风格） │ ├── lib/ # 共享工具与业务逻辑 │ ├── hooks/ # 共享 React Hooks │ ├── validation/ # Zod Schema 与校验 │ ├── ai-sdk/ # AI SDK 记忆操作封装 │ ├── tools/ # 各框架（Mastra/OpenAI/Vercel/VoltAgent）工具集成 │ ├── memory-graph/ # 记忆图谱可视化库 │ ├── agent-framework-python/ # Python Agent 框架集成 │ ├── openai-sdk-python/ # Python OpenAI SDK 集成 │ ├── cartesia-sdk-python/ # Cartesia SDK 集成 │ └── pipecat-sdk-python/ # Pipecat SDK 集成 ├── turbo.json # Turbo 任务编排 ├── biome.json # Biome 格式化与 Lint 配置 └── package.json # 根包配置（workspaces / scripts）

说明：原文档中列举的openai-sdk-ts、eslint-config、typescript-config三个包在当前仓库中已被实际的 Python SDK 包族与memory-graph等取代，以上结构以仓库现状为准。

常用脚本命令

根目录 package.json 聚合了全部工作流命令，配合 turbo.json 的任务依赖（build、check-types均声明dependsOn: ["^build"]/["^check-types"]，保证按依赖拓扑顺序执行）：

turbo.json中dev与dev:app任务均设置了"cache": false与"persistent": true（turbo.json），确保长期运行的开发进程不被 Turbo 缓存干扰；build任务的输出目录限定为.next/**与dist/**（turbo.json），构建产物可被 Turbo 增量缓存。

技术栈一览

根据 CONTRIBUTING.md 与各应用的真实依赖清单，项目技术栈如下：

• 前端：Next.js（当前仓库锁定^16.0.11）、React 19、TypeScript 5.8，参见 apps/web/package.json；
• 样式：Tailwind CSS 4、Radix UI 组件、shadcn 风格封装（packages/ui/components）；
• 状态管理：Zustand 管理全局状态（zustand@^5.0.7）、TanStack Query 管理服务端状态（@tanstack/react-query@^5.90.14）；
• 构建工具：Turbo 2.5 驱动 Monorepo 任务编排；
• 包管理器：Bun（根packageManager: bun@1.3.6）；
• 部署：Cloudflare（Web 通过opennextjs-cloudflare构建部署，MCP 通过wrangler deploy，见 apps/mcp/package.json）。

如何贡献：从 Issue 到分支

贡献类型

项目欢迎多种形式的贡献：🐛 Bug 修复、✨ 新功能、🎨 UI/UX 优化、⚡ 性能优化。寻找任务时，可以优先关注仓库 Issues 中标记为good first issue（适合新手）与help wanted的问题；新功能建议先开 Issue 讨论再动手，避免方向偏差。

创建分支

git checkout -b feature/your-feature-name # 或 git checkout -b fix/your-bug-fix

分支命名采用feature/或fix/前缀，保持与提交内容语义一致。

本地验证

提交前依次执行质量检查（对应 CONTRIBUTING.md 的提交流程）：

bun run format-lint # Biome 格式化与 Lint bun run check-types # 全仓类型检查 bun run build # 确认可构建

代码规范：Biome 与 TypeScript 实践

Biome 配置要点

根目录 biome.json 是格式化与 Lint 的唯一事实来源，几个关键配置：

• 格式化：indentStyle: "tab"（缩进使用 Tab），JS 采用双引号quoteStyle: "double"、省略分号semicolons: "asNeeded"（biome.json）；
• Lint：启用recommended规则集，并额外开启useExhaustiveDependencies、noUnusedVariables、noUnusedImports等正确性检查；style域中noInferrableTypes、noParameterAssign、noUselessElse、useAsConstAssertion等设为error（biome.json）；
• VCS 集成：开启vcs.enabled并使用.gitignore，已忽略的目录不会参与检查。

执行bun run format-lint（即bunx biome check --write）可自动修复大部分格式问题。

编码总体原则

• 新代码一律使用TypeScript；
• 遵循既有代码风格与模式，编写自文档化代码（清晰的变量命名）；
• 复杂函数补充 JSDoc 注释；
• 保持函数小而聚焦，单一职责。

组件与命名规范

• 组件：优先函数组件 + Hooks，组合优于继承，可复用逻辑抽取为自定义 Hook，props 使用完整 TypeScript 类型；
• 文件命名：文件名kebab-case（如search-request.ts），组件文件PascalCase（如DashboardView.tsx），工具函数camelCase。

Import 组织顺序

仓库约定按四层分组导入，见 CONTRIBUTING.md：

// 1. React 与 Next.js 导入 import React from 'react'; import { NextPage } from 'next'; // 2. 第三方库 import { clsx } from 'clsx'; import { motion } from 'motion'; // 3. 内部包 import { Button } from '@repo/ui'; import { useAuth } from '@repo/lib'; // 4. 相对路径导入 import { Header } from './header'; import { Footer } from './footer';

Pull Request 流程

提交前检查清单

1. 确保分支与main保持同步；
2. 运行全部质量检查（format-lint / check-types / build）；
3. 充分测试改动；
4. 如涉及文档，同步更新对应文档。

PR 编写规范

• 标题：清晰描述性标题，遵循 Conventional Commits 风格。示例：
  • ✅feat: add semantic search to memory graph
  • ✅fix: resolve authentication redirect loop
  • ❌update stuff
• 描述：说明改动内容与原因；UI 改动附截图；标注破坏性变更；关联 Issue 编号；
• 体量：保持 PR 聚焦，优先多个小 PR 而非一个大 PR，每个 PR 只解决单一问题。

Review 流程

所有 PR 至少需要一次评审。收到反馈后及时、专业地响应，保持开放协作态度。仓库根目录的 README.md 与 README.zh-CN.md 会持续收录贡献者名单与 Release Notes，每一份贡献都会被记录。

报告 Issue 的规范模板

Bug 报告

提交 Bug 时请包含：环境（操作系统、Node.js 版本、浏览器）、复现步骤、预期行为、实际行为、截图（如适用）、错误信息或控制台日志。清晰的复现路径是维护者定位问题的最快方式。

功能请求

功能建议请提供：问题陈述（解决什么问题）、方案设想（期望如何工作）、备选方案（考虑过的其他做法）、附加上下文。这有助于维护者评估方案的合理性与实现成本。

架构设计约定

CONTRIBUTING.md 对模块实现提出了统一约定，这些约定与仓库源码一一对应：

状态管理

• 全局状态使用Zustand：如 apps/web/stores 下的chat.ts、highlights.ts、indexeddb-storage.ts等 store 即采用 Zustand 模式；
• 服务端状态使用TanStack Query：仓库大量use-*.tsHooks（见 apps/web/hooks）均基于@tanstack/react-query封装；
• 状态尽量本地化，为状态提供完整 TypeScript 类型。

API 集成

• 复用既有 API 客户端模式（参考 packages/lib/api.ts）；
• 妥善处理 loading 与 error 状态；
• 实现合理的 Error Boundary；
• 在合适的场景使用乐观更新（optimistic updates）提升交互体验。

性能

• 对昂贵组件使用React.memo()；
• 实现恰当的加载状态与骨架屏；
• 优化图片与静态资源；
• 按需使用代码分割（code splitting）。

社区准则与许可

参与贡献需遵守社区行为准则：保持尊重与包容、欢迎并帮助新人、聚焦建设性反馈、全程保持专业。有问题可以在 Discord、GitHub Discussions 讨论，Bug 报告走 Issues。

根据 CONTRIBUTING.md，贡献者同意其贡献将与项目采用相同的开源许可（见仓库根目录 LICENSE），所有贡献者都会在 README 与 Release Notes 中获得致谢。无论贡献大小，每一份参与都在共同推进 AI 记忆层基础设施的演进。

【免费下载链接】supermemoryMemory and context engine + app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory