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/supermemorysupermemory 是一个面向 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字段锁定为bun1.3.6同时engines声明要求Node.js 20用于运行 Next.js 等工具链Git版本控制用于 Fork、Clone 与分支管理。克隆与安装依赖git clone https://gitcode.com/GitHub_Trending/su/supermemory.git cd supermemory bun installbun install会依据根目录 package.json 中声明的workspacesapps/*与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 定义了三个关键变量变量名示例值说明NEXT_PUBLIC_BACKEND_URLhttps://api.supermemory.ai前端请求的后端 API 地址dev:local模式下默认指向公共 APINEXT_PUBLIC_POSTHOG_KEY空PostHog 产品分析密钥本地开发可留空NEXT_PUBLIC_AGENTID_AUTH_ENABLED空是否启用 Agent ID 认证的开关需要注意的是浏览器扩展等子应用也有独立的 apps/browser-extension/.env.example接入不同子应用时请到对应目录下复制环境文件。启动本地开发服务器dev:local 与 dev 的区别推荐方式bun run dev:localbun run dev:local这是官方推荐给 OSS 贡献者的启动方式。根目录 package.json 中该命令映射为turbo run dev:app由 turbo.json 定义的dev:app任务驱动各子应用并行启动每个应用监听独立的 localhost 端口应用端口启动脚本依据Web 应用Next.js3000apps/web/package.json 中next dev --port ${PORT:-3000}MCP ServerWrangler8788apps/mcp/package.json 中wrangler dev --port ${PORT:-8788}文档站Mintlify3003apps/docs/package.json 中bunx mintlifylatest dev --no-open --port 3003记忆图谱 Playground3004apps/memory-graph-playground/package.json 中next dev --port ${PORT:-3004}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 devbun 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 ServerCloudflare 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]保证按依赖拓扑顺序执行命令实际执行用途bun run dev:localturbo run dev:app在 localhost 端口启动全部开发服务器OSS 贡献者推荐bun run devturbo run dev通过 portless 启动内部团队使用bun run buildturbo run build构建所有应用与包bun run format-lintbunx biome check --write使用 Biome 格式化并修复 Lint 问题bun run check-typesturbo run check-types全仓类型检查turbo.json中dev与dev:app任务均设置了cache: false与persistent: trueturbo.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: bun1.3.6部署CloudflareWeb 通过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缩进使用 TabJS 采用双引号quoteStyle: double、省略分号semicolons: asNeededbiome.jsonLint启用recommended规则集并额外开启useExhaustiveDependencies、noUnusedVariables、noUnusedImports等正确性检查style域中noInferrableTypes、noParameterAssign、noUselessElse、useAsConstAssertion等设为errorbiome.jsonVCS 集成开启vcs.enabled并使用.gitignore已忽略的目录不会参与检查。执行bun run format-lint即bunx biome check --write可自动修复大部分格式问题。编码总体原则新代码一律使用TypeScript遵循既有代码风格与模式编写自文档化代码清晰的变量命名复杂函数补充 JSDoc 注释保持函数小而聚焦单一职责。组件与命名规范组件优先函数组件 Hooks组合优于继承可复用逻辑抽取为自定义 Hookprops 使用完整 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 流程提交前检查清单确保分支与main保持同步运行全部质量检查format-lint / check-types / build充分测试改动如涉及文档同步更新对应文档。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/supermemorysupermemory 是一个面向 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字段锁定为bun1.3.6同时engines声明要求Node.js 20用于运行 Next.js 等工具链Git版本控制用于 Fork、Clone 与分支管理。克隆与安装依赖git clone https://gitcode.com/GitHub_Trending/su/supermemory.git cd supermemory bun installbun install会依据根目录 package.json 中声明的workspacesapps/*与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 定义了三个关键变量变量名示例值说明NEXT_PUBLIC_BACKEND_URLhttps://api.supermemory.ai前端请求的后端 API 地址dev:local模式下默认指向公共 APINEXT_PUBLIC_POSTHOG_KEY空PostHog 产品分析密钥本地开发可留空NEXT_PUBLIC_AGENTID_AUTH_ENABLED空是否启用 Agent ID 认证的开关需要注意的是浏览器扩展等子应用也有独立的 apps/browser-extension/.env.example接入不同子应用时请到对应目录下复制环境文件。启动本地开发服务器dev:local 与 dev 的区别推荐方式bun run dev:localbun run dev:local这是官方推荐给 OSS 贡献者的启动方式。根目录 package.json 中该命令映射为turbo run dev:app由 turbo.json 定义的dev:app任务驱动各子应用并行启动每个应用监听独立的 localhost 端口应用端口启动脚本依据Web 应用Next.js3000apps/web/package.json 中next dev --port ${PORT:-3000}MCP ServerWrangler8788apps/mcp/package.json 中wrangler dev --port ${PORT:-8788}文档站Mintlify3003apps/docs/package.json 中bunx mintlifylatest dev --no-open --port 3003记忆图谱 Playground3004apps/memory-graph-playground/package.json 中next dev --port ${PORT:-3004}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 devbun 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 ServerCloudflare 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]保证按依赖拓扑顺序执行命令实际执行用途bun run dev:localturbo run dev:app在 localhost 端口启动全部开发服务器OSS 贡献者推荐bun run devturbo run dev通过 portless 启动内部团队使用bun run buildturbo run build构建所有应用与包bun run format-lintbunx biome check --write使用 Biome 格式化并修复 Lint 问题bun run check-typesturbo run check-types全仓类型检查turbo.json中dev与dev:app任务均设置了cache: false与persistent: trueturbo.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: bun1.3.6部署CloudflareWeb 通过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缩进使用 TabJS 采用双引号quoteStyle: double、省略分号semicolons: asNeededbiome.jsonLint启用recommended规则集并额外开启useExhaustiveDependencies、noUnusedVariables、noUnusedImports等正确性检查style域中noInferrableTypes、noParameterAssign、noUselessElse、useAsConstAssertion等设为errorbiome.jsonVCS 集成开启vcs.enabled并使用.gitignore已忽略的目录不会参与检查。执行bun run format-lint即bunx biome check --write可自动修复大部分格式问题。编码总体原则新代码一律使用TypeScript遵循既有代码风格与模式编写自文档化代码清晰的变量命名复杂函数补充 JSDoc 注释保持函数小而聚焦单一职责。组件与命名规范组件优先函数组件 Hooks组合优于继承可复用逻辑抽取为自定义 Hookprops 使用完整 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 流程提交前检查清单确保分支与main保持同步运行全部质量检查format-lint / check-types / build充分测试改动如涉及文档同步更新对应文档。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考