Mem0 开源仓库贡献实战指南：从 PR Gate 准入机制到 Python/TypeScript 双 SDK 工具链

Mem0（mem0ai）是一个为 AI Agent 提供持久记忆层的多语言 monorepo，同时维护 Python SDK、TypeScript SDK、两套 CLI、自托管 server 与文档站。本文基于仓库根目录的 CONTRIBUTING.md 完整梳理其贡献体系：先讲清"Issue 优先 + accepted 标签 + CLA"的准入规则与自动闸门机制，再给出 Python 与 TypeScript 两套 SDK 的本地开发、测试与构建工作流，最后覆盖发布（releasing）的 tag 规则与 OIDC 免 token 发布细节，帮助你在提交第一个 PR 前就掌握这套仓库的全部约定。

一、开始之前：Mem0 的三条前置规则

Mem0 明确将贡献流程设计为"先立规矩、再写代码"。CONTRIBUTING.md 的 Before You Start 部分列出三条硬性前置要求：先开 Issue、必须理解自己的代码、签署 CLA。参与贡献即视为同意 CODE_OF_CONDUCT.md，其中 Contribution Conduct 小节是本页规则的"可执行版本"：披露 AI 使用情况、不提交自己没运行过的代码、不伪造复现步骤或基准数据、提交量与参与度匹配、不催合并。

1.1 先开 Issue，且 Issue 必须带 accepted 标签

规则原文要求：永远先开 Issue 再开 PR。目的是在投入编码前先讨论方案、避免重复劳动、与 maintainer 对齐做法。操作流程是：

1. 先搜索已有 Issue，确认问题或想法不存在；
2. 若不存在，提交 bug report 或 feature request；
3. 对于任何超出"琐碎修复"的工作，等待 maintainer 确认方案后再动手。

对 Issue 质量有明确要求：bug report 必须包含可运行的复现步骤、你所处的版本、真实输出或 traceback——缺这些的 report 无法被处理，会被直接关闭；feature request 需要说明你遇到的问题和目前靠什么 workaround 活着，而不是只描述你想要的 API。

每个 PR 都必须用 Closes #<issue-number> 链接 Issue，且该 Issue 必须带有 accepted 标签（由 maintainer 在认可方案后打上）。

PR Gate 自动闸门：closed 不等于 rejected

未链接 accepted Issue 的 PR 会被 PR Gate 工作流 自动关闭。文档特别强调了一个对新手很重要的认知：

Closed does not mean rejected.（关闭不等于被拒）

它只表示"这个变更还没进入队列"。一旦 maintainer 给 Issue 打上 accepted 标签，PR 会自动重新打开，贡献者无需做任何操作。仅修改文档（docs-only）的变更完全跳过这道闸门。

此外还有第二道检查，它判断的不是变更内容而是提交者账号。若你不在本仓库的 contributor 列表（.github/VOUCHED.td）中，系统会留下一条评论提示你——不阻塞任何东西，你也不需要做任何事。maintainer 可以在任意 Issue 下评论 !vouch @you 将你加入列表，效果仅是那条提示评论不再重复出现。列表也有负面用法：maintainer 可以对经过 行为准则 处理流程的账号执行 !denounce，此后该账号的 PR 无论是否链接 accepted Issue 都会被关闭——文档说明这很罕见、可逆，且"没有任何人从这里开始"。这两道闸门对应仓库中的两个实际工作流：pr-gate.yml（判断变更）与 vouch-check-pr.yml（判断账号），可结合根目录 AGENTS.md 中 Two gates decide whether your pull request stays open 一节查看两者各自的豁免条件（draft、docs-only、推送到本仓库而非 fork 的分支均豁免 PR Gate）。

安全修复是唯一例外：安全类修复不走公开 PR，而应遵循 SECURITY.md 的私有 advisory + private fork 流程，避免漏洞在修复发布前被公开。

1.2 必须能解释你的代码——AI 使用需披露

