The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.
Python agentic-memoryagentic-memory-systemagentsaiai-agentschatgptgenaillmlong-term-memorymemorymemory-managementpythonragstate-management
docs: add SECURITY.md and improve contribution guidelines (#5855)
Kartike4efdd2e29e4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 Release1. 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 prefix3. 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.mdnew file mode 100644index 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.mdxindex 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 PR1. **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 ManagementWe 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 pyprmake 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):```bashpre-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**):```bashmake 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"`):```bashmake 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!