14.1 · 开发设置（Development Setup）

开发设置

开发环境搭建

相关源文件

本章引用的主要源码文件：

• .github/workflows/ci.yml
• .github/workflows/ts-sdk-ci.yml
• Makefile
• docs/changelog/sdk.mdx
• docs/components/vectordbs/config.mdx
• docs/components/vectordbs/dbs/chroma.mdx
• docs/components/vectordbs/dbs/qdrant.mdx
• docs/components/vectordbs/overview.mdx
• mem0-ts/jest.config.js
• mem0-ts/jest.setup.ts
• mem0-ts/src/global.d.ts
• mem0-ts/src/oss/src/utils/telemetry.ts
• mem0-ts/tsup.config.ts
• mem0/utils/factory.py
• mem0/vector_stores/configs.py
• poetry.lock
• pyproject.toml

本文档介绍如何搭建本地开发环境，以便为 Mem0 代码库贡献代码。内容涵盖仓库设置、使用 Hatch 进行依赖管理、预提交钩子以及开发工作流工具。

前提条件

Mem0 的开发需要以下环境：

注意：核心 mem0 包在 Python 3.10-3.12 上测试，旧版 embedchain 包在 Python 3.9-3.12 上测试，具体定义见 .github/workflows/ci.yml:84 和 .github/workflows/ci.yml:125。

来源：pyproject.toml:15, .github/workflows/ci.yml:84, .github/workflows/ci.yml:107, .github/workflows/ci.yml:125

仓库设置

Fork 和克隆

# 通过 GitHub UI 在 https://github.com/mem0ai/mem0 上 Fork 仓库

# 克隆你的 Fork
git clone https://github.com/YOUR_USERNAME/mem0.git
cd mem0

# 添加上游远程仓库
git remote add upstream https://github.com/mem0ai/mem0.git

创建功能分支

# 创建并切换到专用的功能分支
git checkout -b feature/my-feature-name

来源：.github/workflows/ci.yml:1-18

Hatch 环境管理

Mem0 使用 Hatch 作为构建后端和环境管理器 pyproject.toml:1-3。环境配置了特定的功能集，以便在不同提供商集成中进行测试。

Hatch 环境设置流程

环境激活

Hatch 提供了多个特定 Python 版本的环境，定义在 pyproject.toml 中：

# 激活特定 Python 版本的环境
hatch shell dev_py_3_10  # [pyproject.toml:102]
hatch shell dev_py_3_11  # [pyproject.toml:111]
hatch shell dev_py_3_12  # [pyproject.toml:120]

每个环境会自动安装 test、vector_stores、llms 和 extras 功能组 pyproject.toml:104-127。

依赖安装

项目将依赖分为多个层级：

1. 核心依赖：基本功能所需（例如 qdrant-client、openai、pydantic） pyproject.toml:16-24。
2. 可选依赖：特定提供商所需（例如 vector_stores、llms、nlp） pyproject.toml:26-74。

# 1. 创建 hatch 环境
make install

# 2. 安装所有可选依赖（需要完整提供商支持时）
make install_all

make install_all 命令会执行全面的安装，包括 chromadb、pinecone、weaviate 和 langchain-community 等受支持的提供商 Makefile:13-16。

来源：pyproject.toml:1-127, Makefile:10-16

开发工作流工具

开发工作流集成

代码检查和格式化

项目使用 ruff 进行代码检查和格式化，配置的行长度为 120 pyproject.toml:146-147。isort 配置也通过 ruff 和独立的 isort 管理，以保持与 Black 兼容的导入排序 pyproject.toml:150-155。

# 运行代码检查
make lint

# 运行格式化
make format

# 排序导入
make sort

这些命令使用 hatch run 来执行 pyproject.toml 中 [tool.hatch.envs.default.scripts] 部分定义的脚本 pyproject.toml:129-141。

测试

测试套件基于 pytest 构建 pyproject.toml:76。

# 使用默认环境运行测试
make test

# 测试特定 Python 版本
make test-py-3.10  # [Makefile:45]
make test-py-3.11  # [Makefile:48]
make test-py-3.12  # [Makefile:51]

来源：pyproject.toml:76-156, Makefile:18-53

持续集成与持续交付管线概览

CI 管线定义在 .github/workflows/ci.yml 中，会在推送到 main 分支或影响核心文件的拉取请求时触发 .github/workflows/ci.yml:3-17。

任务结构

1. changelog_check：如果 pyproject.toml 中的版本发生变化，则需要更新 docs/changelog/sdk.mdx .github/workflows/ci.yml:20-58。
2. check_changes：使用 dorny/paths-filter 判断 mem0 或 embedchain 代码是否发生变化 .github/workflows/ci.yml:59-77。
3. build_mem0：在 Python 3.10、3.11 和 3.12 上运行 mem0 的代码检查和测试 .github/workflows/ci.yml:78-118。
4. build_embedchain：运行旧版 embedchain 包的格式化、代码检查和测试 .github/workflows/ci.yml:119-157。

CI 环境设置

CI 环境使用以下命令安装依赖： pip install -e ".[test,graph,vector_stores,llms,extras]" .github/workflows/ci.yml:111。

来源：.github/workflows/ci.yml:1-157, docs/changelog/sdk.mdx:10-22

TypeScript 开发环境搭建

仓库中包含一个 TypeScript SDK，位于 mem0-ts/ 目录下。它使用 tsup 进行构建和打包 mem0-ts/tsup.config.ts:1。

构建配置

tsup.config.ts 定义了两个入口点：

• src/client/index.ts：主平台客户端。
• src/oss/src/index.ts：开源实现 mem0-ts/tsup.config.ts:31-49。

遥测配置

遥测功能由 UnifiedTelemetry 类管理 mem0-ts/src/oss/src/utils/telemetry.ts:40。

• 选择退出：可以通过设置 MEM0_TELEMETRY="false" 来禁用 mem0-ts/src/oss/src/utils/telemetry.ts:16。
• 采样：非生命周期事件默认以 10%（0.1）的采样率进行采样，可通过 MEM0_TELEMETRY_SAMPLE_RATE 配置 mem0-ts/src/oss/src/utils/telemetry.ts:23-35。
• 生命周期事件：像 init 和 reset 这样的事件会绕过采样 mem0-ts/src/oss/src/utils/telemetry.ts:38。

来源：mem0-ts/tsup.config.ts:1-49, mem0-ts/src/oss/src/utils/telemetry.ts:14-127

平台特定设置

Linux 依赖

安装 libgeos-dev，这是向量存储集成中地理空间依赖所需的：

sudo apt-get update && sudo apt-get install -y libgeos-dev

这是 CI 环境中的必要步骤 .github/workflows/ci.yml:107。

磁盘空间管理

为防止 CI 运行器中磁盘空间不足，工作流会清理未使用的 SDK 和 Docker 镜像 .github/workflows/ci.yml:91-97。

来源：.github/workflows/ci.yml:91-107