这是文档中"唯一不会让步的一条规则"：你必须能在不使用 AI 工具辅助的情况下，解释你的变更做了什么、如何与其余代码库交互。 用 AI 写代码没问题（"我们大多数人都在用"），你甚至可以通过反复向 agent 提问来建立对这个代码库的理解；不可接受的，是提一个你在 review 中无法为自己辩护的 diff。

PR 模板要求你披露 AI 使用并说明自己检查了什么——仓库中的实际模板 .github/PULL_REQUEST_TEMPLATE.md 可以印证这一点，其中 AI Assistance 小节区分了 "No AI / AI-assisted / AI-generated" 三档，并要求勾选"I 能在不问 AI 工具的情况下解释这个 diff 的每一行"。文档特别说明：问的是代码而不是文案——用 AI 起草 PR 描述完全没问题；披露不是为了"扣分"，而是告诉 reviewer 该重点看哪里。"一个 agent 写了这些，这是我亲自验证的部分"这样的诚实陈述完全被欢迎。

文档还列出了"你的 PR 会被关闭"的具体征兆，值得逐条对照自查：

• 虚构了本仓库中不存在的 API、配置键或 provider；
• 测试断言的是实现本身而非行为（assert the implementation back at itself）；
• PR 描述与 diff 实际做的变更对不上；
• 把大量无关的重格式化捆绑进一个小修复；
• 无法回答 reviewer 关于你自己 diff 的直接提问。

1.3 签署 CLA 是合并前提

CLA 签署是接受任何 PR 的前提：首次开 PR 时 CLA bot 会自动评论并给出签署链接，签署不到一分钟且每个 GitHub 账号只需一次；未签署者（license/cla check 保持红色）的 PR 会被阻止合并。AGENTS.md 中 The CLA is not optional 一节语气更直接：未签 CLA 的 PR 根本不进入 review 队列——maintainer 不读 diff、不留反馈、不讨论方案，直至过期关闭。

二、首次贡献快速通道（First Contribution Fast Path）

修一个 typo 或小的文档问题不需要走完整流程，CONTRIBUTING.md 给出了四步 fast path：

