01-Mem0 的多语言单体仓库架构

Mem0 的多语言单体仓库架构

学习目标

本章分析 Mem0 如何组织一个包含 Python + TypeScript + Docker + Next.js 的 polyglot monorepo。你将了解：

各子包的技术栈与构建工具链
CI/CD 工作流的触发条件与并行策略
OIDC trusted publishing 如何实现零 Token 发布
多语言 repo 中的编码规范一致性维护

项目实践

目录结构与子包划分

Mem0 的顶层目录：

目录	语言	构建工具	发布目标	用途
`mem0/`	Python	Hatch	PyPI: `mem0ai`	核心 Python SDK
`mem0-ts/`	TypeScript	pnpm + tsup	npm: `mem0ai`	TypeScript SDK
`cli/python/`	Python	pip + hatch	PyPI: `mem0-cli`	Python CLI（Typer）
`cli/node/`	TypeScript	pnpm + tsup	npm: `@mem0/cli`	Node CLI（Commander）
`vercel-ai-sdk/`	TypeScript	pnpm + tsup	npm: `@mem0/vercel-ai-provider`	Vercel AI 集成
`openclaw/`	TypeScript	pnpm + tsup	npm: `@mem0/openclaw-mem0`	OpenClaw 插件
`server/`	Python + Docker	Docker Compose	Docker Hub	自托管 API 服务
`openmemory/`	Python + TypeScript	Docker + npm	Docker Hub	记忆管理平台
`mem0-plugin/`	TypeScript	pnpm	N/A	AI 编辑器插件
`skills/`	Markdown	N/A	N/A	Agent Skills 定义
`docs/`	MDX	Mintlify	Vercel	文档站点
`tests/`	Python	pytest	N/A	Python SDK 测试
`evaluation/`	Python	Makefile	N/A	基准测试框架

构建工具链对比

Mem0 在不同子包中使用了不同的构建工具：

子包	包管理器	构建工具	Linter	测试框架
Python SDK	Hatch	hatch build	ruff (line=120)	pytest
Python CLI	pip	hatch build	ruff (line=100)	pytest
TypeScript SDK	pnpm	tsup	Prettier	jest
Node CLI	pnpm	tsup	Biome	vitest
Vercel AI SDK	pnpm	tsup	ESLint + Prettier	jest + vitest
OpenClaw	pnpm	tsup	—	vitest

潜在陷阱：

ruff line-length 不一致：根 SDK 用 120，Python CLI 用 100。开发者跨子包工作时需要注意
Node CLI 使用 Biome 而非 ESLint：与其他 TS 包不同，Node CLI 选择了 Biome
测试框架碎片化：jest、vitest、pytest 三种框架并存

CI/CD 工作流

Mem0 的 GitHub Actions 采用按目录触发的策略：

OIDC Trusted Publishing

所有发布工作流使用 OIDC trusted publishing：

# 伪代码 - CD 工作流
permissions:
  id-token: write  # OIDC 信任发布

优势：

不需要在 GitHub Secrets 中存储 PyPI/npm Token
发布权限由 GitHub Actions 的 OIDC 身份验证，安全性更高
首次发布需手动，后续自动

Tag 前缀约定：

v* → Python SDK
ts-v* → TypeScript SDK
cli-v* → Python CLI
cli-node-v* → Node CLI
vercel-ai-v* → Vercel AI SDK
openclaw-v* → OpenClaw

文档同步检查

Mem0 的 docs-llms-txt-check.yml 工作流确保 docs/llms.txt 与 docs/**/*.mdx 同步：

PR 修改文档时自动检查
不同步则 CI 失败
本地修复命令：python scripts/check-llms-txt-coverage.py --write

问题与规避

问题	对策
ruff 配置不一致	每个子包有独立的 `pyproject.toml` ruff 配置
Node CLI 使用 Biome	在 AGENTS.md 中明确标注差异
OIDC 首次发布失败	首次发布手动操作，后续自动
文档不同步	CI 自动检查，本地脚本修复

设计取舍

为什么选 monorepo 而非多仓库？

优势：

SDK、CLI、Server 共享代码（如配置定义、异常类）
统一版本管理：一次 release 覆盖所有子包
PR 可以跨子包修改（如修改 SDK 配置，同时更新 CLI）

代价：

CI 需要按目录精确触发，避免无关子包构建
开发者需要掌握多种构建工具（Hatch + pnpm + Docker）
PR 体积大：涉及多个子包的修改需要更大的上下文

参考来源

Mem0 源码：pyproject.toml、.github/workflows/
OIDC Trusted Publishing: https://docs.pypi.org/trusted-publishers/

版本信息

📅 2026-05-27 🏷️ 8893430 🔀 8893430