From 13d42a99e96891a3e4334fbebc35fa7aea6a8daa Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Sat, 28 Mar 2026 06:20:03 +0530 Subject: [PATCH] docs: improve CLI dev workflow and prioritize Node.js installation (#4579) --- README.md | 2 +- cli/CLI_SPECIFICATION.md | 2 +- cli/README.md | 6 +-- cli/node/package.json | 3 ++ cli/python/Makefile | 47 ++++++++++++------- cli/python/README.md | 10 ++++ cli/python/development.md | 97 ++++++++++++++++++++++++++------------- docs/platform/cli.mdx | 12 ++--- 8 files changed, 118 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index ee2138da7..3ef703709 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ npm install mem0ai Manage memories from your terminal: ```bash -pip install mem0-cli # or: npm install -g @mem0/cli +npm install -g @mem0/cli # or: pip install mem0-cli mem0 init mem0 add "Prefers dark mode and vim keybindings" --user-id alice diff --git a/cli/CLI_SPECIFICATION.md b/cli/CLI_SPECIFICATION.md index 145b1af18..255c8b0b4 100644 --- a/cli/CLI_SPECIFICATION.md +++ b/cli/CLI_SPECIFICATION.md @@ -37,8 +37,8 @@ The `cli/` directory provides the mem0 CLI in two languages with a shared specif | Language | Directory | Package Name | Install Command | |------------|------------|---------------|----------------------------| -| Python | `python/` | `mem0-cli` | `pip install mem0-cli` | | TypeScript | `node/` | `@mem0/cli` | `npm install -g @mem0/cli` | +| Python | `python/` | `mem0-cli` | `pip install mem0-cli` | Both implementations produce a binary named `mem0` and provide **identical CLI behavior** -- same commands, same options, same output formats, same error messages. diff --git a/cli/README.md b/cli/README.md index 558649e9b..82335dbe1 100644 --- a/cli/README.md +++ b/cli/README.md @@ -5,11 +5,11 @@ The official command-line interface for [mem0](https://mem0.ai) — the memory l ## Installation ```bash -pip install mem0-cli +npm install -g @mem0/cli ``` ```bash -npm install -g @mem0/cli +pip install mem0-cli ``` Both packages install a `mem0` binary with identical behavior. @@ -86,8 +86,8 @@ mem0 search "preferences" --user-id alice --output json | jq '.data.results[].me | Language | Directory | Package | Docs | |----------|-----------|---------|------| -| Python | [`python/`](./python/) | `mem0-cli` | [README](./python/README.md) | | TypeScript | [`node/`](./node/) | `@mem0/cli` | [README](./node/README.md) | +| Python | [`python/`](./python/) | `mem0-cli` | [README](./python/README.md) | ## Documentation diff --git a/cli/node/package.json b/cli/node/package.json index ec92cb7b0..bee02b2f4 100644 --- a/cli/node/package.json +++ b/cli/node/package.json @@ -21,6 +21,9 @@ "license": "Apache-2.0", "author": "mem0.ai ", "keywords": ["mem0", "memory", "ai", "agents", "cli"], + "publishConfig": { + "access": "public" + }, "dependencies": { "commander": "^12.0.0", "chalk": "^5.3.0", diff --git a/cli/python/Makefile b/cli/python/Makefile index b60221887..c9493a3e6 100644 --- a/cli/python/Makefile +++ b/cli/python/Makefile @@ -1,30 +1,43 @@ -.PHONY: install dev lint format test build clean publish publish-test +VENV := .venv +PYTHON := $(VENV)/bin/python +PIP := $(VENV)/bin/pip -install: - pip install -e . +.PHONY: install dev lint format test build clean publish publish-test shell -dev: - pip install -e ".[dev]" +$(VENV)/bin/activate: + python3 -m venv $(VENV) + $(PIP) install -U pip -lint: - ruff check . - ruff format --check . +install: $(VENV)/bin/activate + $(PIP) install -e . -format: - ruff check --fix . - ruff format . +dev: $(VENV)/bin/activate + $(PIP) install -e ".[dev]" -test: - pytest +lint: dev + $(VENV)/bin/ruff check . + $(VENV)/bin/ruff format --check . -build: clean - hatch build +format: dev + $(VENV)/bin/ruff check --fix . + $(VENV)/bin/ruff format . + +test: dev + $(VENV)/bin/pytest + +build: clean $(VENV)/bin/activate + $(PIP) install hatch + $(VENV)/bin/hatch build clean: rm -rf dist/ publish: build - hatch publish + $(VENV)/bin/hatch publish publish-test: build - hatch publish --repo test + $(VENV)/bin/hatch publish --repo test + +shell: $(VENV)/bin/activate + @echo "Spawning a new shell with the virtual environment activated..." + @VIRTUAL_ENV=$(CURDIR)/$(VENV) PATH=$(CURDIR)/$(VENV)/bin:$$PATH exec $(SHELL) diff --git a/cli/python/README.md b/cli/python/README.md index d4f6e2646..574004c30 100644 --- a/cli/python/README.md +++ b/cli/python/README.md @@ -4,10 +4,20 @@ The official command-line interface for [mem0](https://mem0.ai) — the memory l ## Installation +### Using pipx (recommended) + +```bash +pipx install mem0-cli +``` + +### Using pip + ```bash pip install mem0-cli ``` +> **Note:** On macOS with Homebrew Python, `pip install` outside a virtual environment will fail with an `externally-managed-environment` error ([PEP 668](https://peps.python.org/pep-0668/)). Use `pipx` instead, or install inside a virtual environment. + ## Quick Start ```bash diff --git a/cli/python/development.md b/cli/python/development.md index b38df6336..e05a2b062 100644 --- a/cli/python/development.md +++ b/cli/python/development.md @@ -3,8 +3,7 @@ ## Prerequisites - Python **3.10+** - -## Setup +- `make` (optional — you can use plain Python commands instead) All commands below should be run from the `python/` directory: @@ -12,7 +11,21 @@ All commands below should be run from the `python/` directory: cd python ``` -## Install local (editable) + run +## Setup + +### Using Make (recommended) + +All `make` targets automatically create a virtual environment (`.venv/`) and install the required dependencies — no manual setup needed. + +```bash +# Install the CLI in editable mode +make install + +# Install with dev tools (tests + linting) +make dev +``` + +### Using Python directly ```bash python3 -m venv .venv @@ -22,43 +35,32 @@ python -m pip install -U pip # Install in editable mode pip install -e . -# Run -mem0 --help -mem0 version -``` - -> **After moving to the new directory structure:** If you previously had the CLI installed from the old repo root, you need to re-run `pip install -e .` from inside the `python/` directory to pick up the new location. - -## Run without installing globally - -This still installs the package into your active virtualenv (editable), but you can invoke it via module execution: - -```bash -source .venv/bin/activate -pip install -e . -python -m mem0_cli --help -``` - -## Optional extras - -### OSS integration extras - -```bash -pip install -e ".[oss]" -``` - -### Dev tools (tests/lint) - -```bash +# With dev tools pip install -e ".[dev]" ``` +## Make targets + +| Target | Description | +| ------------------- | ------------------------------------------------ | +| `make install` | Create venv and install the CLI (editable mode) | +| `make dev` | Create venv and install CLI + dev dependencies | +| `make test` | Run all tests (installs dev deps if needed) | +| `make lint` | Run linter and format check | +| `make format` | Auto-fix lint issues and format code | +| `make build` | Build distribution packages | +| `make clean` | Remove `dist/` | +| `make publish` | Build and publish to PyPI | +| `make publish-test` | Build and publish to Test PyPI | +| `make shell` | Open a new shell with the venv activated | + ## Run tests ```bash -pip install -e ".[dev]" +# Using Make +make test -# Run all tests +# Using Python directly pytest # Run a specific test file @@ -68,9 +70,38 @@ pytest tests/test_cli_integration.py pytest -k test_help ``` +## Run the CLI + +```bash +# Using Make — drop into an activated shell +make shell +mem0 --help + +# Using Python directly (with venv activated) +source .venv/bin/activate +mem0 --help +mem0 version + +# Or run without activating +.venv/bin/mem0 --help +``` + ## Lint ```bash +# Using Make +make lint # check only +make format # auto-fix + +# Using Python directly (with venv activated) ruff check . ruff format . ``` + +## Optional extras + +### OSS integration + +```bash +pip install -e ".[oss]" +``` diff --git a/docs/platform/cli.mdx b/docs/platform/cli.mdx index 93c3aad77..1935945de 100644 --- a/docs/platform/cli.mdx +++ b/docs/platform/cli.mdx @@ -1,24 +1,24 @@ --- title: CLI -description: "Manage memories from your terminal. Available for Python and Node.js." +description: "Manage memories from your terminal. Available for Node.js and Python." icon: "terminal" iconType: "solid" --- -The mem0 CLI lets you add, search, list, update, and delete memories directly from the terminal. It works with the Mem0 Platform API and is available as both a Python package and an npm package. +The mem0 CLI lets you add, search, list, update, and delete memories directly from the terminal. It works with the Mem0 Platform API and is available as both an npm package and a Python package. Both implementations provide identical behavior — same commands, same options, same output formats. ## Installation -```bash pip -pip install mem0-cli -``` - ```bash npm npm install -g @mem0/cli ``` + +```bash pip +pip install mem0-cli +``` ## Authentication