1. 选一个小的：找带 documentation 或 good first issue 标签的 Issue，或你读文档时注意到的 typo / 断链；
2. 从 main 拉分支，分支名说明你要修什么，例如 docs/fix-quickstart-typo 或 fix/broken-crewai-link；
3. 改完只运行适用的检查：
   • 仅文档变更（docs/**）：用 make docs 预览；如果增删了 .mdx 页面，运行 python scripts/check-llms-txt-coverage.py --write 保持 docs/llms.txt 同步——该脚本在仓库中确实存在（scripts/check-llms-txt-coverage.py），且 Makefile 中的 docs 目标对应的就是 cd docs && mintlify dev 本地预览；
   • 代码变更：运行所触碰包的 linter 与测试（见下文 Development Workflow）；
4. 开 PR 到 main，带上 Closes #<issue-number> 和一行修复说明。

比文档修复或小 bug 更大的变更，则必须走下文完整工作流。

三、仓库布局：多语言 monorepo 与"每包一套规则"

Mem0 是 polyglot monorepo，CONTRIBUTING.md 给出的两个最主要贡献目标是 SDK：

包	路径	语言	包管理器
Python SDK（mem0ai）	mem0/	Python	hatch
TypeScript SDK（mem0ai）	mem0-ts/	TypeScript	pnpm

其余包包括 CLI（cli/python/、cli/node/）、集成（integrations/）、自托管 server/ 与文档站（docs/），完整地图见根目录 AGENTS.md。

从源码结构看，这个 monorepo 最重要的约定是每个包都有自己的工具链，用错配置会直接挂 CI 或制造大量噪音 diff。根目录 AGENTS.md 的 Where to look 表格给出了逐包对照，例如：根级 Python 用 ruff（行宽 120）、cli/python/ 用 ruff（行宽 100）、cli/node/ 用 Biome、mem0-ts/ 用 Prettier、integrations/vercel-ai-sdk/ 用 ESLint——每编辑一个包，都应先读该包最近的 AGENTS.md（如 mem0/AGENTS.md、mem0-ts/AGENTS.md）再动手。

四、开发工作流（Development Workflow）

完整流程六步：Fork 并 clone 你的 fork；从 main 建 feature 分支（如 feature/my-new-feature、fix/issue-1234）；做变更——按情况补测试、文档、示例；对每个触碰过的包运行 lint 与测试；用 Conventional Commits 提交（feat:、fix:、docs:、refactor:、test:）；推送并开 PR 到 main，用 Closes #<number> 链接 Issue 并填写 PR 模板。

4.1 贡献 Python SDK（mem0/）：hatch + ruff + isort + pytest

Python 侧统一用 hatch 管理环境，文档明确警告：不要用 pip 或 conda 管理依赖。命令如下：

# 激活开发环境（3.10 / 3.11 / 3.12，见 pyproject.toml 中的 dev_py_3_10/3_11/3_12）
hatch shell dev_py_3_11

# 安装 pre-commit 钩子（commit 时运行 ruff + isort）
pre-commit install

# Lint、格式化、导入排序
make lint
make format
make sort

# 运行测试（若缺依赖先跑 make install_all）
make test

这些命令在仓库中都有实据可查。根目录 Makefile 中 format / lint 转发到 hatch run format / hatch run lint，sort 是 hatch run isort mem0/，test 是 hatch run test，另有 test-py-3.10 / test-py-3.11 / test-py-3.12 目标用于在指定 Python 版本环境跑测试，install_all 则一次性安装全套可选依赖（ruff、groq、together、boto3、litellm、ollama、chromadb、weaviate、pinecone、faiss-cpu 等）。

而各脚本背后执行的具体命令定义在 pyproject.toml 的 [tool.hatch.envs.default.scripts] 中：format = ruff format、lint = ruff check、test = pytest tests/ {args}。工具配置要点：

• Linter / Formatter：Ruff，行宽 120（[tool.ruff] line-length = 120，lint 规则选 E4, E7, E9, F）；
• Import 排序：isort，profile = "black"，known_first_party = ["mem0", "mem0_cli"]——注释里还提到该 scope 与 [tool.ruff.lint.isort] 保持对齐，升插件版本时需同步修改以触发 CI 检查；
• 测试：pytest，测试放在根目录 tests/ 下（tests/），[tool.pytest.ini_options] 中设置了 pythonpath = ["."]。

一个版本事实需要说明：CONTRIBUTING.md 的仓库布局表写的是 "Python 3.9+"，而当前仓库 pyproject.toml 实际声明 requires-python = ">=3.10,<4.0"，hatch 开发环境也只定义了 dev_py_3_10/3_11/3_12 三档——以仓库实际内容为准，本地开发请按 Python 3.10+ 准备。

4.2 贡献 TypeScript SDK（mem0-ts/）：pnpm + tsup + jest

TypeScript 侧所有包统一使用 pnpm（v10+），文档明确警告：不要用 npm 或 yarn。命令如下：

cd mem0-ts
pnpm install

pnpm run build        # tsup 构建（CJS + ESM）
pnpm run test         # jest（全部测试）
pnpm run test:unit    # 带 coverage 的单元测试

工具链要点（与 mem0-ts/AGENTS.md 一致）：

• 构建：tsup（双格式 CJS + ESM）；
• 格式化：Prettier；
• 测试：jest；
• 变更后必须跑类型检查：pnpm run typecheck（或 tsc --noEmit）；
• 一律使用 ES module import 语法，禁止 require()。

CI 侧对应 ts-sdk-ci.yml 等工作流，会对构建、测试与类型检查进行复核。

五、好的贡献实践与 PR Checklist

CONTRIBUTING.md 的 Good Contribution Practices 部分给出十条实践准则，核心可归纳为：

• PR 小而聚焦：一个 PR 只做一件逻辑变更，更容易 review 和合并；
• 遵循既有模式：与周围代码的风格、结构、约定保持一致；不经过讨论不要引入新框架或抽象；
• 写"没有这个变更就会失败"的测试：bug 要回归测试，新功能要覆盖；
• 更新文档：任何用户可见的变更都要更新 docs/；新增 .mdx 页面必须加入 docs/llms.txt（用 python scripts/check-llms-txt-coverage.py --write 生成条目，该仓库还有专门的 docs-llms-txt-check.yml 工作流在 CI 中强制检查）；
• 加示例：引入新的用户可见行为时补 example；
• 本地先跑 lint 与测试：CI 会在每个 PR 上通过 CI Gate（ci-gate.yml）重跑这些检查；
• 永不提交密钥：.env、API key、凭据一律不进仓库；
• 不要轻易添加核心依赖：新的 Python 依赖应放进 pyproject.toml 的可选组（optional group），而不是核心 dependencies 列表——对照 pyproject.toml 可以看到该文件实际按 nlp / vector-stores / llms / extras / test / dev 分组管理可选依赖，核心 dependencies 只有 qdrant-client、pydantic、openai、httpx、posthog、pytz、sqlalchemy、protobuf 八个；
• 对 review 反馈保持响应，并让分支与 main 保持同步。

提 review 前过一遍 PR Checklist：

• [ ] Issue 存在且已用 Closes #<number> 链接
• [ ] 已签署 CLA
• [ ] 代码符合项目风格规范（lint 通过）
• [ ] 已自查（self-review）变更
• [ ] 测试已添加/更新且在本地通过
• [ ] 文档按需已更新

六、安全问题上报

安全漏洞不要通过公开 Issue 或 PR 上报，应走 SECURITY.md 的私有渠道：GitHub Private Vulnerability Reporting，或邮件 [e-mail]（主题行 SECURITY: Mem0 vulnerability report）。报告中应尽量包含受影响的组件/包、版本或 commit、逐步复现步骤、安全影响与 PoC、建议修复或缓解方案，以及是否有 AI 工具参与。政策承诺 72 小时内确认收到报告，修复发布前请勿公开技术细节。

七、发布（Releasing）：tag 前缀与 OIDC 免 token 发布

Mem0 所有包都由 GitHub Actions 在创建带正确 tag 前缀的 GitHub Release 时自动发布。tag 前缀对照表（以 CONTRIBUTING.md 为准）：

包	仓库（Registry）	Tag 前缀	示例
mem0ai（Python SDK）	PyPI	v*	v0.1.31
mem0-cli（Python CLI）	PyPI	cli-v*	cli-v0.2.1
mem0ai（TypeScript SDK）	npm	ts-v*	ts-v2.4.6
@mem0/cli（Node CLI）	npm	cli-node-v*	cli-node-v0.1.2
@mem0/vercel-ai-provider	npm	vercel-ai-v*	vercel-ai-v2.0.6
@mem0/openclaw-mem0	npm	openclaw-v*	openclaw-v1.0.1

发布三步走：

1. 在 pyproject.toml（Python）或 package.json（Node）中升版本号；
2. 创建带对应 tag 前缀的 GitHub Release；
3. 对应 workflow 自动触发，在 Actions 面板确认即可。仓库中可见主发布流程 release.yml 以及各包的 *-cd.yml（如 ts-sdk-cd.yml、cli-python-cd.yml、cli-node-cd.yml）分别承接不同 tag 前缀。

发布机制细节：

• PyPI 包使用 OIDC trusted publishing（pypa/gh-action-pypi-publish）；
• npm 包使用 OIDC trusted publishing（npm CLI >= 11.5.1）——全程无需 token 或 secret；
• 所有发布 workflow 都要求 permissions: id-token: write 以完成 OIDC 鉴权；
• 新 npm 包的首次发布必须手工完成，OIDC 只对后续版本生效。

八、结语

Mem0 的贡献体系可以概括为三层：入口层（Issue 先行 + accepted 标签 + CLA + 双闸门）、执行层（hatch/ruff/isort/pytest 与 pnpm/tsup/jest 两套包级工具链）、出口层（Conventional Commits、llms.txt 同步、tag 前缀 + OIDC 自动发布）。对贡献者而言，最实际的两条建议是：动手前先让 Issue 拿到 accepted 标签，以及编辑哪个包就先读哪个包最近的 AGENTS.md——这两点能帮你避开绝大多数 CI 失败与 PR 被关闭的场景。