Skip to content

armgit / mem0

Public Imported from GitHub
0

The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.

docs: add SECURITY.md and improve contribution guidelines (#5855)

Kartike4efdd2e29e4
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 #<issue-number>`.
-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 #<number>` 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
-
-# The environment will automatically install all dev dependencies
-# Run tests within the activated shell:
+# 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
```
-### πŸ“Œ Pre-commit
+- **Linter / formatter:** Ruff (line length **120**)
+- **Import sorting:** isort (`profile = "black"`)
+- **Tests:** pytest (in `tests/`)
+
+See the full [Development guide](https://docs.mem0.ai/contributing/development) for
+environment details.
+
+### Contributing to the TypeScript SDK (`mem0-ts/`)
-To ensure our standards, make sure to install pre-commit before starting to contribute.
+We use [`pnpm`](https://pnpm.io/) (v10+) for all TypeScript packages. **Do not use
+`npm` or `yarn`.**
```bash
-pre-commit install
+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
```
-### πŸ§ͺ Testing
+- **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 use `pytest` to test our code across multiple Python versions. You can run tests using:
+## Good Contribution Practices
-```bash
-# Run tests with default Python version
-make test
+- **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`.
-# 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
+## Pull Request Checklist
-# When using hatch shells, run tests with:
-make test # After activating a shell with hatch shell test_XX
-```
+Before requesting review, make sure:
-Make sure that all tests pass across all supported Python versions before submitting a pull request.
+- [ ] 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
-We look forward to your pull requests and can't wait to see your contributions!
+## Reporting Security Issues
-### πŸš€ Releasing
+**Do not report security vulnerabilities through public issues or pull requests.**
+Please follow our [Security Policy](./SECURITY.md) to report them privately.
-All packages are published automatically via GitHub Actions when a GitHub Release is created with the correct tag prefix.
+## Releasing
-#### Tag Prefixes
+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 **[email protected]** 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
+<Note>
+ For the complete contributor checklist, see
+ [CONTRIBUTING.md](https://github.com/mem0ai/mem0/blob/main/CONTRIBUTING.md) in
+ the repository root.
+</Note>
-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 #<issue-number>`.
+
+### 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
---
+## TypeScript SDK (`mem0-ts/`)
+
+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()`
+
+---
+
+## 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
-Currently, releases are handled manually. We aim for frequent releases, typically when new features or bug fixes are introduced.
+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!
\ No newline at end of file
+Thank you for contributing to Mem0!