面向 Claude Code 与开发者的 supermemory 开发指南Turbo 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 仓库根目录的 CLAUDE.md 为骨架系统梳理该 Turbo Monorepo 的整体结构、开发命令、前后端架构、内容处理管线、Cloudflare 部署配置与代码质量规范。读者将能快速掌握如何在本地用 Bun 驱动整个 monorepo 的开发与构建理解/v3/*API 与 MCP 服务端的关系并了解该仓库面向 AI 编程助手Claude Code设计的关键上下文约定。一、CLAUDE.md 是什么给 Claude Code 的仓库导航文件CLAUDE.md是项目根目录下的一份特殊说明文档其定位是向 Claude Codeclaude.ai/code等 AI 编程助手提供在本仓库内工作时的上下文指引——包括仓库布局、可用的开发命令、技术栈选型、核心工作流以及必须遵守的工程规范。它的存在意味着当 AI 助手进入该仓库时可以依赖这份文件快速建立全局认知避免误读目录结构、使用错误的包管理器或绕过既定的 lint/type-check 流程。对人工开发者而言它同样是一份高质量的 onboarding 文档下面各节将逐一展开其中的每一条。二、仓库结构Turbo Monorepo 的应用与共享包布局CLAUDE.md 明确指出这是一个Turbo monorepo包含多个应用Applications与共享包Shared Packages。结合根目录 package.json 的workspaces字段可以看到实际范围workspaces: [ apps/*, !apps/raycast-extension, !tools/test/chatapp, packages/* ]应用层apps/应用说明关键入口apps/webNext.js Web 应用用户控制台 / 产品前端apps/web/package.jsonapps/mcpModel Context Protocol 服务端以 Cloudflare Worker 形式运行apps/mcp/package.json值得注意的是仓库中还存在apps/browser-extension、apps/raycast-extension、apps/memory-graph-playground、apps/sdk-playground与apps/docs等目录它们被显式排除在根 workspaces 之外或作为独立子项目维护——这解释了为什么 CLAUDE.md 只把web与mcp列为受 Turbo 编排的核心应用。共享包层packages/monorepo 的共享代码沉淀在packages/下包括libAPI 客户端、认证上下文、查询封装、validationzod schema、ui组件库、toolsAI 工具封装、hooks、memory-graph等。Web 应用通过workspace:*协议引用它们例如 apps/web/package.json 中的repo/lib: workspace:*与repo/validation: workspace:*。Turbo 的任务编排定义在根目录 turbo.jsonbuild任务通过dependsOn: [^build]保证先构建依赖包dev/dev:app任务关闭缓存并标记为persistent长驻进程check-types与lint同样按依赖拓扑传播。三、开发命令从根目录到子应用的一键工作流根级命令Monorepo 维度CLAUDE.md 给出的根级命令与 package.json 中的 scripts 一一对应命令作用底层实现bun run dev启动所有应用的开发模式turbo run devbun run build构建所有应用turbo run buildbun run check-types对所有应用执行 TypeScript 类型检查turbo run check-typesbun run format-lint使用 Biome 统一格式化与 lintbunx biome check --writebun run dev:local本地开发模式应用侧turbo run dev:app额外的工程化脚本还包括sentry:sourcemaps构建后将 sourcemap 上传 Sentry--strip-prefix dist/..以及postbuild构建后自动触发 sourcemap 上传。环境约束来自根 package.json包管理器为Bun版本固定为bun1.3.6packageManager字段要求Node.js 20engines.node。Web 应用命令apps/web/进入apps/web后的常用命令命令作用bun run dev启动 Next.js 开发服务器经由portless实际执行next dev --port ${PORT:-3000}bun run build构建 Next.js 应用next buildbun run lint使用 Biome 检查并写入修复biome check --writebun run preview/deploy/upload基于 OpenNext for Cloudflare 的构建与部署bun run cf-typegen生成 Cloudflare 环境类型声明MCP 应用apps/mcp则使用wrangler dev --port ${PORT:-8788}启动本地 Worker并提供test:unit/test:e2evitest与studiowidget 调试面板等专用命令详见 apps/mcp/package.json。四、架构概览技术栈与核心模块核心技术栈CLAUDE.md 明确列出的技术选型运行时/框架Next.jsWeb 与 API 应用语言全仓 TypeScript包管理器BunMonorepo 编排Turbo认证Better Auth支持组织化账号体系监控Sentry含 sourcemap 上传与上下文追踪API 应用主后端API 承担核心后端职责CLAUDE.md 列出以下关键路由。从 MCP 服务端源码可以看到这些端点的实际调用——例如 apps/mcp/src/server/client/index.ts 中通过fetch(\${this.apiUrl}/v3/container-tags/list)拉取容器标签同文件第 340 行调用/v3/documents/documents 获取文档列表路由职责/v3/documents文档/记忆的增删改查CRUD/v3/search对已索引内容的语义搜索/v3/connections外部服务集成Google Drive、Notion、OneDrive 等/v3/settings组织与用户设置/v3/analytics用量统计与报表/api/auth/*认证端点Better Auth 挂载点Web 应用Next.js 前端为用户提供可视化界面覆盖文档管理、语义搜索、连接器配置与用量分析等能力。其依赖结构apps/web/package.json印证了 CLAUDE.md 的描述next、radix-ui/*无障碍 UI 原语、tanstack/react-query服务端状态缓存、recharts分析图表并集成sentry/nextjs、PostHogposthog-js等可观测性组件。MCP 服务端虽然 CLAUDE.md 未展开 MCP 细节但作为apps/mcp的核心应用其服务端结构apps/mcp/src/server/值得补充说明包含auth含 RBAC 实现及index.test.ts/rbac.test.ts测试、client对/v3/*API 的封装、toolsadd-memory、search-memory、save-memory、list-memories、memory-graph、upload-file等十余个 MCP 工具以及space.ts/container-tag.ts/analytics.ts等业务模块。五、关键依赖一览共享依赖better-auth认证系统内置组织organization支持drizzle-orm数据库 ORMzodschema 校验配合drizzle-zod、zod-openapi生成类型与 OpenAPI 文档honoWeb 框架API 与 MCP 均使用见 apps/mcp/package.json 的hono依赖sentry/*错误监控turbomonorepo 构建系统。根 package.json 中还有一组值得注意的依赖hono/zod-validator、hono-openapi、scalar/hono-api-reference自动生成 API 参考文档、neverthrowResult 风格错误处理、pino结构化日志、pg/postgresPostgreSQL 驱动、resend邮件、cloudflare与wranglerWorker 工具链。Web 专属依赖nextReact 框架radix-ui/*UI 组件原语dialog、dropdown-menu、select、tooltip 等tanstack/react-query数据请求与缓存recharts分析图表可视化以及 TipTap富文本/Markdown 编辑器、d3-force记忆图谱力导向布局、zustand客户端状态等。六、开发工作流内容处理管线CLAUDE.md 指出所有内容都经由IngestContentWorkflow处理管线覆盖五个环节内容类型检测与抽取自动识别文档类型并提取正文AI 驱动的摘要与自动打标签借助大模型生成摘要和标签向量嵌入生成使用 Cloudflare AI 将内容向量化分块Chunking为语义搜索优化做切片空间关系管理维护内容与 Space空间之间的归属关系。这条管线直接支撑/v3/documents的写入路径与/v3/search的检索质量——入库内容经过分块与嵌入后才可被语义搜索命中。仓库中与空间相关的实现可见于 apps/mcp/src/server/space.ts含space.test.ts容器标签管理见 apps/mcp/src/server/container-tag.ts。七、环境配置Cloudflare Workers 部署模型配置载体根级配置使用wrangler.jsonc同时支持 staging 与 production 两套环境需要 Cloudflare 绑定Hyperdrive数据库加速、AI向量嵌入/推理、KV 存储、Workflows每 4 小时触发一次 Cron用于连接器connections的定时导入。Web 应用 Workerapps/web/wrangler.jsonc{ main: .open-next/worker.js, name: supermemory-app, compatibility_flags: [nodejs_compat, global_fetch_strictly_public], assets: { directory: .open-next/assets, binding: ASSETS }, r2_buckets: [{ binding: NEXT_INC_CACHE_R2_BUCKET, bucket_name: supermemory-console-cache }] }Web 应用通过OpenNext for Cloudflareopennextjs-cloudflare将 Next.js 编译为 Worker 形态静态资源挂载为ASSETS增量缓存写入 R2 桶supermemory-console-cache。MCP Workerapps/mcp/wrangler.jsonc{ name: supermemory-mcp, main: src/server/index.ts, vars: { API_URL: https://api.supermemory.ai }, routes: [{ pattern: mcp.supermemory.ai, zone_name: supermemory.ai, custom_domain: true }], durable_objects: { bindings: [ { name: MCP_SERVER, class_name: SupermemoryMCP }, { name: SPACE_STATE, class_name: SpaceState } ] }, migrations: [ { tag: v1, new_sqlite_classes: [SupermemoryMCP] }, { tag: v2, new_sqlite_classes: [SpaceState] } ] }MCP 服务端以自定义域名mcp.supermemory.ai对外提供服务使用 Durable Objects基于 SQLite 的SupermemoryMCP与SpaceState两类维护会话与空间状态API_URL指向主 API 后端。八、错误处理与监控HTTPExceptionAPI 统一抛出该异常以生成一致的错误响应hono 生态标准做法Sentry 集成错误上报附带用户与组织上下文便于定位到具体租户自定义日志对分析类噪音进行过滤避免污染监控数据。根 package.json 中的sentry:sourcemaps脚本与postbuild钩子共同构成了构建即上传 sourcemap的发布链路保证生产环境堆栈可读。九、代码质量与工程标准Lint 与格式化全仓统一使用Biomelint format配置文件为根目录 biome.json一键执行bun run format-lint即bunx biome check --write。TypeScript基于total-typescript/tsconfig的严格 TypeScript 配置类型检查bun run check-typesCloudflare 环境类型通过cf-typegenwrangler types生成。数据库管理Drizzle ORMschema 位于共享包中packages/内供多应用复用迁移由 Drizzle Kit 处理Schema 类型自动生成并在包间共享避免手写类型漂移。十、安全与最佳实践认证Better Auth 统一处理用户认证与组织管理对外访问支持 API Key 认证组织内部实现基于角色的访问控制RBAC——该逻辑在 MCP 服务端有独立实现与测试见 apps/mcp/src/server/auth/rbac.ts 及配套的rbac.test.ts。数据安全内容哈希去重对内容做哈希防止重复处理同一份数据凭据安全外部服务凭据Google Drive、Notion、OneDrive 等连接器 token全程安全处理自动类型检测与校验入库前完成内容类型识别与合法性校验。部署基于 Cloudflare Workers 的无服务器部署天然具备弹性伸缩能力生产环境 sourcemap 上传 Sentry保障线上排障能力环境差异化配置管理staging / production。十一、给 AI 助手与贡献者的使用建议综合全文CLAUDE.md 实际上为两类读者定义了正确的打开方式对 Claude Code 等 AI 助手进入仓库后应优先读取 CLAUDE.md据此选择 Bun 而非 npm/pnpm 执行命令遵循 Biome 与check-types的质量门槛并在涉及内容处理时了解IngestContentWorkflow管线避免绕过既有架构。对人类开发者它是一份浓缩的架构地图——根目录跑bun run dev即可拉起 web 与 mcp 全部服务改共享包后依赖它的应用会自动重构建TurbodependsOn机制涉及数据库变更时走 Drizzle Kit 迁移流程涉及认证与权限时对齐 Better Auth 与 RBAC 模块。后续深入阅读仓库时建议按如下路径展开根 package.json命令与依赖→ turbo.json任务编排→ apps/web/package.json前端技术栈→ apps/mcp/src/server/client/index.tsAPI 调用实证→ apps/mcp/wrangler.jsoncWorker 部署形态。这份 CLAUDE.md 与上述源码互相印证共同构成了理解 supermemory 工程全貌的最短路径。【免费下载链接】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），仅供参考 
长河君 · 2026/9/11 13:33:34 · 阅读 1.2k 面向 Claude Code 与开发者的 supermemory 开发指南：Turbo Monorepo 架构、命令与工程规范全解析
面向 Claude Code 与开发者的 supermemory 开发指南Turbo 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 仓库根目录的 CLAUDE.md 为骨架系统梳理该 Turbo Monorepo 的整体结构、开发命令、前后端架构、内容处理管线、Cloudflare 部署配置与代码质量规范。读者将能快速掌握如何在本地用 Bun 驱动整个 monorepo 的开发与构建理解/v3/*API 与 MCP 服务端的关系并了解该仓库面向 AI 编程助手Claude Code设计的关键上下文约定。一、CLAUDE.md 是什么给 Claude Code 的仓库导航文件CLAUDE.md是项目根目录下的一份特殊说明文档其定位是向 Claude Codeclaude.ai/code等 AI 编程助手提供在本仓库内工作时的上下文指引——包括仓库布局、可用的开发命令、技术栈选型、核心工作流以及必须遵守的工程规范。它的存在意味着当 AI 助手进入该仓库时可以依赖这份文件快速建立全局认知避免误读目录结构、使用错误的包管理器或绕过既定的 lint/type-check 流程。对人工开发者而言它同样是一份高质量的 onboarding 文档下面各节将逐一展开其中的每一条。二、仓库结构Turbo Monorepo 的应用与共享包布局CLAUDE.md 明确指出这是一个Turbo monorepo包含多个应用Applications与共享包Shared Packages。结合根目录 package.json 的workspaces字段可以看到实际范围workspaces: [ apps/*, !apps/raycast-extension, !tools/test/chatapp, packages/* ]应用层apps/应用说明关键入口apps/webNext.js Web 应用用户控制台 / 产品前端apps/web/package.jsonapps/mcpModel Context Protocol 服务端以 Cloudflare Worker 形式运行apps/mcp/package.json值得注意的是仓库中还存在apps/browser-extension、apps/raycast-extension、apps/memory-graph-playground、apps/sdk-playground与apps/docs等目录它们被显式排除在根 workspaces 之外或作为独立子项目维护——这解释了为什么 CLAUDE.md 只把web与mcp列为受 Turbo 编排的核心应用。共享包层packages/monorepo 的共享代码沉淀在packages/下包括libAPI 客户端、认证上下文、查询封装、validationzod schema、ui组件库、toolsAI 工具封装、hooks、memory-graph等。Web 应用通过workspace:*协议引用它们例如 apps/web/package.json 中的repo/lib: workspace:*与repo/validation: workspace:*。Turbo 的任务编排定义在根目录 turbo.jsonbuild任务通过dependsOn: [^build]保证先构建依赖包dev/dev:app任务关闭缓存并标记为persistent长驻进程check-types与lint同样按依赖拓扑传播。三、开发命令从根目录到子应用的一键工作流根级命令Monorepo 维度CLAUDE.md 给出的根级命令与 package.json 中的 scripts 一一对应命令作用底层实现bun run dev启动所有应用的开发模式turbo run devbun run build构建所有应用turbo run buildbun run check-types对所有应用执行 TypeScript 类型检查turbo run check-typesbun run format-lint使用 Biome 统一格式化与 lintbunx biome check --writebun run dev:local本地开发模式应用侧turbo run dev:app额外的工程化脚本还包括sentry:sourcemaps构建后将 sourcemap 上传 Sentry--strip-prefix dist/..以及postbuild构建后自动触发 sourcemap 上传。环境约束来自根 package.json包管理器为Bun版本固定为bun1.3.6packageManager字段要求Node.js 20engines.node。Web 应用命令apps/web/进入apps/web后的常用命令命令作用bun run dev启动 Next.js 开发服务器经由portless实际执行next dev --port ${PORT:-3000}bun run build构建 Next.js 应用next buildbun run lint使用 Biome 检查并写入修复biome check --writebun run preview/deploy/upload基于 OpenNext for Cloudflare 的构建与部署bun run cf-typegen生成 Cloudflare 环境类型声明MCP 应用apps/mcp则使用wrangler dev --port ${PORT:-8788}启动本地 Worker并提供test:unit/test:e2evitest与studiowidget 调试面板等专用命令详见 apps/mcp/package.json。四、架构概览技术栈与核心模块核心技术栈CLAUDE.md 明确列出的技术选型运行时/框架Next.jsWeb 与 API 应用语言全仓 TypeScript包管理器BunMonorepo 编排Turbo认证Better Auth支持组织化账号体系监控Sentry含 sourcemap 上传与上下文追踪API 应用主后端API 承担核心后端职责CLAUDE.md 列出以下关键路由。从 MCP 服务端源码可以看到这些端点的实际调用——例如 apps/mcp/src/server/client/index.ts 中通过fetch(\${this.apiUrl}/v3/container-tags/list)拉取容器标签同文件第 340 行调用/v3/documents/documents 获取文档列表路由职责/v3/documents文档/记忆的增删改查CRUD/v3/search对已索引内容的语义搜索/v3/connections外部服务集成Google Drive、Notion、OneDrive 等/v3/settings组织与用户设置/v3/analytics用量统计与报表/api/auth/*认证端点Better Auth 挂载点Web 应用Next.js 前端为用户提供可视化界面覆盖文档管理、语义搜索、连接器配置与用量分析等能力。其依赖结构apps/web/package.json印证了 CLAUDE.md 的描述next、radix-ui/*无障碍 UI 原语、tanstack/react-query服务端状态缓存、recharts分析图表并集成sentry/nextjs、PostHogposthog-js等可观测性组件。MCP 服务端虽然 CLAUDE.md 未展开 MCP 细节但作为apps/mcp的核心应用其服务端结构apps/mcp/src/server/值得补充说明包含auth含 RBAC 实现及index.test.ts/rbac.test.ts测试、client对/v3/*API 的封装、toolsadd-memory、search-memory、save-memory、list-memories、memory-graph、upload-file等十余个 MCP 工具以及space.ts/container-tag.ts/analytics.ts等业务模块。五、关键依赖一览共享依赖better-auth认证系统内置组织organization支持drizzle-orm数据库 ORMzodschema 校验配合drizzle-zod、zod-openapi生成类型与 OpenAPI 文档honoWeb 框架API 与 MCP 均使用见 apps/mcp/package.json 的hono依赖sentry/*错误监控turbomonorepo 构建系统。根 package.json 中还有一组值得注意的依赖hono/zod-validator、hono-openapi、scalar/hono-api-reference自动生成 API 参考文档、neverthrowResult 风格错误处理、pino结构化日志、pg/postgresPostgreSQL 驱动、resend邮件、cloudflare与wranglerWorker 工具链。Web 专属依赖nextReact 框架radix-ui/*UI 组件原语dialog、dropdown-menu、select、tooltip 等tanstack/react-query数据请求与缓存recharts分析图表可视化以及 TipTap富文本/Markdown 编辑器、d3-force记忆图谱力导向布局、zustand客户端状态等。六、开发工作流内容处理管线CLAUDE.md 指出所有内容都经由IngestContentWorkflow处理管线覆盖五个环节内容类型检测与抽取自动识别文档类型并提取正文AI 驱动的摘要与自动打标签借助大模型生成摘要和标签向量嵌入生成使用 Cloudflare AI 将内容向量化分块Chunking为语义搜索优化做切片空间关系管理维护内容与 Space空间之间的归属关系。这条管线直接支撑/v3/documents的写入路径与/v3/search的检索质量——入库内容经过分块与嵌入后才可被语义搜索命中。仓库中与空间相关的实现可见于 apps/mcp/src/server/space.ts含space.test.ts容器标签管理见 apps/mcp/src/server/container-tag.ts。七、环境配置Cloudflare Workers 部署模型配置载体根级配置使用wrangler.jsonc同时支持 staging 与 production 两套环境需要 Cloudflare 绑定Hyperdrive数据库加速、AI向量嵌入/推理、KV 存储、Workflows每 4 小时触发一次 Cron用于连接器connections的定时导入。Web 应用 Workerapps/web/wrangler.jsonc{ main: .open-next/worker.js, name: supermemory-app, compatibility_flags: [nodejs_compat, global_fetch_strictly_public], assets: { directory: .open-next/assets, binding: ASSETS }, r2_buckets: [{ binding: NEXT_INC_CACHE_R2_BUCKET, bucket_name: supermemory-console-cache }] }Web 应用通过OpenNext for Cloudflareopennextjs-cloudflare将 Next.js 编译为 Worker 形态静态资源挂载为ASSETS增量缓存写入 R2 桶supermemory-console-cache。MCP Workerapps/mcp/wrangler.jsonc{ name: supermemory-mcp, main: src/server/index.ts, vars: { API_URL: https://api.supermemory.ai }, routes: [{ pattern: mcp.supermemory.ai, zone_name: supermemory.ai, custom_domain: true }], durable_objects: { bindings: [ { name: MCP_SERVER, class_name: SupermemoryMCP }, { name: SPACE_STATE, class_name: SpaceState } ] }, migrations: [ { tag: v1, new_sqlite_classes: [SupermemoryMCP] }, { tag: v2, new_sqlite_classes: [SpaceState] } ] }MCP 服务端以自定义域名mcp.supermemory.ai对外提供服务使用 Durable Objects基于 SQLite 的SupermemoryMCP与SpaceState两类维护会话与空间状态API_URL指向主 API 后端。八、错误处理与监控HTTPExceptionAPI 统一抛出该异常以生成一致的错误响应hono 生态标准做法Sentry 集成错误上报附带用户与组织上下文便于定位到具体租户自定义日志对分析类噪音进行过滤避免污染监控数据。根 package.json 中的sentry:sourcemaps脚本与postbuild钩子共同构成了构建即上传 sourcemap的发布链路保证生产环境堆栈可读。九、代码质量与工程标准Lint 与格式化全仓统一使用Biomelint format配置文件为根目录 biome.json一键执行bun run format-lint即bunx biome check --write。TypeScript基于total-typescript/tsconfig的严格 TypeScript 配置类型检查bun run check-typesCloudflare 环境类型通过cf-typegenwrangler types生成。数据库管理Drizzle ORMschema 位于共享包中packages/内供多应用复用迁移由 Drizzle Kit 处理Schema 类型自动生成并在包间共享避免手写类型漂移。十、安全与最佳实践认证Better Auth 统一处理用户认证与组织管理对外访问支持 API Key 认证组织内部实现基于角色的访问控制RBAC——该逻辑在 MCP 服务端有独立实现与测试见 apps/mcp/src/server/auth/rbac.ts 及配套的rbac.test.ts。数据安全内容哈希去重对内容做哈希防止重复处理同一份数据凭据安全外部服务凭据Google Drive、Notion、OneDrive 等连接器 token全程安全处理自动类型检测与校验入库前完成内容类型识别与合法性校验。部署基于 Cloudflare Workers 的无服务器部署天然具备弹性伸缩能力生产环境 sourcemap 上传 Sentry保障线上排障能力环境差异化配置管理staging / production。十一、给 AI 助手与贡献者的使用建议综合全文CLAUDE.md 实际上为两类读者定义了正确的打开方式对 Claude Code 等 AI 助手进入仓库后应优先读取 CLAUDE.md据此选择 Bun 而非 npm/pnpm 执行命令遵循 Biome 与check-types的质量门槛并在涉及内容处理时了解IngestContentWorkflow管线避免绕过既有架构。对人类开发者它是一份浓缩的架构地图——根目录跑bun run dev即可拉起 web 与 mcp 全部服务改共享包后依赖它的应用会自动重构建TurbodependsOn机制涉及数据库变更时走 Drizzle Kit 迁移流程涉及认证与权限时对齐 Better Auth 与 RBAC 模块。后续深入阅读仓库时建议按如下路径展开根 package.json命令与依赖→ turbo.json任务编排→ apps/web/package.json前端技术栈→ apps/mcp/src/server/client/index.tsAPI 调用实证→ apps/mcp/wrangler.jsoncWorker 部署形态。这份 CLAUDE.md 与上述源码互相印证共同构成了理解 supermemory 工程全貌的最短路径。【免费下载链接】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），仅供参考