Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (133 loc) · 6.94 KB

CONTRIBUTING.md

File metadata and controls

178 lines (133 loc) · 6.94 KB
Raw

Contributing to Mem0

First off, thank you for taking the time to contribute! 🎉 Mem0 is a community-driven project and we welcome contributions of all kinds — bug fixes, new features, documentation, examples, and integrations.

Mem0 is a polyglot monorepo, and this guide covers contributing to both the Python SDK and the TypeScript SDK (and the rest of the repository).

Before You Start

1. Open an Issue First

Always open an issue before opening a pull request. This lets us discuss the change, avoid duplicate effort, and agree on the approach before you invest time in code.

  • Search existing issues first to see if your bug or idea already exists.
  • If it doesn't, open a bug report or feature request.
  • For anything beyond a trivial fix, wait for a maintainer to confirm the approach before starting significant work.

Every pull request must link to an issue using Closes #<issue-number>.

2. Sign the Contributor License Agreement (CLA)

We cannot accept or merge any pull request until you have signed our Contributor License Agreement (CLA).

When you open your first PR, the CLA bot will automatically comment with a link to sign. Signing takes less than a minute and only needs to be done once. Pull requests from contributors who have not signed the CLA will be blocked from merging.

Repository Layout

The two most common contribution targets are the SDKs:

Package Path Language Package manager
Python SDK (mem0ai) mem0/ Python 3.9+ hatch
TypeScript SDK (mem0ai) mem0-ts/ TypeScript pnpm

Other packages include the CLIs (cli/python/, cli/node/), integrations (integrations/), the self-hosted server/, openmemory/, and the docs site (docs/). See AGENTS.md for a full map of the repository.

Development Workflow

  1. Fork the repository and clone your fork.
  2. Create a feature branch from main (e.g. feature/my-new-feature or fix/issue-1234).
  3. Make your changes — add tests, documentation, and examples as appropriate.
  4. Run linting and tests for every package you touched (see below).
  5. Commit using Conventional Commits (e.g. feat:, fix:, docs:, refactor:, test:).
  6. Push and open a pull request against main, linking the issue with Closes #<number> and filling out the PR template.

Contributing to the Python SDK (mem0/)

We use hatch to manage environments. Do not use pip or conda for dependency management.

# Activate a dev environment (3.9 / 3.10 / 3.11 / 3.12)
hatch shell dev_py_3_11

# Install pre-commit hooks (runs ruff + isort on commit)
pre-commit install

# Lint, format, and sort imports
make lint
make format
make sort

# Run the test suite (run `make install_all` first if deps are missing)
make test
  • Linter / formatter: Ruff (line length 120)
  • Import sorting: isort (profile = "black")
  • Tests: pytest (in tests/)

See the full Development guide for environment details.

Contributing to the TypeScript SDK (mem0-ts/)

We use pnpm (v10+) for all TypeScript packages. Do not use npm or yarn.

cd mem0-ts
pnpm install

pnpm run build        # tsup (CJS + ESM)
pnpm run test         # jest (all tests)
pnpm run test:unit    # unit tests with coverage
  • Build: tsup
  • Formatter: Prettier
  • Tests: jest
  • Always run type checking after changes: pnpm run typecheck (or tsc --noEmit).
  • Use ES module import syntax — never require().

Good Contribution Practices

  • Keep PRs small and focused. One logical change per PR is easier to review and merge.
  • Follow existing patterns. Match the style, structure, and conventions of the code around you. Don't introduce new frameworks or abstractions without discussion.
  • Write tests that would fail without your change — regression tests for bugs, coverage for new features.
  • Update documentation in docs/ for any user-facing change. New .mdx pages must be added to docs/llms.txt (run python scripts/check-llms-txt-coverage.py --write to scaffold entries).
  • Add examples when introducing new user-facing behavior.
  • Run linters and tests locally before pushing — CI re-runs them on every PR via the CI Gate.
  • Never commit secrets — no .env files, API keys, or credentials.
  • Don't add core dependencies lightly. New Python dependencies belong in an optional group in pyproject.toml, not the core dependencies list.
  • Be responsive to review feedback and keep your branch up to date with main.

Pull Request Checklist

Before requesting review, make sure:

  • An issue exists and is linked with Closes #<number>
  • You have signed the CLA
  • Your code follows the project's style guidelines (lint passes)
  • You performed a self-review of your changes
  • Tests are added/updated and pass locally
  • Documentation is updated if needed

Reporting Security Issues

Do not report security vulnerabilities through public issues or pull requests. Please follow our Security Policy to report them privately.

Releasing

All packages are published automatically via GitHub Actions when a GitHub Release is created with the correct tag prefix.

Tag Prefixes

Package Registry Tag Prefix Example
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

How to Release

  1. Bump the version in pyproject.toml (Python) or package.json (Node)
  2. Create a GitHub Release with the matching tag prefix
  3. The correct workflow will trigger automatically — verify in the Actions tab

Publishing Details

  • PyPI packages use OIDC trusted publishing via pypa/gh-action-pypi-publish
  • npm packages use OIDC trusted publishing via npm CLI (>= 11.5.1) — no tokens or secrets required
  • All workflows require permissions: id-token: write for OIDC authentication
  • First publish of a new npm package must be done manually; OIDC works for subsequent versions

We look forward to your pull requests and can't wait to see your contributions!