docs: improve CLI dev workflow and prioritize Node.js installation (#4579)

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

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.
 

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
 

cli/node/package.json

@@ -21,6 +21,9 @@
   "license": "Apache-2.0",
   "author": "mem0.ai <founders@mem0.ai>",
   "keywords": ["mem0", "memory", "ai", "agents", "cli"],
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "commander": "^12.0.0",
     "chalk": "^5.3.0",

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:
+.PHONY: install dev lint format test build clean publish publish-test shell
-	pip install -e .
 
-dev:
+$(VENV)/bin/activate:
-	pip install -e ".[dev]"
+	python3 -m venv $(VENV)
+	$(PIP) install -U pip
 
-lint:
+install: $(VENV)/bin/activate
-	ruff check .
+	$(PIP) install -e .
-	ruff format --check .
 
-format:
+dev: $(VENV)/bin/activate
-	ruff check --fix .
+	$(PIP) install -e ".[dev]"
-	ruff format .
 
-test:
+lint: dev
-	pytest
+	$(VENV)/bin/ruff check .
+	$(VENV)/bin/ruff format --check .
 
-build: clean
+format: dev
-	hatch build
+	$(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)

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

cli/python/development.md

@@ -3,8 +3,7 @@
 ## Prerequisites
 
 - Python **3.10+**
-
+- `make` (optional — you can use plain Python commands instead)
-## Setup
 
 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
+# With dev tools
-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
 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]"
+```

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
 
 <CodeGroup>
-```bash pip
-pip install mem0-cli
-```
-
 ```bash npm
 npm install -g @mem0/cli
 ```
+
+```bash pip
+pip install mem0-cli
+```
 </CodeGroup>
 
 ## Authentication