From e4efdd2e29e4a53d2821e9829e004686f3458a9e Mon Sep 17 00:00:00 2001 From: Kartik Date: Fri, 26 Jun 2026 16:02:53 +0530 Subject: [PATCH] docs: add SECURITY.md and improve contribution guidelines (#5855) --- CONTRIBUTING.md | 181 ++++++++++++++++++++++-------- SECURITY.md | 48 ++++++++ docs/contributing/development.mdx | 102 ++++++++++++++--- 3 files changed, 266 insertions(+), 65 deletions(-) create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80a9852f6..ddba58989 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,72 +1,157 @@ -# Contributing to mem0 +# Contributing to Mem0 -Let us make contribution easy, collaborative and fun. +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. -## Submit your Contribution through PR +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). -To make a contribution, follow these steps: +## Before You Start -1. Fork and clone this repository -2. Do the changes on your fork with dedicated feature branch `feature/f1` -3. If you modified the code (new feature or bug-fix), please add tests for it -4. Include proper documentation / docstring and examples to run the feature -5. Ensure that all tests pass -6. Submit a pull request +### 1. Open an Issue First -For more details about pull requests, please read [GitHub's guides](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). +**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](https://github.com/mem0ai/mem0/issues) first to see if + your bug or idea already exists. +- If it doesn't, open a + [bug report](https://github.com/mem0ai/mem0/issues/new?template=bug_report.yml) or + [feature request](https://github.com/mem0ai/mem0/issues/new?template=feature_request.yml). +- For anything beyond a trivial fix, wait for a maintainer to confirm the approach + before starting significant work. -### ๐Ÿ“ฆ Development Environment +Every pull request must link to an issue using `Closes #`. -We use `hatch` for managing development environments. To set up: +### 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](./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](https://www.conventionalcommits.org/) + (e.g. `feat:`, `fix:`, `docs:`, `refactor:`, `test:`). +6. Push and open a **pull request** against `main`, linking the issue with + `Closes #` and filling out the + [PR template](./.github/PULL_REQUEST_TEMPLATE.md). + +### Contributing to the Python SDK (`mem0/`) + +We use [`hatch`](https://hatch.pypa.io/latest/install/) to manage environments. +**Do not use `pip` or `conda` for dependency management.** ```bash -# Activate environment for specific Python version: -hatch shell dev_py_3_9 # Python 3.9 -hatch shell dev_py_3_10 # Python 3.10 -hatch shell dev_py_3_11 # Python 3.11 -hatch shell dev_py_3_12 # Python 3.12 +# Activate a dev environment (3.9 / 3.10 / 3.11 / 3.12) +hatch shell dev_py_3_11 -# The environment will automatically install all dev dependencies -# Run tests within the activated shell: -make test -``` - -### ๐Ÿ“Œ Pre-commit - -To ensure our standards, make sure to install pre-commit before starting to contribute. - -```bash +# 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 ``` -### ๐Ÿงช Testing +- **Linter / formatter:** Ruff (line length **120**) +- **Import sorting:** isort (`profile = "black"`) +- **Tests:** pytest (in `tests/`) -We use `pytest` to test our code across multiple Python versions. You can run tests using: +See the full [Development guide](https://docs.mem0.ai/contributing/development) for +environment details. + +### Contributing to the TypeScript SDK (`mem0-ts/`) + +We use [`pnpm`](https://pnpm.io/) (v10+) for all TypeScript packages. **Do not use +`npm` or `yarn`.** ```bash -# Run tests with default Python version -make test +cd mem0-ts +pnpm install -# Test specific Python versions: -make test-py-3.9 # Python 3.9 environment -make test-py-3.10 # Python 3.10 environment -make test-py-3.11 # Python 3.11 environment -make test-py-3.12 # Python 3.12 environment - -# When using hatch shells, run tests with: -make test # After activating a shell with hatch shell test_XX +pnpm run build # tsup (CJS + ESM) +pnpm run test # jest (all tests) +pnpm run test:unit # unit tests with coverage ``` -Make sure that all tests pass across all supported Python versions before submitting a pull request. +- **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()`. -We look forward to your pull requests and can't wait to see your contributions! +## Good Contribution Practices -### ๐Ÿš€ Releasing +- **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`. -All packages are published automatically via GitHub Actions when a GitHub Release is created with the correct tag prefix. +## Pull Request Checklist -#### Tag Prefixes +Before requesting review, make sure: + +- [ ] An issue exists and is linked with `Closes #` +- [ ] 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](./SECURITY.md) 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 | |---------|----------|------------|---------| @@ -77,15 +162,17 @@ All packages are published automatically via GitHub Actions when a GitHub Releas | `@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 +### How to Release 1. Bump the version in `pyproject.toml` (Python) or `package.json` (Node) 2. Create a [GitHub Release](https://github.com/mem0ai/mem0/releases/new) with the matching tag prefix 3. The correct workflow will trigger automatically โ€” verify in the [Actions tab](https://github.com/mem0ai/mem0/actions) -#### Publishing Details +### 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! diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..67bf77ba8 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,48 @@ +# Security Policy + +We take the security of Mem0 and our community seriously. Thank you for helping +keep Mem0 and its users safe by disclosing vulnerabilities responsibly. + +## Reporting a Vulnerability + +Please **do not** report security vulnerabilities through public GitHub issues, +pull requests, or discussions. + +If you believe you have found a security vulnerability in Mem0, please report it +privately through one of the following channels: + +1. **GitHub Private Vulnerability Reporting** โ€” open a + [private security advisory](https://github.com/mem0ai/mem0/security/advisories/new) + directly on this repository. +2. **Email** the maintainers at **support@mem0.ai** with the subject line: + + `SECURITY: Mem0 vulnerability report` + +To help us triage and resolve the issue quickly, please include as much of the +following as you can: + +- Affected component or package (e.g. Python SDK, TypeScript SDK, server, OpenMemory) +- Affected version, tag, or commit +- Clear, step-by-step reproduction instructions +- The security impact and a proof of concept, if available +- Any suggested fix or mitigation + +## Response Process + +- We will acknowledge receipt of your report within **72 hours**. +- We will work with you privately to confirm the issue and assess its impact. +- Once a fix or mitigation is ready, we will coordinate a disclosure timeline + with you and credit you for the discovery, unless you prefer to remain anonymous. + +## Public Disclosure + +Please avoid sharing technical details of the vulnerability publicly until the +maintainers have reviewed the issue and a fix or mitigation has been released. We +are committed to resolving valid reports promptly and keeping you informed +throughout the process. + +## Supported Versions + +We release security fixes against the latest published version of each package. +Whenever possible, please reproduce the issue on the most recent release before +reporting. diff --git a/docs/contributing/development.mdx b/docs/contributing/development.mdx index b8565739d..a381e844a 100644 --- a/docs/contributing/development.mdx +++ b/docs/contributing/development.mdx @@ -1,32 +1,65 @@ --- title: Development -description: "Guide to contributing code to Mem0, covering the fork and clone workflow, PR submission, and code quality checks." +description: "Guide to contributing code to Mem0, covering the issue-first workflow, the CLA, environment setup for the Python and TypeScript SDKs, and code quality checks." icon: "code" --- # Development Contributions -We strive to make contributions **easy, collaborative, and enjoyable**. Follow the steps below to ensure a smooth contribution process. +We strive to make contributions **easy, collaborative, and enjoyable**. Mem0 is a +polyglot monorepo containing the **Python SDK** (`mem0/`), the **TypeScript SDK** +(`mem0-ts/`), CLIs, integrations, the self-hosted server, and the docs site. +Follow the steps below for a smooth contribution process. -## Submitting Your Contribution through PR + + For the complete contributor checklist, see + [CONTRIBUTING.md](https://github.com/mem0ai/mem0/blob/main/CONTRIBUTING.md) in + the repository root. + -To contribute, follow these steps: +## 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 work, and agree on the approach before you write code. + +- Search [existing issues](https://github.com/mem0ai/mem0/issues) first. +- If none match, open a + [bug report](https://github.com/mem0ai/mem0/issues/new?template=bug_report.yml) + or [feature request](https://github.com/mem0ai/mem0/issues/new?template=feature_request.yml). +- For anything beyond a trivial fix, wait for a maintainer to confirm the approach. + +Every pull request must link to an issue using `Closes #`. + +### 2. Sign the Contributor License Agreement (CLA) + +**We cannot merge any pull request until you have signed our Contributor License +Agreement (CLA).** When you open your first PR, the CLA bot will comment with a +link to sign โ€” it takes less than a minute and only needs to be done once. + +## Submitting Your Contribution through a PR 1. **Fork & Clone** the repository: [Mem0 on GitHub](https://github.com/mem0ai/mem0) -2. **Create a Feature Branch**: Use a dedicated branch for your changes, e.g., `feature/my-new-feature` -3. **Implement Changes**: If adding a feature or fixing a bug, ensure to: +2. **Create a Feature Branch**: Use a dedicated branch, e.g., `feature/my-new-feature` +3. **Implement Changes**: If adding a feature or fixing a bug, be sure to: - Write necessary **tests** - Add **documentation, docstrings, and runnable examples** 4. **Code Quality Checks**: - Run **linting** to catch style issues - Ensure **all tests pass** -5. **Submit a Pull Request** +5. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/) + (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`) +6. **Submit a Pull Request** against `main`, linking the issue and filling out the + PR template. For detailed guidance on pull requests, refer to [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). --- -## Dependency Management +## Python SDK (`mem0/`) + +### Dependency Management We use `hatch` as our package manager. Install it by following the [official instructions](https://hatch.pypa.io/latest/install/). @@ -44,13 +77,9 @@ hatch -e dev_py_3_11 shell # For dev_py_3_11 (differences are mentioned in pypr make install_all ``` ---- - -## Development Standards - ### Pre-commit Hooks -Ensure `pre-commit` is installed before contributing: +Ensure `pre-commit` is installed before contributing (hooks run ruff + isort): ```bash pre-commit install @@ -58,7 +87,7 @@ pre-commit install ### Linting with `ruff` -Run the linter and fix any reported issues before submitting your PR: +Run the linter and fix any reported issues before submitting your PR (line length **120**): ```bash make lint @@ -66,10 +95,11 @@ make lint ### Code Formatting -To maintain a consistent code style, format your code: +To maintain a consistent code style, format your code and sort imports (isort, `profile = "black"`): ```bash make format +make sort ``` ### Testing with `pytest` @@ -84,10 +114,46 @@ make test --- -## Release Process +## TypeScript SDK (`mem0-ts/`) -Currently, releases are handled manually. We aim for frequent releases, typically when new features or bug fixes are introduced. +We use [`pnpm`](https://pnpm.io/) (v10+) for all TypeScript packages. **Do NOT use +`npm` or `yarn`.** + +```bash +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 +``` + +### Standards + +- **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()` --- -Thank you for contributing to Mem0! \ No newline at end of file +## Reporting Security Issues + +**Do not report security vulnerabilities through public issues or pull requests.** +Please follow our [Security Policy](https://github.com/mem0ai/mem0/blob/main/SECURITY.md) +to report them privately. + +--- + +## Release Process + +Packages are published automatically via GitHub Actions when a GitHub Release is +created with the correct tag prefix (e.g. `v*` for the Python SDK, `ts-v*` for the +TypeScript SDK). See +[CONTRIBUTING.md](https://github.com/mem0ai/mem0/blob/main/CONTRIBUTING.md#releasing) +for the full tag-prefix table and publishing details. + +--- + +Thank you for contributing to Mem0!