Merge remote-tracking branch 'origin/main' into fix/codex-install-docs

# Conflicts:
#	mem0-plugin/README.md

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "mem0-plugins",
+  "interface": {
+    "displayName": "Mem0 Plugins"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": {
+        "source": "local",
+        "path": "./mem0-plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "mem0",
       "source": "./mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
-      "version": "0.1.0"
+      "version": "0.1.1"
     }
   ]
 }

.cursor-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "mem0",
       "source": "./mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
-      "version": "0.1.0"
+      "version": "0.1.1"
     }
   ]
 }

.github/workflows/cd.yml

@@ -7,6 +7,7 @@ on:
 jobs:
   build-n-publish:
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+    if: startsWith(github.event.release.tag_name, 'v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -38,7 +39,7 @@ jobs:
       #     packages_dir: dist/
 
       - name: Publish distribution 📦 to PyPI
-        if: startsWith(github.ref, 'refs/tags')
+        if: startsWith(github.ref, 'refs/tags/v')
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages_dir: dist/

.github/workflows/ci.yml

@@ -14,8 +14,48 @@ on:
       - 'mem0/**'
       - 'tests/**'
       - 'embedchain/**'
+      - 'pyproject.toml'
 
 jobs:
+  changelog_check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Require CHANGELOG entry when Python SDK version changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+
+          extract_version() {
+            python3 -c "import sys, re; m = re.search(r'^\s*version\s*=\s*\"([^\"]+)\"', sys.stdin.read(), re.M); print(m.group(1) if m else '')"
+          }
+
+          base_version=$(git show "$BASE_SHA:pyproject.toml" 2>/dev/null | extract_version || echo "")
+          head_version=$(extract_version < pyproject.toml)
+
+          echo "Base version: ${base_version:-<unknown>}"
+          echo "Head version: $head_version"
+
+          if [ -z "$base_version" ] || [ "$base_version" = "$head_version" ]; then
+            echo "pyproject.toml version unchanged — no CHANGELOG entry required."
+            exit 0
+          fi
+
+          echo "Detected version bump ${base_version} -> ${head_version}. Checking docs/changelog/sdk.mdx…"
+
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- docs/changelog/sdk.mdx | grep -q .; then
+            echo "Changelog update present in docs/changelog/sdk.mdx ✅"
+          else
+            echo "::error file=pyproject.toml::pyproject.toml version changed from ${base_version} to ${head_version} but docs/changelog/sdk.mdx was not updated in this PR. Add a new <Update> entry under the Python tab for v${head_version}."
+            exit 1
+          fi
+
   check_changes:
     runs-on: ubuntu-latest
     outputs:

.github/workflows/cli-node-cd.yml

@@ -0,0 +1,46 @@
+name: Publish @mem0/cli 📦 to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/cli 📦 to npm
+    if: startsWith(github.event.release.tag_name, 'cli-node-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: cli/node
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/cli-node-ci.yml

@@ -0,0 +1,100 @@
+name: CLI Node CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'cli/node/**'
+      - '.github/workflows/cli-node-ci.yml'
+  pull_request:
+    paths:
+      - 'cli/node/**'
+      - '.github/workflows/cli-node-ci.yml'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: cli/node
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: cli/node
+        run: pnpm run lint
+
+      - name: Type check
+        working-directory: cli/node
+        run: pnpm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: cli/node
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        working-directory: cli/node
+        run: pnpm run test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: cli/node
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: cli/node
+        run: pnpm run build
+
+      - name: Verify dist output
+        run: |
+          test -f cli/node/dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)

.github/workflows/cli-python-cd.yml

@@ -0,0 +1,34 @@
+name: Publish mem0-cli 🐍 distributions 📦 to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish mem0-cli 📦 to PyPI
+    if: startsWith(github.event.release.tag_name, 'cli-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: cli/python
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build a binary wheel and a source tarball
+        run: hatch build --clean
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: cli/python/dist/

.github/workflows/cli-python-ci.yml

@@ -0,0 +1,79 @@
+name: CLI Python CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'cli/python/**'
+      - '.github/workflows/cli-python-ci.yml'
+  pull_request:
+    paths:
+      - 'cli/python/**'
+      - '.github/workflows/cli-python-ci.yml'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dev dependencies
+        working-directory: cli/python
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        working-directory: cli/python
+        run: ruff check .
+
+      - name: Check formatting
+        working-directory: cli/python
+        run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dev dependencies
+        working-directory: cli/python
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        working-directory: cli/python
+        run: pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build
+        working-directory: cli/python
+        run: hatch build --clean
+
+      - name: Verify dist output
+        run: |
+          ls cli/python/dist/*.whl || (echo "Wheel file missing" && exit 1)
+          ls cli/python/dist/*.tar.gz || (echo "Source dist missing" && exit 1)

.github/workflows/docs-llms-txt-check.yml

@@ -0,0 +1,45 @@
+name: docs - llms.txt check
+
+# Blocks PRs that introduce new .mdx pages without a matching entry in
+# docs/llms.txt, or that link to pages that no longer exist. Contributors
+# must update docs/llms.txt in the same PR. Run locally with:
+#   python scripts/check-llms-txt-coverage.py           # read-only
+#   python scripts/check-llms-txt-coverage.py --write   # scaffold placeholders
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**/*.mdx'
+      - 'docs/llms.txt'
+      - 'scripts/check-llms-txt-coverage.py'
+      - 'scripts/llms-txt-ignore.txt'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  check-llms-txt:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify docs/llms.txt coverage
+        run: |
+          if ! python3 scripts/check-llms-txt-coverage.py; then
+            echo ""
+            echo "::error title=llms.txt out of sync::docs/llms.txt does not match docs/**/*.mdx."
+            echo ""
+            echo "To fix:"
+            echo "  1. Run locally:  python scripts/check-llms-txt-coverage.py --write"
+            echo "     This appends placeholder entries under '## Unclassified - needs triage'."
+            echo "  2. For each placeholder:"
+            echo "       - replace [TODO: Platform|OSS|Both] with the correct scope tag"
+            echo "       - rewrite the description as 'Use when ...'"
+            echo "       - move the entry into the appropriate section"
+            echo "       - delete the '## Unclassified - needs triage' heading once empty"
+            echo "  3. Resolve any stale URLs listed above by updating or removing the link."
+            echo "  4. Commit the updated docs/llms.txt to this PR."
+            exit 1
+          fi

.github/workflows/openclaw-cd.yml

@@ -0,0 +1,46 @@
+name: Publish @mem0/openclaw-mem0 📦 to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/openclaw-mem0 📦 to npm
+    if: startsWith(github.event.release.tag_name, 'openclaw-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: openclaw
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/ts-sdk-cd.yml

@@ -0,0 +1,46 @@
+name: Publish mem0ai 📦 to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish mem0ai 📦 to npm
+    if: startsWith(github.event.release.tag_name, 'ts-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: mem0-ts
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: mem0-ts/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/ts-sdk-ci.yml

@@ -24,6 +24,42 @@ jobs:
             ts_sdk:
               - 'mem0-ts/**'
 
+  changelog_check:
+    needs: check_changes
+    if: github.event_name == 'pull_request' && needs.check_changes.outputs.ts_sdk_changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Require CHANGELOG entry when SDK version changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+
+          base_version=$(git show "$BASE_SHA:mem0-ts/package.json" 2>/dev/null | jq -r .version || echo "")
+          head_version=$(jq -r .version mem0-ts/package.json)
+
+          echo "Base version: ${base_version:-<unknown>}"
+          echo "Head version: $head_version"
+
+          if [ -z "$base_version" ] || [ "$base_version" = "$head_version" ]; then
+            echo "mem0-ts/package.json version unchanged — no CHANGELOG entry required."
+            exit 0
+          fi
+
+          echo "Detected version bump ${base_version} -> ${head_version}. Checking docs/changelog/sdk.mdx…"
+
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- docs/changelog/sdk.mdx | grep -q .; then
+            echo "Changelog update present in docs/changelog/sdk.mdx ✅"
+          else
+            echo "::error file=mem0-ts/package.json::mem0-ts/package.json version changed from ${base_version} to ${head_version} but docs/changelog/sdk.mdx was not updated in this PR. Add a new <Update> entry under the TypeScript tab for v${head_version}."
+            exit 1
+          fi
+
   build_ts_sdk:
     needs: check_changes
     if: needs.check_changes.outputs.ts_sdk_changed == 'true'

.github/workflows/vercel-ai-cd.yml

@@ -0,0 +1,46 @@
+name: Publish @mem0/vercel-ai-provider 📦 to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/vercel-ai-provider 📦 to npm
+    if: startsWith(github.event.release.tag_name, 'vercel-ai-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: vercel-ai-sdk
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: vercel-ai-sdk/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.gitignore

@@ -4,6 +4,10 @@ __pycache__/
 *$py.class
 **/node_modules/
 
+# Self-hosted server local runtime state
+server/history/
+server/.env
+
 # C extensions
 *.so
 
@@ -15,8 +19,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/

AGENTS.md

@@ -0,0 +1,583 @@
+# AGENTS.md
+
+This file provides context for AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, etc.) working with the Mem0 repository.
+
+## Project Overview
+
+**Mem0** ("mem-zero") is an intelligent memory layer for AI agents and assistants. It provides persistent, personalized memory via both a hosted platform API and self-hosted open-source SDKs.
+
+- **Repository**: https://github.com/mem0ai/mem0
+- **Documentation**: https://docs.mem0.ai
+- **License**: Apache-2.0
+
+## Repository Structure
+
+This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs, servers, plugins, documentation, and evaluation tooling.
+
+### Key Directories
+
+| Directory | Description |
+|-----------|-------------|
+| `mem0/` | Core Python SDK (`mem0ai` on PyPI) — memory, LLMs, embeddings, vector stores, graphs, rerankers |
+| `mem0-ts/` | TypeScript SDK (`mem0ai` on npm) — client + OSS memory |
+| `cli/python/` | Python CLI (`mem0-cli` on PyPI) — Typer-based, entry point `mem0` |
+| `cli/node/` | Node CLI (`@mem0/cli` on npm) — Commander-based, entry point `mem0` |
+| `vercel-ai-sdk/` | `@mem0/vercel-ai-provider` — Vercel AI SDK memory provider |
+| `openclaw/` | `@mem0/openclaw-mem0` — OpenClaw plugin for Claude Code / AI editors |
+| `server/` | FastAPI REST server for self-hosted Mem0 (Docker: FastAPI + PostgreSQL/pgvector + Neo4j) |
+| `openmemory/` | Self-hosted memory platform — `api/` (FastAPI + Alembic + MCP server) and `ui/` (Next.js 15 + React 19) |
+| `mem0-plugin/` | AI editor plugins (Claude Code, Cursor, Codex) — MCP server connection, lifecycle hooks, skills |
+| `skills/` | Claude Code skill definitions — `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/` |
+| `docs/` | Documentation site (Mintlify) |
+| `tests/` | Python SDK tests (pytest) |
+| `evaluation/` | Benchmarking framework — LOCOMO evals, experiment runner, score generation |
+| `examples/` | Sample projects — demo apps, Chrome extension, multi-agent patterns |
+| `cookbooks/` | Jupyter notebooks — customer support chatbot, AutoGen integration |
+| `embedchain/` | Legacy Embedchain RAG framework (maintained separately, Poetry-based) |
+| `pr-reviews/` | Pull request review materials |
+| `scripts/` | Repo-wide utility scripts (e.g., `check-llms-txt-coverage.py` for docs/llms.txt sync) |
+
+### Core Package Dependencies
+
+```
+mem0 (Python SDK)          mem0-ts (TypeScript SDK)
+├── mem0/memory/           ├── src/client/        (MemoryClient — hosted)
+├── mem0/llms/             └── src/oss/           (Memory — self-hosted)
+├── mem0/embeddings/           ├── src/llms/
+├── mem0/vector_stores/        ├── src/embeddings/
+├── mem0/graphs/               ├── src/vector_stores/
+└── mem0/reranker/             └── src/graphs/
+
+cli/python/ ──▶ mem0ai (optional, for OSS mode)
+cli/node/   ──▶ mem0ai (npm, for API calls)
+vercel-ai-sdk/ ──▶ ai, @ai-sdk/* providers
+openclaw/   ──▶ mem0ai (npm)
+```
+
+## Development Setup
+
+### Requirements
+
+- **Python**: 3.9+ (3.10+ for CLI)
+- **Node.js**: v18+ (v20 or v22 recommended)
+- **pnpm**: v10+ (`npm install -g pnpm@10`) — used for all TypeScript packages
+- **Hatch**: Python build/environment tool (`pip install hatch`)
+- **Docker**: Required for `server/` and `openmemory/` development
+
+### Initial Setup
+
+```bash
+# Python SDK
+hatch shell dev_py_3_11           # creates environment with all deps
+pre-commit install                # install git hooks
+
+# TypeScript packages
+cd mem0-ts && pnpm install        # TS SDK
+cd cli/node && pnpm install       # Node CLI
+cd vercel-ai-sdk && pnpm install  # Vercel AI provider
+cd openclaw && pnpm install       # OpenClaw plugin
+```
+
+## Build, Lint, and Test Commands
+
+### Python SDK (`mem0/`)
+
+```bash
+# Environment setup (uses Hatch)
+hatch shell dev_py_3_11           # or dev_py_3_9, dev_py_3_10, dev_py_3_12
+
+# Linting and formatting
+make lint                          # ruff check
+make format                        # ruff format
+make sort                          # isort mem0/
+
+# Tests
+make test                          # pytest tests/
+make test-py-3.9                   # test specific Python version (3.9–3.12)
+
+# Build and publish
+make build                         # hatch build
+make publish                       # hatch publish
+```
+
+- **Python:** 3.9, 3.10, 3.11, 3.12
+- **Linter/formatter:** Ruff (line length **120**)
+- **Import sorting:** isort (`profile = "black"`)
+- **Test framework:** pytest (with pytest-mock, pytest-asyncio)
+- **Pre-commit hooks:** ruff + isort — run `pre-commit install` before committing
+
+### TypeScript SDK (`mem0-ts/`)
+
+```bash
+cd mem0-ts
+pnpm install
+pnpm run build                     # tsup
+pnpm run test                      # jest (all tests)
+pnpm run test:unit                 # jest --coverage (unit tests only)
+pnpm run test:integration          # jest (integration tests, needs MEM0_API_KEY)
+pnpm run test:ci                   # jest --coverage --ci (CI mode)
+pnpm run test:watch                # jest watch mode
+```
+
+- **Node:** 20, 22 (CI-tested)
+- **Build:** tsup (CJS + ESM)
+- **Test:** jest
+- **Formatter:** prettier
+
+### Python CLI (`cli/python/`)
+
+```bash
+cd cli/python
+pip install -e ".[dev]"            # dev install with ruff + pytest
+ruff check .                       # lint
+ruff format .                      # format
+pytest                             # test
+hatch build                        # build
+```
+
+- **Python:** 3.10+ (not 3.9)
+- **Linter/formatter:** Ruff (line length **100** — different from root SDK)
+- **Ruff rules:** E, F, I, W, UP, B, SIM, RUF (ignores E501, B008 for Typer patterns, SIM108)
+- **Framework:** Typer + Rich + httpx
+- **Entry point:** `mem0 = "mem0_cli.app:main"`
+- **Source layout:** `src/mem0_cli/`
+- **Optional dependency:** `mem0ai` (for OSS mode, via `[oss]` extra)
+
+### Node CLI (`cli/node/`)
+
+```bash
+cd cli/node
+pnpm install
+pnpm run build                     # tsup
+pnpm run lint                      # biome check src/
+pnpm run lint:fix                  # biome check --write src/
+pnpm run typecheck                 # tsc --noEmit
+pnpm run test                      # vitest run
+pnpm run test:watch                # vitest (watch mode)
+pnpm run dev                       # tsx src/index.ts (development)
+```
+
+- **Node:** 18+ required
+- **Build:** tsup (ESM)
+- **Linter:** Biome (not ESLint, not Ruff)
+- **Test:** vitest (not jest)
+- **Framework:** Commander + Chalk + ora + cli-table3
+
+### Vercel AI SDK Provider (`vercel-ai-sdk/`)
+
+```bash
+cd vercel-ai-sdk
+pnpm install
+pnpm run build                     # tsup
+pnpm run lint                      # eslint
+pnpm run type-check                # tsc --noEmit
+pnpm run prettier-check            # prettier --check
+pnpm run test                      # jest
+pnpm run test:edge                 # vitest (edge runtime)
+pnpm run test:node                 # vitest (node runtime)
+```
+
+- **Build:** tsup (CJS + ESM)
+- **Lint:** ESLint + Prettier
+- **Test:** jest + vitest (edge/node configs)
+
+### OpenClaw Plugin (`openclaw/`)
+
+```bash
+cd openclaw
+pnpm install
+pnpm run build                     # tsup
+pnpm run test                      # vitest run
+```
+
+- **Build:** tsup (ESM)
+- **Test:** vitest (with Codecov in CI)
+- **Plugin manifest:** `openclaw.plugin.json`
+
+### Server (`server/`)
+
+```bash
+# Docker production build
+cd server
+make build                         # docker build -t mem0-api-server .
+make run_local                     # docker run -p 8000:8000 with .env
+
+# Docker Compose development (FastAPI + PostgreSQL/pgvector + Neo4j)
+cd server
+docker-compose up                  # starts all 3 services
+# mem0 API: localhost:8888
+# PostgreSQL: localhost:8432
+# Neo4j HTTP: localhost:8474, Bolt: localhost:8687
+```
+
+- **Framework:** FastAPI with uvicorn (auto-reload in dev)
+- **Services:** PostgreSQL with pgvector, Neo4j 5.x with APOC plugin
+- **Hot reload:** Dev Dockerfile mounts `server/` and `mem0/` for live changes
+
+### OpenMemory (`openmemory/`)
+
+```bash
+# Full stack via Docker Compose
+cd openmemory
+docker-compose up
+# Qdrant: localhost:6333
+# API (MCP): localhost:8765
+# UI: localhost:3000
+
+# Individual development
+cd openmemory/api && uvicorn main:app --reload       # FastAPI backend
+cd openmemory/ui && npm run dev                       # Next.js frontend
+
+# Tests
+cd openmemory/api && pytest tests/                   # API tests (e.g., test_mcp_server.py)
+```
+
+- **API:** FastAPI + Alembic (DB migrations) + MCP server (Model Context Protocol)
+- **UI:** Next.js 15, React 19, Radix UI, Redux Toolkit, TailwindCSS, Recharts
+- **Vector store:** Qdrant
+
+### Documentation (`docs/`)
+
+```bash
+make docs                          # or: cd docs && mintlify dev
+```
+
+- **Framework:** Mintlify
+- **API spec:** `docs/openapi.json`
+- **Structure:** `api-reference/`, `open-source/`, `platform/`, `integrations/`, `cookbooks/`, `core-concepts/`
+
+### Evaluation (`evaluation/`)
+
+```bash
+cd evaluation
+make run-mem0-add                  # Run mem0 add experiments
+make run-mem0-search               # Run mem0 search experiments
+make run-mem0-plus-add             # With graph memory
+make run-mem0-plus-search          # With graph memory
+make run-rag                       # RAG baseline
+make run-full-context              # Full context baseline
+make run-langmem                   # LangMem comparison
+make run-openai                    # OpenAI comparison
+```
+
+## Core APIs
+
+### Python
+
+| Function / Class | Purpose | Import |
+|-----------------|---------|--------|
+| `Memory` | Self-hosted memory (sync) | `from mem0 import Memory` |
+| `AsyncMemory` | Self-hosted memory (async) | `from mem0 import AsyncMemory` |
+| `MemoryClient` | Hosted platform client (sync) | `from mem0 import MemoryClient` |
+| `AsyncMemoryClient` | Hosted platform client (async) | `from mem0 import AsyncMemoryClient` |
+
+**Key `Memory` / `MemoryClient` methods:**
+
+| Method | Purpose |
+|--------|---------|
+| `add(messages, *, user_id, agent_id, run_id, metadata)` | Store a new memory |
+| `search(query, *, user_id, agent_id, run_id, limit, filters)` | Search memories |
+| `get(memory_id)` | Retrieve a single memory by ID |
+| `get_all(*, user_id, agent_id, run_id, limit)` | List all memories |
+| `update(memory_id, data)` | Update a memory |
+| `delete(memory_id)` | Delete a memory |
+| `delete_all(*, user_id, agent_id, run_id)` | Delete all memories |
+| `history(memory_id)` | Get change history for a memory |
+
+### TypeScript
+
+| Export | Purpose | Import |
+|--------|---------|--------|
+| `MemoryClient` | Hosted platform client | `import { MemoryClient } from 'mem0ai'` |
+| `Memory` | Self-hosted OSS memory | `import { Memory } from 'mem0ai/oss'` |
+
+## Import Patterns
+
+### Python
+
+| What | Import |
+|------|--------|
+| Core memory classes | `from mem0 import Memory, AsyncMemory` |
+| Platform client | `from mem0 import MemoryClient, AsyncMemoryClient` |
+| Configuration | `from mem0.configs.base import MemoryConfig` |
+| LLM providers | `from mem0.llms.<provider> import <ProviderLLM>` |
+| Embedding providers | `from mem0.embeddings.<provider> import <ProviderEmbedding>` |
+| Vector store providers | `from mem0.vector_stores.<provider> import <ProviderVectorStore>` |
+
+### TypeScript
+
+| What | Import |
+|------|--------|
+| Hosted client | `import { MemoryClient } from 'mem0ai'` |
+| OSS memory | `import { Memory } from 'mem0ai/oss'` |
+| Specific providers (OSS) | `import { OpenAIEmbedding } from 'mem0ai/oss'` |
+
+## Coding Standards
+
+### File Naming Conventions
+
+- **Python source files:** `snake_case.py` (e.g., `azure_openai.py`, `cohere_reranker.py`)
+- **Python test files:** `test_<module>.py` (e.g., `test_memory.py`, `test_main.py`)
+- **TypeScript source files:** `snake_case.ts` (e.g., `azure_ai_search.ts`)
+- **TypeScript test files:** `<module>.test.ts` (e.g., `memory.test.ts`)
+- **Config/manifest files:** `kebab-case` (e.g., `openclaw.plugin.json`, `jest.config.js`)
+
+### Python Conventions
+
+- **Provider pattern:** All providers (LLMs, embeddings, vector stores, graphs, rerankers) inherit from a `base.py` abstract class in their directory. Config classes live in `configs.py`.
+- **Pydantic v2** for all data models and configuration.
+- **Ruff** is the single linting and formatting tool — no black, no flake8.
+  - Root SDK: line length **120**
+  - Python CLI: line length **100** with extended rule set (UP, B, SIM, RUF)
+- **isort** with `profile = "black"` for import sorting.
+- Ruff excludes `embedchain/` and `openmemory/` from root config.
+
+### TypeScript Conventions
+
+- **Build:** tsup across all packages.
+- **Package manager:** pnpm everywhere (no npm, no yarn).
+- **TypeScript strict mode** across all packages.
+- **Linting varies by package:**
+
+| Package | Linter | Formatter | Test Framework |
+|---------|--------|-----------|---------------|
+| `mem0-ts/` | — | Prettier | jest |
+| `cli/node/` | Biome | Biome | vitest |
+| `vercel-ai-sdk/` | ESLint | Prettier | jest + vitest |
+| `openclaw/` | — | — | vitest |
+
+### Type Checking
+
+Always run type checking after modifying TypeScript code:
+
+```bash
+cd <package> && pnpm run typecheck    # or: tsc --noEmit
+```
+
+## Architecture
+
+### Provider Pattern
+
+The SDK uses a consistent plugin architecture across 5 categories. Each category has a `base.py` abstract class and concrete provider implementations:
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| **LLMs** | 24 | OpenAI, Anthropic, AWS Bedrock, Azure OpenAI, Gemini, Groq, Ollama, Together, DeepSeek, vLLM, LiteLLM, LM Studio, xAI |
+| **Vector Stores** | 30 | Qdrant, Pinecone, Chroma, Weaviate, Milvus, MongoDB, Redis, Elasticsearch, pgvector, Supabase, Faiss, S3 Vectors |
+| **Embeddings** | 15 | OpenAI, Azure OpenAI, Gemini, HuggingFace, FastEmbed, Together, AWS Bedrock, Ollama, Vertex AI |
+| **Graph Stores** | 4 | Neo4j, Memgraph, Kuzu, Apache AGE |
+| **Rerankers** | 5 | Cohere, HuggingFace, LLM-based, Sentence Transformer, Zero Entropy |
+
+### Two Usage Modes
+
+Self-hosted `Memory` / `AsyncMemory` classes and hosted-platform `MemoryClient` — both in Python and TypeScript.
+
+### Graph Memory
+
+Optional layer on top of vector memory for relationship-aware retrieval. Configured via the `graph` section of `MemoryConfig`.
+
+### MCP Integration
+
+Model Context Protocol support in multiple places:
+
+- **Remote:** MCP server at `mcp.mem0.ai`
+- **Local:** MCP server in `openmemory/api/` (FastAPI-based)
+- **Plugin:** MCP tools in `mem0-plugin/` — 9 tools: `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities`
+
+### Plugin & Skills System
+
+- `mem0-plugin/` provides integrations for Claude Code, Cursor, and Codex via MCP server connections and lifecycle hooks for automatic memory capture.
+- `skills/` contains structured skill definitions for AI agents, covering SDK usage, CLI workflows, and Vercel AI SDK patterns.
+
+### Adding a New Provider
+
+To add a new LLM, embedding, vector store, or reranker provider:
+
+1. Create `mem0/<category>/<provider_name>.py`
+2. Inherit from the abstract base class in `mem0/<category>/base.py`
+3. Add configuration to `mem0/<category>/configs.py` (if the category uses one)
+4. Register the provider in `mem0/<category>/__init__.py`
+5. Add tests in `tests/<category>/<provider_name>/`
+6. Add any new dependencies to the appropriate optional group in `pyproject.toml` (never to core `dependencies`)
+7. Follow the exact pattern of existing providers in the same category — match method signatures, error handling, and config structure
+
+## CI/CD
+
+### CI Workflows (automated testing)
+
+| Workflow | File | Triggers | Tests |
+|----------|------|----------|-------|
+| Python SDK | `ci.yml` | Push to main, PRs on `mem0/`, `tests/`, `pyproject.toml` | Ruff lint + pytest on Python 3.10, 3.11, 3.12 |
+| TypeScript SDK | `ts-sdk-ci.yml` | Push to main, PRs on `mem0-ts/` | Prettier + build + jest on Node 20, 22 |
+| Python CLI | `cli-python-ci.yml` | Push to `cli/python/`, PRs, manual | Ruff lint + pytest + hatch build on Python 3.10, 3.11, 3.12 |
+| Node CLI | `cli-node-ci.yml` | Push to `cli/node/`, PRs, manual | Biome lint + tsc + vitest + tsup build on Node 20, 22 |
+| OpenClaw | `openclaw-checks.yml` | Push to `openclaw/`, PRs, manual | tsc + vitest (with Codecov) + tsup build on Node 20, 22 |
+| Embedchain | `ci.yml` (shared) | PRs on `embedchain/` | Ruff + pytest + coverage on Python 3.9–3.12 |
+
+### CD Workflows (automated publishing)
+
+| Workflow | File | Tag Prefix | Target |
+|----------|------|------------|--------|
+| Python SDK | `cd.yml` | `v*` | PyPI (`mem0ai`) |
+| TypeScript SDK | `ts-sdk-cd.yml` | `ts-v*` | npm (`mem0ai`) |
+| Python CLI | `cli-python-cd.yml` | `cli-v*` | PyPI (`mem0-cli`) |
+| Node CLI | `cli-node-cd.yml` | `cli-node-v*` | npm (`@mem0/cli`) |
+| Vercel AI SDK | `vercel-ai-cd.yml` | `vercel-ai-v*` | npm (`@mem0/vercel-ai-provider`) |
+| OpenClaw | `openclaw-cd.yml` | `openclaw-v*` | npm (`@mem0/openclaw-mem0`) |
+
+- All publishing uses **OIDC trusted publishing** — no tokens or secrets required.
+- First publish of a new npm package must be done manually; OIDC works for subsequent versions.
+
+### Utility Workflows
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| Issue Labeler | `issue-labeler.yml` | Automatic issue labeling |
+| Stale Bot | `stale.yml` | Marks stale issues and PRs |
+| llms.txt Check | `docs-llms-txt-check.yml` | Blocks PRs touching `docs/**/*.mdx` when `docs/llms.txt` is out of sync. Fix locally with `python scripts/check-llms-txt-coverage.py --write`. |
+
+## Task Completion Guidelines
+
+These guidelines outline typical artifacts for different task types. Use judgment to adapt based on scope and context.
+
+### Bug Fixes
+
+1. **Unit tests**: Add tests that would fail without the fix (regression tests)
+2. **Implementation**: Fix the bug
+3. **Manual verification**: Run the relevant test suite to confirm the fix
+4. **Lint**: Run the appropriate linter for the package you modified
+
+### New Features
+
+1. **Implementation**: Build the feature following existing patterns
+2. **Unit tests**: Comprehensive test coverage for new functionality
+3. **Documentation**: Update relevant docs in `docs/` for public APIs
+4. **Examples**: Add usage examples if the feature introduces new user-facing behavior
+5. **llms.txt**: Any new `.mdx` page under `docs/` must be linked in `docs/llms.txt` with a scope tag (`[Platform]` / `[OSS]` / `[Both]`) and a `Use when ...` description. The `docs-llms-txt-check.yml` workflow runs on every PR that touches docs and **fails the check** if the index is out of sync. To fix: run `python scripts/check-llms-txt-coverage.py --write` locally to scaffold placeholders under `## Unclassified - needs triage`, then replace the `[TODO: ...]` tags, rewrite descriptions as `Use when ...`, move entries into the right section, and delete the triage heading when empty.
+
+### New Provider (LLM / Embedding / Vector Store / Reranker)
+
+1. **Implementation**: Follow the "Adding a New Provider" steps above
+2. **Tests**: Add unit tests matching the pattern of existing providers
+3. **Configuration**: Add to the appropriate `configs.py` and `__init__.py`
+4. **Dependencies**: Add to the correct optional group in `pyproject.toml`
+5. **Documentation**: Add an integration guide in `docs/integrations/`
+
+### Refactoring / Internal Changes
+
+- Unit tests for any changed behavior
+- No documentation needed for internal-only changes
+- Ensure all existing tests still pass
+
+### When to Deviate
+
+These are guidelines, not rigid rules. Adjust based on:
+
+- **Scope**: Trivial fixes (typos, comments) may not need tests
+- **Visibility**: Internal changes may not need documentation
+- **Context**: Some changes span multiple categories — use judgment
+
+When uncertain about expected artifacts, ask for clarification.
+
+## Contributing Guidelines
+
+### Workflow
+
+1. Fork and clone the repository.
+2. Create a feature branch from `main` (e.g., `feature/my-new-feature`).
+3. Make your changes — add tests, docs, and examples as appropriate.
+4. Run linting and tests for every package you modified (see commands above).
+5. Run `pre-commit install` on first setup — hooks run ruff + isort automatically.
+6. Commit with a clear message following [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`, `refactor:`).
+7. Push and open a Pull Request against `main`.
+
+### Pull Request Requirements
+
+Every PR must follow the repo's PR template (`.github/PULL_REQUEST_TEMPLATE.md`):
+
+1. **Linked Issue** — Reference the issue with `Closes #<number>`. If no issue exists, create one first or explain why in the description.
+2. **Description** — Explain what the PR does and why it's needed.
+3. **Type of Change** — Check the appropriate box:
+   - Bug fix / New feature / Breaking change / Refactor / Documentation update
+4. **Breaking Changes** — If applicable, describe what breaks and the migration path.
+5. **Test Coverage** — Check what applies:
+   - Added/updated unit tests
+   - Added/updated integration tests
+   - Tested manually (describe how)
+   - No tests needed (explain why)
+6. **Checklist** — All must be checked before merge:
+   - [ ] Code follows the project's style guidelines
+   - [ ] Self-review performed
+   - [ ] Tests added that prove the fix/feature works
+   - [ ] New and existing tests pass locally
+   - [ ] Documentation updated if needed
+
+### PR Description Template
+
+```markdown
+## Linked Issue
+
+Closes #<!-- issue number -->
+
+## Description
+
+<!-- What does this PR do? Why is it needed? -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Refactor (no functional changes)
+- [ ] Documentation update
+
+## Breaking Changes
+
+N/A
+
+## Test Coverage
+
+- [ ] I added/updated unit tests
+- [ ] I added/updated integration tests
+- [ ] I tested manually (describe below)
+- [ ] No tests needed (explain why)
+
+## Checklist
+
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my code
+- [ ] I have added tests that prove my fix/feature works
+- [ ] New and existing tests pass locally
+- [ ] I have updated documentation if needed
+```
+
+### General Rules
+
+- Follow existing code patterns — don't introduce new frameworks or abstractions without discussion.
+- Version bumps go in `pyproject.toml` (Python) or `package.json` (TypeScript).
+- For `server/` and `openmemory/` work, use Docker Compose for local development.
+- Do NOT use `pip` or `conda` for dependency management — use `hatch` (see `docs/contributing/development.mdx`).
+
+### Contributing Guides
+
+| Task | Guide |
+|------|-------|
+| Code contributions | `docs/contributing/development.mdx` |
+| Documentation contributions | `docs/contributing/documentation.mdx` |
+| PR template | `.github/PULL_REQUEST_TEMPLATE.md` |
+| Bug reports | `.github/ISSUE_TEMPLATE/bug_report.yml` |
+| Feature requests | `.github/ISSUE_TEMPLATE/feature_request.yml` |
+| Documentation issues | `.github/ISSUE_TEMPLATE/documentation_issue.yml` |
+
+## Do NOT
+
+- Modify CI/CD workflows without explicit approval.
+- Add new Python dependencies to the core `dependencies` list in `pyproject.toml` without discussion — use optional dependency groups instead.
+- Commit `.env` files, API keys, or credentials.
+- Modify `embedchain/` unless specifically working on that package — it has its own build system (Poetry).
+- Skip pre-commit hooks.
+- Use npm or yarn in TypeScript packages — this repo uses pnpm exclusively.
+- Use `require()` for imports in TypeScript — use ES module `import` syntax.
+- Mix up linter configs: root Python SDK uses line-length 120, Python CLI uses 100, Node CLI uses Biome (not ESLint/Ruff).
+- Modify `openmemory/` database migrations without understanding the Alembic migration chain.
+- Change public APIs without updating documentation in `docs/`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -61,3 +61,31 @@ make test  # After activating a shell with hatch shell test_XX
 Make sure that all tests pass across all supported Python versions before submitting a pull request.
 
 We look forward to your pull requests and can't wait to see your contributions!
+
+### 🚀 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 |
+|---------|----------|------------|---------|
+| `mem0ai` (Python SDK) | PyPI | `v*` | `v0.1.31` |
+| `mem0-cli` (Python CLI) | PyPI | `cli-v*` | `cli-v0.2.1` |
+| `mem0ai` (TypeScript SDK) | npm | `ts-v*` | `ts-v2.4.6` |
+| `@mem0/cli` (Node CLI) | npm | `cli-node-v*` | `cli-node-v0.1.2` |
+| `@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
+
+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
+
+- **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

LLM.md

@@ -266,7 +266,7 @@ config = MemoryConfig(
     graph_store=GraphStoreConfig(provider="neo4j", config={...}),  # optional
     history_db_path="~/.mem0/history.db",
     version="v1.1",
-    custom_fact_extraction_prompt="Custom prompt...",
+    custom_instructions="Custom prompt...",
     custom_update_memory_prompt="Custom prompt..."
 )
 ```
@@ -684,7 +684,7 @@ Conversation: {messages}
 """
 
 config = MemoryConfig(
-    custom_fact_extraction_prompt=custom_extraction_prompt
+    custom_instructions=custom_extraction_prompt
 )
 memory = Memory(config)
 ```
@@ -1313,7 +1313,7 @@ async def delete_memory(memory_id: str):
 - **Documentation**: https://docs.mem0.ai
 - **GitHub Repository**: https://github.com/mem0ai/mem0
 - **Discord Community**: https://mem0.dev/DiG
-- **Platform**: https://app.mem0.ai
+- **Platform**: https://app.mem0.ai?utm_source=oss&utm_medium=llm
 - **Research Paper**: https://mem0.ai/research
 - **Examples**: https://github.com/mem0ai/mem0/tree/main/examples
 

Makefile

@@ -42,9 +42,6 @@ clean:
 test:
 	hatch run test
 
-test-py-3.9:
-	hatch run dev_py_3_9:test
-
 test-py-3.10:
 	hatch run dev_py_3_10:test
 

README.md

@@ -39,18 +39,32 @@
 </p>
 
 <p align="center">
-  <a href="https://mem0.ai/research"><strong>📄 Building Production-Ready AI Agents with Scalable Long-Term Memory →</strong></a>
-</p>
-<p align="center">
-  <strong>⚡ +26% Accuracy vs. OpenAI Memory • 🚀 91% Faster • 💰 90% Fewer Tokens</strong>
+  <a href="https://mem0.ai/research"><strong>📄 Benchmarking Mem0's token-efficient memory algorithm →</strong></a>
 </p>
 
-> **🎉 mem0ai v1.0.0 is now available!** This major release includes API modernization, improved vector store support, and enhanced GCP integration. [See migration guide →](MIGRATION_GUIDE_v1.0.md)
+## New Memory Algorithm (April 2026)
 
-##  🔥 Research Highlights
-- **+26% Accuracy** over OpenAI Memory on the LOCOMO benchmark
-- **91% Faster Responses** than full-context, ensuring low-latency at scale
-- **90% Lower Token Usage** than full-context, cutting costs without compromise
+| Benchmark | Old | New  | Tokens  | Latency p50  |
+| --- | --- | --- | --- | --- |
+| **LoCoMo** | 71.4 | **91.6** | 7.0K  | 0.88s  |
+| **LongMemEval** | 67.8 | **93.4** | 6.8K  | 1.09s  |
+| **BEAM (1M)** | — | **64.1** | 6.7K  | 1.00s  |
+| **BEAM (10M)** | — | **48.6** | 6.9K  | 1.05s  |
+
+All benchmarks run on the same production-representative model stack. Single-pass retrieval (one call, no agentic loops).
+
+**What changed:**
+- **Single-pass ADD-only extraction** -- one LLM call, no UPDATE/DELETE. Memories accumulate; nothing is overwritten.
+- **Agent-generated facts are first-class** -- when an agent confirms an action, that information is now stored with equal weight.
+- **Entity linking** -- entities are extracted, embedded, and linked across memories for retrieval boosting.
+- **Multi-signal retrieval** -- semantic, BM25 keyword, and entity matching scored in parallel and fused.
+
+See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for upgrade instructions. The [evaluation framework](https://github.com/mem0ai/memory-benchmarks) is open-sourced so anyone can reproduce the numbers.
+
+## Research Highlights
+- **91.6 on LoCoMo** -- +20 points over the previous algorithm
+- **93.4 on LongMemEval** -- +26 points, with +53.6 on assistant memory recall
+- **64.1 on BEAM (1M)** -- production-scale memory evaluation at 1M tokens
 - [Read the full paper](https://mem0.ai/research)
 
 # Introduction
@@ -71,28 +85,54 @@
 
 ## 🚀 Quickstart Guide <a name="quickstart"></a>
 
-Choose between our hosted platform or self-hosted package:
+| | Library | Self-Hosted Server | Cloud Platform |
+|---|---------|-------------------|----------------|
+| **Best for** | Testing, prototyping | Teams running on their own infrastructure | Zero-ops production use |
+| **Setup** | `pip install mem0ai` | `docker compose up` | Sign up at [app.mem0.ai](https://app.mem0.ai?utm_source=oss&utm_medium=readme) |
+| **Dashboard** | -- | [Yes](https://docs.mem0.ai/open-source/setup) | Yes |
+| **Auth & API Keys** | -- | Yes | Yes |
+| **Advanced Features** | -- | Teasers | All included |
 
-### Hosted Platform
+Just testing? Use the library. Building for a team? Self-hosted. Want zero ops? Cloud.
 
-Get up and running in minutes with automatic updates, analytics, and enterprise security.
-
-1. Sign up on [Mem0 Platform](https://app.mem0.ai)
-2. Embed the memory layer via SDK or API keys
-
-### Self-Hosted (Open Source)
-
-Install the sdk via pip:
+### Library (pip / npm)
 
 ```bash
 pip install mem0ai
 ```
 
+For enhanced hybrid search with BM25 keyword matching and entity extraction, install with NLP support:
+
+```bash
+pip install mem0ai[nlp]
+python -m spacy download en_core_web_sm
+```
+
 Install sdk via npm:
+
 ```bash
 npm install mem0ai
 ```
 
+### Self-Hosted Server
+
+> **Note:** Self-hosted auth is on by default. Upgrading from a pre-auth build? Set `ADMIN_API_KEY`, register an admin through the wizard, or `AUTH_DISABLED=true` for local dev only. See [upgrade notes](https://docs.mem0.ai/open-source/setup#upgrade-notes).
+
+```bash
+# Recommended: one command — start the stack, create an admin, issue the first API key.
+cd server && make bootstrap
+
+# Manual: start the stack and finish setup via the browser wizard.
+cd server && docker compose up -d    # http://localhost:3000
+```
+
+See the [self-hosted docs](https://docs.mem0.ai/open-source/overview) for configuration.
+
+### Cloud Platform
+
+1. Sign up on [Mem0 Platform](https://app.mem0.ai?utm_source=oss&utm_medium=readme)
+2. Embed the memory layer via SDK or API keys
+
 ### CLI
 
 Manage memories from your terminal:
@@ -109,7 +149,9 @@ See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full comm
 
 ### Basic Usage
 
-Mem0 requires an LLM to function, with `gpt-4.1-nano-2025-04-14 from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+Mem0 requires an LLM to function, with `gpt-5-mini` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+
+Mem0 uses `text-embedding-3-small` from OpenAI as the default embedding model. For best results with hybrid search (semantic + keyword + entity boosting), we recommend using at least [Qwen 600M](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct) or a comparable embedding model. See [Supported Embeddings](https://docs.mem0.ai/components/embedders/overview) for configuration details.
 
 First step is to instantiate the memory:
 
@@ -122,13 +164,13 @@ memory = Memory()
 
 def chat_with_memories(message: str, user_id: str = "default_user") -> str:
     # Retrieve relevant memories
-    relevant_memories = memory.search(query=message, user_id=user_id, limit=3)
+    relevant_memories = memory.search(query=message, filters={"user_id": user_id}, top_k=3)
     memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories["results"])
 
     # Generate Assistant response
     system_prompt = f"You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n{memories_str}"
     messages = [{"role": "system", "content": system_prompt}, {"role": "user", "content": message}]
-    response = openai_client.chat.completions.create(model="gpt-4.1-nano-2025-04-14", messages=messages)
+    response = openai_client.chat.completions.create(model="gpt-5-mini", messages=messages)
     assistant_response = response.choices[0].message.content
 
     # Create new memories from the conversation
@@ -162,7 +204,7 @@ For detailed integration steps, see the [Quickstart](https://docs.mem0.ai/quicks
 ## 📚 Documentation & Support
 
 - Full docs: https://docs.mem0.ai
-- Community: [Discord](https://mem0.dev/DiG) · [Twitter](https://x.com/mem0ai)
+- Community: [Discord](https://mem0.dev/DiG) · [X (formerly Twitter)](https://x.com/mem0ai)
 - Contact: founders@mem0.ai
 
 ## Citation
@@ -180,4 +222,4 @@ We now have a paper you can cite:
 
 ## ⚖️ License
 
-Apache 2.0 — see the [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE) file for details.
+Apache 2.0 — see the [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE) file for details.

cli/CLI_SPECIFICATION.md

@@ -28,7 +28,7 @@ mem0 CLI is the official command-line interface for [mem0](https://mem0.ai) -- t
 ### Who is it for?
 
 - Developers integrating mem0 into their workflows
-- AI agents that need persistent memory (the CLI is designed with `--output json` and `help --json` specifically for machine consumption)
+- AI agents that need persistent memory (the CLI is designed with `--json`/`--agent` global flags and `help --json` specifically for machine consumption)
 - DevOps/CI pipelines that need to manage memories programmatically
 
 ### Project Structure
@@ -79,6 +79,7 @@ Apache-2.0
 │           ├── init_cmd.py          # run_init (interactive wizard)
 │           ├── config_cmd.py        # cmd_config_show, cmd_config_get, cmd_config_set
 │           ├── entities.py          # cmd_entities_list, cmd_entities_delete
+│           ├── events_cmd.py        # cmd_event_list, cmd_event_status
 │           └── utils.py             # cmd_status, cmd_version, cmd_import
 └── node/
     ├── package.json                 # Node package config (tsup build)
@@ -88,6 +89,7 @@ Apache-2.0
         ├── config.ts                # Config loading/saving, env var overrides
         ├── branding.ts              # Colors, icons, banner, timedStatus, print helpers
         ├── output.ts                # Output formatting (text, json, table, quiet)
+        ├── state.ts                 # Agent mode flag (setAgentMode, isAgentMode)
         ├── help.ts                  # Rich-style help formatter (panels, command ordering)
         ├── backend/
         │   ├── index.ts             # Re-exports
@@ -98,6 +100,7 @@ Apache-2.0
             ├── init.ts              # runInit (interactive wizard)
             ├── config.ts            # cmdConfigShow, cmdConfigGet, cmdConfigSet
             ├── entities.ts          # cmdEntitiesList, cmdEntitiesDelete
+            ├── events.ts            # cmdEventList, cmdEventStatus
             └── utils.ts             # cmdStatus, cmdVersion, cmdImport
 ```
 
@@ -153,8 +156,25 @@ Interactive setup wizard for mem0 CLI.
 |-----------------|--------|----------|---------|------|
 | `--api-key`     | string | No       | -       | API key (skip prompt). |
 | `-u, --user-id` | string | No       | -       | Default user ID (skip prompt). |
+| `--email`       | string | No       | -       | Login via email verification code. |
+| `--code`        | string | No       | -       | Verification code (use with --email for non-interactive login). |
+| `--force`       | bool   | No       | false   | Overwrite existing config without confirmation. |
 
 **Behavior:**
+
+*Existing config protection:*
+- If `~/.mem0/config.json` exists with an API key, the CLI warns and asks for confirmation before overwriting.
+- In non-TTY mode, this is a hard error unless `--force` is passed.
+- `--force` skips the confirmation in both TTY and non-TTY modes.
+
+*Email login flow (when `--email` is provided):*
+- Sends a 6-digit verification code to the email via `POST /api/v1/auth/email_code/`.
+- If `--code` is also provided, verifies immediately (fully non-interactive).
+- If `--code` is not provided, prompts for the code interactively.
+- On success: receives API key, org_id, project_id. Saves to config. Creates account if email is new.
+- Cannot be combined with `--api-key`.
+
+*API key flow (existing behavior):*
 - If both `--api-key` and `--user-id` are provided, runs non-interactively (no prompts).
 - If running in a non-TTY without both flags, prints an error with usage hint and exits.
 - Interactive mode: prints banner, prompts for API key (masked with `*`), prompts for default user ID (default: `mem0-cli`), validates connection, saves config.
@@ -164,6 +184,9 @@ Interactive setup wizard for mem0 CLI.
 ```bash
 mem0 init
 mem0 init --api-key m0-xxx --user-id alice
+mem0 init --api-key m0-xxx --user-id alice --force
+mem0 init --email alice@company.com
+mem0 init --email alice@company.com --code 482901
 ```
 
 ---
@@ -687,7 +710,114 @@ mem0 entity delete --user-id alice --dry-run
 
 ---
 
-### 3.14 `status`
+### 3.14 `event list`
+
+List recent background processing events.
+
+| Property         | Value |
+|------------------|-------|
+| Usage            | `mem0 event list [OPTIONS]` |
+| needsBackend     | Yes |
+| needsConfig      | Yes |
+| resolveIds       | No |
+| resolveGraph     | No |
+| confirmDangerous | No |
+| Output formats   | text (table), json |
+| Default output   | table |
+| API endpoint     | `GET /v1/events/` |
+
+**Options:**
+
+| Flag           | Type   | Default | Panel      | Help |
+|----------------|--------|---------|------------|------|
+| `-o, --output` | string | "table" | Output     | Output: text, json. |
+| `--api-key`    | string | -       | Connection | Override API key. |
+| `--base-url`   | string | -       | Connection | Override API base URL. |
+
+**Behavior:** Fetches all background events for the project. Displays as a table with columns: Event ID (first 8 chars), Type, Status (color-coded), Latency, Created. Status values: `PENDING` (accent), `SUCCEEDED` (green), `FAILED` (red), `PROCESSING` (yellow).
+
+**JSON output envelope:**
+```json
+{
+  "status": "success",
+  "command": "event list",
+  "count": 3,
+  "duration_ms": 87,
+  "data": [
+    { "id": "evt-abc", "event_type": "ADD", "status": "SUCCEEDED", "latency": 412.0, "created_at": "2026-01-01T10:00:00Z" }
+  ]
+}
+```
+
+**Examples:**
+```bash
+mem0 event list
+mem0 event list --output json
+```
+
+---
+
+### 3.15 `event status`
+
+Get the status and results of a specific background event.
+
+| Property         | Value |
+|------------------|-------|
+| Usage            | `mem0 event status <event_id> [OPTIONS]` |
+| needsBackend     | Yes |
+| needsConfig      | Yes |
+| resolveIds       | No |
+| resolveGraph     | No |
+| confirmDangerous | No |
+| Output formats   | text, json |
+| Default output   | text |
+| API endpoint     | `GET /v1/events/{event_id}/` |
+
+**Arguments:**
+
+| Name       | Type   | Required | Help |
+|------------|--------|----------|------|
+| `event_id` | string | Yes      | Event ID to inspect. |
+
+**Options:**
+
+| Flag           | Type   | Default | Panel      | Help |
+|----------------|--------|---------|------------|------|
+| `-o, --output` | string | "text"  | Output     | Output: text, json. |
+| `--api-key`    | string | -       | Connection | Override API key. |
+| `--base-url`   | string | -       | Connection | Override API base URL. |
+
+**Behavior:** Fetches the event by ID and displays: Event ID, Type, Status (color-coded), Latency, Created, Updated, and a numbered list of result memories (event type, memory text, user_id, truncated memory ID). Displayed in a boxed panel (text) or JSON envelope.
+
+**JSON output envelope:**
+```json
+{
+  "status": "success",
+  "command": "event status",
+  "duration_ms": 65,
+  "data": {
+    "id": "evt-abc",
+    "event_type": "ADD",
+    "status": "SUCCEEDED",
+    "latency": 412.0,
+    "created_at": "2026-01-01T10:00:00Z",
+    "updated_at": "2026-01-01T10:00:01Z",
+    "results": [
+      { "id": "mem-xyz", "event": "ADD", "user_id": "alice", "memory": "User prefers dark mode" }
+    ]
+  }
+}
+```
+
+**Examples:**
+```bash
+mem0 event status evt-abc-123
+mem0 event status evt-abc-123 --output json
+```
+
+---
+
+### 3.16 `status`
 
 Check connectivity and authentication.
 
@@ -708,20 +838,19 @@ Check connectivity and authentication.
 | `--api-key`    | string | -       | Connection | Override API key. |
 | `--base-url`   | string | -       | Connection | Override API base URL. |
 
-**Behavior:** If config has a default `user_id` or `agent_id`, validates by making a minimal `POST /v2/memories/` with `page=1&page_size=1`. Otherwise validates via `GET /v1/entities/`. Displays connection status in a boxed panel (text) or JSON envelope.
+**Behavior:** Validates connectivity by calling `GET /v1/ping/`. Displays connection status in a boxed panel (text) or JSON envelope. The ping endpoint is lightweight and does not require any entity scope.
 
 **JSON output:**
 ```json
 {
   "status": "success",
   "command": "status",
+  "duration_ms": 112,
   "data": {
     "connected": true,
     "backend": "platform",
-    "base_url": "https://api.mem0.ai",
-    "latency_ms": 245
-  },
-  "duration_ms": 245
+    "base_url": "https://api.mem0.ai"
+  }
 }
 ```
 
@@ -733,7 +862,7 @@ mem0 status -o json
 
 ---
 
-### 3.15 `help`
+### 3.17 `help`
 
 Show help. Use `--json` for machine-readable output (for LLM agents).
 
@@ -793,6 +922,9 @@ The auth header name is `Authorization` and the scheme is `Token` (not Bearer).
 | Delete all      | `DELETE` | `/v1/memories/`               | -                | entity ID params        |
 | List entities   | `GET`    | `/v1/entities/`               | -                | -                       |
 | Delete entities | `DELETE` | `/v1/entities/`               | -                | entity ID params        |
+| List events     | `GET`    | `/v1/events/`                 | -                | -                       |
+| Get event       | `GET`    | `/v1/events/{event_id}/`      | -                | -                       |
+| Ping (status)   | `GET`    | `/v1/ping/`                   | -                | -                       |
 
 ### How Filters Are Built (`_buildFilters` / `_build_filters`)
 
@@ -1095,6 +1227,8 @@ For `PENDING` events, displays "Processing in background" with the event ID.
 
 ### 7.1 Supported Modes Per Command
 
+All commands also support `agent` mode via the global `--json`/`--agent` flag, which wraps output in a structured JSON envelope with sanitized fields.
+
 | Command        | text | json | table | quiet |
 |----------------|------|------|-------|-------|
 | add            | Y    | Y    | -     | Y     |
@@ -1109,12 +1243,16 @@ For `PENDING` events, displays "Processing in background" with the event ID.
 | config set     | (success msg) | - | - | -  |
 | entity list    | -    | Y    | Y (default) | -  |
 | entity delete  | Y    | Y    | -     | Y     |
+| event list     | Y (table) | Y | -  | -     |
+| event status   | Y    | Y    | -     | -     |
 | status         | Y    | Y    | -     | -     |
 | help           | Y    | Y (--json) | - | -   |
 
-### 7.2 JSON Envelope Format (`formatJsonEnvelope`)
+### 7.2 JSON Envelope Format
 
-Used by `config show`, `status`, and `import` for structured JSON output:
+There are two related envelope formats:
+
+**`formatJsonEnvelope`** — used by `config show`, `status`, and `import` for `--output json`:
 
 ```json
 {
@@ -1128,14 +1266,39 @@ Used by `config show`, `status`, and `import` for structured JSON output:
 }
 ```
 
+**`formatAgentEnvelope`** — used by all commands in agent mode (`--json`/`--agent`). Same structure, but `data` is passed through `sanitizeAgentData(command, data)` to project only the most relevant fields:
+
+| Command       | Fields in `data` |
+|---------------|-----------------|
+| add           | `[{id, memory, event}]` or `[{status, event_id}]` for PENDING |
+| search        | `[{id, memory, score, created_at, categories}]` |
+| list          | `[{id, memory, created_at, categories}]` |
+| get           | `{id, memory, created_at, updated_at, categories, metadata}` |
+| update        | `{id, memory}` |
+| delete        | (raw API response) |
+| entity list   | `[{name, type, count}]` |
+| event list    | `[{id, event_type, status, latency, created_at}]` |
+| event status  | `{id, event_type, status, latency, created_at, updated_at, results: [{id, event, user_id, memory}]}` |
+| status/config/import | (pass-through) |
+
+Error envelopes (on non-zero exit):
+```json
+{
+  "status": "error",
+  "command": "<command_name>",
+  "error": "Authentication failed. Your API key may be invalid or expired.",
+  "data": null
+}
+```
+
 Fields:
-- `status`: Always `"success"` (errors go to stderr before exit).
-- `command`: The command name (e.g. `"status"`, `"config show"`, `"import"`).
+- `status`: `"success"` or `"error"`.
+- `command`: The command name.
 - `duration_ms`: Optional, elapsed time in milliseconds.
-- `scope`: Optional, active entity scope.
+- `scope`: Optional, active entity scope (omitted if empty).
 - `count`: Optional, result count.
-- `error`: Optional, error message string.
-- `data`: The primary payload.
+- `error`: Only present when `status` is `"error"`.
+- `data`: The primary payload (sanitized in agent mode).
 
 ### 7.3 Text Output
 
@@ -1206,6 +1369,16 @@ Destructive commands (`delete --all`, `delete --entity`, `entity delete`) requir
 - CI/CD pipelines
 - Scripting
 
+### Why `--json`/`--agent` global flags exist
+
+The `--json` and `--agent` flags (aliases of each other) activate agent mode globally. When set:
+1. All output becomes a structured JSON envelope (`{status, command, duration_ms, scope, count, data}`).
+2. The `data` field is sanitized via `sanitizeAgentData` — only the most relevant fields are included per command, reducing noise for agents parsing the output.
+3. All human-readable output (spinners, colors, banners, timing lines) is suppressed.
+4. Errors are emitted as JSON to stdout with a non-zero exit code, not to stderr as text.
+
+This is distinct from `--output json`, which returns the raw API response without sanitization.
+
 ### Why `--output json` is on every command
 
 Every data-returning command supports `--output json` (or `--json` for `help`). This enables machine consumption by AI agents and scripts. JSON output goes to stdout while human-readable spinners/timing go to stderr, so piping `mem0 list -o json | jq .` works cleanly.

cli/README.md

@@ -2,6 +2,8 @@
 
 The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. Works with the Mem0 Platform API. Available in Python and Node.js.
 
+> **For AI agents:** pass `--agent` (or `--json`) on any command for structured JSON output purpose-built for tool loops — sanitized fields, no colors or spinners, errors as JSON. See [Agent mode](#agent-mode) below.
+
 ## Installation
 
 ```bash
@@ -17,9 +19,15 @@ Both packages install a `mem0` binary with identical behavior.
 ## Quick start
 
 ```bash
-# Authenticate and save config
+# Interactive setup wizard
 mem0 init
 
+# Or login via email (get a new API key)
+mem0 init --email alice@company.com
+
+# Or authenticate with an existing API key
+mem0 init --api-key m0-xxx
+
 # Add a memory
 mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
 
@@ -40,7 +48,7 @@ mem0 delete <memory-id>
 
 | Command | Description |
 |---------|-------------|
-| `mem0 init` | Interactive setup wizard — configures API key and default user ID |
+| `mem0 init` | Setup wizard — login via email or configure API key manually |
 | `mem0 add` | Add a memory from text, JSON messages, a file, or stdin |
 | `mem0 search` | Search memories using natural language |
 | `mem0 list` | List memories with optional filters and pagination |
@@ -49,12 +57,45 @@ mem0 delete <memory-id>
 | `mem0 delete` | Delete a memory, all memories for a scope, or an entity |
 | `mem0 import` | Bulk import memories from a JSON file |
 | `mem0 config` | View or modify CLI configuration |
-| `mem0 entities` | List or delete entities (users, agents, apps) |
+| `mem0 entity` | List or delete entities (users, agents, apps, runs) |
+| `mem0 event` | Inspect background processing events (bulk deletes, large add jobs) |
 | `mem0 status` | Verify API connection and display current project |
 | `mem0 version` | Print the CLI version |
 
 Run `mem0 <command> --help` for detailed usage on any command.
 
+## Agent mode
+
+Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
+
+```bash
+mem0 --agent search "user preferences" --user-id alice
+mem0 --agent add "User prefers dark mode" --user-id alice
+mem0 --agent list --user-id alice
+```
+
+Every command returns the same envelope shape:
+
+```json
+{
+  "status": "success",
+  "command": "search",
+  "duration_ms": 134,
+  "scope": { "user_id": "alice" },
+  "count": 2,
+  "data": [
+    { "id": "abc-123", "memory": "User prefers dark mode", "score": 0.97, "created_at": "2026-01-15", "categories": ["preferences"] }
+  ]
+}
+```
+
+What agent mode does differently from `--output json`:
+- **Sanitized `data`**: only the fields an agent needs (id, memory, score, etc.) — no internal API noise
+- **No human output**: spinners, colors, and banners are suppressed entirely
+- **Errors as JSON**: errors go to stdout as `{"status": "error", "command": "...", "error": "..."}` with a non-zero exit code
+
+Use `mem0 help --json` to get the full command tree as JSON — useful for agents that need to self-discover available commands.
+
 ## Output formats
 
 Control how results are displayed with `--output`:
@@ -62,13 +103,10 @@ Control how results are displayed with `--output`:
 | Format | Description |
 |--------|-------------|
 | `text` | Human-readable with colors and formatting (default) |
-| `json` | Structured JSON for piping to `jq` or agent consumption |
+| `json` | Structured JSON for piping to `jq` (raw API response) |
 | `table` | Tabular format (default for `list`) |
 | `quiet` | Minimal — just IDs or status codes |
-
-```bash
-mem0 search "preferences" --user-id alice --output json | jq '.data.results[].memory'
-```
+| `agent` | Structured JSON envelope with sanitized fields (set by `--agent`/`--json`) |
 
 ## Environment variables
 

cli/cli-spec.json

@@ -503,15 +503,21 @@
     },
     {
       "name": "init",
-      "description": "Interactive setup wizard for mem0 CLI.",
-      "usage": "mem0 init",
+      "description": "Setup wizard for mem0 CLI. Supports email login (--email) or manual API key (--api-key).",
+      "usage": "mem0 init [OPTIONS]",
       "needsBackend": false,
       "needsConfig": false,
       "resolveIds": false,
       "resolveGraph": false,
       "confirmDangerous": false,
       "arguments": [],
-      "options": []
+      "options": [
+        { "name": "api-key", "flags": ["--api-key"], "type": "string", "default": null, "help": "API key (skip prompt)." },
+        { "name": "user-id", "flags": ["-u", "--user-id"], "type": "string", "default": null, "help": "Default user ID (skip prompt)." },
+        { "name": "email", "flags": ["--email"], "type": "string", "default": null, "help": "Login via email verification code." },
+        { "name": "code", "flags": ["--code"], "type": "string", "default": null, "help": "Verification code (use with --email for non-interactive login)." },
+        { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Overwrite existing config without confirmation." }
+      ]
     },
     {
       "name": "status",

cli/node/README.md

@@ -2,10 +2,12 @@
 
 The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. TypeScript implementation.
 
+> **Built for AI agents.** Pass `--agent` (or `--json`) as a global flag on any command to get structured JSON output optimized for programmatic consumption — sanitized fields, no colors or spinners, and errors as JSON too.
+
 ## Prerequisites
 
 - Node.js **18+**
-- pnpm (`npm install -g pnpm`)
+- pnpm (`npm install -g pnpm`) — for development only
 
 ## Installation
 
@@ -13,22 +15,307 @@ The official command-line interface for [mem0](https://mem0.ai) — the memory l
 npm install -g @mem0/cli
 ```
 
-Or from source:
+## Quick start
 
 ```bash
-cd node
-pnpm install
-pnpm build
-pnpm link --global
+# Interactive setup wizard
+mem0 init
 
-# Now use it like a normal CLI
-mem0 --help
+# Or login via email
+mem0 init --email alice@company.com
+
+# Or authenticate with an existing API key
+mem0 init --api-key m0-xxx
+
+# Add a memory
+mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
+
+# Search memories
+mem0 search "What are Alice's preferences?" --user-id alice
+
+# List all memories for a user
+mem0 list --user-id alice
+
+# Get a specific memory
+mem0 get <memory-id>
+
+# Update a memory
+mem0 update <memory-id> "I switched to light mode"
+
+# Delete a memory
+mem0 delete <memory-id>
 ```
 
-## Running during development
+## Commands
+
+### `mem0 init`
+
+Interactive setup wizard. Prompts for your API key and default user ID.
 
 ```bash
-cd node
+mem0 init
+mem0 init --api-key m0-xxx --user-id alice
+mem0 init --email alice@company.com
+```
+
+If an existing configuration is detected, the CLI asks for confirmation before overwriting. Use `--force` to skip the prompt (useful in CI/CD).
+
+```bash
+mem0 init --api-key m0-xxx --user-id alice --force
+```
+
+| Flag | Description |
+|------|-------------|
+| `--api-key` | API key (skip prompt) |
+| `-u, --user-id` | Default user ID (skip prompt) |
+| `--email` | Login via email verification code |
+| `--code` | Verification code (use with `--email` for non-interactive login) |
+| `--force` | Overwrite existing config without confirmation |
+
+### `mem0 add`
+
+Add a memory from text, a JSON messages array, a file, or stdin.
+
+```bash
+mem0 add "I prefer dark mode" --user-id alice
+mem0 add --file conversation.json --user-id alice
+echo "Loves hiking on weekends" | mem0 add --user-id alice
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Scope to a user |
+| `--agent-id` | Scope to an agent |
+| `--messages` | Conversation messages as JSON |
+| `-f, --file` | Read messages from a JSON file |
+| `-m, --metadata` | Custom metadata as JSON |
+| `--categories` | Categories (JSON array or comma-separated) |
+| `--graph / --no-graph` | Enable or disable graph memory extraction |
+| `-o, --output` | Output format: `text`, `json`, `quiet` |
+
+### `mem0 search`
+
+Search memories using natural language.
+
+```bash
+mem0 search "dietary restrictions" --user-id alice
+mem0 search "preferred tools" --user-id alice --output json --top-k 5
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Filter by user |
+| `-k, --top-k` | Number of results (default: 10) |
+| `--threshold` | Minimum similarity score (default: 0.3) |
+| `--rerank` | Enable reranking |
+| `--keyword` | Use keyword search instead of semantic |
+| `--filter` | Advanced filter expression (JSON) |
+| `--graph / --no-graph` | Enable or disable graph in search |
+| `-o, --output` | Output format: `text`, `json`, `table` |
+
+### `mem0 list`
+
+List memories with optional filters and pagination.
+
+```bash
+mem0 list --user-id alice
+mem0 list --user-id alice --category preferences --output json
+mem0 list --user-id alice --after 2024-01-01 --page-size 50
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Filter by user |
+| `--page` | Page number (default: 1) |
+| `--page-size` | Results per page (default: 100) |
+| `--category` | Filter by category |
+| `--after` | Created after date (YYYY-MM-DD) |
+| `--before` | Created before date (YYYY-MM-DD) |
+| `-o, --output` | Output format: `text`, `json`, `table` |
+
+### `mem0 get`
+
+Retrieve a specific memory by ID.
+
+```bash
+mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
+mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json
+```
+
+### `mem0 update`
+
+Update the text or metadata of an existing memory.
+
+```bash
+mem0 update <memory-id> "Updated preference text"
+mem0 update <memory-id> --metadata '{"priority": "high"}'
+echo "new text" | mem0 update <memory-id>
+```
+
+### `mem0 delete`
+
+Delete a single memory, all memories for a scope, or an entire entity.
+
+```bash
+# Delete a single memory
+mem0 delete <memory-id>
+
+# Delete all memories for a user
+mem0 delete --all --user-id alice --force
+
+# Delete all memories project-wide
+mem0 delete --all --project --force
+
+# Preview what would be deleted
+mem0 delete --all --user-id alice --dry-run
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Delete all memories matching scope filters |
+| `--entity` | Delete the entity and all its memories |
+| `--project` | With `--all`: delete all memories project-wide |
+| `--dry-run` | Preview without deleting |
+| `--force` | Skip confirmation prompt |
+
+### `mem0 import`
+
+Bulk import memories from a JSON file.
+
+```bash
+mem0 import data.json --user-id alice
+```
+
+The file should be a JSON array where each item has a `memory` (or `text` or `content`) field and optional `user_id`, `agent_id`, and `metadata` fields.
+
+### `mem0 config`
+
+View or modify the local CLI configuration.
+
+```bash
+mem0 config show              # Display current config (secrets redacted)
+mem0 config get api_key       # Get a specific value
+mem0 config set user_id bob   # Set a value
+```
+
+### `mem0 entity`
+
+List or delete entities (users, agents, apps, runs).
+
+```bash
+mem0 entity list users
+mem0 entity list agents --output json
+mem0 entity delete --user-id alice --force
+```
+
+### `mem0 event`
+
+Inspect background processing events created by async operations (e.g. bulk deletes, large add jobs).
+
+```bash
+# List recent events
+mem0 event list
+
+# Check the status of a specific event
+mem0 event status <event-id>
+```
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Output format: `text`, `json` |
+
+### `mem0 status`
+
+Verify your API connection and display the current project.
+
+```bash
+mem0 status
+```
+
+### `mem0 version`
+
+Print the CLI version.
+
+```bash
+mem0 version
+```
+
+## Agent mode
+
+Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
+
+```bash
+mem0 --agent search "user preferences" --user-id alice
+mem0 --agent add "User prefers dark mode" --user-id alice
+mem0 --agent list --user-id alice
+mem0 --agent delete --all --user-id alice --force
+```
+
+Every command returns the same envelope shape:
+
+```json
+{
+  "status": "success",
+  "command": "search",
+  "duration_ms": 134,
+  "scope": { "user_id": "alice" },
+  "count": 2,
+  "data": [
+    { "id": "abc-123", "memory": "User prefers dark mode", "score": 0.97, "created_at": "2026-01-15", "categories": ["preferences"] }
+  ]
+}
+```
+
+What agent mode does differently from `--output json`:
+
+- **Sanitized `data`**: only the fields an agent needs (id, memory, score, etc.) — no internal API noise
+- **No human output**: spinners, colors, and banners are suppressed entirely
+- **Errors as JSON**: errors go to stdout as `{"status": "error", "command": "...", "error": "..."}` with a non-zero exit code
+
+Use `mem0 help --json` to get the full command tree as JSON — useful for agents that need to self-discover available commands.
+
+## Output formats
+
+Control how results are displayed with `--output`:
+
+| Format | Description |
+|--------|-------------|
+| `text` | Human-readable with colors and formatting (default) |
+| `json` | Structured JSON for piping to `jq` (raw API response) |
+| `table` | Tabular format (default for `list`) |
+| `quiet` | Minimal — just IDs or status codes |
+| `agent` | Structured JSON envelope with sanitized fields (set by `--agent`/`--json`) |
+
+## Global flags
+
+These flags are available on all commands:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Enable agent mode: structured JSON envelope output, no colors or spinners |
+| `--agent` | Alias for `--json` |
+| `--api-key` | Override the configured API key for this request |
+| `--base-url` | Override the configured API base URL for this request |
+| `-o, --output` | Set the output format |
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `MEM0_API_KEY` | API key (overrides config file) |
+| `MEM0_BASE_URL` | API base URL |
+| `MEM0_USER_ID` | Default user ID |
+| `MEM0_AGENT_ID` | Default agent ID |
+| `MEM0_APP_ID` | Default app ID |
+| `MEM0_RUN_ID` | Default run ID |
+| `MEM0_ENABLE_GRAPH` | Enable graph memory (`true` / `false`) |
+
+Environment variables take precedence over values in the config file, which take precedence over defaults.
+
+## Development
+
+```bash
+cd cli/node
 pnpm install
 
 # Development mode (runs TypeScript directly, no build needed)
@@ -39,36 +326,11 @@ pnpm dev search "test" --user-id alice
 # Or build first, then run the compiled JS
 pnpm build
 node dist/index.js --help
-node dist/index.js add "test memory" --user-id alice
 ```
 
-## Quick Start
+## Documentation
 
-```bash
-# Set up your configuration
-mem0 init
-
-# Add a memory
-mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
-
-# Search memories
-mem0 search "What are Alice's preferences?" --user-id alice
-
-# List all memories
-mem0 list --user-id alice
-```
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `MEM0_API_KEY` | API key (overrides config file) |
-| `MEM0_BASE_URL` | API base URL |
-| `MEM0_USER_ID` | Default user ID |
-| `MEM0_AGENT_ID` | Default agent ID |
-| `MEM0_APP_ID` | Default app ID |
-| `MEM0_RUN_ID` | Default run ID |
-| `MEM0_ENABLE_GRAPH` | Enable graph memory (true/false) |
+Full documentation is available at [docs.mem0.ai/platform/cli](https://docs.mem0.ai/platform/cli).
 
 ## License
 

cli/node/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@mem0/cli",
-  "version": "0.1.0",
+  "version": "0.2.4",
   "description": "The official CLI for mem0 — the memory layer for AI agents",
   "type": "module",
   "bin": {
     "mem0": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -20,6 +20,11 @@
   },
   "license": "Apache-2.0",
   "author": "mem0.ai <founders@mem0.ai>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mem0ai/mem0",
+    "directory": "cli/node"
+  },
   "keywords": ["mem0", "memory", "ai", "agents", "cli"],
   "publishConfig": {
     "access": "public"

cli/node/src/backend/base.ts

@@ -6,110 +6,122 @@ import type { Mem0Config } from "../config.js";
 import { PlatformBackend } from "./platform.js";
 
 export interface AddOptions {
-  userId?: string;
-  agentId?: string;
-  appId?: string;
-  runId?: string;
-  metadata?: Record<string, unknown>;
-  immutable?: boolean;
-  infer?: boolean;
-  expires?: string;
-  categories?: string[];
-  enableGraph?: boolean;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	metadata?: Record<string, unknown>;
+	immutable?: boolean;
+	infer?: boolean;
+	expires?: string;
+	categories?: string[];
 }
 
 export interface SearchOptions {
-  userId?: string;
-  agentId?: string;
-  appId?: string;
-  runId?: string;
-  topK?: number;
-  threshold?: number;
-  rerank?: boolean;
-  keyword?: boolean;
-  filters?: Record<string, unknown>;
-  fields?: string[];
-  enableGraph?: boolean;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	topK?: number;
+	threshold?: number;
+	rerank?: boolean;
+	keyword?: boolean;
+	filters?: Record<string, unknown>;
+	fields?: string[];
 }
 
 export interface ListOptions {
-  userId?: string;
-  agentId?: string;
-  appId?: string;
-  runId?: string;
-  page?: number;
-  pageSize?: number;
-  category?: string;
-  after?: string;
-  before?: string;
-  enableGraph?: boolean;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	page?: number;
+	pageSize?: number;
+	category?: string;
+	after?: string;
+	before?: string;
 }
 
 export interface DeleteOptions {
-  all?: boolean;
-  userId?: string;
-  agentId?: string;
-  appId?: string;
-  runId?: string;
+	all?: boolean;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
 }
 
 export interface EntityIds {
-  userId?: string;
-  agentId?: string;
-  appId?: string;
-  runId?: string;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
 }
 
 export interface Backend {
-  add(
-    content?: string,
-    messages?: Record<string, unknown>[],
-    opts?: AddOptions,
-  ): Promise<Record<string, unknown>>;
+	add(
+		content?: string,
+		messages?: Record<string, unknown>[],
+		opts?: AddOptions,
+	): Promise<Record<string, unknown>>;
 
-  search(query: string, opts?: SearchOptions): Promise<Record<string, unknown>[]>;
+	search(
+		query: string,
+		opts?: SearchOptions,
+	): Promise<Record<string, unknown>[]>;
 
-  get(memoryId: string): Promise<Record<string, unknown>>;
+	get(memoryId: string): Promise<Record<string, unknown>>;
 
-  listMemories(opts?: ListOptions): Promise<Record<string, unknown>[]>;
+	listMemories(opts?: ListOptions): Promise<Record<string, unknown>[]>;
 
-  update(
-    memoryId: string,
-    content?: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<Record<string, unknown>>;
+	update(
+		memoryId: string,
+		content?: string,
+		metadata?: Record<string, unknown>,
+	): Promise<Record<string, unknown>>;
 
-  delete(memoryId?: string, opts?: DeleteOptions): Promise<Record<string, unknown>>;
+	delete(
+		memoryId?: string,
+		opts?: DeleteOptions,
+	): Promise<Record<string, unknown>>;
 
-  deleteEntities(opts: EntityIds): Promise<Record<string, unknown>>;
+	deleteEntities(opts: EntityIds): Promise<Record<string, unknown>>;
 
-  status(opts?: { userId?: string; agentId?: string }): Promise<Record<string, unknown>>;
+	ping(): Promise<Record<string, unknown>>;
 
-  entities(entityType: string): Promise<Record<string, unknown>[]>;
+	status(opts?: { userId?: string; agentId?: string }): Promise<
+		Record<string, unknown>
+	>;
+
+	entities(entityType: string): Promise<Record<string, unknown>[]>;
+
+	listEvents(): Promise<Record<string, unknown>[]>;
+
+	getEvent(eventId: string): Promise<Record<string, unknown>>;
 }
 
 export class AuthError extends Error {
-  constructor(message = "Authentication failed. Your API key may be invalid or expired.") {
-    super(message);
-    this.name = "AuthError";
-  }
+	constructor(
+		message = "Authentication failed. Your API key may be invalid or expired.",
+	) {
+		super(message);
+		this.name = "AuthError";
+	}
 }
 
 export class NotFoundError extends Error {
-  constructor(path: string) {
-    super(`Resource not found: ${path}`);
-    this.name = "NotFoundError";
-  }
+	constructor(path: string) {
+		super(`Resource not found: ${path}`);
+		this.name = "NotFoundError";
+	}
 }
 
 export class APIError extends Error {
-  constructor(path: string, detail: string) {
-    super(`Bad request to ${path}: ${detail}`);
-    this.name = "APIError";
-  }
+	constructor(path: string, detail: string) {
+		super(`Bad request to ${path}: ${detail}`);
+		this.name = "APIError";
+	}
 }
 
 export function getBackend(config: Mem0Config): Backend {
-  return new PlatformBackend(config.platform);
+	return new PlatformBackend(config.platform);
 }
-

cli/node/src/backend/index.ts

@@ -3,5 +3,12 @@
  */
 
 export { getBackend } from "./base.js";
-export type { Backend, AddOptions, SearchOptions, ListOptions, DeleteOptions, EntityIds } from "./base.js";
+export type {
+	Backend,
+	AddOptions,
+	SearchOptions,
+	ListOptions,
+	DeleteOptions,
+	EntityIds,
+} from "./base.js";
 export { AuthError, NotFoundError, APIError } from "./base.js";

cli/node/src/backend/platform.ts

@@ -3,301 +3,358 @@
  */
 
 import type { PlatformConfig } from "../config.js";
+import { isAgentMode } from "../state.js";
+import { CLI_VERSION } from "../version.js";
 import {
-  type AddOptions,
-  APIError,
-  AuthError,
-  type Backend,
-  type DeleteOptions,
-  type EntityIds,
-  type ListOptions,
-  NotFoundError,
-  type SearchOptions,
+	APIError,
+	type AddOptions,
+	AuthError,
+	type Backend,
+	type DeleteOptions,
+	type EntityIds,
+	type ListOptions,
+	NotFoundError,
+	type SearchOptions,
 } from "./base.js";
 
 export class PlatformBackend implements Backend {
-  private baseUrl: string;
-  private headers: Record<string, string>;
+	private baseUrl: string;
+	private headers: Record<string, string>;
 
-  constructor(config: PlatformConfig) {
-    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
-    this.headers = {
-      Authorization: `Token ${config.apiKey}`,
-      "Content-Type": "application/json",
-    };
-  }
+	constructor(config: PlatformConfig) {
+		this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this.headers = {
+			Authorization: `Token ${config.apiKey}`,
+			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
+		};
+	}
 
-  private async _request(
-    method: string,
-    path: string,
-    opts?: { json?: unknown; params?: Record<string, string> },
-  ): Promise<unknown> {
-    let url = `${this.baseUrl}${path}`;
-    if (opts?.params) {
-      const qs = new URLSearchParams(opts.params).toString();
-      url += `?${qs}`;
-    }
+	private async _request(
+		method: string,
+		path: string,
+		opts?: { json?: unknown; params?: Record<string, string> },
+	): Promise<unknown> {
+		let url = `${this.baseUrl}${path}`;
+		if (opts?.params) {
+			const qs = new URLSearchParams(opts.params).toString();
+			url += `?${qs}`;
+		}
 
-    const fetchOpts: RequestInit = {
-      method,
-      headers: this.headers,
-      signal: AbortSignal.timeout(30_000),
-    };
-    if (opts?.json) {
-      fetchOpts.body = JSON.stringify(opts.json);
-    }
+		const headers = {
+			...this.headers,
+			"X-Mem0-Caller-Type": isAgentMode() ? "agent" : "user",
+		};
 
-    const resp = await fetch(url, fetchOpts);
+		const fetchOpts: RequestInit = {
+			method,
+			headers,
+			signal: AbortSignal.timeout(30_000),
+		};
+		if (opts?.json) {
+			fetchOpts.body = JSON.stringify(opts.json);
+		}
 
-    if (resp.status === 401) {
-      throw new AuthError();
-    }
-    if (resp.status === 404) {
-      throw new NotFoundError(path);
-    }
-    if (resp.status === 400) {
-      let detail: string;
-      try {
-        const body = await resp.json();
-        detail = (body as Record<string, string>).detail ?? resp.statusText;
-      } catch {
-        detail = resp.statusText;
-      }
-      throw new APIError(path, detail);
-    }
-    if (!resp.ok) {
-      throw new Error(`HTTP ${resp.status}: ${resp.statusText}`);
-    }
-    if (resp.status === 204) {
-      return {};
-    }
-    return resp.json();
-  }
+		const resp = await fetch(url, fetchOpts);
 
-  async add(
-    content?: string,
-    messages?: Record<string, unknown>[],
-    opts: AddOptions = {},
-  ): Promise<Record<string, unknown>> {
-    const payload: Record<string, unknown> = {};
+		if (resp.status === 401) {
+			throw new AuthError();
+		}
+		if (resp.status === 404) {
+			throw new NotFoundError(path);
+		}
+		if (resp.status === 400) {
+			let detail: string;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail =
+					((body.detail ?? body.message ?? JSON.stringify(body)) as string) ??
+					resp.statusText;
+			} catch {
+				detail = resp.statusText;
+			}
+			throw new APIError(path, detail);
+		}
+		if (!resp.ok) {
+			let detail: string = resp.statusText;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail = (body.detail ?? body.message ?? resp.statusText) as string;
+			} catch {
+				/* ignore */
+			}
+			throw new Error(`HTTP ${resp.status}: ${detail}`);
+		}
+		if (resp.status === 204) {
+			return {};
+		}
+		return resp.json();
+	}
 
-    if (messages) {
-      payload.messages = messages;
-    } else if (content) {
-      payload.messages = [{ role: "user", content }];
-    }
+	async add(
+		content?: string,
+		messages?: Record<string, unknown>[],
+		opts: AddOptions = {},
+	): Promise<Record<string, unknown>> {
+		const payload: Record<string, unknown> = {};
 
-    if (opts.userId) payload.user_id = opts.userId;
-    if (opts.agentId) payload.agent_id = opts.agentId;
-    if (opts.appId) payload.app_id = opts.appId;
-    if (opts.runId) payload.run_id = opts.runId;
-    if (opts.metadata) payload.metadata = opts.metadata;
-    if (opts.immutable) payload.immutable = true;
-    if (opts.infer === false) payload.infer = false;
-    if (opts.expires) payload.expiration_date = opts.expires;
-    if (opts.categories) payload.categories = opts.categories;
-    if (opts.enableGraph) payload.enable_graph = true;
+		if (messages) {
+			payload.messages = messages;
+		} else if (content) {
+			payload.messages = [{ role: "user", content }];
+		}
 
-    return (await this._request("POST", "/v1/memories/", { json: payload })) as Record<
-      string,
-      unknown
-    >;
-  }
+		if (opts.userId) payload.user_id = opts.userId;
+		if (opts.agentId) payload.agent_id = opts.agentId;
+		if (opts.appId) payload.app_id = opts.appId;
+		if (opts.runId) payload.run_id = opts.runId;
+		if (opts.metadata) payload.metadata = opts.metadata;
+		if (opts.immutable) payload.immutable = true;
+		if (opts.infer === false) payload.infer = false;
+		if (opts.expires) payload.expiration_date = opts.expires;
+		if (opts.categories) payload.categories = opts.categories;
+		payload.source = "CLI";
 
-  private _buildFilters(opts: {
-    userId?: string;
-    agentId?: string;
-    appId?: string;
-    runId?: string;
-    extraFilters?: Record<string, unknown>;
-  }): Record<string, unknown> | undefined {
-    // If caller passed a pre-built filter structure, use it directly
-    if (opts.extraFilters && ("AND" in opts.extraFilters || "OR" in opts.extraFilters)) {
-      return opts.extraFilters;
-    }
+		return (await this._request("POST", "/v3/memories/add/", {
+			json: payload,
+		})) as Record<string, unknown>;
+	}
 
-    const andConditions: Record<string, unknown>[] = [];
-    if (opts.userId) andConditions.push({ user_id: opts.userId });
-    if (opts.agentId) andConditions.push({ agent_id: opts.agentId });
-    if (opts.appId) andConditions.push({ app_id: opts.appId });
-    if (opts.runId) andConditions.push({ run_id: opts.runId });
+	private _buildFilters(opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		extraFilters?: Record<string, unknown>;
+	}): Record<string, unknown> | undefined {
+		// If caller passed a pre-built filter structure, use it directly
+		if (
+			opts.extraFilters &&
+			("AND" in opts.extraFilters || "OR" in opts.extraFilters)
+		) {
+			return opts.extraFilters;
+		}
 
-    if (opts.extraFilters) {
-      for (const [k, v] of Object.entries(opts.extraFilters)) {
-        andConditions.push({ [k]: v });
-      }
-    }
+		const andConditions: Record<string, unknown>[] = [];
+		if (opts.userId) andConditions.push({ user_id: opts.userId });
+		if (opts.agentId) andConditions.push({ agent_id: opts.agentId });
+		if (opts.appId) andConditions.push({ app_id: opts.appId });
+		if (opts.runId) andConditions.push({ run_id: opts.runId });
 
-    if (andConditions.length === 1) return andConditions[0];
-    if (andConditions.length > 1) return { AND: andConditions };
-    return undefined;
-  }
+		if (opts.extraFilters) {
+			for (const [k, v] of Object.entries(opts.extraFilters)) {
+				andConditions.push({ [k]: v });
+			}
+		}
 
-  async search(query: string, opts: SearchOptions = {}): Promise<Record<string, unknown>[]> {
-    const payload: Record<string, unknown> = {
-      query,
-      top_k: opts.topK ?? 10,
-      threshold: opts.threshold ?? 0.3,
-    };
+		if (andConditions.length === 1) return andConditions[0];
+		if (andConditions.length > 1) return { AND: andConditions };
+		return undefined;
+	}
 
-    const apiFilters = this._buildFilters({
-      userId: opts.userId,
-      agentId: opts.agentId,
-      appId: opts.appId,
-      runId: opts.runId,
-      extraFilters: opts.filters,
-    });
-    if (apiFilters) payload.filters = apiFilters;
-    if (opts.rerank) payload.rerank = true;
-    if (opts.keyword) payload.keyword_search = true;
-    if (opts.fields) payload.fields = opts.fields;
-    if (opts.enableGraph) payload.enable_graph = true;
+	async search(
+		query: string,
+		opts: SearchOptions = {},
+	): Promise<Record<string, unknown>[]> {
+		const payload: Record<string, unknown> = {
+			query,
+			top_k: opts.topK ?? 10,
+			threshold: opts.threshold ?? 0.3,
+		};
 
-    const result = (await this._request("POST", "/v2/memories/search/", {
-      json: payload,
-    })) as unknown;
-    if (Array.isArray(result)) return result;
-    const obj = result as Record<string, unknown>;
-    return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
-  }
+		const apiFilters = this._buildFilters({
+			userId: opts.userId,
+			agentId: opts.agentId,
+			appId: opts.appId,
+			runId: opts.runId,
+			extraFilters: opts.filters,
+		});
+		if (apiFilters) payload.filters = apiFilters;
+		if (opts.rerank) payload.rerank = true;
+		if (opts.keyword) payload.keyword_search = true;
+		if (opts.fields) payload.fields = opts.fields;
+		payload.source = "CLI";
 
-  async get(memoryId: string): Promise<Record<string, unknown>> {
-    return (await this._request("GET", `/v1/memories/${memoryId}/`)) as Record<string, unknown>;
-  }
+		const result = (await this._request("POST", "/v3/memories/search/", {
+			json: payload,
+		})) as unknown;
+		if (Array.isArray(result)) return result;
+		const obj = result as Record<string, unknown>;
+		return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
+	}
 
-  async listMemories(opts: ListOptions = {}): Promise<Record<string, unknown>[]> {
-    const payload: Record<string, unknown> = {};
-    const params: Record<string, string> = {
-      page: String(opts.page ?? 1),
-      page_size: String(opts.pageSize ?? 100),
-    };
+	async get(memoryId: string): Promise<Record<string, unknown>> {
+		return (await this._request("GET", `/v1/memories/${memoryId}/`, {
+			params: { source: "CLI" },
+		})) as Record<string, unknown>;
+	}
 
-    const extra: Record<string, unknown> = {};
-    if (opts.category) {
-      extra.categories = { contains: opts.category };
-    }
-    if (opts.after) {
-      extra.created_at = { ...(extra.created_at as Record<string, unknown> | undefined), gte: opts.after };
-    }
-    if (opts.before) {
-      extra.created_at = { ...(extra.created_at as Record<string, unknown> | undefined), lte: opts.before };
-    }
+	async listMemories(
+		opts: ListOptions = {},
+	): Promise<Record<string, unknown>[]> {
+		const payload: Record<string, unknown> = {};
+		const params: Record<string, string> = {
+			page: String(opts.page ?? 1),
+			page_size: String(opts.pageSize ?? 100),
+		};
 
-    const apiFilters = this._buildFilters({
-      userId: opts.userId,
-      agentId: opts.agentId,
-      appId: opts.appId,
-      runId: opts.runId,
-      extraFilters: Object.keys(extra).length > 0 ? extra : undefined,
-    });
-    if (apiFilters) payload.filters = apiFilters;
-    if (opts.enableGraph) payload.enable_graph = true;
+		const extra: Record<string, unknown> = {};
+		if (opts.category) {
+			extra.categories = { contains: opts.category };
+		}
+		if (opts.after) {
+			extra.created_at = {
+				...(extra.created_at as Record<string, unknown> | undefined),
+				gte: opts.after,
+			};
+		}
+		if (opts.before) {
+			extra.created_at = {
+				...(extra.created_at as Record<string, unknown> | undefined),
+				lte: opts.before,
+			};
+		}
 
-    const result = (await this._request("POST", "/v2/memories/", { json: payload, params })) as unknown;
-    if (Array.isArray(result)) return result;
-    const obj = result as Record<string, unknown>;
-    return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
-  }
+		const apiFilters = this._buildFilters({
+			userId: opts.userId,
+			agentId: opts.agentId,
+			appId: opts.appId,
+			runId: opts.runId,
+			extraFilters: Object.keys(extra).length > 0 ? extra : undefined,
+		});
+		if (apiFilters) payload.filters = apiFilters;
+		payload.source = "CLI";
 
-  async update(
-    memoryId: string,
-    content?: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<Record<string, unknown>> {
-    const payload: Record<string, unknown> = {};
-    if (content) payload.text = content;
-    if (metadata) payload.metadata = metadata;
-    return (await this._request("PUT", `/v1/memories/${memoryId}/`, {
-      json: payload,
-    })) as Record<string, unknown>;
-  }
+		const result = (await this._request("POST", "/v3/memories/", {
+			json: payload,
+			params,
+		})) as unknown;
+		if (Array.isArray(result)) return result;
+		const obj = result as Record<string, unknown>;
+		return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
+	}
 
-  async delete(
-    memoryId?: string,
-    opts: DeleteOptions = {},
-  ): Promise<Record<string, unknown>> {
-    if (opts.all) {
-      const params: Record<string, string> = {};
-      if (opts.userId) params.user_id = opts.userId;
-      if (opts.agentId) params.agent_id = opts.agentId;
-      if (opts.appId) params.app_id = opts.appId;
-      if (opts.runId) params.run_id = opts.runId;
-      return (await this._request("DELETE", "/v1/memories/", { params })) as Record<
-        string,
-        unknown
-      >;
-    }
-    if (memoryId) {
-      return (await this._request("DELETE", `/v1/memories/${memoryId}/`)) as Record<
-        string,
-        unknown
-      >;
-    }
-    throw new Error("Either memoryId or --all is required");
-  }
+	async update(
+		memoryId: string,
+		content?: string,
+		metadata?: Record<string, unknown>,
+	): Promise<Record<string, unknown>> {
+		const payload: Record<string, unknown> = {};
+		if (content) payload.text = content;
+		if (metadata) payload.metadata = metadata;
+		payload.source = "CLI";
+		return (await this._request("PUT", `/v1/memories/${memoryId}/`, {
+			json: payload,
+		})) as Record<string, unknown>;
+	}
 
-  async deleteEntities(opts: EntityIds): Promise<Record<string, unknown>> {
-    const params: Record<string, string> = {};
-    if (opts.userId) params.user_id = opts.userId;
-    if (opts.agentId) params.agent_id = opts.agentId;
-    if (opts.appId) params.app_id = opts.appId;
-    if (opts.runId) params.run_id = opts.runId;
-    if (Object.keys(params).length === 0) {
-      throw new Error("At least one entity ID is required for deleteEntities.");
-    }
-    return (await this._request("DELETE", "/v1/entities/", { params })) as Record<
-      string,
-      unknown
-    >;
-  }
+	async delete(
+		memoryId?: string,
+		opts: DeleteOptions = {},
+	): Promise<Record<string, unknown>> {
+		if (opts.all) {
+			const params: Record<string, string> = { source: "CLI" };
+			if (opts.userId) params.user_id = opts.userId;
+			if (opts.agentId) params.agent_id = opts.agentId;
+			if (opts.appId) params.app_id = opts.appId;
+			if (opts.runId) params.run_id = opts.runId;
+			return (await this._request("DELETE", "/v1/memories/", {
+				params,
+			})) as Record<string, unknown>;
+		}
+		if (memoryId) {
+			return (await this._request("DELETE", `/v1/memories/${memoryId}/`, {
+				params: { source: "CLI" },
+			})) as Record<string, unknown>;
+		}
+		throw new Error("Either memoryId or --all is required");
+	}
 
-  async status(
-    opts: { userId?: string; agentId?: string } = {},
-  ): Promise<Record<string, unknown>> {
-    try {
-      if (opts.userId || opts.agentId) {
-        const payload: Record<string, unknown> = {};
-        const statusParams: Record<string, string> = { page: "1", page_size: "1" };
-        const apiFilters = this._buildFilters({
-          userId: opts.userId,
-          agentId: opts.agentId,
-        });
-        if (apiFilters) payload.filters = apiFilters;
-        await this._request("POST", "/v2/memories/", { json: payload, params: statusParams });
-      } else {
-        await this._request("GET", "/v1/entities/");
-      }
-      return { connected: true, backend: "platform", base_url: this.baseUrl };
-    } catch (e) {
-      return {
-        connected: false,
-        backend: "platform",
-        error: e instanceof Error ? e.message : String(e),
-      };
-    }
-  }
+	async deleteEntities(opts: EntityIds): Promise<Record<string, unknown>> {
+		// v2 endpoint: DELETE /v2/entities/{entity_type}/{entity_id}/
+		const typeMap: [string, string | undefined][] = [
+			["user", opts.userId],
+			["agent", opts.agentId],
+			["app", opts.appId],
+			["run", opts.runId],
+		];
+		const entities = typeMap.filter(([, v]) => v) as [string, string][];
+		if (entities.length === 0) {
+			throw new Error("At least one entity ID is required for deleteEntities.");
+		}
+		// Delete each provided entity via the v2 path-based endpoint
+		let result: Record<string, unknown> = {};
+		for (const [entityType, entityId] of entities) {
+			result = (await this._request(
+				"DELETE",
+				`/v2/entities/${entityType}/${entityId}/`,
+				{ params: { source: "CLI" } },
+			)) as Record<string, unknown>;
+		}
+		return result;
+	}
 
-  async entities(entityType: string): Promise<Record<string, unknown>[]> {
-    const result = (await this._request("GET", "/v1/entities/")) as unknown;
-    let items: Record<string, unknown>[];
-    if (Array.isArray(result)) {
-      items = result;
-    } else {
-      items = ((result as Record<string, unknown>).results ?? []) as Record<string, unknown>[];
-    }
+	async ping(): Promise<Record<string, unknown>> {
+		return (await this._request("GET", "/v1/ping/")) as Record<string, unknown>;
+	}
 
-    const typeMap: Record<string, string> = {
-      users: "user",
-      agents: "agent",
-      apps: "app",
-      runs: "run",
-    };
-    const targetType = typeMap[entityType];
-    if (targetType) {
-      items = items.filter(
-        (e) => (e.type as string | undefined)?.toLowerCase() === targetType,
-      );
-    }
-    return items;
-  }
+	async status(
+		opts: { userId?: string; agentId?: string } = {},
+	): Promise<Record<string, unknown>> {
+		try {
+			await this.ping();
+			return { connected: true, backend: "platform", base_url: this.baseUrl };
+		} catch (e) {
+			return {
+				connected: false,
+				backend: "platform",
+				error: e instanceof Error ? e.message : String(e),
+			};
+		}
+	}
+
+	async entities(entityType: string): Promise<Record<string, unknown>[]> {
+		const result = (await this._request("GET", "/v1/entities/")) as unknown;
+		let items: Record<string, unknown>[];
+		if (Array.isArray(result)) {
+			items = result;
+		} else {
+			items = ((result as Record<string, unknown>).results ?? []) as Record<
+				string,
+				unknown
+			>[];
+		}
+
+		const typeMap: Record<string, string> = {
+			users: "user",
+			agents: "agent",
+			apps: "app",
+			runs: "run",
+		};
+		const targetType = typeMap[entityType];
+		if (targetType) {
+			items = items.filter(
+				(e) => (e.type as string | undefined)?.toLowerCase() === targetType,
+			);
+		}
+		return items;
+	}
+
+	async listEvents(): Promise<Record<string, unknown>[]> {
+		const result = (await this._request("GET", "/v1/events/")) as unknown;
+		if (Array.isArray(result)) return result;
+		return ((result as Record<string, unknown>).results ?? []) as Record<
+			string,
+			unknown
+		>[];
+	}
+
+	async getEvent(eventId: string): Promise<Record<string, unknown>> {
+		return (await this._request("GET", `/v1/event/${eventId}/`)) as Record<
+			string,
+			unknown
+		>;
+	}
 }

cli/node/src/branding.ts

@@ -4,10 +4,8 @@
 
 import chalk from "chalk";
 import ora, { type Ora } from "ora";
-import { createRequire } from "node:module";
-
-const _require = createRequire(import.meta.url);
-const PKG_VERSION: string = _require("../package.json").version;
+import { getCurrentCommand, isAgentMode } from "./state.js";
+import { CLI_VERSION } from "./version.js";
 
 export const LOGO = `
 ███╗   ███╗███████╗███╗   ███╗ ██████╗      ██████╗██╗     ██╗
@@ -40,75 +38,96 @@ const dim = chalk.hex(DIM_COLOR);
  * plain-text for piped/non-TTY or NO_COLOR environments.
  */
 export function sym(fancy: string, plain: string): string {
-  if (!process.stdout.isTTY || process.env.NO_COLOR) return plain;
-  return fancy;
+	if (!process.stdout.isTTY || process.env.NO_COLOR) return plain;
+	return fancy;
 }
 
 export function printBanner(): void {
-  const pad = 3; // horizontal padding each side (matches Rich's padding=(0, 2))
-  const logoLines = LOGO.trimEnd().split("\n");
-  const tagline = `  ${TAGLINE}`;
-  const subtitle = `Node.js SDK · v${PKG_VERSION}`;
-  const contentLines = ["", ...logoLines, "", tagline, ""];
+	if (isAgentMode()) return;
+	const pad = 3; // horizontal padding each side (matches Rich's padding=(0, 2))
+	const logoLines = LOGO.trimEnd().split("\n");
+	const tagline = `  ${TAGLINE}`;
+	const subtitle = `Node.js SDK · v${CLI_VERSION}`;
+	const contentLines = ["", ...logoLines, "", tagline, ""];
 
-  // Compute inner width from longest content line + padding both sides
-  const maxContent = Math.max(...contentLines.map((l) => l.length));
-  const innerWidth = maxContent + pad * 2;
-  const totalWidth = innerWidth + 2; // + 2 for │ borders
+	// Compute inner width from longest content line + padding both sides
+	const maxContent = Math.max(...contentLines.map((l) => l.length));
+	const innerWidth = maxContent + pad * 2;
+	const totalWidth = innerWidth + 2; // + 2 for │ borders
 
-  const topBorder = brand(`╭${"─".repeat(totalWidth - 2)}╮`);
-  const subtitleFill = totalWidth - 2 - subtitle.length - 3; // 3 = "─ " before subtitle + "─" after
-  const bottomBorder = brand(`╰${"─".repeat(subtitleFill)} ${dim(subtitle)} ${"─"}╯`);
+	const topBorder = brand(`╭${"─".repeat(totalWidth - 2)}╮`);
+	const subtitleFill = totalWidth - 2 - subtitle.length - 3; // 3 = "─ " before subtitle + "─" after
+	const bottomBorder = brand(
+		`╰${"─".repeat(subtitleFill)} ${dim(subtitle)} ${"─"}╯`,
+	);
 
-  const body = contentLines.map((line) => {
-    const rightPad = innerWidth - pad - line.length;
-    return `${brand("│")}${" ".repeat(pad)}${brand.bold(line)}${" ".repeat(Math.max(rightPad, 0))}${brand("│")}`;
-  });
-  // Re-color tagline line with accent instead of brand.bold
-  const taglineIdx = body.length - 2; // second-to-last (before trailing empty line)
-  const taglineRightPad = innerWidth - pad - tagline.length;
-  body[taglineIdx] = `${brand("│")}${" ".repeat(pad)}${accent(tagline)}${" ".repeat(Math.max(taglineRightPad, 0))}${brand("│")}`;
+	const body = contentLines.map((line) => {
+		const rightPad = innerWidth - pad - line.length;
+		return `${brand("│")}${" ".repeat(pad)}${brand.bold(line)}${" ".repeat(Math.max(rightPad, 0))}${brand("│")}`;
+	});
+	// Re-color tagline line with accent instead of brand.bold
+	const taglineIdx = body.length - 2; // second-to-last (before trailing empty line)
+	const taglineRightPad = innerWidth - pad - tagline.length;
+	body[taglineIdx] =
+		`${brand("│")}${" ".repeat(pad)}${accent(tagline)}${" ".repeat(Math.max(taglineRightPad, 0))}${brand("│")}`;
 
-  console.log(topBorder);
-  for (const line of body) console.log(line);
-  console.log(bottomBorder);
+	console.log(topBorder);
+	for (const line of body) console.log(line);
+	console.log(bottomBorder);
 }
 
 export function printSuccess(message: string): void {
-  console.log(`${success(sym("✓", "[ok]"))} ${message}`);
+	if (isAgentMode()) return;
+	console.log(`${success(sym("✓", "[ok]"))} ${message}`);
 }
 
 export function printError(message: string, hint?: string): void {
-  console.error(`${error(sym("✗", "[error]") + " Error:")} ${message}`);
-  if (hint) {
-    console.error(`  ${dim(hint)}`);
-  }
+	if (isAgentMode()) {
+		const envelope = {
+			status: "error",
+			command: getCurrentCommand(),
+			error: message,
+			data: null,
+		};
+		console.log(JSON.stringify(envelope));
+		return;
+	}
+	console.error(`${error(`${sym("✗", "[error]")} Error:`)} ${message}`);
+	const resolvedHint =
+		hint ??
+		(message.includes("Authentication failed")
+			? `Run ${brand("mem0 init")} to reconfigure your API key · https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node`
+			: undefined);
+	if (resolvedHint) {
+		console.error(`  ${dim(resolvedHint)}`);
+	}
 }
 
 export function printWarning(message: string): void {
-  console.error(`${warning(sym("⚠", "[warn]"))} ${message}`);
+	console.error(`${warning(sym("⚠", "[warn]"))} ${message}`);
 }
 
 export function printInfo(message: string): void {
-  console.log(`${brand(sym("◆", "*"))} ${message}`);
+	if (isAgentMode()) return;
+	console.error(`${brand(sym("◆", "*"))} ${message}`);
 }
 
 export function printScope(ids: Record<string, string | undefined>): void {
-  const parts: string[] = [];
-  for (const [key, val] of Object.entries(ids)) {
-    if (val) {
-      const label = key.replace(/_/g, " ").replace("id", "ID").trim();
-      parts.push(`${label}=${val}`);
-    }
-  }
-  if (parts.length > 0) {
-    console.log(`  ${dim(`Scope: ${parts.join(", ")}`)}`);
-  }
+	if (isAgentMode()) return;
+	const parts: string[] = [];
+	for (const [key, val] of Object.entries(ids)) {
+		if (val) {
+			parts.push(`${key}=${val}`);
+		}
+	}
+	if (parts.length > 0) {
+		console.error(`  ${dim(`Scope: ${parts.join(", ")}`)}`);
+	}
 }
 
 export interface TimedStatusContext {
-  successMsg: string;
-  errorMsg: string;
+	successMsg: string;
+	errorMsg: string;
 }
 
 /**
@@ -116,29 +135,37 @@ export interface TimedStatusContext {
  * Equivalent to Python's timed_status context manager.
  */
 export async function timedStatus<T>(
-  message: string,
-  fn: (ctx: TimedStatusContext) => Promise<T>,
+	message: string,
+	fn: (ctx: TimedStatusContext) => Promise<T>,
 ): Promise<T> {
-  const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
-  const spinner = ora({ text: dim(message), color: "magenta", stream: process.stderr }).start();
-  const start = performance.now();
+	if (isAgentMode()) {
+		const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+		return fn(ctx);
+	}
+	const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+	const spinner = ora({
+		text: dim(message),
+		color: "yellow",
+		stream: process.stderr,
+	}).start();
+	const start = performance.now();
 
-  try {
-    const result = await fn(ctx);
-    const elapsed = ((performance.now() - start) / 1000).toFixed(2);
-    spinner.stop();
-    if (ctx.successMsg) {
-      console.error(`${success("✓")} ${ctx.successMsg} (${elapsed}s)`);
-    }
-    return result;
-  } catch (err) {
-    const elapsed = ((performance.now() - start) / 1000).toFixed(2);
-    spinner.stop();
-    if (ctx.errorMsg) {
-      console.error(`${error("✗ Error:")} ${ctx.errorMsg} (${elapsed}s)`);
-    }
-    throw err;
-  }
+	try {
+		const result = await fn(ctx);
+		const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+		spinner.stop();
+		if (ctx.successMsg) {
+			console.error(`${success("✓")} ${ctx.successMsg} (${elapsed}s)`);
+		}
+		return result;
+	} catch (err) {
+		const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+		spinner.stop();
+		if (ctx.errorMsg) {
+			printError(`${ctx.errorMsg} (${elapsed}s)`);
+		}
+		throw err;
+	}
 }
 
 /** Format helpers using brand colors for external use. */

cli/node/src/commands/config.ts

@@ -3,88 +3,107 @@
  */
 
 import Table from "cli-table3";
-import { printError, printSuccess, colors } from "../branding.js";
+import { colors, printError, printSuccess } from "../branding.js";
 import {
-  getNestedValue,
-  loadConfig,
-  redactKey,
-  saveConfig,
-  setNestedValue,
+	getNestedValue,
+	loadConfig,
+	redactKey,
+	saveConfig,
+	setNestedValue,
 } from "../config.js";
-import { formatJsonEnvelope } from "../output.js";
+import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
+import { isAgentMode, setCurrentCommand } from "../state.js";
 
 const { brand, accent, dim } = colors;
 
 export function cmdConfigShow(opts: { output?: string } = {}): void {
-  const config = loadConfig();
+	setCurrentCommand("config show");
+	const config = loadConfig();
 
-  if (opts.output === "json") {
-    formatJsonEnvelope({
-      command: "config show",
-      data: {
-        defaults: {
-          user_id: config.defaults.userId || null,
-          agent_id: config.defaults.agentId || null,
-          app_id: config.defaults.appId || null,
-          run_id: config.defaults.runId || null,
-          enable_graph: config.defaults.enableGraph,
-        },
-        platform: {
-          api_key: redactKey(config.platform.apiKey),
-          base_url: config.platform.baseUrl,
-        },
-      },
-    });
-    return;
-  }
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "config show",
+			data: {
+				defaults: {
+					user_id: config.defaults.userId || null,
+					agent_id: config.defaults.agentId || null,
+					app_id: config.defaults.appId || null,
+					run_id: config.defaults.runId || null,
+				},
+				platform: {
+					api_key: redactKey(config.platform.apiKey),
+					base_url: config.platform.baseUrl,
+				},
+			},
+		});
+		return;
+	}
 
-  console.log();
-  console.log(`  ${brand("◆ mem0 Configuration")}\n`);
+	console.log();
+	console.log(`  ${brand("◆ mem0 Configuration")}\n`);
 
-  const table = new Table({
-    head: [accent("Key"), accent("Value")],
-    style: { head: [], border: [] },
-  });
+	const table = new Table({
+		head: [accent("Key"), accent("Value")],
+		style: { head: [], border: [] },
+	});
 
-  // Defaults
-  table.push(["defaults.user_id", config.defaults.userId || dim("(not set)")]);
-  table.push(["defaults.agent_id", config.defaults.agentId || dim("(not set)")]);
-  table.push(["defaults.app_id", config.defaults.appId || dim("(not set)")]);
-  table.push(["defaults.run_id", config.defaults.runId || dim("(not set)")]);
-  table.push(["defaults.enable_graph", String(config.defaults.enableGraph)]);
-  table.push(["", ""]);
+	// Defaults
+	table.push(["defaults.user_id", config.defaults.userId || dim("(not set)")]);
+	table.push([
+		"defaults.agent_id",
+		config.defaults.agentId || dim("(not set)"),
+	]);
+	table.push(["defaults.app_id", config.defaults.appId || dim("(not set)")]);
+	table.push(["defaults.run_id", config.defaults.runId || dim("(not set)")]);
+	table.push(["", ""]);
 
-  // Platform
-  table.push(["platform.api_key", redactKey(config.platform.apiKey)]);
-  table.push(["platform.base_url", config.platform.baseUrl]);
+	// Platform
+	table.push(["platform.api_key", redactKey(config.platform.apiKey)]);
+	table.push(["platform.base_url", config.platform.baseUrl]);
 
-  console.log(table.toString());
-  console.log();
+	console.log(table.toString());
+	console.log();
 }
 
 export function cmdConfigGet(key: string): void {
-  const config = loadConfig();
-  const value = getNestedValue(config, key);
+	setCurrentCommand("config get");
+	const config = loadConfig();
+	const value = getNestedValue(config, key);
 
-  if (value === undefined) {
-    printError(`Unknown config key: ${key}`);
-  } else {
-    // Redact secrets
-    if (key.includes("api_key") || key.split(".").pop() === "key") {
-      console.log(redactKey(String(value)));
-    } else {
-      console.log(String(value));
-    }
-  }
+	if (value === undefined) {
+		printError(`Unknown config key: ${key}`);
+	} else {
+		// Redact secrets
+		const displayValue =
+			key.includes("api_key") || key.split(".").pop() === "key"
+				? redactKey(String(value))
+				: String(value);
+		if (isAgentMode()) {
+			formatAgentEnvelope({
+				command: "config get",
+				data: { key, value: displayValue },
+			});
+		} else {
+			console.log(displayValue);
+		}
+	}
 }
 
 export function cmdConfigSet(key: string, value: string): void {
-  const config = loadConfig();
-  if (setNestedValue(config, key, value)) {
-    saveConfig(config);
-    const display = key.includes("key") ? redactKey(value) : value;
-    printSuccess(`${key} = ${display}`);
-  } else {
-    printError(`Unknown config key: ${key}`);
-  }
+	setCurrentCommand("config set");
+	const config = loadConfig();
+	if (setNestedValue(config, key, value)) {
+		saveConfig(config);
+		const display = key.includes("key") ? redactKey(value) : value;
+		if (isAgentMode()) {
+			formatAgentEnvelope({
+				command: "config set",
+				data: { key, value: display },
+			});
+		} else {
+			printSuccess(`${key} = ${display}`);
+		}
+	} else {
+		printError(`Unknown config key: ${key}`);
+	}
 }

cli/node/src/commands/entities.ts

@@ -4,136 +4,165 @@
 
 import readline from "node:readline";
 import Table from "cli-table3";
-import { printError, printInfo, printSuccess, timedStatus, colors } from "../branding.js";
 import type { Backend } from "../backend/base.js";
-import { formatJson } from "../output.js";
+import {
+	colors,
+	printError,
+	printInfo,
+	printSuccess,
+	timedStatus,
+} from "../branding.js";
+import { formatAgentEnvelope, formatJson } from "../output.js";
+import { setCurrentCommand } from "../state.js";
 
 const { brand, accent, dim } = colors;
 
 const VALID_TYPES = new Set(["users", "agents", "apps", "runs"]);
 
 export async function cmdEntitiesList(
-  backend: Backend,
-  entityType: string,
-  opts: { output: string },
+	backend: Backend,
+	entityType: string,
+	opts: { output: string },
 ): Promise<void> {
-  if (!VALID_TYPES.has(entityType)) {
-    printError(`Invalid entity type: ${entityType}. Use: ${[...VALID_TYPES].join(", ")}`);
-    process.exit(1);
-  }
+	setCurrentCommand("entity list");
+	if (!VALID_TYPES.has(entityType)) {
+		printError(
+			`Invalid entity type: ${entityType}. Use: ${[...VALID_TYPES].join(", ")}`,
+		);
+		process.exit(1);
+	}
 
-  const start = performance.now();
-  let results: Record<string, unknown>[];
-  try {
-    results = await timedStatus(`Fetching ${entityType}...`, async () => {
-      return backend.entities(entityType);
-    });
-  } catch (e) {
-    printError(
-      e instanceof Error ? e.message : String(e),
-      "This feature may require the mem0 Platform.",
-    );
-    process.exit(1);
-  }
-  const elapsed = (performance.now() - start) / 1000;
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus(`Fetching ${entityType}...`, async () => {
+			return backend.entities(entityType);
+		});
+	} catch (e) {
+		printError(
+			e instanceof Error ? e.message : String(e),
+			"This feature may require the mem0 Platform.",
+		);
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
 
-  if (opts.output === "json") {
-    formatJson(results);
-    return;
-  }
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "entity list",
+			data: results,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
 
-  if (!results.length) {
-    printInfo(`No ${entityType} found.`);
-    return;
-  }
+	if (!results.length) {
+		printInfo(`No ${entityType} found.`);
+		return;
+	}
 
-  const table = new Table({
-    head: [accent("Name / ID"), accent("Created")],
-    style: { head: [], border: [] },
-  });
+	const table = new Table({
+		head: [accent("Name / ID"), accent("Created")],
+		style: { head: [], border: [] },
+	});
 
-  for (const entity of results) {
-    const name = String(entity.name ?? entity.id ?? "—");
-    const created = String(entity.created_at ?? "—").slice(0, 10);
-    table.push([name, created]);
-  }
+	for (const entity of results) {
+		const name = String(entity.name ?? entity.id ?? "—");
+		const created = String(entity.created_at ?? "—").slice(0, 10);
+		table.push([name, created]);
+	}
 
-  console.log();
-  console.log(table.toString());
-  console.log(`  ${dim(`${results.length} ${entityType} (${elapsed.toFixed(2)}s)`)}`);
-  console.log();
+	console.log();
+	console.log(table.toString());
+	console.log(
+		`  ${dim(`${results.length} ${entityType} (${elapsed.toFixed(2)}s)`)}`,
+	);
+	console.log();
 }
 
 export async function cmdEntitiesDelete(
-  backend: Backend,
-  opts: {
-    userId?: string;
-    agentId?: string;
-    appId?: string;
-    runId?: string;
-    dryRun?: boolean;
-    force: boolean;
-    output: string;
-  },
+	backend: Backend,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		dryRun?: boolean;
+		force: boolean;
+		output: string;
+	},
 ): Promise<void> {
-  if (!opts.userId && !opts.agentId && !opts.appId && !opts.runId) {
-    printError("Provide at least one of --user-id, --agent-id, --app-id, --run-id.");
-    process.exit(1);
-  }
+	setCurrentCommand("entity delete");
+	const { isAgentMode } = await import("../state.js");
+	if (isAgentMode() && !opts.force) {
+		printError("Destructive operation requires --force in agent mode.");
+		process.exit(1);
+	}
+	if (!opts.userId && !opts.agentId && !opts.appId && !opts.runId) {
+		printError(
+			"Provide at least one of --user-id, --agent-id, --app-id, --run-id.",
+		);
+		process.exit(1);
+	}
 
-  if (opts.dryRun) {
-    const scopeParts: string[] = [];
-    if (opts.userId) scopeParts.push(`user=${opts.userId}`);
-    if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
-    if (opts.appId) scopeParts.push(`app=${opts.appId}`);
-    if (opts.runId) scopeParts.push(`run=${opts.runId}`);
-    printInfo(`Would delete entity ${scopeParts.join(", ")} and all its memories.`);
-    printInfo("No changes made.");
-    return;
-  }
+	const scopeParts: string[] = [];
+	if (opts.userId) scopeParts.push(`user=${opts.userId}`);
+	if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
+	if (opts.appId) scopeParts.push(`app=${opts.appId}`);
+	if (opts.runId) scopeParts.push(`run=${opts.runId}`);
+	const scope = scopeParts.join(", ");
 
-  if (!opts.force) {
-    const scopeParts: string[] = [];
-    if (opts.userId) scopeParts.push(`user=${opts.userId}`);
-    if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
-    if (opts.appId) scopeParts.push(`app=${opts.appId}`);
-    if (opts.runId) scopeParts.push(`run=${opts.runId}`);
-    const scope = scopeParts.join(", ");
+	if (opts.dryRun) {
+		printInfo(`Would delete entity ${scope} and all its memories.`);
+		printInfo("No changes made.");
+		return;
+	}
 
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise<string>((resolve) => {
-      rl.question(
-        `\n  \u26a0  Delete entity ${scope} AND all its memories? This cannot be undone. [y/N] `,
-        resolve,
-      );
-    });
-    rl.close();
-    if (answer.toLowerCase() !== "y") {
-      printInfo("Cancelled.");
-      process.exit(0);
-    }
-  }
+	if (!opts.force) {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		const answer = await new Promise<string>((resolve) => {
+			rl.question(
+				`\n  \u26a0  Delete entity ${scope} AND all its memories? This cannot be undone. [y/N] `,
+				resolve,
+			);
+		});
+		rl.close();
+		if (answer.toLowerCase() !== "y") {
+			printInfo("Cancelled.");
+			process.exit(0);
+		}
+	}
 
-  const start = performance.now();
-  let result: Record<string, unknown>;
-  try {
-    result = await timedStatus("Deleting entity...", async () => {
-      return backend.deleteEntities({
-        userId: opts.userId,
-        agentId: opts.agentId,
-        appId: opts.appId,
-        runId: opts.runId,
-      });
-    });
-  } catch (e) {
-    printError(e instanceof Error ? e.message : String(e));
-    process.exit(1);
-  }
-  const elapsed = (performance.now() - start) / 1000;
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting entity...", async () => {
+			return backend.deleteEntities({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
 
-  if (opts.output === "json") {
-    formatJson(result);
-  } else if (opts.output !== "quiet") {
-    printSuccess(`Entity deleted with all memories (${elapsed.toFixed(2)}s)`);
-  }
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "entity delete",
+			data: { deleted: true },
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(`Entity deleted with all memories (${elapsed.toFixed(2)}s)`);
+	}
 }

cli/node/src/commands/events.ts

@@ -0,0 +1,169 @@
+/**
+ * Event commands: list and status.
+ */
+
+import boxen from "boxen";
+import Table from "cli-table3";
+import type { Backend } from "../backend/base.js";
+import { colors, printError, printInfo, timedStatus } from "../branding.js";
+import { formatAgentEnvelope, formatJson } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+
+const { brand, accent, success, error: errorColor, warning, dim } = colors;
+
+function statusStyled(status: string): string {
+	switch (status.toUpperCase()) {
+		case "SUCCEEDED":
+			return success("SUCCEEDED");
+		case "PENDING":
+			return accent("PENDING");
+		case "FAILED":
+			return errorColor("FAILED");
+		case "PROCESSING":
+			return warning("PROCESSING");
+		default:
+			return status;
+	}
+}
+
+export async function cmdEventList(
+	backend: Backend,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("event list");
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Fetching events...", async () => {
+			return backend.listEvents();
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "event list",
+			data: results,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (results.length === 0) {
+		console.log();
+		printInfo("No events found.");
+		console.log();
+		return;
+	}
+
+	const table = new Table({
+		head: [
+			accent("Event ID"),
+			accent("Type"),
+			accent("Status"),
+			accent("Latency"),
+			accent("Created"),
+		],
+		colWidths: [12, 14, 14, 10, 22],
+		wordWrap: true,
+		style: { head: [], border: [] },
+	});
+
+	for (const ev of results) {
+		const evId = String(ev.id ?? "").slice(0, 8);
+		const evType = String(ev.event_type ?? "—");
+		const status = String(ev.status ?? "—");
+		const latency = ev.latency as number | undefined;
+		const latencyStr = latency !== undefined ? `${Math.round(latency)}ms` : "—";
+		const created = String(ev.created_at ?? "—")
+			.slice(0, 19)
+			.replace("T", " ");
+		table.push([dim(evId), evType, statusStyled(status), latencyStr, created]);
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log(
+		`  ${dim(`${results.length} event${results.length !== 1 ? "s" : ""}`)}`,
+	);
+	console.log();
+}
+
+export async function cmdEventStatus(
+	backend: Backend,
+	eventId: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("event status");
+	const start = performance.now();
+	let ev: Record<string, unknown>;
+	try {
+		ev = await timedStatus("Fetching event...", async () => {
+			return backend.getEvent(eventId);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "event status",
+			data: ev,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	const status = String(ev.status ?? "—");
+	const evType = String(ev.event_type ?? "—");
+	const latency = ev.latency as number | undefined;
+	const latencyStr = latency !== undefined ? `${Math.round(latency)}ms` : "—";
+	const created = String(ev.created_at ?? "—")
+		.slice(0, 19)
+		.replace("T", " ");
+	const updated = String(ev.updated_at ?? "—")
+		.slice(0, 19)
+		.replace("T", " ");
+	const results = ev.results as Record<string, unknown>[] | undefined;
+
+	const lines: string[] = [];
+	lines.push(`  ${dim("Event ID:")}     ${eventId}`);
+	lines.push(`  ${dim("Type:")}         ${evType}`);
+	lines.push(`  ${dim("Status:")}       ${statusStyled(status)}`);
+	lines.push(`  ${dim("Latency:")}      ${latencyStr}`);
+	lines.push(`  ${dim("Created:")}      ${created}`);
+	lines.push(`  ${dim("Updated:")}      ${updated}`);
+
+	if (results && results.length > 0) {
+		lines.push("");
+		lines.push(`  ${dim(`Results (${results.length}):`)}`);
+		for (const r of results) {
+			const memId = String(r.id ?? "").slice(0, 8);
+			const data = r.data as Record<string, unknown> | undefined;
+			const memory = data?.memory ? String(data.memory) : "";
+			const evName = String(r.event ?? "");
+			const user = String(r.user_id ?? "");
+			let detail = `${evName}  ${memory}`;
+			if (user) detail += `  ${dim(`(user_id=${user})`)}`;
+			lines.push(`    ${success("·")} ${detail}  ${dim(`(${memId})`)}`);
+		}
+	}
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Event Status"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}

cli/node/src/commands/init.ts

@@ -2,181 +2,445 @@
  * mem0 init — interactive setup wizard.
  */
 
+import fs from "node:fs";
 import readline from "node:readline";
-import {
-  printBanner,
-  printError,
-  printInfo,
-  printSuccess,
-  colors,
-} from "../branding.js";
-import { type Mem0Config, createDefaultConfig, saveConfig } from "../config.js";
 import { PlatformBackend } from "../backend/platform.js";
+import {
+	colors,
+	printBanner,
+	printError,
+	printInfo,
+	printSuccess,
+} from "../branding.js";
+import {
+	CONFIG_FILE,
+	DEFAULT_BASE_URL,
+	type Mem0Config,
+	createDefaultConfig,
+	loadConfig,
+	redactKey,
+	saveConfig,
+} from "../config.js";
 
 const { brand, dim } = colors;
 
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function validateEmail(email: string): void {
+	if (!EMAIL_RE.test(email)) {
+		printError(`Invalid email address: ${JSON.stringify(email)}`);
+		process.exit(1);
+	}
+}
+
+async function emailLogin(
+	email: string,
+	code: string | undefined,
+	baseUrl: string,
+): Promise<Record<string, unknown>> {
+	const url = baseUrl.replace(/\/+$/, "");
+	let codeValue = code;
+
+	const sourceHeaders = {
+		"Content-Type": "application/json",
+		"X-Mem0-Source": "cli",
+		"X-Mem0-Client-Language": "node",
+	};
+
+	if (!codeValue) {
+		const resp = await fetch(`${url}/api/v1/auth/email_code/`, {
+			method: "POST",
+			headers: sourceHeaders,
+			body: JSON.stringify({ email }),
+			signal: AbortSignal.timeout(30_000),
+		});
+		if (resp.status === 429) {
+			printError("Too many attempts. Try again in a few minutes.");
+			process.exit(1);
+		}
+		if (!resp.ok) {
+			let detail: string;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail = (body.error ?? body.detail ?? resp.statusText) as string;
+			} catch {
+				detail = resp.statusText;
+			}
+			printError(`Failed to send code: ${detail}`);
+			process.exit(1);
+		}
+
+		printSuccess("Verification code sent! Check your email.");
+
+		if (!process.stdin.isTTY) {
+			printError(
+				"No --code provided and terminal is non-interactive.",
+				"Run: mem0 init --email <email> --code <code>",
+			);
+			process.exit(1);
+		}
+
+		console.log();
+		const entered = await promptLine(`  ${brand("Verification Code")}`);
+		if (!entered) {
+			printError("Code is required.");
+			process.exit(1);
+		}
+		codeValue = entered;
+	}
+
+	const verifyResp = await fetch(`${url}/api/v1/auth/email_code/verify/`, {
+		method: "POST",
+		headers: sourceHeaders,
+		body: JSON.stringify({ email, code: codeValue.trim() }),
+		signal: AbortSignal.timeout(30_000),
+	});
+	if (verifyResp.status === 429) {
+		printError("Too many attempts. Try again in a few minutes.");
+		process.exit(1);
+	}
+	if (!verifyResp.ok) {
+		let detail: string;
+		try {
+			const body = (await verifyResp.json()) as Record<string, unknown>;
+			detail = (body.error ?? body.detail ?? verifyResp.statusText) as string;
+		} catch {
+			detail = verifyResp.statusText;
+		}
+		printError(`Verification failed: ${detail}`);
+		process.exit(1);
+	}
+
+	return verifyResp.json() as Promise<Record<string, unknown>>;
+}
+
 function promptSecret(label: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    process.stdout.write(label);
+	return new Promise((resolve, reject) => {
+		process.stdout.write(label);
 
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(true);
-    }
-    process.stdin.resume();
-    process.stdin.setEncoding("utf-8");
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(true);
+		}
+		process.stdin.resume();
+		process.stdin.setEncoding("utf-8");
 
-    const chars: string[] = [];
+		const chars: string[] = [];
 
-    const onData = (key: string) => {
-      for (const ch of key) {
-        if (ch === "\r" || ch === "\n") {
-          cleanup();
-          process.stdout.write("\n");
-          resolve(chars.join(""));
-          return;
-        }
-        if (ch === "\x03") {
-          cleanup();
-          reject(new Error("Interrupted"));
-          return;
-        }
-        if (ch === "\x7f" || ch === "\x08") {
-          // backspace
-          if (chars.length > 0) {
-            chars.pop();
-            process.stdout.write("\b \b");
-          }
-        } else if (ch === "\x15") {
-          // Ctrl+U — clear line
-          process.stdout.write("\b \b".repeat(chars.length));
-          chars.length = 0;
-        } else if (ch >= " ") {
-          chars.push(ch);
-          process.stdout.write("*");
-        }
-      }
-    };
+		const onData = (key: string) => {
+			for (const ch of key) {
+				if (ch === "\r" || ch === "\n") {
+					cleanup();
+					process.stdout.write("\n");
+					resolve(chars.join(""));
+					return;
+				}
+				if (ch === "\x03") {
+					cleanup();
+					reject(new Error("Interrupted"));
+					return;
+				}
+				if (ch === "\x7f" || ch === "\x08") {
+					// backspace
+					if (chars.length > 0) {
+						chars.pop();
+						process.stdout.write("\b \b");
+					}
+				} else if (ch === "\x15") {
+					// Ctrl+U — clear line
+					process.stdout.write("\b \b".repeat(chars.length));
+					chars.length = 0;
+				} else if (ch >= " ") {
+					chars.push(ch);
+					process.stdout.write("*");
+				}
+			}
+		};
 
-    const cleanup = () => {
-      process.stdin.removeListener("data", onData);
-      if (process.stdin.isTTY) {
-        process.stdin.setRawMode(false);
-      }
-      process.stdin.pause();
-    };
+		const cleanup = () => {
+			process.stdin.removeListener("data", onData);
+			if (process.stdin.isTTY) {
+				process.stdin.setRawMode(false);
+			}
+			process.stdin.pause();
+		};
 
-    process.stdin.on("data", onData);
-  });
+		process.stdin.on("data", onData);
+	});
 }
 
 function promptLine(label: string, defaultValue?: string): Promise<string> {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const prompt = defaultValue ? `${label} [${defaultValue}]: ` : `${label}: `;
-  return new Promise((resolve) => {
-    rl.question(prompt, (answer) => {
-      rl.close();
-      resolve(answer.trim() || defaultValue || "");
-    });
-  });
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	const prompt = defaultValue ? `${label} [${defaultValue}]: ` : `${label}: `;
+	return new Promise((resolve) => {
+		rl.question(prompt, (answer) => {
+			rl.close();
+			resolve(answer.trim() || defaultValue || "");
+		});
+	});
 }
 
 async function setupPlatform(config: Mem0Config): Promise<void> {
-  console.log();
-  console.log(`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys")}`);
-  console.log();
+	console.log();
+	console.log(
+		`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
+	);
+	console.log();
 
-  process.stdout.write(`  ${brand("API Key")}: `);
-  const apiKey = await promptSecret("");
-  if (!apiKey) {
-    printError("API key is required.");
-    process.exit(1);
-  }
-  config.platform.apiKey = apiKey;
+	process.stdout.write(`  ${brand("API Key")}: `);
+	const apiKey = await promptSecret("");
+	if (!apiKey) {
+		printError("API key is required.");
+		process.exit(1);
+	}
+	config.platform.apiKey = apiKey;
 }
 
 async function setupDefaults(config: Mem0Config): Promise<void> {
-  console.log();
-  printInfo("Set default entity IDs (press Enter to skip).\n");
+	console.log();
+	printInfo("Set default entity IDs (press Enter to skip).\n");
 
-  const userId = await promptLine(`  ${brand("Default User ID")} ${dim("(recommended)")}`, "mem0-cli");
-  if (userId) config.defaults.userId = userId;
+	const _systemUser = process.env.USER || process.env.USERNAME || "mem0-cli";
+	const userId = await promptLine(
+		`  ${brand("Default User ID")} ${dim("(recommended)")}`,
+		_systemUser,
+	);
+	if (userId) config.defaults.userId = userId;
 }
 
 async function validatePlatform(config: Mem0Config): Promise<void> {
-  console.log();
-  printInfo("Validating connection...");
-  try {
-    const backend = new PlatformBackend(config.platform);
-    const status = await backend.status({
-      userId: config.defaults.userId || undefined,
-      agentId: config.defaults.agentId || undefined,
-    });
-    if (status.connected) {
-      printSuccess("Connected to mem0 Platform!");
-    } else {
-      printError(
-        `Could not connect: ${status.error ?? "Unknown error"}`,
-        "Check your API key and try again.",
-      );
-    }
-  } catch (e) {
-    printError(`Connection test failed: ${e instanceof Error ? e.message : e}`);
-  }
+	console.log();
+	printInfo("Validating connection...");
+	try {
+		const backend = new PlatformBackend(config.platform);
+		const status = await backend.status({
+			userId: config.defaults.userId || undefined,
+			agentId: config.defaults.agentId || undefined,
+		});
+		if (status.connected) {
+			printSuccess("Connected to mem0 Platform!");
+			// Cache user_email from ping response for telemetry distinct_id
+			try {
+				const pingData = (await backend.ping()) as Record<string, unknown>;
+				const userEmail = pingData?.user_email as string | undefined;
+				if (userEmail) {
+					config.platform.userEmail = userEmail;
+				}
+			} catch {
+				/* ignore — telemetry ID will fall back to API key hash */
+			}
+		} else {
+			printError(
+				`Could not connect: ${status.error ?? "Unknown error"}`,
+				"Visit https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node to get a new key, or run mem0 init again.",
+			);
+		}
+	} catch (e) {
+		printError(`Connection test failed: ${e instanceof Error ? e.message : e}`);
+	}
 }
 
-export async function runInit(opts: { apiKey?: string; userId?: string } = {}): Promise<void> {
-  const config = createDefaultConfig();
+export async function runInit(
+	opts: {
+		apiKey?: string;
+		userId?: string;
+		email?: string;
+		code?: string;
+		force?: boolean;
+	} = {},
+): Promise<void> {
+	const config = createDefaultConfig();
+	const savedConfig = loadConfig();
+	const baseUrl =
+		process.env.MEM0_BASE_URL ||
+		savedConfig.platform.baseUrl ||
+		DEFAULT_BASE_URL;
 
-  // Non-interactive: both flags provided
-  if (opts.apiKey && opts.userId) {
-    config.platform.apiKey = opts.apiKey;
-    config.defaults.userId = opts.userId;
-    await validatePlatform(config);
-    saveConfig(config);
-    printSuccess("Configuration saved to ~/.mem0/config.json");
-    return;
-  }
+	// Guards
+	if (opts.code && !opts.email) {
+		printError("--code requires --email.");
+		process.exit(1);
+	}
+	if (opts.email && opts.apiKey) {
+		printError("Cannot use both --api-key and --email.");
+		process.exit(1);
+	}
 
-  // Non-TTY without full flags: error with usage hint
-  if (!process.stdin.isTTY && (!opts.apiKey || !opts.userId)) {
-    printError(
-      "Non-interactive terminal detected and missing required flags.",
-      "Usage: mem0 init --api-key <key> --user-id <id>",
-    );
-    process.exit(1);
-  }
+	// Warn if an existing config with an API key would be overwritten
+	if (
+		!opts.force &&
+		fs.existsSync(CONFIG_FILE) &&
+		savedConfig.platform.apiKey
+	) {
+		console.log(
+			`\n  ${brand("Existing configuration found")} ${dim(`(API key: ${redactKey(savedConfig.platform.apiKey)})`)}`,
+		);
+		if (process.stdin.isTTY) {
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+			const answer = await new Promise<string>((resolve) => {
+				rl.question(
+					"  Overwrite existing config? This cannot be undone. [y/N] ",
+					resolve,
+				);
+			});
+			rl.close();
+			if (answer.toLowerCase() !== "y") {
+				printInfo("Cancelled. Use --force to skip this check.");
+				process.exit(0);
+			}
+		} else {
+			printError(
+				"Existing config would be overwritten.",
+				"Use --force to overwrite.",
+			);
+			process.exit(1);
+		}
+	}
 
-  printBanner();
-  console.log();
-  printInfo("Welcome! Let's set up your mem0 CLI.\n");
+	// ── Email login flow ──────────────────────────────────────────────────────
+	if (opts.email) {
+		const email = opts.email.trim().toLowerCase();
+		validateEmail(email);
 
-  // Use provided API key or prompt
-  if (opts.apiKey) {
-    config.platform.apiKey = opts.apiKey;
-  } else {
-    await setupPlatform(config);
-  }
+		printBanner();
+		console.log();
+		printInfo(`Logging in as ${email}...\n`);
 
-  // Use provided user ID or prompt
-  if (opts.userId) {
-    config.defaults.userId = opts.userId;
-  } else {
-    await setupDefaults(config);
-  }
+		const result = await emailLogin(email, opts.code, baseUrl);
 
-  await validatePlatform(config);
+		const apiKeyVal = result.api_key as string | undefined;
+		if (!apiKeyVal) {
+			printError(
+				"Auth succeeded but no API key was returned. Contact support.",
+			);
+			process.exit(1);
+		}
 
-  saveConfig(config);
-  console.log();
-  printSuccess("Configuration saved to ~/.mem0/config.json");
-  console.log();
-  console.log(`  ${dim("Get started:")}`);
-  if (config.defaults.userId) {
-    console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
-    console.log(`  ${dim('  mem0 search "preferences"')}`);
-  } else {
-    console.log(`  ${dim('  mem0 add "I prefer dark mode" --user-id alice')}`);
-    console.log(`  ${dim('  mem0 search "preferences" --user-id alice')}`);
-  }
-  console.log();
+		config.platform.apiKey = apiKeyVal;
+		config.platform.baseUrl = baseUrl;
+		config.platform.userEmail = email;
+		config.defaults.userId =
+			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+
+		saveConfig(config);
+		console.log();
+		printSuccess("Authenticated! Configuration saved to ~/.mem0/config.json");
+		console.log();
+		console.log(`  ${dim("Get started:")}`);
+		console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+		console.log(`  ${dim('  mem0 search "preferences"')}`);
+		console.log();
+		return;
+	}
+
+	// ── API key flow ──────────────────────────────────────────────────────────
+
+	// Non-TTY: resolve defaults so partial flags work in pipelines / CI
+	if (!process.stdin.isTTY) {
+		if (!opts.apiKey) {
+			printError(
+				"Non-interactive terminal detected and --api-key is required.",
+				"Usage: mem0 init --api-key <key> [--user-id <id>]",
+			);
+			process.exit(1);
+		}
+		opts.userId =
+			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+	}
+
+	// Non-interactive: both flags provided
+	if (opts.apiKey && opts.userId) {
+		config.platform.apiKey = opts.apiKey;
+		config.defaults.userId = opts.userId;
+		await validatePlatform(config);
+		saveConfig(config);
+		printSuccess("Configuration saved to ~/.mem0/config.json");
+		return;
+	}
+
+	printBanner();
+	console.log();
+	printInfo("Welcome! Let's set up your mem0 CLI.\n");
+
+	// Use provided API key or prompt
+	if (opts.apiKey) {
+		config.platform.apiKey = opts.apiKey;
+	} else {
+		console.log(`  ${brand("How would you like to authenticate?")}`);
+		console.log(`  ${dim("1.")} Login with email ${dim("(recommended)")}`);
+		console.log(`  ${dim("2.")} Enter API key manually`);
+		console.log();
+
+		const choice = await promptLine(`  ${brand("Choose")} [1/2]`, "1");
+
+		if (choice === "1") {
+			console.log();
+			const emailAddr = await promptLine(`  ${brand("Email")}`);
+			if (!emailAddr) {
+				printError("Email is required.");
+				process.exit(1);
+			}
+
+			const email = emailAddr.trim().toLowerCase();
+			validateEmail(email);
+			printInfo(`Logging in as ${email}...\n`);
+
+			const result = await emailLogin(email, undefined, baseUrl);
+
+			const apiKeyVal = result.api_key as string | undefined;
+			if (!apiKeyVal) {
+				printError(
+					"Auth succeeded but no API key was returned. Contact support.",
+				);
+				process.exit(1);
+			}
+
+			config.platform.apiKey = apiKeyVal;
+			config.platform.baseUrl = baseUrl;
+			config.platform.userEmail = email;
+			config.defaults.userId =
+				opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+
+			saveConfig(config);
+			console.log();
+			printSuccess("Authenticated! Configuration saved to ~/.mem0/config.json");
+			console.log();
+			console.log(`  ${dim("Get started:")}`);
+			console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+			console.log(`  ${dim('  mem0 search "preferences"')}`);
+			console.log();
+			return;
+		}
+
+		// choice === "2": fall through to API key prompt
+		await setupPlatform(config);
+	}
+
+	// Use provided user ID or prompt
+	if (opts.userId) {
+		config.defaults.userId = opts.userId;
+	} else {
+		await setupDefaults(config);
+	}
+
+	await validatePlatform(config);
+
+	saveConfig(config);
+	console.log();
+	printSuccess("Configuration saved to ~/.mem0/config.json");
+	console.log();
+	console.log(`  ${dim("Get started:")}`);
+	if (config.defaults.userId) {
+		console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+		console.log(`  ${dim('  mem0 search "preferences"')}`);
+	} else {
+		console.log(`  ${dim('  mem0 add "I prefer dark mode" --user-id alice')}`);
+		console.log(`  ${dim('  mem0 search "preferences" --user-id alice')}`);
+	}
+	console.log();
 }

cli/node/src/commands/utils.ts

@@ -3,137 +3,153 @@
  */
 
 import fs from "node:fs";
-import { createRequire } from "node:module";
-import { printError, printSuccess, timedStatus, colors } from "../branding.js";
-import type { Backend } from "../backend/base.js";
-import { formatJsonEnvelope } from "../output.js";
 import boxen from "boxen";
+import type { Backend } from "../backend/base.js";
+import { colors, printError, printSuccess, timedStatus } from "../branding.js";
+import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+import { CLI_VERSION } from "../version.js";
 
 const { brand, dim, success, error: errorColor } = colors;
 
-const _require = createRequire(import.meta.url);
-const VERSION: string = _require("../../package.json").version;
-
 export async function cmdStatus(
-  backend: Backend,
-  opts: { userId?: string; agentId?: string; output?: string } = {},
+	backend: Backend,
+	opts: { userId?: string; agentId?: string; output?: string } = {},
 ): Promise<void> {
-  const start = performance.now();
-  let result: Record<string, unknown>;
-  try {
-    result = await timedStatus("Checking connection...", async () => {
-      return backend.status({ userId: opts.userId, agentId: opts.agentId });
-    });
-  } catch (e) {
-    result = { connected: false, error: e instanceof Error ? e.message : String(e) };
-  }
-  const elapsed = (performance.now() - start) / 1000;
+	setCurrentCommand("status");
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Checking connection...", async () => {
+			return backend.status({ userId: opts.userId, agentId: opts.agentId });
+		});
+	} catch (e) {
+		result = {
+			connected: false,
+			error: e instanceof Error ? e.message : String(e),
+		};
+	}
+	const elapsed = (performance.now() - start) / 1000;
 
-  if (opts.output === "json") {
-    formatJsonEnvelope({
-      command: "status",
-      data: {
-        connected: result.connected,
-        backend: result.backend ?? null,
-        base_url: result.base_url ?? null,
-        latency_ms: Math.round(elapsed * 1000),
-      },
-      durationMs: Math.round(elapsed * 1000),
-    });
-    return;
-  }
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "status",
+			data: {
+				connected: result.connected,
+				backend: result.backend ?? null,
+				base_url: result.base_url ?? null,
+			},
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
 
-  const lines: string[] = [];
-  if (result.connected) {
-    lines.push(`  ${success("\u25cf")} Connected`);
-  } else {
-    lines.push(`  ${errorColor("\u25cf")} Disconnected`);
-  }
+	const lines: string[] = [];
+	if (result.connected) {
+		lines.push(`  ${success("\u25cf")} Connected`);
+	} else {
+		lines.push(`  ${errorColor("\u25cf")} Disconnected`);
+	}
 
-  lines.push(`  ${dim("Backend:")}  ${result.backend ?? "?"}`);
-  if (result.base_url) {
-    lines.push(`  ${dim("API URL:")}  ${result.base_url}`);
-  }
-  if (result.error) {
-    lines.push(`  ${errorColor("Error:")}    ${result.error}`);
-  }
-  lines.push(`  ${dim("Latency:")}  ${elapsed.toFixed(2)}s`);
+	lines.push(`  ${dim("Backend:")}  ${result.backend ?? "?"}`);
+	if (result.base_url) {
+		lines.push(`  ${dim("API URL:")}  ${result.base_url}`);
+	}
+	if (result.error) {
+		lines.push(`  ${errorColor("Error:")}    ${result.error}`);
+		if (String(result.error).includes("Authentication failed")) {
+			lines.push("");
+			lines.push(
+				`  ${dim("Run")} ${brand("mem0 init")} ${dim("to reconfigure your API key")}`,
+			);
+			lines.push(
+				`  ${dim("Get a key at")} ${brand("https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
+			);
+		}
+	}
+	lines.push(`  ${dim("Latency:")}  ${elapsed.toFixed(2)}s`);
 
-  const content = lines.join("\n");
-  console.log();
-  console.log(
-    boxen(content, {
-      title: brand("Connection Status"),
-      titleAlignment: "left",
-      borderColor: "magenta",
-      padding: 1,
-    }),
-  );
-  console.log();
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Connection Status"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
 }
 
 export function cmdVersion(): void {
-  console.log(`  ${brand("◆ Mem0")} CLI v${VERSION}`);
+	console.log(`  ${brand("◆ Mem0")} CLI v${CLI_VERSION}`);
 }
 
 export async function cmdImport(
-  backend: Backend,
-  filePath: string,
-  opts: { userId?: string; agentId?: string; output?: string },
+	backend: Backend,
+	filePath: string,
+	opts: { userId?: string; agentId?: string; output?: string },
 ): Promise<void> {
-  let data: Record<string, unknown>[];
-  try {
-    const raw = fs.readFileSync(filePath, "utf-8");
-    const parsed = JSON.parse(raw);
-    data = Array.isArray(parsed) ? parsed : [parsed];
-  } catch (e) {
-    printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
-    process.exit(1);
-  }
+	setCurrentCommand("import");
+	let data: Record<string, unknown>[];
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		data = Array.isArray(parsed) ? parsed : [parsed];
+	} catch (e) {
+		printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
+		process.exit(1);
+	}
 
-  let added = 0;
-  let failed = 0;
-  const start = performance.now();
+	let added = 0;
+	let failed = 0;
+	const start = performance.now();
 
-  for (let i = 0; i < data.length; i++) {
-    const item = data[i];
-    const content = (item.memory ?? item.text ?? item.content ?? "") as string;
-    if (!content) {
-      failed++;
-      continue;
-    }
+	for (let i = 0; i < data.length; i++) {
+		const item = data[i];
+		const content = (item.memory ?? item.text ?? item.content ?? "") as string;
+		if (!content) {
+			failed++;
+			continue;
+		}
 
-    try {
-      await backend.add(content, undefined, {
-        userId: opts.userId ?? (item.user_id as string | undefined),
-        agentId: opts.agentId ?? (item.agent_id as string | undefined),
-        metadata: item.metadata as Record<string, unknown> | undefined,
-      });
-      added++;
-    } catch {
-      failed++;
-    }
+		try {
+			await backend.add(content, undefined, {
+				userId: opts.userId ?? (item.user_id as string | undefined),
+				agentId: opts.agentId ?? (item.agent_id as string | undefined),
+				metadata: item.metadata as Record<string, unknown> | undefined,
+			});
+			added++;
+		} catch {
+			failed++;
+		}
 
-    // Simple progress indicator
-    if ((i + 1) % 10 === 0 || i === data.length - 1) {
-      process.stdout.write(`\r  ${dim(`Importing memories... ${i + 1}/${data.length}`)}`);
-    }
-  }
+		// Simple progress indicator
+		if ((i + 1) % 10 === 0 || i === data.length - 1) {
+			process.stdout.write(
+				`\r  ${dim(`Importing memories... ${i + 1}/${data.length}`)}`,
+			);
+		}
+	}
 
-  const elapsed = (performance.now() - start) / 1000;
-  console.log(); // Clear progress line
+	const elapsed = (performance.now() - start) / 1000;
+	console.log(); // Clear progress line
 
-  if (opts.output === "json") {
-    formatJsonEnvelope({
-      command: "import",
-      data: { added, failed, duration_s: parseFloat(elapsed.toFixed(2)) },
-      durationMs: Math.round(elapsed * 1000),
-    });
-    return;
-  }
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "import",
+			data: {
+				added,
+				failed,
+			},
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
 
-  printSuccess(`Imported ${added} memories (${elapsed.toFixed(2)}s)`);
-  if (failed > 0) {
-    printError(`${failed} memories failed to import.`);
-  }
+	printSuccess(`Imported ${added} memories (${elapsed.toFixed(2)}s)`);
+	if (failed > 0) {
+		printError(`${failed} memories failed to import.`);
+	}
 }

cli/node/src/config.ts

@@ -18,142 +18,165 @@ export const DEFAULT_BASE_URL = "https://api.mem0.ai";
 export const CONFIG_VERSION = 1;
 
 export interface PlatformConfig {
-  apiKey: string;
-  baseUrl: string;
+	apiKey: string;
+	baseUrl: string;
+	userEmail: string;
 }
 
 export interface DefaultsConfig {
-  userId: string;
-  agentId: string;
-  appId: string;
-  runId: string;
-  enableGraph: boolean;
+	userId: string;
+	agentId: string;
+	appId: string;
+	runId: string;
+}
+
+export interface TelemetryConfig {
+	anonymousId: string;
 }
 
 export interface Mem0Config {
-  version: number;
-  defaults: DefaultsConfig;
-  platform: PlatformConfig;
+	version: number;
+	defaults: DefaultsConfig;
+	platform: PlatformConfig;
+	telemetry: TelemetryConfig;
 }
 
 export function createDefaultConfig(): Mem0Config {
-  return {
-    version: CONFIG_VERSION,
-    defaults: {
-      userId: "",
-      agentId: "",
-      appId: "",
-      runId: "",
-      enableGraph: false,
-    },
-    platform: {
-      apiKey: "",
-      baseUrl: DEFAULT_BASE_URL,
-    },
-  };
+	return {
+		version: CONFIG_VERSION,
+		defaults: {
+			userId: "",
+			agentId: "",
+			appId: "",
+			runId: "",
+		},
+		platform: {
+			apiKey: "",
+			baseUrl: DEFAULT_BASE_URL,
+			userEmail: "",
+		},
+		telemetry: {
+			anonymousId: "",
+		},
+	};
 }
 
 export function ensureConfigDir(): string {
-  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
-  return CONFIG_DIR;
+	fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+	return CONFIG_DIR;
 }
 
 export function loadConfig(): Mem0Config {
-  const config = createDefaultConfig();
+	const config = createDefaultConfig();
 
-  if (fs.existsSync(CONFIG_FILE)) {
-    const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
-    const data = JSON.parse(raw);
+	if (fs.existsSync(CONFIG_FILE)) {
+		const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+		const data = JSON.parse(raw);
 
-    config.version = data.version ?? CONFIG_VERSION;
+		config.version = data.version ?? CONFIG_VERSION;
 
-    const plat = data.platform ?? {};
-    config.platform.apiKey = plat.api_key ?? "";
-    config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
+		const plat = data.platform ?? {};
+		config.platform.apiKey = plat.api_key ?? "";
+		config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
+		config.platform.userEmail = plat.user_email ?? "";
 
-    const defaults = data.defaults ?? {};
-    config.defaults.userId = defaults.user_id ?? "";
-    config.defaults.agentId = defaults.agent_id ?? "";
-    config.defaults.appId = defaults.app_id ?? "";
-    config.defaults.runId = defaults.run_id ?? "";
-    config.defaults.enableGraph = defaults.enable_graph ?? false;
-  }
+		const defaults = data.defaults ?? {};
+		config.defaults.userId = defaults.user_id ?? "";
+		config.defaults.agentId = defaults.agent_id ?? "";
+		config.defaults.appId = defaults.app_id ?? "";
+		config.defaults.runId = defaults.run_id ?? "";
+		const telemetry = data.telemetry ?? {};
+		config.telemetry.anonymousId = telemetry.anonymous_id ?? "";
+	}
 
-  // Environment variable overrides
-  if (process.env.MEM0_API_KEY) config.platform.apiKey = process.env.MEM0_API_KEY;
-  if (process.env.MEM0_BASE_URL) config.platform.baseUrl = process.env.MEM0_BASE_URL;
-  if (process.env.MEM0_USER_ID) config.defaults.userId = process.env.MEM0_USER_ID;
-  if (process.env.MEM0_AGENT_ID) config.defaults.agentId = process.env.MEM0_AGENT_ID;
-  if (process.env.MEM0_APP_ID) config.defaults.appId = process.env.MEM0_APP_ID;
-  if (process.env.MEM0_RUN_ID) config.defaults.runId = process.env.MEM0_RUN_ID;
-  if (process.env.MEM0_ENABLE_GRAPH) {
-    config.defaults.enableGraph = ["true", "1", "yes"].includes(
-      process.env.MEM0_ENABLE_GRAPH.toLowerCase(),
-    );
-  }
-
-  return config;
+	// Environment variable overrides
+	if (process.env.MEM0_API_KEY)
+		config.platform.apiKey = process.env.MEM0_API_KEY;
+	if (process.env.MEM0_BASE_URL)
+		config.platform.baseUrl = process.env.MEM0_BASE_URL;
+	if (process.env.MEM0_USER_ID)
+		config.defaults.userId = process.env.MEM0_USER_ID;
+	if (process.env.MEM0_AGENT_ID)
+		config.defaults.agentId = process.env.MEM0_AGENT_ID;
+	if (process.env.MEM0_APP_ID) config.defaults.appId = process.env.MEM0_APP_ID;
+	if (process.env.MEM0_RUN_ID) config.defaults.runId = process.env.MEM0_RUN_ID;
+	return config;
 }
 
 export function saveConfig(config: Mem0Config): void {
-  ensureConfigDir();
+	ensureConfigDir();
 
-  const data = {
-    version: config.version,
-    defaults: {
-      user_id: config.defaults.userId,
-      agent_id: config.defaults.agentId,
-      app_id: config.defaults.appId,
-      run_id: config.defaults.runId,
-      enable_graph: config.defaults.enableGraph,
-    },
-    platform: {
-      api_key: config.platform.apiKey,
-      base_url: config.platform.baseUrl,
-    },
-  };
+	const data = {
+		version: config.version,
+		defaults: {
+			user_id: config.defaults.userId,
+			agent_id: config.defaults.agentId,
+			app_id: config.defaults.appId,
+			run_id: config.defaults.runId,
+		},
+		platform: {
+			api_key: config.platform.apiKey,
+			base_url: config.platform.baseUrl,
+			user_email: config.platform.userEmail,
+		},
+		telemetry: {
+			anonymous_id: config.telemetry.anonymousId,
+		},
+	};
 
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
-  fs.chmodSync(CONFIG_FILE, 0o600);
+	fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
+	fs.chmodSync(CONFIG_FILE, 0o600);
 }
 
 export function redactKey(key: string): string {
-  if (!key) return "(not set)";
-  if (key.length <= 8) return key.slice(0, 2) + "***";
-  return key.slice(0, 4) + "..." + key.slice(-4);
+	if (!key) return "(not set)";
+	if (key.length <= 8) return `${key.slice(0, 2)}***`;
+	return `${key.slice(0, 4)}...${key.slice(-4)}`;
 }
 
 /** Key map from dotted config path to the config object fields. */
 const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
-  "platform.api_key": ["platform", "apiKey"],
-  "platform.base_url": ["platform", "baseUrl"],
-  "defaults.user_id": ["defaults", "userId"],
-  "defaults.agent_id": ["defaults", "agentId"],
-  "defaults.app_id": ["defaults", "appId"],
-  "defaults.run_id": ["defaults", "runId"],
-  "defaults.enable_graph": ["defaults", "enableGraph"],
+	"platform.api_key": ["platform", "apiKey"],
+	"platform.base_url": ["platform", "baseUrl"],
+	"platform.user_email": ["platform", "userEmail"],
+	"defaults.user_id": ["defaults", "userId"],
+	"defaults.agent_id": ["defaults", "agentId"],
+	"defaults.app_id": ["defaults", "appId"],
+	"defaults.run_id": ["defaults", "runId"],
+	// Short-form aliases
+	api_key: ["platform", "apiKey"],
+	base_url: ["platform", "baseUrl"],
+	user_email: ["platform", "userEmail"],
+	user_id: ["defaults", "userId"],
+	agent_id: ["defaults", "agentId"],
+	app_id: ["defaults", "appId"],
+	run_id: ["defaults", "runId"],
 };
 
 export function getNestedValue(config: Mem0Config, dottedKey: string): unknown {
-  const mapping = KEY_MAP[dottedKey];
-  if (!mapping) return undefined;
-  const [section, field] = mapping;
-  return (config[section] as unknown as Record<string, unknown>)[field];
+	const mapping = KEY_MAP[dottedKey];
+	if (!mapping) return undefined;
+	const [section, field] = mapping;
+	return (config[section] as unknown as Record<string, unknown>)[field];
 }
 
-export function setNestedValue(config: Mem0Config, dottedKey: string, value: string): boolean {
-  const mapping = KEY_MAP[dottedKey];
-  if (!mapping) return false;
-  const [section, field] = mapping;
-  const obj = config[section] as unknown as Record<string, unknown>;
+export function setNestedValue(
+	config: Mem0Config,
+	dottedKey: string,
+	value: string,
+): boolean {
+	const mapping = KEY_MAP[dottedKey];
+	if (!mapping) return false;
+	const [section, field] = mapping;
+	const obj = config[section] as unknown as Record<string, unknown>;
 
-  const current = obj[field];
-  if (typeof current === "boolean") {
-    obj[field] = ["true", "1", "yes"].includes(value.toLowerCase());
-  } else if (typeof current === "number") {
-    obj[field] = parseInt(value, 10);
-  } else {
-    obj[field] = value;
-  }
-  return true;
+	const current = obj[field];
+	if (typeof current === "boolean") {
+		obj[field] = ["true", "1", "yes"].includes(value.toLowerCase());
+	} else if (typeof current === "number") {
+		obj[field] = Number.parseInt(value, 10);
+	} else {
+		obj[field] = value;
+	}
+	return true;
 }

cli/node/src/globals.d.ts

@@ -0,0 +1,2 @@
+/** Injected by tsup at build time from package.json version field. Undefined in dev/test. */
+declare const __CLI_VERSION__: string | undefined;

cli/node/src/help.ts

@@ -4,40 +4,40 @@
  */
 
 import chalk from "chalk";
-import type { Command, Help, Option, Argument } from "commander";
+import type { Argument, Command, Help, Option } from "commander";
 // Colors imported from chalk directly to match Typer/Rich defaults
 
 // ── Colors (matching Typer/Rich defaults) ────────────────────────────────
 
-const cyanBold = chalk.cyan.bold;       // option flags, command names
-const greenBold = chalk.green.bold;     // switch flags (boolean --force etc)
-const yellowBold = chalk.yellow.bold;   // metavar <value>
-const yellow = chalk.yellow;            // "Usage:" label
-const bold = chalk.bold;                // command name in usage
-const dim = chalk.dim;                  // defaults, descriptions
-const dimBorder = chalk.dim;            // panel borders
+const cyanBold = chalk.cyan.bold; // option flags, command names
+const greenBold = chalk.green.bold; // switch flags (boolean --force etc)
+const yellowBold = chalk.yellow.bold; // metavar <value>
+const yellow = chalk.yellow; // "Usage:" label
+const bold = chalk.bold; // command name in usage
+const dim = chalk.dim; // defaults, descriptions
+const dimBorder = chalk.dim; // panel borders
 
 // ── Strip ANSI ───────────────────────────────────────────────────────────
 
-// eslint-disable-next-line no-control-regex
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence is intentional
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 
 function stripAnsi(str: string): number {
-  return str.replace(ANSI_RE, "").length;
+	return str.replace(ANSI_RE, "").length;
 }
 
 // ── Command display order (matches Python CLI) ──────────────────────────
 
 /** Commands grouped into panels, matching Python CLI's rich_help_panel. */
 const COMMAND_GROUPS: { panel: string; commands: string[] }[] = [
-  {
-    panel: "Memory",
-    commands: ["add", "search", "get", "list", "update", "delete"],
-  },
-  {
-    panel: "Management",
-    commands: ["init", "status", "import", "help", "entity", "config"],
-  },
+	{
+		panel: "Memory",
+		commands: ["add", "search", "get", "list", "update", "delete"],
+	},
+	{
+		panel: "Management",
+		commands: ["init", "status", "import", "help", "entity", "event", "config"],
+	},
 ];
 
 /** Flat order derived from COMMAND_GROUPS. */
@@ -46,88 +46,88 @@ const COMMAND_ORDER: string[] = COMMAND_GROUPS.flatMap((g) => g.commands);
 // ── Option-to-panel mapping (derived from Python's rich_help_panel) ─────
 
 const OPTION_PANELS: Record<string, Record<string, string>> = {
-  add: {
-    "--user-id": "Scope",
-    "--agent-id": "Scope",
-    "--app-id": "Scope",
-    "--run-id": "Scope",
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  search: {
-    "--user-id": "Scope",
-    "--agent-id": "Scope",
-    "--app-id": "Scope",
-    "--run-id": "Scope",
-    "--top-k": "Search",
-    "--threshold": "Search",
-    "--rerank": "Search",
-    "--keyword": "Search",
-    "--filter": "Search",
-    "--fields": "Search",
-    "--graph": "Search",
-    "--no-graph": "Search",
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  get: {
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  list: {
-    "--user-id": "Scope",
-    "--agent-id": "Scope",
-    "--app-id": "Scope",
-    "--run-id": "Scope",
-    "--page": "Pagination",
-    "--page-size": "Pagination",
-    "--category": "Filters",
-    "--after": "Filters",
-    "--before": "Filters",
-    "--graph": "Filters",
-    "--no-graph": "Filters",
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  update: {
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  delete: {
-    "--user-id": "Scope",
-    "--agent-id": "Scope",
-    "--app-id": "Scope",
-    "--run-id": "Scope",
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  status: {
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
-  import: {
-    "--user-id": "Scope",
-    "--agent-id": "Scope",
-    "--output": "Output",
-    "--api-key": "Connection",
-    "--base-url": "Connection",
-  },
+	add: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	search: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--top-k": "Search",
+		"--threshold": "Search",
+		"--rerank": "Search",
+		"--keyword": "Search",
+		"--filter": "Search",
+		"--fields": "Search",
+		"--graph": "Search",
+		"--no-graph": "Search",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	get: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	list: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--page": "Pagination",
+		"--page-size": "Pagination",
+		"--category": "Filters",
+		"--after": "Filters",
+		"--before": "Filters",
+		"--graph": "Filters",
+		"--no-graph": "Filters",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	update: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	delete: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	status: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	import: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
 };
 
 const PANEL_ORDER: string[] = [
-  "Scope",
-  "Search",
-  "Pagination",
-  "Filters",
-  "Output",
-  "Connection",
+	"Scope",
+	"Search",
+	"Pagination",
+	"Filters",
+	"Output",
+	"Connection",
 ];
 
 // ── Panel rendering ─────────────────────────────────────────────────────
@@ -141,234 +141,238 @@ const PANEL_ORDER: string[] = [
  * ╰────────────────────────────────╯
  * ```
  */
-function renderPanel(
-  title: string,
-  rows: string[],
-  width: number,
-): string {
-  if (rows.length === 0) return "";
+function renderPanel(title: string, rows: string[], width: number): string {
+	if (rows.length === 0) return "";
 
-  // Inner width is total width minus the two border chars
-  const inner = width - 2;
+	// Inner width is total width minus the two border chars
+	const inner = width - 2;
 
-  // Top border: ╭─ Title ─...─╮
-  const titleStr = ` ${title} `;
-  const fillLen = Math.max(0, inner - 1 - titleStr.length);
-  const topLine =
-    dimBorder("╭─") +
-    dimBorder(titleStr) +
-    dimBorder("─".repeat(fillLen)) +
-    dimBorder("╮");
+	// Top border: ╭─ Title ─...─╮
+	const titleStr = ` ${title} `;
+	const fillLen = Math.max(0, inner - 1 - titleStr.length);
+	const topLine =
+		dimBorder("╭─") +
+		dimBorder(titleStr) +
+		dimBorder("─".repeat(fillLen)) +
+		dimBorder("╮");
 
-  // Bottom border: ╰─...─╯
-  const bottomLine = dimBorder("╰") + dimBorder("─".repeat(inner)) + dimBorder("╯");
+	// Bottom border: ╰─...─╯
+	const bottomLine =
+		dimBorder("╰") + dimBorder("─".repeat(inner)) + dimBorder("╯");
 
-  // Content rows
-  const contentLines = rows.map((row) => {
-    const visLen = stripAnsi(row);
-    const pad = Math.max(0, inner - 1 - visLen);
-    return dimBorder("│") + " " + row + " ".repeat(pad) + dimBorder("│");
-  });
+	// Content rows
+	const contentLines = rows.map((row) => {
+		const visLen = stripAnsi(row);
+		const pad = Math.max(0, inner - 1 - visLen);
+		return `${dimBorder("│")} ${row}${" ".repeat(pad)}${dimBorder("│")}`;
+	});
 
-  return [topLine, ...contentLines, bottomLine].join("\n");
+	return [topLine, ...contentLines, bottomLine].join("\n");
 }
 
 // ── Format an option term (short + long) ────────────────────────────────
 
 function formatOptionTerm(opt: Option): string {
-  const parts: string[] = [];
-  if (opt.short) parts.push(opt.short);
-  if (opt.long) parts.push(opt.long);
-  let term = parts.join(", ");
+	const parts: string[] = [];
+	if (opt.short) parts.push(opt.short);
+	if (opt.long) parts.push(opt.long);
+	let term = parts.join(", ");
 
-  // Append value placeholder for non-boolean options
-  if (opt.flags) {
-    const match = opt.flags.match(/<[^>]+>|\[[^\]]+\]/);
-    if (match) {
-      term += " " + match[0];
-    }
-  }
-  return term;
+	// Append value placeholder for non-boolean options
+	if (opt.flags) {
+		const match = opt.flags.match(/<[^>]+>|\[[^\]]+\]/);
+		if (match) {
+			term += ` ${match[0]}`;
+		}
+	}
+	return term;
 }
 
 // ── Get the long flag name for panel lookup ─────────────────────────────
 
 function getLongFlag(opt: Option): string {
-  if (opt.long) return opt.long;
-  return opt.short || "";
+	if (opt.long) return opt.long;
+	return opt.short || "";
 }
 
 // ── Format a default value ──────────────────────────────────────────────
 
 function formatDefault(opt: Option): string {
-  if (opt.defaultValue !== undefined && opt.defaultValue !== false) {
-    return dim(` [default: ${opt.defaultValue}]`);
-  }
-  return "";
+	if (opt.defaultValue !== undefined && opt.defaultValue !== false) {
+		return dim(` [default: ${opt.defaultValue}]`);
+	}
+	return "";
 }
 
 // ── The main help formatter ─────────────────────────────────────────────
 
 export function richFormatHelp(cmd: Command, helper: Help): string {
-  const width = process.stdout.columns || 80;
-  const lines: string[] = [];
+	const width = process.stdout.columns || 80;
+	const lines: string[] = [];
 
-  const isRoot = !cmd.parent;
+	const isRoot = !cmd.parent;
 
-  // ── Usage line ──
-  const usage = helper.commandUsage(cmd);
-  lines.push("");
-  if (isRoot) {
-    // Root: "Usage: mem0 <command> [options]" — <command> yellow, [options] bold
-    lines.push(` ${yellow("Usage:")} ${bold(cmd.name())} ${yellow("<command>")} ${bold("[options]")}`);
-  } else {
-    // Subcommands: split into command path (bold) and args (yellow)
-    const usageParts = usage.split(" ");
-    const cmdPath: string[] = [];
-    const argParts: string[] = [];
-    let pastCmd = false;
-    for (const part of usageParts) {
-      if (!pastCmd && !part.startsWith("[") && !part.startsWith("<")) {
-        cmdPath.push(part);
-      } else {
-        pastCmd = true;
-        argParts.push(part);
-      }
-    }
-    lines.push(` ${yellow("Usage:")} ${bold(cmdPath.join(" "))} ${yellow(argParts.join(" "))}`);
-  }
-  lines.push("");
+	// ── Usage line ──
+	const usage = helper.commandUsage(cmd);
+	lines.push("");
+	if (isRoot) {
+		// Root: "Usage: mem0 <command> [options]" — <command> yellow, [options] bold
+		lines.push(
+			` ${yellow("Usage:")} ${bold(cmd.name())} ${yellow("<command>")} ${bold("[options]")}`,
+		);
+	} else {
+		// Subcommands: split into command path (bold) and args (yellow)
+		const usageParts = usage.split(" ");
+		const cmdPath: string[] = [];
+		const argParts: string[] = [];
+		let pastCmd = false;
+		for (const part of usageParts) {
+			if (!pastCmd && !part.startsWith("[") && !part.startsWith("<")) {
+				cmdPath.push(part);
+			} else {
+				pastCmd = true;
+				argParts.push(part);
+			}
+		}
+		lines.push(
+			` ${yellow("Usage:")} ${bold(cmdPath.join(" "))} ${yellow(argParts.join(" "))}`,
+		);
+	}
+	lines.push("");
 
-  // ── Description ──
-  const desc = helper.commandDescription(cmd);
-  if (desc) {
-    // Split multi-line descriptions (e.g., title + tagline)
-    const descLines = desc.split("\n");
-    for (let i = 0; i < descLines.length; i++) {
-      const dLine = descLines[i];
-      // First line is the title, subsequent non-empty lines are tagline (dimmed)
-      if (i === 0 || dLine.trim() === "") {
-        lines.push(` ${dLine}`);
-      } else {
-        lines.push(` ${dim(dLine)}`);
-      }
-    }
-    lines.push("");
-  }
+	// ── Description ──
+	const desc = helper.commandDescription(cmd);
+	if (desc) {
+		// Split multi-line descriptions (e.g., title + tagline)
+		const descLines = desc.split("\n");
+		for (let i = 0; i < descLines.length; i++) {
+			const dLine = descLines[i];
+			// First line is the title, subsequent non-empty lines are tagline (dimmed)
+			if (i === 0 || dLine.trim() === "") {
+				lines.push(` ${dLine}`);
+			} else {
+				lines.push(` ${dim(dLine)}`);
+			}
+		}
+		lines.push("");
+	}
 
-  // ── Arguments panel (subcommands only) ──
-  if (!isRoot) {
-    const visibleArgs = helper.visibleArguments(cmd);
-    if (visibleArgs.length > 0) {
-      const maxLen = Math.max(...visibleArgs.map((a: Argument) => a.name().length));
-      const argRows = visibleArgs.map((a: Argument) => {
-        const name = cyanBold(a.name().padEnd(maxLen));
-        const description = helper.argumentDescription(a);
-        return ` ${name}  ${description}`;
-      });
-      const panel = renderPanel("Arguments", argRows, width);
-      if (panel) lines.push(panel);
-    }
-  }
+	// ── Arguments panel (subcommands only) ──
+	if (!isRoot) {
+		const visibleArgs = helper.visibleArguments(cmd);
+		if (visibleArgs.length > 0) {
+			const maxLen = Math.max(
+				...visibleArgs.map((a: Argument) => a.name().length),
+			);
+			const argRows = visibleArgs.map((a: Argument) => {
+				const name = cyanBold(a.name().padEnd(maxLen));
+				const description = helper.argumentDescription(a);
+				return ` ${name}  ${description}`;
+			});
+			const panel = renderPanel("Arguments", argRows, width);
+			if (panel) lines.push(panel);
+		}
+	}
 
-  // ── Collect options (grouped into panels for subcommands) ──
-  const visibleOpts = helper.visibleOptions(cmd);
-  const cmdName = cmd.name();
-  const panelMap = (!isRoot && OPTION_PANELS[cmdName]) ? OPTION_PANELS[cmdName] : {};
+	// ── Collect options (grouped into panels for subcommands) ──
+	const visibleOpts = helper.visibleOptions(cmd);
+	const cmdName = cmd.name();
+	const panelMap =
+		!isRoot && OPTION_PANELS[cmdName] ? OPTION_PANELS[cmdName] : {};
 
-  const grouped: Record<string, Option[]> = { Options: [] };
-  for (const panelName of PANEL_ORDER) {
-    grouped[panelName] = [];
-  }
+	const grouped: Record<string, Option[]> = { Options: [] };
+	for (const panelName of PANEL_ORDER) {
+		grouped[panelName] = [];
+	}
 
-  for (const opt of visibleOpts) {
-    const flag = getLongFlag(opt);
-    const panel = panelMap[flag];
-    if (panel && PANEL_ORDER.includes(panel)) {
-      grouped[panel].push(opt);
-    } else {
-      grouped["Options"].push(opt);
-    }
-  }
+	for (const opt of visibleOpts) {
+		const flag = getLongFlag(opt);
+		const panel = panelMap[flag];
+		if (panel && PANEL_ORDER.includes(panel)) {
+			grouped[panel].push(opt);
+		} else {
+			grouped.Options.push(opt);
+		}
+	}
 
-  // ── Collect commands ──
-  const visibleCmds = helper.visibleCommands(cmd);
+	// ── Collect commands ──
+	const visibleCmds = helper.visibleCommands(cmd);
 
-  if (isRoot) {
-    // ROOT: Options first, then command groups (matches Python/Typer ordering)
-    if (grouped["Options"].length > 0) {
-      const optRows = formatOptionRows(grouped["Options"]);
-      const panel = renderPanel("Options", optRows, width);
-      if (panel) lines.push(panel);
-    }
-    if (visibleCmds.length > 0) {
-      const cmdMap = new Map(visibleCmds.map((c) => [c.name(), c]));
-      for (const group of COMMAND_GROUPS) {
-        const groupCmds = group.commands
-          .map((name) => cmdMap.get(name))
-          .filter((c): c is Command => c !== undefined);
-        if (groupCmds.length === 0) continue;
-        const maxLen = Math.max(...groupCmds.map((c) => c.name().length));
-        const cmdRows = groupCmds.map((c) => {
-          const name = cyanBold(c.name().padEnd(maxLen));
-          const description = helper.subcommandDescription(c);
-          return ` ${name}  ${description}`;
-        });
-        const panel = renderPanel(group.panel, cmdRows, width);
-        if (panel) lines.push(panel);
-      }
-    }
-  } else {
-    // SUBCOMMANDS: Options/panels first, then sub-subcommands
-    const panelSequence = ["Options", ...PANEL_ORDER];
-    for (const panelName of panelSequence) {
-      const opts = grouped[panelName];
-      if (opts && opts.length > 0) {
-        const optRows = formatOptionRows(opts);
-        const panel = renderPanel(panelName, optRows, width);
-        if (panel) lines.push(panel);
-      }
-    }
-    // Sub-subcommands (e.g., config show/get/set, entity list/delete)
-    if (visibleCmds.length > 0) {
-      const maxLen = Math.max(...visibleCmds.map((c) => c.name().length));
-      const cmdRows = visibleCmds.map((c) => {
-        const name = cyanBold(c.name().padEnd(maxLen));
-        const description = helper.subcommandDescription(c);
-        return ` ${name}  ${description}`;
-      });
-      const panel = renderPanel("Commands", cmdRows, width);
-      if (panel) lines.push(panel);
-    }
-  }
+	if (isRoot) {
+		// ROOT: Options first, then command groups (matches Python/Typer ordering)
+		if (grouped.Options.length > 0) {
+			const optRows = formatOptionRows(grouped.Options);
+			const panel = renderPanel("Options", optRows, width);
+			if (panel) lines.push(panel);
+		}
+		if (visibleCmds.length > 0) {
+			const cmdMap = new Map(visibleCmds.map((c) => [c.name(), c]));
+			for (const group of COMMAND_GROUPS) {
+				const groupCmds = group.commands
+					.map((name) => cmdMap.get(name))
+					.filter((c): c is Command => c !== undefined);
+				if (groupCmds.length === 0) continue;
+				const maxLen = Math.max(...groupCmds.map((c) => c.name().length));
+				const cmdRows = groupCmds.map((c) => {
+					const name = cyanBold(c.name().padEnd(maxLen));
+					const description = helper.subcommandDescription(c);
+					return ` ${name}  ${description}`;
+				});
+				const panel = renderPanel(group.panel, cmdRows, width);
+				if (panel) lines.push(panel);
+			}
+		}
+	} else {
+		// SUBCOMMANDS: Options/panels first, then sub-subcommands
+		const panelSequence = ["Options", ...PANEL_ORDER];
+		for (const panelName of panelSequence) {
+			const opts = grouped[panelName];
+			if (opts && opts.length > 0) {
+				const optRows = formatOptionRows(opts);
+				const panel = renderPanel(panelName, optRows, width);
+				if (panel) lines.push(panel);
+			}
+		}
+		// Sub-subcommands (e.g., config show/get/set, entity list/delete)
+		if (visibleCmds.length > 0) {
+			const maxLen = Math.max(...visibleCmds.map((c) => c.name().length));
+			const cmdRows = visibleCmds.map((c) => {
+				const name = cyanBold(c.name().padEnd(maxLen));
+				const description = helper.subcommandDescription(c);
+				return ` ${name}  ${description}`;
+			});
+			const panel = renderPanel("Commands", cmdRows, width);
+			if (panel) lines.push(panel);
+		}
+	}
 
-  lines.push("");
-  return lines.join("\n");
+	lines.push("");
+	return lines.join("\n");
 }
 
 // ── Format option rows with aligned columns ─────────────────────────────
 
 function formatOptionRows(opts: Option[]): string[] {
-  const terms = opts.map((o) => formatOptionTerm(o));
-  const maxTermLen = Math.max(...terms.map((t) => t.length));
+	const terms = opts.map((o) => formatOptionTerm(o));
+	const maxTermLen = Math.max(...terms.map((t) => t.length));
 
-  return opts.map((opt, i) => {
-    const term = cyanBold(terms[i].padEnd(maxTermLen));
-    const desc = opt.description || "";
-    const def = formatDefault(opt);
-    return ` ${term}  ${desc}${def}`;
-  });
+	return opts.map((opt, i) => {
+		const term = cyanBold(terms[i].padEnd(maxTermLen));
+		const desc = opt.description || "";
+		const def = formatDefault(opt);
+		return ` ${term}  ${desc}${def}`;
+	});
 }
 
 // ── Sort commands by COMMAND_ORDER ──────────────────────────────────────
 
 function sortCommands(cmds: Command[]): Command[] {
-  return [...cmds].sort((a, b) => {
-    const ai = COMMAND_ORDER.indexOf(a.name());
-    const bi = COMMAND_ORDER.indexOf(b.name());
-    // Unknown commands go to end, preserving original order
-    const aIdx = ai === -1 ? COMMAND_ORDER.length : ai;
-    const bIdx = bi === -1 ? COMMAND_ORDER.length : bi;
-    return aIdx - bIdx;
-  });
+	return [...cmds].sort((a, b) => {
+		const ai = COMMAND_ORDER.indexOf(a.name());
+		const bi = COMMAND_ORDER.indexOf(b.name());
+		// Unknown commands go to end, preserving original order
+		const aIdx = ai === -1 ? COMMAND_ORDER.length : ai;
+		const bIdx = bi === -1 ? COMMAND_ORDER.length : bi;
+		return aIdx - bIdx;
+	});
 }

cli/node/src/output.ts

@@ -2,229 +2,380 @@
  * Output formatting for mem0 CLI — text, JSON, table, quiet modes.
  */
 
-import Table from "cli-table3";
 import boxen from "boxen";
+import Table from "cli-table3";
 import { colors, sym } from "./branding.js";
 
 const { brand, accent, success, error: errorColor, dim } = colors;
 
 function formatDate(dtStr?: string): string | undefined {
-  if (!dtStr) return undefined;
-  try {
-    const dt = new Date(dtStr.replace("Z", "+00:00"));
-    return dt.toISOString().slice(0, 10);
-  } catch {
-    return dtStr?.slice(0, 10);
-  }
+	if (!dtStr) return undefined;
+	try {
+		const dt = new Date(dtStr.replace("Z", "+00:00"));
+		return dt.toISOString().slice(0, 10);
+	} catch {
+		return dtStr?.slice(0, 10);
+	}
 }
 
 export function formatMemoriesText(
-  memories: Record<string, unknown>[],
-  title = "memories",
+	memories: Record<string, unknown>[],
+	title = "memories",
 ): void {
-  const count = memories.length;
-  console.log(`\n${brand(`Found ${count} ${title}:`)}\n`);
+	const count = memories.length;
+	console.log(`\n${brand(`Found ${count} ${title}:`)}\n`);
 
-  for (let i = 0; i < memories.length; i++) {
-    const mem = memories[i];
-    const memoryText = (mem.memory ?? mem.text ?? "") as string;
-    const memId = ((mem.id as string) ?? "").slice(0, 8);
-    const score = mem.score as number | undefined;
-    const created = formatDate(mem.created_at as string | undefined);
-    let category: string | undefined;
-    const cats = mem.categories;
-    if (Array.isArray(cats)) {
-      category = cats[0] as string | undefined;
-    }
+	for (let i = 0; i < memories.length; i++) {
+		const mem = memories[i];
+		const memoryText = (mem.memory ?? mem.text ?? "") as string;
+		const memId = ((mem.id as string) ?? "").slice(0, 8);
+		const score = mem.score as number | undefined;
+		const created = formatDate(mem.created_at as string | undefined);
+		let category: string | undefined;
+		const cats = mem.categories;
+		if (Array.isArray(cats)) {
+			category = cats[0] as string | undefined;
+		}
 
-    console.log(`  ${i + 1}. ${memoryText}`);
+		console.log(`  ${i + 1}. ${memoryText}`);
 
-    const details: string[] = [];
-    if (score !== undefined) details.push(`Score: ${score.toFixed(2)}`);
-    if (memId) details.push(`ID: ${memId}`);
-    if (created) details.push(`Created: ${created}`);
-    if (category) details.push(`Category: ${category}`);
+		const details: string[] = [];
+		if (score !== undefined) details.push(`Score: ${score.toFixed(2)}`);
+		if (memId) details.push(`ID: ${memId}`);
+		if (created) details.push(`Created: ${created}`);
+		if (category) details.push(`Category: ${category}`);
 
-    if (details.length > 0) {
-      console.log(`     ${dim(details.join(" · "))}`);
-    }
-    console.log();
-  }
+		if (details.length > 0) {
+			console.log(`     ${dim(details.join(" · "))}`);
+		}
+		console.log();
+	}
 }
 
-export function formatMemoriesTable(memories: Record<string, unknown>[]): void {
-  const table = new Table({
-    head: [accent("ID"), accent("Memory"), accent("Category"), accent("Created")],
-    colWidths: [12, 52, 16, 14],
-    wordWrap: true,
-    style: { head: [], border: [] },
-  });
+export function formatMemoriesTable(
+	memories: Record<string, unknown>[],
+	opts: { showScore?: boolean } = {},
+): void {
+	const head = opts.showScore
+		? [
+				accent("ID"),
+				accent("Score"),
+				accent("Memory"),
+				accent("Category"),
+				accent("Created"),
+			]
+		: [accent("ID"), accent("Memory"), accent("Category"), accent("Created")];
+	const colWidths = opts.showScore ? [38, 8, 40, 16, 14] : [38, 40, 16, 14];
+	const table = new Table({
+		head,
+		colWidths,
+		wordWrap: true,
+		style: { head: [], border: [] },
+	});
 
-  for (const mem of memories) {
-    const memId = ((mem.id as string) ?? "").slice(0, 8);
-    let memoryText = (mem.memory ?? mem.text ?? "") as string;
-    if (memoryText.length > 60) {
-      memoryText = memoryText.slice(0, 57) + "...";
-    }
-    const categories = mem.categories;
-    const cat =
-      Array.isArray(categories) && categories.length > 0
-        ? (categories[0] as string)
-        : "—";
-    const created = formatDate(mem.created_at as string | undefined) ?? "—";
-    table.push([dim(memId), memoryText, cat, created]);
-  }
+	for (const mem of memories) {
+		const memId = (mem.id as string) ?? "";
+		let memoryText = (mem.memory ?? mem.text ?? "") as string;
+		if (memoryText.length > 60) {
+			memoryText = `${memoryText.slice(0, 57)}...`;
+		}
+		const categories = mem.categories;
+		const cat =
+			Array.isArray(categories) && categories.length > 0
+				? categories.length > 1
+					? `${categories[0]} (+${categories.length - 1})`
+					: (categories[0] as string)
+				: "—";
+		const created = formatDate(mem.created_at as string | undefined) ?? "—";
+		if (opts.showScore) {
+			const score = mem.score as number | undefined;
+			const scoreStr = score !== undefined ? score.toFixed(2) : "—";
+			table.push([dim(memId), scoreStr, memoryText, cat, created]);
+		} else {
+			table.push([dim(memId), memoryText, cat, created]);
+		}
+	}
 
-  console.log();
-  console.log(table.toString());
-  console.log();
+	console.log();
+	console.log(table.toString());
+	console.log();
 }
 
 export function formatJson(data: unknown): void {
-  console.log(JSON.stringify(data, null, 2));
+	console.log(JSON.stringify(data, null, 2));
 }
 
 export function formatSingleMemory(
-  mem: Record<string, unknown>,
-  output = "text",
+	mem: Record<string, unknown>,
+	output = "text",
 ): void {
-  if (output === "json") {
-    formatJson(mem);
-    return;
-  }
+	if (output === "json") {
+		formatJson(mem);
+		return;
+	}
 
-  const memoryText = (mem.memory ?? mem.text ?? "") as string;
-  const memId = (mem.id ?? "") as string;
+	const memoryText = (mem.memory ?? mem.text ?? "") as string;
+	const memId = (mem.id ?? "") as string;
 
-  const lines: string[] = [];
-  lines.push(`  ${memoryText}`);
-  lines.push("");
+	const lines: string[] = [];
+	lines.push(`  ${memoryText}`);
+	lines.push("");
 
-  if (memId) lines.push(`  ${dim("ID:")}         ${memId}`);
-  const created = formatDate(mem.created_at as string | undefined);
-  if (created) lines.push(`  ${dim("Created:")}    ${created}`);
-  const updated = formatDate(mem.updated_at as string | undefined);
-  if (updated) lines.push(`  ${dim("Updated:")}    ${updated}`);
-  const meta = mem.metadata;
-  if (meta) lines.push(`  ${dim("Metadata:")}   ${JSON.stringify(meta)}`);
-  const categories = mem.categories;
-  if (categories) {
-    const catStr = Array.isArray(categories) ? categories.join(", ") : String(categories);
-    lines.push(`  ${dim("Categories:")} ${catStr}`);
-  }
+	if (memId) lines.push(`  ${dim("ID:")}         ${memId}`);
+	const created = formatDate(mem.created_at as string | undefined);
+	if (created) lines.push(`  ${dim("Created:")}    ${created}`);
+	const updated = formatDate(mem.updated_at as string | undefined);
+	if (updated) lines.push(`  ${dim("Updated:")}    ${updated}`);
+	const meta = mem.metadata;
+	if (meta) lines.push(`  ${dim("Metadata:")}   ${JSON.stringify(meta)}`);
+	const categories = mem.categories;
+	if (categories) {
+		const catStr = Array.isArray(categories)
+			? categories.join(", ")
+			: String(categories);
+		lines.push(`  ${dim("Categories:")} ${catStr}`);
+	}
 
-  const content = lines.join("\n");
-  console.log();
-  console.log(
-    boxen(content, {
-      title: brand("Memory"),
-      titleAlignment: "left",
-      borderColor: "magenta",
-      padding: 1,
-    }),
-  );
-  console.log();
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Memory"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
 }
 
 export function formatAddResult(
-  result: Record<string, unknown> | Record<string, unknown>[],
-  output = "text",
+	result: Record<string, unknown> | Record<string, unknown>[],
+	output = "text",
 ): void {
-  if (output === "json") {
-    formatJson(result);
-    return;
-  }
-  if (output === "quiet") return;
+	if (output === "json") {
+		formatJson(result);
+		return;
+	}
+	if (output === "quiet") return;
 
-  const results: Record<string, unknown>[] = Array.isArray(result)
-    ? result
-    : ((result.results as Record<string, unknown>[]) ?? [result]);
+	const results: Record<string, unknown>[] = Array.isArray(result)
+		? result
+		: ((result.results as Record<string, unknown>[]) ?? [result]);
 
-  if (!results.length) {
-    console.log(`  ${dim("No memories extracted.")}`);
-    return;
-  }
+	if (!results.length) {
+		console.log(`  ${dim("No memories extracted.")}`);
+		return;
+	}
 
-  console.log();
-  for (const r of results) {
-    // Detect async PENDING response
-    if (r.status === "PENDING") {
-      const eventId = ((r.event_id as string) ?? "").slice(0, 8);
-      const icon = accent(sym("⧗", "..."));
-      const parts = [`  ${icon} ${dim("Queued".padEnd(10))}`, "Processing in background"];
-      if (eventId) parts.push(dim(`(event ${eventId})`));
-      console.log(parts.join("  "));
-      continue;
-    }
+	console.log();
+	const seenPendingEvents = new Set<string>();
+	for (const r of results) {
+		// Detect async PENDING response
+		if (r.status === "PENDING") {
+			const eventId = (r.event_id as string) ?? "";
+			// Deduplicate PENDING entries with the same event_id
+			if (eventId && seenPendingEvents.has(eventId)) continue;
+			if (eventId) seenPendingEvents.add(eventId);
+			const icon = accent(sym("⧗", "..."));
+			const parts = [
+				`  ${icon} ${dim("Queued".padEnd(10))}`,
+				"Processing in background",
+			];
+			console.log(parts.join("  "));
+			if (eventId) {
+				console.log(`  ${dim(`  event_id: ${eventId}`)}`);
+				console.log(
+					`  ${dim(`  → Check status: mem0 event status ${eventId}`)}`,
+				);
+			}
+			continue;
+		}
 
-    const event = (r.event ?? "ADD") as string;
-    const memory = (r.memory ?? r.text ?? r.content ?? r.data ?? "") as string;
-    const memId = ((r.id as string) ?? (r.memory_id as string) ?? "").slice(0, 8);
+		const event = (r.event ?? "ADD") as string;
+		const memory = (r.memory ?? r.text ?? r.content ?? r.data ?? "") as string;
+		const memId = ((r.id as string) ?? (r.memory_id as string) ?? "").slice(
+			0,
+			8,
+		);
 
-    let icon: string;
-    let label: string;
-    if (event === "ADD") {
-      icon = success("+");
-      label = "Added";
-    } else if (event === "UPDATE") {
-      icon = accent("~");
-      label = "Updated";
-    } else if (event === "DELETE") {
-      icon = errorColor("-");
-      label = "Deleted";
-    } else if (event === "NOOP") {
-      icon = dim("·");
-      label = "No change";
-    } else {
-      icon = dim("?");
-      label = event;
-    }
+		let icon: string;
+		let label: string;
+		if (event === "ADD") {
+			icon = success("+");
+			label = "Added";
+		} else if (event === "UPDATE") {
+			icon = accent("~");
+			label = "Updated";
+		} else if (event === "DELETE") {
+			icon = errorColor("-");
+			label = "Deleted";
+		} else if (event === "NOOP") {
+			icon = dim("·");
+			label = "No change";
+		} else {
+			icon = dim("?");
+			label = event;
+		}
 
-    const parts = [`  ${icon} ${dim(label.padEnd(10))}`];
-    if (memory) parts.push(memory);
-    if (memId) parts.push(dim(`(${memId})`));
-    console.log(parts.join("  "));
-  }
-  console.log();
+		const parts = [`  ${icon} ${dim(label.padEnd(10))}`];
+		if (memory) parts.push(memory);
+		if (memId) parts.push(dim(`(${memId})`));
+		console.log(parts.join("  "));
+	}
+	console.log();
 }
 
 export function formatJsonEnvelope(opts: {
-  command: string;
-  data: unknown;
-  durationMs?: number;
-  scope?: Record<string, string | undefined>;
-  count?: number;
-  status?: string;
-  error?: string;
+	command: string;
+	data: unknown;
+	durationMs?: number;
+	scope?: Record<string, string | undefined>;
+	count?: number;
+	status?: string;
+	error?: string;
 }): void {
-  const envelope: Record<string, unknown> = {
-    status: opts.status ?? "success",
-    command: opts.command,
-  };
-  if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
-  if (opts.scope !== undefined) envelope.scope = opts.scope;
-  if (opts.count !== undefined) envelope.count = opts.count;
-  if (opts.error) envelope.error = opts.error;
-  envelope.data = opts.data;
-  console.log(JSON.stringify(envelope, null, 2));
+	const envelope: Record<string, unknown> = {
+		status: opts.status ?? "success",
+		command: opts.command,
+	};
+	if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+	if (opts.scope !== undefined) envelope.scope = opts.scope;
+	if (opts.count !== undefined) envelope.count = opts.count;
+	if (opts.error) envelope.error = opts.error;
+	envelope.data = opts.data;
+	console.log(JSON.stringify(envelope, null, 2));
+}
+
+function pick(
+	obj: Record<string, unknown>,
+	keys: string[],
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const key of keys) {
+		if (key in obj) result[key] = obj[key];
+	}
+	return result;
+}
+
+export function sanitizeAgentData(command: string, data: unknown): unknown {
+	if (data === null || data === undefined) return data;
+
+	switch (command) {
+		case "add": {
+			const items = Array.isArray(data) ? data : [data];
+			return items.map((item) => {
+				const r = item as Record<string, unknown>;
+				if (r.status === "PENDING") return pick(r, ["status", "event_id"]);
+				return pick(r, ["id", "memory", "event"]);
+			});
+		}
+		case "search":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "memory", "score", "created_at", "categories"]),
+			);
+		case "list":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "memory", "created_at", "categories"]),
+			);
+		case "get": {
+			const r = data as Record<string, unknown>;
+			return pick(r, [
+				"id",
+				"memory",
+				"created_at",
+				"updated_at",
+				"categories",
+				"metadata",
+			]);
+		}
+		case "update": {
+			const r = data as Record<string, unknown>;
+			return pick(r, ["id", "memory"]);
+		}
+		case "delete":
+		case "delete-all":
+		case "entity delete":
+			return data;
+		case "entity list":
+			return (data as Record<string, unknown>[]).map((r) => ({
+				name: (r.name ?? r.id) as string,
+				...pick(r, ["type", "count"]),
+			}));
+		case "event list":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "event_type", "status", "latency", "created_at"]),
+			);
+		case "event status": {
+			const ev = data as Record<string, unknown>;
+			const rawResults =
+				(ev.results as Record<string, unknown>[] | undefined) ?? [];
+			const sanitizedResults = rawResults.map((r) => {
+				const nested = r.data as Record<string, unknown> | undefined;
+				return {
+					id: r.id,
+					event: r.event,
+					user_id: r.user_id,
+					memory: nested?.memory ?? null,
+				};
+			});
+			return {
+				...pick(ev, [
+					"id",
+					"event_type",
+					"status",
+					"latency",
+					"created_at",
+					"updated_at",
+				]),
+				results: sanitizedResults,
+			};
+		}
+		default:
+			return data;
+	}
+}
+
+export function formatAgentEnvelope(opts: {
+	command: string;
+	data: unknown;
+	durationMs?: number;
+	scope?: Record<string, string | undefined>;
+	count?: number;
+}): void {
+	const envelope: Record<string, unknown> = {
+		status: "success",
+		command: opts.command,
+	};
+	if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+	if (opts.scope) {
+		const filtered = Object.fromEntries(
+			Object.entries(opts.scope).filter(([, v]) => v),
+		);
+		if (Object.keys(filtered).length > 0) envelope.scope = filtered;
+	}
+	if (opts.count !== undefined) envelope.count = opts.count;
+	envelope.data = sanitizeAgentData(opts.command, opts.data);
+	console.log(JSON.stringify(envelope, null, 2));
 }
 
 export function printResultSummary(opts: {
-  count: number;
-  durationSecs?: number;
-  page?: number;
-  scopeIds?: Record<string, string | undefined>;
+	count: number;
+	durationSecs?: number;
+	page?: number;
+	scopeIds?: Record<string, string | undefined>;
 }): void {
-  const parts = [`${opts.count} result${opts.count !== 1 ? "s" : ""}`];
-  if (opts.page !== undefined) parts.push(`page ${opts.page}`);
-  if (opts.scopeIds) {
-    const scopeParts = Object.entries(opts.scopeIds)
-      .filter(([, v]) => v)
-      .map(([k, v]) => `${k.replace(/_/g, " ")}=${v}`);
-    if (scopeParts.length > 0) parts.push(scopeParts.join(", "));
-  }
-  if (opts.durationSecs !== undefined) parts.push(`${opts.durationSecs.toFixed(2)}s`);
+	const parts = [`${opts.count} result${opts.count !== 1 ? "s" : ""}`];
+	if (opts.page !== undefined) parts.push(`page ${opts.page}`);
+	if (opts.scopeIds) {
+		const scopeParts = Object.entries(opts.scopeIds)
+			.filter(([, v]) => v)
+			.map(([k, v]) => `${k}=${v}`);
+		if (scopeParts.length > 0) parts.push(scopeParts.join(", "));
+	}
+	if (opts.durationSecs !== undefined)
+		parts.push(`${opts.durationSecs.toFixed(2)}s`);
 
-  console.log(`  ${dim(parts.join(" · "))}`);
-  console.log();
+	console.log(`  ${dim(parts.join(" · "))}`);
+	console.log();
 }

cli/node/src/state.ts

@@ -0,0 +1,23 @@
+/**
+ * Agent mode state — set by the root program option handler,
+ * read by commands and branding functions.
+ */
+
+let _agentMode = false;
+let _currentCommand = "";
+
+export function isAgentMode(): boolean {
+	return _agentMode;
+}
+
+export function setAgentMode(val: boolean): void {
+	_agentMode = val;
+}
+
+export function getCurrentCommand(): string {
+	return _currentCommand;
+}
+
+export function setCurrentCommand(name: string): void {
+	_currentCommand = name;
+}

cli/node/src/telemetry.ts

@@ -0,0 +1,153 @@
+/**
+ * CLI telemetry — anonymous usage tracking via PostHog.
+ *
+ * Sends fire-and-forget events by spawning a detached child process
+ * (telemetry-sender.cjs). The parent CLI process exits immediately;
+ * the child handles email resolution, caching, and the HTTP POST.
+ *
+ * Disable with: MEM0_TELEMETRY=false
+ */
+
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_FILE, loadConfig, saveConfig } from "./config.js";
+import { CLI_VERSION } from "./version.js";
+
+const POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
+const POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SENDER_SCRIPT = path.join(__dirname, "..", "telemetry-sender.cjs");
+
+function isTelemetryEnabled(): boolean {
+	try {
+		return process.env.MEM0_TELEMETRY !== "false";
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Return a persistent per-machine anonymous ID, generating one if needed.
+ *
+ * Stored in ~/.mem0/config.json under `telemetry.anonymous_id` so that
+ * repeat runs on the same machine share one PostHog identity instead of
+ * collapsing into a single shared fallback string.
+ */
+function getOrCreateAnonymousId(): string {
+	const config = loadConfig();
+	if (config.telemetry.anonymousId) {
+		return config.telemetry.anonymousId;
+	}
+
+	const newId = `cli-anon-${randomUUID().replace(/-/g, "")}`;
+	config.telemetry.anonymousId = newId;
+	try {
+		saveConfig(config);
+	} catch {
+		/* ignore persistence failure — still return the generated ID */
+	}
+	return newId;
+}
+
+/**
+ * Return a stable anonymous identifier for the current user.
+ *
+ * Priority: cached user_email (from /v1/ping/) > MD5(api_key) >
+ * persistent per-machine anonymous ID.
+ */
+function getDistinctId(): string {
+	try {
+		const config = loadConfig();
+		if (config.platform.userEmail) {
+			return config.platform.userEmail;
+		}
+		if (config.platform.apiKey) {
+			return createHash("md5").update(config.platform.apiKey).digest("hex");
+		}
+	} catch {
+		/* ignore */
+	}
+	try {
+		return getOrCreateAnonymousId();
+	} catch {
+		return `cli-anon-${randomUUID().replace(/-/g, "")}`;
+	}
+}
+
+/**
+ * Fire a PostHog event (non-blocking, returns void, never throws).
+ * Spawns telemetry-sender.cjs as a detached subprocess.
+ *
+ * When `preResolvedEmail` is provided (e.g. from an upfront ping
+ * validation), it is used directly as the PostHog distinct ID and the
+ * subprocess skips its own `/v1/ping/` call.
+ */
+export function captureEvent(
+	eventName: string,
+	properties: Record<string, unknown> = {},
+	preResolvedEmail?: string,
+): void {
+	if (!isTelemetryEnabled()) return;
+
+	try {
+		const config = loadConfig();
+		const distinctId = preResolvedEmail || getDistinctId();
+
+		// Detect anonymous → identified transition. If a stored anonymous_id
+		// exists and we just resolved to a real identity, fire a one-shot
+		// $identify event so PostHog stitches the pre-signup history onto
+		// the authenticated profile. Clear the stored id so we don't re-alias.
+		let anonIdToAlias: string | null = null;
+		if (
+			distinctId &&
+			!distinctId.startsWith("cli-anon-") &&
+			config.telemetry.anonymousId
+		) {
+			anonIdToAlias = config.telemetry.anonymousId;
+			config.telemetry.anonymousId = "";
+			try {
+				saveConfig(config);
+			} catch {
+				/* ignore — alias may double-fire next run, harmless */
+			}
+		}
+
+		const payload = {
+			api_key: POSTHOG_API_KEY,
+			distinct_id: distinctId,
+			event: eventName,
+			properties: {
+				source: "CLI",
+				language: "node",
+				cli_version: CLI_VERSION,
+				node_version: process.version,
+				os: process.platform,
+				...properties,
+				$process_person_profile: false,
+				$lib: "posthog-node",
+			},
+		};
+
+		const context = {
+			payload,
+			posthogHost: POSTHOG_HOST,
+			needsEmail: !distinctId || !distinctId.includes("@"),
+			mem0ApiKey: config.platform.apiKey || "",
+			mem0BaseUrl: config.platform.baseUrl || "https://api.mem0.ai",
+			configPath: CONFIG_FILE,
+			anonDistinctIdToAlias: anonIdToAlias,
+		};
+
+		const child = spawn(
+			process.execPath,
+			[SENDER_SCRIPT, JSON.stringify(context)],
+			{ detached: true, stdio: "ignore" },
+		);
+		child.unref();
+	} catch {
+		/* silently swallow */
+	}
+}

cli/node/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module";
+
+// __CLI_VERSION__ is replaced at build time by tsup (see tsup.config.ts).
+// When running via tsx in dev/test mode, fall back to reading package.json.
+// typeof is safe to use on undeclared identifiers — it returns 'undefined' without throwing.
+export const CLI_VERSION: string =
+	typeof __CLI_VERSION__ !== "undefined"
+		? (__CLI_VERSION__ as string)
+		: (createRequire(import.meta.url)("../package.json") as { version: string })
+				.version;

cli/node/telemetry-sender.cjs

@@ -0,0 +1,129 @@
+/**
+ * Standalone telemetry sender — runs as a detached child process.
+ *
+ * Usage: node telemetry-sender.cjs '<json context>'
+ *
+ * This script is spawned by telemetry.captureEvent() and runs independently
+ * of the parent CLI process. It:
+ *
+ * 1. Resolves the user's email via /v1/ping/ if not already cached
+ * 2. Caches the email in ~/.mem0/config.json for future runs
+ * 3. Sends the PostHog event
+ *
+ * All errors are silently swallowed — this process must never produce output
+ * or affect the user experience.
+ */
+
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+
+function httpsRequest(url, method, headers, body) {
+	return new Promise((resolve, reject) => {
+		const u = new URL(url);
+		const opts = {
+			hostname: u.hostname,
+			path: u.pathname + u.search,
+			method,
+			headers,
+			timeout: 10000,
+		};
+		const req = https.request(opts, (res) => {
+			let data = "";
+			res.on("data", (chunk) => (data += chunk));
+			res.on("end", () => {
+				try {
+					resolve(JSON.parse(data));
+				} catch {
+					resolve({});
+				}
+			});
+		});
+		req.on("error", reject);
+		req.on("timeout", () => {
+			req.destroy();
+			reject(new Error("timeout"));
+		});
+		if (body) {
+			req.end(body);
+		} else {
+			req.end();
+		}
+	});
+}
+
+async function resolveAndCacheEmail(ctx, payload) {
+	try {
+		const pingUrl = ctx.mem0BaseUrl.replace(/\/+$/, "") + "/v1/ping/";
+		const data = await httpsRequest(pingUrl, "GET", {
+			Authorization: "Token " + ctx.mem0ApiKey,
+			"Content-Type": "application/json",
+		});
+		if (data.user_email) {
+			payload.distinct_id = data.user_email;
+			cacheEmail(ctx.configPath, data.user_email);
+		}
+	} catch {
+		// silently swallow
+	}
+}
+
+function cacheEmail(configPath, email) {
+	if (!configPath) return;
+	try {
+		const raw = fs.readFileSync(configPath, "utf-8");
+		const cfg = JSON.parse(raw);
+		if (!cfg.platform) cfg.platform = {};
+		cfg.platform.user_email = email;
+		fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+	} catch {
+		// silently swallow
+	}
+}
+
+async function sendPosthogEvent(posthogHost, payload) {
+	try {
+		const body = JSON.stringify(payload);
+		await httpsRequest(posthogHost, "POST", {
+			"Content-Type": "application/json",
+			"Content-Length": Buffer.byteLength(body),
+		}, body);
+	} catch {
+		// silently swallow
+	}
+}
+
+async function sendIdentifyEvent(ctx, payload, anonId) {
+	const identifyPayload = {
+		api_key: payload.api_key,
+		event: "$identify",
+		distinct_id: payload.distinct_id,
+		properties: {
+			$anon_distinct_id: anonId,
+			$lib: (payload.properties && payload.properties.$lib) || "posthog-node",
+		},
+	};
+	await sendPosthogEvent(ctx.posthogHost, identifyPayload);
+}
+
+async function main() {
+	const ctx = JSON.parse(process.argv[2]);
+	const payload = ctx.payload;
+
+	if (ctx.needsEmail && ctx.mem0ApiKey) {
+		await resolveAndCacheEmail(ctx, payload);
+	}
+
+	// Fire $identify *after* email resolution so PostHog links the stored
+	// anonymous id directly to the final identity (email, not the api-key
+	// hash). The regular event is sent next so it lands under the merged
+	// profile.
+	if (ctx.anonDistinctIdToAlias) {
+		await sendIdentifyEvent(ctx, payload, ctx.anonDistinctIdToAlias);
+	}
+
+	await sendPosthogEvent(ctx.posthogHost, payload);
+}
+
+main().catch(() => {});

cli/node/tests/branding.test.ts

@@ -80,19 +80,19 @@ describe("printWarning", () => {
 describe("printInfo", () => {
   it("prints info message", () => {
     printInfo("Important note");
-    expect(output).toContain("Important note");
+    expect(errOutput).toContain("Important note");
   });
 });
 
 describe("printScope", () => {
   it("prints scope when IDs present", () => {
     printScope({ user_id: "alice", agent_id: "bot" });
-    expect(output).toContain("alice");
-    expect(output).toContain("bot");
+    expect(errOutput).toContain("alice");
+    expect(errOutput).toContain("bot");
   });
 
   it("prints nothing when no IDs", () => {
     printScope({});
-    expect(output).toBe("");
+    expect(errOutput).toBe("");
   });
 });

cli/node/tests/cli-integration.test.ts

@@ -44,13 +44,6 @@ describe("CLI Integration — help and version", () => {
     expect(result.stdout).toContain("search");
   });
 
-  it("shows version with --version", () => {
-    const result = run(["--version"]);
-    expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("0.1.0");
-  });
-
-
   it("help --json produces valid JSON", () => {
     const result = run(["help", "--json"]);
     expect(result.exitCode).toBe(0);
@@ -114,22 +107,22 @@ describe("CLI Integration — help and version", () => {
     expect(result.exitCode).toBe(0);
   });
 
-  it("add help has --graph flag", () => {
+  it("add help has --output flag", () => {
     const result = run(["add", "--help"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("--graph");
+    expect(result.stdout).toContain("--output");
   });
 
-  it("search help has --graph flag", () => {
+  it("search help has --rerank flag", () => {
     const result = run(["search", "--help"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("--graph");
+    expect(result.stdout).toContain("--rerank");
   });
 
-  it("list help has --graph flag", () => {
+  it("list help has --category flag", () => {
     const result = run(["list", "--help"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("--graph");
+    expect(result.stdout).toContain("--category");
   });
 });
 

cli/node/tests/commands.test.ts

@@ -5,6 +5,7 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { createMockBackend } from "./setup.js";
 import type { Backend } from "../src/backend/base.js";
+import { setAgentMode } from "../src/state.js";
 
 let mockBackend: Backend;
 
@@ -31,6 +32,7 @@ import { afterEach } from "vitest";
 afterEach(() => {
   console.log = originalLog;
   console.error = originalError;
+  setAgentMode(false);
 });
 
 describe("cmdAdd", () => {
@@ -40,7 +42,7 @@ describe("cmdAdd", () => {
       userId: "alice",
       immutable: false,
       noInfer: false,
-      enableGraph: false,
+
       output: "text",
     });
     expect(mockBackend.add).toHaveBeenCalledOnce();
@@ -53,7 +55,7 @@ describe("cmdAdd", () => {
       messages: JSON.stringify([{ role: "user", content: "I love Python" }]),
       immutable: false,
       noInfer: false,
-      enableGraph: false,
+
       output: "text",
     });
     expect(mockBackend.add).toHaveBeenCalledOnce();
@@ -65,7 +67,7 @@ describe("cmdAdd", () => {
       userId: "alice",
       immutable: false,
       noInfer: false,
-      enableGraph: false,
+
       output: "json",
     });
     expect(output).toContain("results");
@@ -77,13 +79,66 @@ describe("cmdAdd", () => {
       userId: "alice",
       immutable: false,
       noInfer: false,
-      enableGraph: false,
+
       output: "quiet",
     });
     expect(output).not.toContain("dark mode");
   });
 });
 
+describe("cmdAdd deduplicates PENDING", () => {
+  const DUPLICATE_PENDING = {
+    results: [
+      { status: "PENDING", event_id: "evt-dup" },
+      { status: "PENDING", event_id: "evt-dup" },
+    ],
+  };
+
+  it("text shows one pending block", async () => {
+    (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(DUPLICATE_PENDING);
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "test", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+
+      output: "text",
+    });
+    expect(output.match(/Queued/g)?.length).toBe(1);
+  });
+
+  it("json shows one pending entry", async () => {
+    (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(DUPLICATE_PENDING);
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "test", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+
+      output: "json",
+    });
+    const data = JSON.parse(output);
+    const pending = data.results.filter((r: Record<string, unknown>) => r.status === "PENDING");
+    expect(pending).toHaveLength(1);
+  });
+
+  it("agent shows one pending entry", async () => {
+    (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(DUPLICATE_PENDING);
+    setAgentMode(true);
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "test", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+
+      output: "agent",
+    });
+    const data = JSON.parse(output);
+    expect(data.count).toBe(1);
+    expect(data.data).toHaveLength(1);
+  });
+});
+
 describe("cmdSearch", () => {
   it("searches and shows results in text mode", async () => {
     const { cmdSearch } = await import("../src/commands/memory.js");
@@ -93,7 +148,7 @@ describe("cmdSearch", () => {
       threshold: 0.3,
       rerank: false,
       keyword: false,
-      enableGraph: false,
+
       output: "text",
     });
     expect(output).toContain("Found 2");
@@ -107,7 +162,7 @@ describe("cmdSearch", () => {
       threshold: 0.3,
       rerank: false,
       keyword: false,
-      enableGraph: false,
+
       output: "json",
     });
     expect(output).toContain("memory");
@@ -122,10 +177,10 @@ describe("cmdSearch", () => {
       threshold: 0.3,
       rerank: false,
       keyword: false,
-      enableGraph: false,
+
       output: "text",
     });
-    expect(output).toContain("No memories found");
+    expect(errOutput).toContain("No memories found");
   });
 });
 
@@ -150,7 +205,7 @@ describe("cmdList", () => {
       userId: "alice",
       page: 1,
       pageSize: 100,
-      enableGraph: false,
+
       output: "table",
     });
     expect(output).toContain("dark mode");
@@ -163,10 +218,10 @@ describe("cmdList", () => {
       userId: "alice",
       page: 1,
       pageSize: 100,
-      enableGraph: false,
+
       output: "text",
     });
-    expect(output).toContain("No memories found");
+    expect(errOutput).toContain("No memories found");
   });
 });
 
@@ -198,13 +253,6 @@ describe("cmdDeleteAll", () => {
   });
 });
 
-describe("cmdVersion", () => {
-  it("shows version", async () => {
-    const { cmdVersion } = await import("../src/commands/utils.js");
-    cmdVersion();
-    expect(output).toContain("0.1.0");
-  });
-});
 
 describe("cmdEntitiesList", () => {
   it("lists users in table mode", async () => {
@@ -219,3 +267,168 @@ describe("cmdEntitiesList", () => {
     expect(output).toContain("alice");
   });
 });
+
+describe("cmdEventList", () => {
+  it("lists events in table mode", async () => {
+    const { cmdEventList } = await import("../src/commands/events.js");
+    await cmdEventList(mockBackend, { output: "table" });
+    expect(output).toContain("evt-abc-");
+    expect(output).toContain("ADD");
+    expect(output).toContain("SUCCEEDED");
+  });
+
+  it("lists events in json mode", async () => {
+    const { cmdEventList } = await import("../src/commands/events.js");
+    await cmdEventList(mockBackend, { output: "json" });
+    expect(output).toContain("evt-abc-123-def-456");
+    expect(output).toContain("evt-def-456-ghi-789");
+  });
+
+  it("shows empty message when no events", async () => {
+    (mockBackend.listEvents as ReturnType<typeof vi.fn>).mockResolvedValueOnce([]);
+    const { cmdEventList } = await import("../src/commands/events.js");
+    await cmdEventList(mockBackend, { output: "table" });
+    expect((output + errOutput).toLowerCase()).toContain("no events");
+  });
+});
+
+describe("cmdEventStatus", () => {
+  it("shows event details in text mode", async () => {
+    const { cmdEventStatus } = await import("../src/commands/events.js");
+    await cmdEventStatus(mockBackend, "evt-abc-123-def-456", { output: "text" });
+    expect(output).toContain("evt-abc-123-def-456");
+    expect(output).toContain("SUCCEEDED");
+  });
+
+  it("shows event details in json mode", async () => {
+    const { cmdEventStatus } = await import("../src/commands/events.js");
+    await cmdEventStatus(mockBackend, "evt-abc-123-def-456", { output: "json" });
+    expect(output).toContain("evt-abc-123-def-456");
+    expect(output).toContain("ADD");
+  });
+});
+
+describe("agent mode", () => {
+  it("cmdAdd outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "test preference", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+
+      output: "agent",
+    });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("add");
+    expect(parsed.data).toBeDefined();
+    expect(parsed.scope).toMatchObject({ user_id: "alice" });
+    expect(Object.keys(parsed.data[0]).sort()).toEqual(["event", "id", "memory"].sort());
+  });
+
+  it("cmdSearch outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdSearch } = await import("../src/commands/memory.js");
+    await cmdSearch(mockBackend, "preferences", {
+      userId: "alice",
+      topK: 10,
+      threshold: 0.3,
+      rerank: false,
+      keyword: false,
+
+      output: "agent",
+    });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("search");
+    expect(Array.isArray(parsed.data)).toBe(true);
+    expect(parsed.count).toBe(2);
+    const keys = Object.keys(parsed.data[0]);
+    expect(keys).toContain("id");
+    expect(keys).toContain("memory");
+    expect(keys).toContain("score");
+    expect(keys).toContain("created_at");
+    expect(keys).toContain("categories");
+    expect(keys).not.toContain("user_id");
+    expect(keys).not.toContain("agent_id");
+  });
+
+  it("cmdList outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdList } = await import("../src/commands/memory.js");
+    await cmdList(mockBackend, {
+      userId: "alice",
+      page: 1,
+      pageSize: 100,
+
+      output: "agent",
+    });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("list");
+    expect(Array.isArray(parsed.data)).toBe(true);
+    expect(parsed.count).toBe(2);
+    expect(Object.keys(parsed.data[0]).sort()).toEqual(["categories", "created_at", "id", "memory"]);
+  });
+
+  it("cmdGet outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdGet } = await import("../src/commands/memory.js");
+    await cmdGet(mockBackend, "abc-123-def-456", { output: "agent" });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("get");
+    expect(parsed.data).toBeDefined();
+    expect(parsed.data).toMatchObject({ id: "abc-123-def-456" });
+    expect(Object.keys(parsed.data)).not.toContain("user_id");
+  });
+
+  it("cmdUpdate outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdUpdate } = await import("../src/commands/memory.js");
+    await cmdUpdate(mockBackend, "abc-123", "Updated text", { output: "agent" });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("update");
+    expect(parsed.data).toBeDefined();
+  });
+
+  it("cmdDelete outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdDelete } = await import("../src/commands/memory.js");
+    await cmdDelete(mockBackend, "abc-123", { output: "agent" });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("delete");
+    expect(parsed.data).toBeDefined();
+  });
+
+  it("cmdEventList outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdEventList } = await import("../src/commands/events.js");
+    await cmdEventList(mockBackend, { output: "agent" });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("event list");
+    expect(Array.isArray(parsed.data)).toBe(true);
+    expect(parsed.count).toBe(2);
+    expect(Object.keys(parsed.data[0]).sort()).toEqual(
+      ["created_at", "event_type", "id", "latency", "status"],
+    );
+    expect(Object.keys(parsed.data[0])).not.toContain("updated_at");
+  });
+
+  it("cmdEventStatus outputs JSON envelope", async () => {
+    setAgentMode(true);
+    const { cmdEventStatus } = await import("../src/commands/events.js");
+    await cmdEventStatus(mockBackend, "evt-abc-123-def-456", { output: "agent" });
+    const parsed = JSON.parse(output.trim());
+    expect(parsed.status).toBe("success");
+    expect(parsed.command).toBe("event status");
+    expect(parsed.data).toBeDefined();
+    expect(parsed.data).toMatchObject({ id: "evt-abc-123-def-456" });
+    expect(parsed.data.results[0]).toHaveProperty("memory");
+    expect(parsed.data.results[0]).not.toHaveProperty("data");
+  });
+});

cli/node/tests/config.test.ts

@@ -64,7 +64,6 @@ describe("createDefaultConfig", () => {
     expect(config.platform.baseUrl).toBe("https://api.mem0.ai");
     expect(config.platform.apiKey).toBe("");
     expect(config.defaults.userId).toBe("");
-    expect(config.defaults.enableGraph).toBe(false);
   });
 });
 
@@ -105,9 +104,4 @@ describe("setNestedValue", () => {
     expect(config.defaults.userId).toBe("bob");
   });
 
-  it("coerces boolean for enable_graph", () => {
-    const config = createDefaultConfig();
-    expect(setNestedValue(config, "defaults.enable_graph", "true")).toBe(true);
-    expect(config.defaults.enableGraph).toBe(true);
-  });
 });

cli/node/tests/output.test.ts

@@ -10,6 +10,7 @@ import {
   formatSingleMemory,
   formatAddResult,
   printResultSummary,
+  sanitizeAgentData,
 } from "../src/output.js";
 
 let output: string;
@@ -98,6 +99,18 @@ describe("formatAddResult", () => {
     });
     expect(output).toContain("Queued");
   });
+
+  it("deduplicates PENDING entries with same event_id", () => {
+    formatAddResult({
+      results: [
+        { status: "PENDING", event_id: "evt-dup" },
+        { status: "PENDING", event_id: "evt-dup" },
+      ],
+    });
+    // Should show only one PENDING block despite two entries with same event_id
+    expect(output.match(/Queued/g)?.length).toBe(1);
+    expect(output.match(/evt-dup/g)?.length).toBe(2); // event_id line + status hint line
+  });
 });
 
 describe("printResultSummary", () => {
@@ -113,3 +126,73 @@ describe("printResultSummary", () => {
     expect(output).not.toContain("results");
   });
 });
+
+describe("sanitizeAgentData", () => {
+  it("projects add results", () => {
+    const raw = [{ id: "abc", memory: "test", event: "ADD", metadata: { x: 1 }, categories: ["a"] }];
+    const result = sanitizeAgentData("add", raw) as Record<string, unknown>[];
+    expect(result).toEqual([{ id: "abc", memory: "test", event: "ADD" }]);
+  });
+
+  it("passes through PENDING add items", () => {
+    const raw = [{ status: "PENDING", event_id: "evt-123", noise: "x" }];
+    const result = sanitizeAgentData("add", raw) as Record<string, unknown>[];
+    expect(result).toEqual([{ status: "PENDING", event_id: "evt-123" }]);
+  });
+
+  it("projects search results", () => {
+    const raw = [{ id: "abc", memory: "test", score: 0.9, created_at: "2026-01-01", categories: ["a"], user_id: "u1" }];
+    const result = sanitizeAgentData("search", raw) as Record<string, unknown>[];
+    expect(result[0]).not.toHaveProperty("user_id");
+    expect(result[0]).toHaveProperty("score");
+  });
+
+  it("projects list results", () => {
+    const raw = [{ id: "abc", memory: "test", created_at: "2026-01-01", categories: ["a"], user_id: "u1" }];
+    const result = sanitizeAgentData("list", raw) as Record<string, unknown>[];
+    expect(Object.keys(result[0]).sort()).toEqual(["categories", "created_at", "id", "memory"]);
+  });
+
+  it("projects get result", () => {
+    const raw = { id: "abc", memory: "test", created_at: "2026-01-01", updated_at: "2026-01-02", categories: ["a"], metadata: { k: "v" }, user_id: "u1" };
+    const result = sanitizeAgentData("get", raw) as Record<string, unknown>;
+    expect(result).not.toHaveProperty("user_id");
+    expect(result).toHaveProperty("metadata");
+  });
+
+  it("projects update result", () => {
+    const raw = { id: "abc", memory: "updated", extra: "noise" };
+    const result = sanitizeAgentData("update", raw);
+    expect(result).toEqual({ id: "abc", memory: "updated" });
+  });
+
+  it("projects event list results", () => {
+    const raw = [{ id: "evt-1", event_type: "ADD", status: "SUCCEEDED", graph_status: null, latency: 100, created_at: "2026-01-01", updated_at: "2026-01-02" }];
+    const result = sanitizeAgentData("event list", raw) as Record<string, unknown>[];
+    expect(result[0]).not.toHaveProperty("updated_at");
+    expect(result[0]).not.toHaveProperty("graph_status");
+  });
+
+  it("flattens event status results", () => {
+    const raw = {
+      id: "evt-1", event_type: "ADD", status: "SUCCEEDED",
+      latency: 100, created_at: "2026-01-01", updated_at: "2026-01-02",
+      results: [{ id: "mem-1", event: "ADD", user_id: "alice", data: { memory: "dark mode" } }],
+    };
+    const result = sanitizeAgentData("event status", raw) as Record<string, unknown>;
+    const firstResult = (result.results as Record<string, unknown>[])[0];
+    expect(firstResult).toHaveProperty("memory", "dark mode");
+    expect(firstResult).not.toHaveProperty("data");
+  });
+
+  it("passes through status/config/import commands unchanged", () => {
+    const data = { key: "value", other: "stuff" };
+    for (const cmd of ["status", "import", "config show", "config get", "config set"]) {
+      expect(sanitizeAgentData(cmd, data)).toEqual(data);
+    }
+  });
+
+  it("handles null data", () => {
+    expect(sanitizeAgentData("add", null)).toBeNull();
+  });
+});

cli/node/tests/setup.ts

@@ -71,5 +71,42 @@ export function createMockBackend(): Backend {
       { name: "alice", count: 5 },
       { name: "bob", count: 3 },
     ]),
+    listEvents: vi.fn().mockResolvedValue([
+      {
+        id: "evt-abc-123-def-456",
+        event_type: "ADD",
+        status: "SUCCEEDED",
+        graph_status: null,
+        latency: 1234.5,
+        created_at: "2026-04-01T10:00:00Z",
+        updated_at: "2026-04-01T10:00:01Z",
+      },
+      {
+        id: "evt-def-456-ghi-789",
+        event_type: "SEARCH",
+        status: "PENDING",
+        graph_status: null,
+        latency: null,
+        created_at: "2026-04-01T10:01:00Z",
+        updated_at: "2026-04-01T10:01:00Z",
+      },
+    ]),
+    getEvent: vi.fn().mockResolvedValue({
+      id: "evt-abc-123-def-456",
+      event_type: "ADD",
+      status: "SUCCEEDED",
+      graph_status: "SUCCEEDED",
+      latency: 1234.5,
+      created_at: "2026-04-01T10:00:00Z",
+      updated_at: "2026-04-01T10:00:01Z",
+      results: [
+        {
+          id: "mem-abc-123",
+          event: "ADD",
+          user_id: "alice",
+          data: { memory: "User prefers dark mode" },
+        },
+      ],
+    }),
   };
 }

cli/node/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup';
+import { createRequire } from 'node:module';
+
+const _require = createRequire(import.meta.url);
+const pkg = _require('./package.json');
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  define: {
+    __CLI_VERSION__: JSON.stringify(pkg.version),
+  },
+});

cli/node/vitest.config.ts

@@ -0,0 +1,11 @@
+import { createRequire } from "node:module";
+import { defineConfig } from "vitest/config";
+
+const _require = createRequire(import.meta.url);
+const pkg = _require("./package.json") as { version: string };
+
+export default defineConfig({
+	define: {
+		__CLI_VERSION__: JSON.stringify(pkg.version),
+	},
+});

cli/python/README.md

@@ -1,6 +1,12 @@
-# mem0 CLI
+# mem0 CLI (Python)
 
-The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents.
+The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. Python implementation.
+
+> **Built for AI agents.** Pass `--agent` (or `--json`) as a global flag on any command to get structured JSON output optimized for programmatic consumption — sanitized fields, no colors or spinners, and errors as JSON too.
+
+## Prerequisites
+
+- Python **3.10+**
 
 ## Installation
 
@@ -18,22 +24,326 @@ 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
+## Quick start
 
 ```bash
-# Set up your configuration
+# Interactive setup wizard
 mem0 init
 
+# Or login via email
+mem0 init --email alice@company.com
+
+# Or authenticate with an existing API key
+mem0 init --api-key m0-xxx
+
 # Add a memory
 mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
 
 # Search memories
 mem0 search "What are Alice's preferences?" --user-id alice
 
-# List all memories
+# List all memories for a user
 mem0 list --user-id alice
+
+# Get a specific memory
+mem0 get <memory-id>
+
+# Update a memory
+mem0 update <memory-id> "I switched to light mode"
+
+# Delete a memory
+mem0 delete <memory-id>
 ```
 
+## Commands
+
+### `mem0 init`
+
+Interactive setup wizard. Prompts for your API key and default user ID.
+
+```bash
+mem0 init
+mem0 init --api-key m0-xxx --user-id alice
+mem0 init --email alice@company.com
+```
+
+If an existing configuration is detected, the CLI asks for confirmation before overwriting. Use `--force` to skip the prompt (useful in CI/CD).
+
+```bash
+mem0 init --api-key m0-xxx --user-id alice --force
+```
+
+| Flag | Description |
+|------|-------------|
+| `--api-key` | API key (skip prompt) |
+| `-u, --user-id` | Default user ID (skip prompt) |
+| `--email` | Login via email verification code |
+| `--code` | Verification code (use with `--email` for non-interactive login) |
+| `--force` | Overwrite existing config without confirmation |
+
+### `mem0 add`
+
+Add a memory from text, a JSON messages array, a file, or stdin.
+
+```bash
+mem0 add "I prefer dark mode" --user-id alice
+mem0 add --file conversation.json --user-id alice
+echo "Loves hiking on weekends" | mem0 add --user-id alice
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Scope to a user |
+| `--agent-id` | Scope to an agent |
+| `--messages` | Conversation messages as JSON |
+| `-f, --file` | Read messages from a JSON file |
+| `-m, --metadata` | Custom metadata as JSON |
+| `--categories` | Categories (JSON array or comma-separated) |
+| `--graph / --no-graph` | Enable or disable graph memory extraction |
+| `-o, --output` | Output format: `text`, `json`, `quiet` |
+
+### `mem0 search`
+
+Search memories using natural language.
+
+```bash
+mem0 search "dietary restrictions" --user-id alice
+mem0 search "preferred tools" --user-id alice --output json --top-k 5
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Filter by user |
+| `-k, --top-k` | Number of results (default: 10) |
+| `--threshold` | Minimum similarity score (default: 0.3) |
+| `--rerank` | Enable reranking |
+| `--keyword` | Use keyword search instead of semantic |
+| `--filter` | Advanced filter expression (JSON) |
+| `--graph / --no-graph` | Enable or disable graph in search |
+| `-o, --output` | Output format: `text`, `json`, `table` |
+
+### `mem0 list`
+
+List memories with optional filters and pagination.
+
+```bash
+mem0 list --user-id alice
+mem0 list --user-id alice --category preferences --output json
+mem0 list --user-id alice --after 2024-01-01 --page-size 50
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Filter by user |
+| `--page` | Page number (default: 1) |
+| `--page-size` | Results per page (default: 100) |
+| `--category` | Filter by category |
+| `--after` | Created after date (YYYY-MM-DD) |
+| `--before` | Created before date (YYYY-MM-DD) |
+| `-o, --output` | Output format: `text`, `json`, `table` |
+
+### `mem0 get`
+
+Retrieve a specific memory by ID.
+
+```bash
+mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
+mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json
+```
+
+### `mem0 update`
+
+Update the text or metadata of an existing memory.
+
+```bash
+mem0 update <memory-id> "Updated preference text"
+mem0 update <memory-id> --metadata '{"priority": "high"}'
+echo "new text" | mem0 update <memory-id>
+```
+
+### `mem0 delete`
+
+Delete a single memory, all memories for a scope, or an entire entity.
+
+```bash
+# Delete a single memory
+mem0 delete <memory-id>
+
+# Delete all memories for a user
+mem0 delete --all --user-id alice --force
+
+# Delete all memories project-wide
+mem0 delete --all --project --force
+
+# Preview what would be deleted
+mem0 delete --all --user-id alice --dry-run
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Delete all memories matching scope filters |
+| `--entity` | Delete the entity and all its memories |
+| `--project` | With `--all`: delete all memories project-wide |
+| `--dry-run` | Preview without deleting |
+| `--force` | Skip confirmation prompt |
+
+### `mem0 import`
+
+Bulk import memories from a JSON file.
+
+```bash
+mem0 import data.json --user-id alice
+```
+
+The file should be a JSON array where each item has a `memory` (or `text` or `content`) field and optional `user_id`, `agent_id`, and `metadata` fields.
+
+### `mem0 config`
+
+View or modify the local CLI configuration.
+
+```bash
+mem0 config show              # Display current config (secrets redacted)
+mem0 config get api_key       # Get a specific value
+mem0 config set user_id bob   # Set a value
+```
+
+### `mem0 entity`
+
+List or delete entities (users, agents, apps, runs).
+
+```bash
+mem0 entity list users
+mem0 entity list agents --output json
+mem0 entity delete --user-id alice --force
+```
+
+### `mem0 event`
+
+Inspect background processing events created by async operations (e.g. bulk deletes, large add jobs).
+
+```bash
+# List recent events
+mem0 event list
+
+# Check the status of a specific event
+mem0 event status <event-id>
+```
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Output format: `text`, `json` |
+
+### `mem0 status`
+
+Verify your API connection and display the current project.
+
+```bash
+mem0 status
+```
+
+### `mem0 version`
+
+Print the CLI version.
+
+```bash
+mem0 version
+```
+
+## Agent mode
+
+Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
+
+```bash
+mem0 --agent search "user preferences" --user-id alice
+mem0 --agent add "User prefers dark mode" --user-id alice
+mem0 --agent list --user-id alice
+mem0 --agent delete --all --user-id alice --force
+```
+
+Every command returns the same envelope shape:
+
+```json
+{
+  "status": "success",
+  "command": "search",
+  "duration_ms": 134,
+  "scope": { "user_id": "alice" },
+  "count": 2,
+  "data": [
+    { "id": "abc-123", "memory": "User prefers dark mode", "score": 0.97, "created_at": "2026-01-15", "categories": ["preferences"] }
+  ]
+}
+```
+
+What agent mode does differently from `--output json`:
+
+- **Sanitized `data`**: only the fields an agent needs (id, memory, score, etc.) — no internal API noise
+- **No human output**: spinners, colors, and banners are suppressed entirely
+- **Errors as JSON**: errors go to stdout as `{"status": "error", "command": "...", "error": "..."}` with a non-zero exit code
+
+Use `mem0 help --json` to get the full command tree as JSON — useful for agents that need to self-discover available commands.
+
+## Output formats
+
+Control how results are displayed with `--output`:
+
+| Format | Description |
+|--------|-------------|
+| `text` | Human-readable with colors and formatting (default) |
+| `json` | Structured JSON for piping to `jq` (raw API response) |
+| `table` | Tabular format (default for `list`) |
+| `quiet` | Minimal — just IDs or status codes |
+| `agent` | Structured JSON envelope with sanitized fields (set by `--agent`/`--json`) |
+
+## Global flags
+
+These flags are available on all commands:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Enable agent mode: structured JSON envelope output, no colors or spinners |
+| `--agent` | Alias for `--json` |
+| `--api-key` | Override the configured API key for this request |
+| `--base-url` | Override the configured API base URL for this request |
+| `-o, --output` | Set the output format |
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `MEM0_API_KEY` | API key (overrides config file) |
+| `MEM0_BASE_URL` | API base URL |
+| `MEM0_USER_ID` | Default user ID |
+| `MEM0_AGENT_ID` | Default agent ID |
+| `MEM0_APP_ID` | Default app ID |
+| `MEM0_RUN_ID` | Default run ID |
+| `MEM0_ENABLE_GRAPH` | Enable graph memory (`true` / `false`) |
+
+Environment variables take precedence over values in the config file, which take precedence over defaults.
+
+## Development
+
+```bash
+cd cli/python
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run during development
+python -m mem0_cli --help
+mem0 add "test memory" --user-id alice
+```
+
+## Releasing
+
+1. Update `version` in `pyproject.toml`
+2. Create a GitHub Release with tag `cli-v<version>` (e.g. `cli-v0.2.1`)
+
+For a pre-release, use a beta version like `0.2.1b1` and check the **pre-release** checkbox.
+
+## Documentation
+
+Full documentation is available at [docs.mem0.ai/platform/cli](https://docs.mem0.ai/platform/cli).
+
 ## License
 
 Apache-2.0

cli/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mem0-cli"
-version = "0.1.0"
+version = "0.2.4"
 description = "The official CLI for mem0 — the memory layer for AI agents"
 readme = "README.md"
 license = "Apache-2.0"

cli/python/src/mem0_cli/__init__.py

@@ -1,3 +1,3 @@
 """mem0 CLI — the command-line interface for the mem0 memory layer."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.4"

cli/python/src/mem0_cli/app.py

@@ -2,7 +2,10 @@
 
 from __future__ import annotations
 
+import contextlib
 import json as _json
+import os
+import stat as _stat_mod
 import sys
 from pathlib import Path
 
@@ -10,7 +13,7 @@ import typer
 from rich.console import Console
 
 from mem0_cli import __version__
-from mem0_cli.branding import BRAND_COLOR, print_error
+from mem0_cli.branding import BRAND_COLOR, print_error, print_warning
 
 console = Console()
 err_console = Console(stderr=True)
@@ -43,7 +46,52 @@ entity_app = typer.Typer(
     no_args_is_help=True,
     rich_markup_mode="rich",
 )
-# entity_app registered after Memory commands to control panel ordering
+
+event_app = typer.Typer(
+    name="event",
+    help="Inspect background processing events.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+# entity_app and event_app registered after Memory commands to control panel ordering
+
+
+# ── Validated user identity (set by _get_backend_and_config) ──────────────
+
+_validated_user_email: str | None = None
+
+# ── Telemetry helper ─────────────────────────────────────────────────────
+
+
+def _fire_telemetry(command_name: str, extra: dict | None = None) -> None:
+    """Fire a PostHog telemetry event (non-blocking, never fails)."""
+    try:
+        from mem0_cli.telemetry import capture_event
+
+        props = {"command": command_name}
+        if extra:
+            props.update(extra)
+        capture_event(f"cli.{command_name}", props, pre_resolved_email=_validated_user_email)
+    except Exception:
+        pass
+
+
+@config_app.callback(invoke_without_command=True)
+def _config_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"config.{ctx.invoked_subcommand}")
+
+
+@entity_app.callback(invoke_without_command=True)
+def _entity_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"entity.{ctx.invoked_subcommand}")
+
+
+@event_app.callback(invoke_without_command=True)
+def _event_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"event.{ctx.invoked_subcommand}")
 
 
 # ── Helpers ───────────────────────────────────────────────────────────────
@@ -53,9 +101,16 @@ def _get_backend_and_config(
     api_key: str | None = None,
     base_url: str | None = None,
 ):
-    """Build and return the Platform backend plus the loaded config."""
+    """Build and return the Platform backend plus the loaded config.
+
+    Validates the API key upfront via ``/v1/ping/`` and caches the
+    resolved user email for telemetry.
+    """
+    global _validated_user_email
+
     from mem0_cli.backend import get_backend
-    from mem0_cli.config import load_config
+    from mem0_cli.backend.platform import AuthError
+    from mem0_cli.config import load_config, save_config
 
     config = load_config()
 
@@ -72,7 +127,29 @@ def _get_backend_and_config(
         )
         raise typer.Exit(1)
 
-    return get_backend(config), config
+    backend = get_backend(config)
+
+    # Validate the API key upfront with a fast timeout
+    try:
+        ping_data = backend.ping(timeout=5.0)
+        email = ping_data.get("user_email") if isinstance(ping_data, dict) else None
+        if email:
+            _validated_user_email = email
+            if config.platform.user_email != email:
+                config.platform.user_email = email
+                with contextlib.suppress(Exception):
+                    save_config(config)
+    except AuthError:
+        print_error(
+            err_console,
+            "Invalid or expired API key.",
+            hint="Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+        )
+        raise typer.Exit(1) from None
+    except Exception:
+        print_warning(err_console, "Could not validate API key (network issue). Proceeding anyway.")
+
+    return backend, config
 
 
 def _get_backend(
@@ -114,9 +191,22 @@ def _resolve_ids(
     }
 
 
+def _stdin_is_piped() -> bool:
+    """Return True only when stdin is an actual pipe or file redirect — not a bare open fd."""
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return False
+    try:
+        mode = os.fstat(sys.stdin.fileno()).st_mode
+        return _stat_mod.S_ISFIFO(mode) or _stat_mod.S_ISREG(mode)
+    except Exception:
+        return False
+
+
 def _read_stdin() -> str | None:
-    """Read from stdin if it is piped (not a TTY)."""
-    if not sys.stdin.isatty():
+    """Read from stdin if it is an actual pipe or file redirect (not a TTY, not agent mode)."""
+    if _stdin_is_piped():
         return sys.stdin.read().strip() or None
     return None
 
@@ -128,12 +218,26 @@ def _read_stdin() -> str | None:
 def main_callback(
     ctx: typer.Context,
     version: bool = typer.Option(False, "--version", help="Show version and exit."),
+    json_agent: bool = typer.Option(
+        False,
+        "--json",
+        "--agent",
+        help="Output as JSON for agent/programmatic use.",
+        is_eager=False,
+    ),
 ) -> None:
+    if json_agent:
+        from mem0_cli.state import set_agent_mode
+
+        set_agent_mode(True)
     if version:
         from mem0_cli.commands.utils import cmd_version
 
+        _fire_telemetry("version")
         cmd_version()
         raise typer.Exit()
+    if ctx.invoked_subcommand:
+        _fire_telemetry(ctx.invoked_subcommand)
 
 
 # ── Memory: add ───────────────────────────────────────────────────────────
@@ -163,8 +267,6 @@ def add(
     categories: str | None = typer.Option(
         None, "--categories", help="Categories (JSON array or comma-separated)."
     ),
-    graph: bool = typer.Option(False, "--graph", help="Enable graph memory extraction."),
-    no_graph: bool = typer.Option(False, "--no-graph", help="Disable graph memory extraction."),
     output: str = typer.Option(
         "text", "--output", "-o", help="Output format: text, json, quiet.", rich_help_panel="Output"
     ),
@@ -191,13 +293,6 @@ def add(
     backend, config = _get_backend_and_config(api_key, base_url)
     ids = _resolve_ids(config, user_id=user_id, agent_id=agent_id, app_id=app_id, run_id=run_id)
 
-    if no_graph:
-        graph_enabled = False
-    elif graph:
-        graph_enabled = True
-    else:
-        graph_enabled = config.defaults.enable_graph
-
     cmd_add(
         backend,
         text,
@@ -209,7 +304,6 @@ def add(
         no_infer=no_infer,
         expires=expires,
         categories=categories,
-        enable_graph=graph_enabled,
         output=output,
     )
 
@@ -253,8 +347,6 @@ def search(
         help="Specific fields to return (comma-separated).",
         rich_help_panel="Search",
     ),
-    graph: bool = typer.Option(False, "--graph", help="Enable graph in search.", rich_help_panel="Search"),
-    no_graph: bool = typer.Option(False, "--no-graph", help="Disable graph in search.", rich_help_panel="Search"),
     output: str = typer.Option(
         "text", "--output", "-o", help="Output: text, json, table.", rich_help_panel="Output"
     ),
@@ -269,7 +361,7 @@ def search(
         None, "--base-url", help="Override API base URL.", rich_help_panel="Connection"
     ),
 ) -> None:
-    """Search memories by semantic query.
+    """Query your memory store — semantic, keyword, or hybrid retrieval.
 
     Examples:
       mem0 search "preferences" --user-id alice
@@ -281,20 +373,13 @@ def search(
     # STEP 7: stdin fallback for query
     if query is None:
         query = _read_stdin()
-    if query is None:
-        print_error(err_console, "No query provided. Pass a query argument or pipe via stdin.")
+    if not query or not query.strip():
+        print_error(err_console, "Search query cannot be empty.")
         raise typer.Exit(1)
 
     backend, config = _get_backend_and_config(api_key, base_url)
     ids = _resolve_ids(config, user_id=user_id, agent_id=agent_id, app_id=app_id, run_id=run_id)
 
-    if no_graph:
-        graph_enabled = False
-    elif graph:
-        graph_enabled = True
-    else:
-        graph_enabled = config.defaults.enable_graph
-
     cmd_search(
         backend,
         query,
@@ -305,7 +390,6 @@ def search(
         keyword=keyword,
         filter_json=filter_json,
         fields=fields,
-        enable_graph=graph_enabled,
         output=output,
     )
 
@@ -372,8 +456,6 @@ def list_cmd(
     before: str | None = typer.Option(
         None, "--before", help="Created before (YYYY-MM-DD).", rich_help_panel="Filters"
     ),
-    graph: bool = typer.Option(False, "--graph", help="Enable graph in listing.", rich_help_panel="Filters"),
-    no_graph: bool = typer.Option(False, "--no-graph", help="Disable graph in listing.", rich_help_panel="Filters"),
     output: str = typer.Option(
         "table", "--output", "-o", help="Output: text, json, table.", rich_help_panel="Output"
     ),
@@ -399,13 +481,6 @@ def list_cmd(
     backend, config = _get_backend_and_config(api_key, base_url)
     ids = _resolve_ids(config, user_id=user_id, agent_id=agent_id, app_id=app_id, run_id=run_id)
 
-    if no_graph:
-        graph_enabled = False
-    elif graph:
-        graph_enabled = True
-    else:
-        graph_enabled = config.defaults.enable_graph
-
     cmd_list(
         backend,
         **ids,
@@ -414,7 +489,6 @@ def list_cmd(
         category=category,
         after=after,
         before=before,
-        enable_graph=graph_enabled,
         output=output,
     )
 
@@ -463,11 +537,19 @@ def update(
 
 @app.command(rich_help_panel="Memory")
 def delete(
-    memory_id: str | None = typer.Argument(None, help="Memory ID to delete (omit when using --all or --entity)."),
+    memory_id: str | None = typer.Argument(
+        None, help="Memory ID to delete (omit when using --all or --entity)."
+    ),
     all_: bool = typer.Option(False, "--all", help="Delete all memories matching scope filters."),
-    entity: bool = typer.Option(False, "--entity", help="Delete the entity itself and all its memories (cascade)."),
-    project: bool = typer.Option(False, "--project", help="With --all: delete ALL memories project-wide."),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be deleted without deleting."),
+    entity: bool = typer.Option(
+        False, "--entity", help="Delete the entity itself and all its memories (cascade)."
+    ),
+    project: bool = typer.Option(
+        False, "--project", help="With --all: delete ALL memories project-wide."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would be deleted without deleting."
+    ),
     force: bool = typer.Option(False, "--force", help="Skip confirmation."),
     user_id: str | None = typer.Option(
         None, "--user-id", "-u", help="Scope to user.", rich_help_panel="Scope"
@@ -522,12 +604,14 @@ def delete(
 
     # ── Dispatch ─────────────────────────────────────────────────────
     if memory_id is not None:
+        _fire_telemetry("delete", {"delete_mode": "single"})
         from mem0_cli.commands.memory import cmd_delete
 
         backend = _get_backend(api_key, base_url)
         cmd_delete(backend, memory_id, dry_run=dry_run, force=force, output=output)
 
     elif all_:
+        _fire_telemetry("delete", {"delete_mode": "all"})
         from mem0_cli.commands.memory import cmd_delete_all
 
         backend, config = _get_backend_and_config(api_key, base_url)
@@ -535,6 +619,7 @@ def delete(
         cmd_delete_all(backend, force=force, dry_run=dry_run, all_=project, **ids, output=output)
 
     else:  # --entity
+        _fire_telemetry("delete", {"delete_mode": "entity"})
         from mem0_cli.commands.entities import cmd_entities_delete
 
         backend = _get_backend(api_key, base_url)
@@ -641,14 +726,12 @@ def entity_delete(
     agent_id: str | None = typer.Option(
         None, "--agent-id", help="Agent ID.", rich_help_panel="Scope"
     ),
-    app_id: str | None = typer.Option(
-        None, "--app-id", help="App ID.", rich_help_panel="Scope"
-    ),
-    run_id: str | None = typer.Option(
-        None, "--run-id", help="Run ID.", rich_help_panel="Scope"
-    ),
+    app_id: str | None = typer.Option(None, "--app-id", help="App ID.", rich_help_panel="Scope"),
+    run_id: str | None = typer.Option(None, "--run-id", help="Run ID.", rich_help_panel="Scope"),
     force: bool = typer.Option(False, "--force", help="Skip confirmation."),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be deleted without deleting."),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would be deleted without deleting."
+    ),
     output: str = typer.Option(
         "text", "--output", "-o", help="Output: text, json, quiet.", rich_help_panel="Output"
     ),
@@ -688,23 +771,98 @@ def entity_delete(
 app.add_typer(entity_app, name="entity", rich_help_panel="Management")
 
 
+# ── Event subcommands ─────────────────────────────────────────────────────
+
+
+@event_app.command("list")
+def event_list(
+    output: str = typer.Option(
+        "table", "--output", "-o", help="Output: table, json.", rich_help_panel="Output"
+    ),
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="Override API key.",
+        envvar="MEM0_API_KEY",
+        rich_help_panel="Connection",
+    ),
+    base_url: str | None = typer.Option(
+        None, "--base-url", help="Override API base URL.", rich_help_panel="Connection"
+    ),
+) -> None:
+    """List recent background processing events.
+
+    Examples:
+      mem0 event list
+      mem0 event list -o json
+    """
+    from mem0_cli.commands.events_cmd import cmd_event_list
+
+    backend = _get_backend(api_key, base_url)
+    cmd_event_list(backend, output=output)
+
+
+@event_app.command("status")
+def event_status(
+    event_id: str = typer.Argument(..., help="Event ID to inspect."),
+    output: str = typer.Option(
+        "text", "--output", "-o", help="Output: text, json.", rich_help_panel="Output"
+    ),
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="Override API key.",
+        envvar="MEM0_API_KEY",
+        rich_help_panel="Connection",
+    ),
+    base_url: str | None = typer.Option(
+        None, "--base-url", help="Override API base URL.", rich_help_panel="Connection"
+    ),
+) -> None:
+    """Check the status of a specific background event.
+
+    Examples:
+      mem0 event status <event-id>
+      mem0 event status <event-id> -o json
+    """
+    from mem0_cli.commands.events_cmd import cmd_event_status
+
+    backend = _get_backend(api_key, base_url)
+    cmd_event_status(backend, event_id, output=output)
+
+
+# ── Event subgroup ──
+app.add_typer(event_app, name="event", rich_help_panel="Management")
+
+
 # ── Management commands ───────────────────────────────────────────────────
 
 
 @app.command(rich_help_panel="Management")
 def init(
     api_key: str | None = typer.Option(None, "--api-key", help="API key (skip prompt)."),
-    user_id: str | None = typer.Option(None, "--user-id", "-u", help="Default user ID (skip prompt)."),
+    user_id: str | None = typer.Option(
+        None, "--user-id", "-u", help="Default user ID (skip prompt)."
+    ),
+    email: str | None = typer.Option(None, "--email", help="Login via email verification code."),
+    code: str | None = typer.Option(
+        None, "--code", help="Verification code (use with --email for non-interactive login)."
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite existing config without confirmation."
+    ),
 ) -> None:
     """Interactive setup wizard for mem0 CLI.
 
     Examples:
       mem0 init
       mem0 init --api-key m0-xxx --user-id alice
+      mem0 init --email alice@company.com
+      mem0 init --email alice@company.com --code 482901
     """
     from mem0_cli.commands.init_cmd import run_init
 
-    run_init(api_key=api_key, user_id=user_id)
+    run_init(api_key=api_key, user_id=user_id, email=email, code=code, force=force)
 
 
 # (entity_app registered at module level, below sub-group definitions)
@@ -743,7 +901,6 @@ def status(
     )
 
 
-
 @app.command("import", rich_help_panel="Management")
 def import_cmd(
     file_path: str = typer.Argument(..., help="JSON file to import."),
@@ -810,7 +967,7 @@ def _build_help_json() -> dict:
             },
         },
         "search": {
-            "description": "Search memories by semantic query.",
+            "description": "Query your memory store — semantic, keyword, or hybrid retrieval.",
             "usage": "mem0 search <query> [OPTIONS]",
             "arguments": {"query": {"description": "Search query.", "required": False}},
             "options": {
@@ -914,6 +1071,24 @@ def _build_help_json() -> dict:
                 "value": {"description": "Value to set.", "required": True},
             },
         },
+        "event": {
+            "description": "Inspect background processing events.",
+            "subcommands": {
+                "list": {
+                    "description": "List recent background processing events.",
+                    "usage": "mem0 event list [OPTIONS]",
+                    "options": {"--output, -o": "Output format: table, json."},
+                },
+                "status": {
+                    "description": "Check the status of a specific background event.",
+                    "usage": "mem0 event status <event_id> [OPTIONS]",
+                    "arguments": {
+                        "event_id": {"description": "Event ID to inspect.", "required": True}
+                    },
+                    "options": {"--output, -o": "Output format: text, json."},
+                },
+            },
+        },
         "entity": {
             "description": "Manage entities.",
             "subcommands": {
@@ -965,6 +1140,7 @@ def _build_help_json() -> dict:
         "global_options": {
             "--api-key": "Override API key (env: MEM0_API_KEY).",
             "--base-url": "Override API base URL.",
+            "--json / --agent": "Output as JSON for agent/programmatic use.",
             "--help": "Show help for a command.",
             "--version": "Show version and exit.",
         },
@@ -994,7 +1170,7 @@ def help(
         console.print("Usage: mem0 <command> [OPTIONS]\n")
         console.print("[bold]Commands:[/]")
         console.print("  add              Add a memory from text, messages, file, or stdin")
-        console.print("  search           Search memories by semantic query")
+        console.print("  search           Query your memory store (semantic, keyword, hybrid)")
         console.print("  get              Get a specific memory by ID")
         console.print("  list             List memories with optional filters")
         console.print("  update           Update a memory's text or metadata")
@@ -1002,6 +1178,7 @@ def help(
         console.print("  import           Import memories from a JSON file")
         console.print("  config           Manage configuration (show, get, set)")
         console.print("  entity           Manage entities (list, delete)")
+        console.print("  event            Inspect background events (list, status)")
         console.print("  init             Interactive setup wizard")
         console.print("  status           Check connectivity and authentication")
         console.print()
@@ -1018,4 +1195,14 @@ app.add_typer(config_app, name="config", rich_help_panel="Management")
 
 
 def main() -> None:
+    import sys
+
+    # Allow --json/--agent anywhere in the command line (not just before subcommand).
+    _json_flags = {"--json", "--agent"}
+    if any(a in _json_flags for a in sys.argv[1:]):
+        from mem0_cli.state import set_agent_mode
+
+        set_agent_mode(True)
+        sys.argv = [sys.argv[0]] + [a for a in sys.argv[1:] if a not in _json_flags]
+
     app()

cli/python/src/mem0_cli/backend/base.py

@@ -26,7 +26,6 @@ class Backend(ABC):
         infer: bool = True,
         expires: str | None = None,
         categories: list[str] | None = None,
-        enable_graph: bool = False,
     ) -> dict: ...
 
     @abstractmethod
@@ -44,7 +43,6 @@ class Backend(ABC):
         keyword: bool = False,
         filters: dict | None = None,
         fields: list[str] | None = None,
-        enable_graph: bool = False,
     ) -> list[dict]: ...
 
     @abstractmethod
@@ -63,7 +61,6 @@ class Backend(ABC):
         category: str | None = None,
         after: str | None = None,
         before: str | None = None,
-        enable_graph: bool = False,
     ) -> list[dict]: ...
 
     @abstractmethod
@@ -104,6 +101,11 @@ class Backend(ABC):
     @abstractmethod
     def entities(self, entity_type: str) -> list[dict]: ...
 
+    @abstractmethod
+    def list_events(self) -> list[dict]: ...
+
+    @abstractmethod
+    def get_event(self, event_id: str) -> dict: ...
 
 
 def get_backend(config: Mem0Config) -> Backend:

cli/python/src/mem0_cli/backend/platform.py

@@ -6,6 +6,7 @@ from typing import Any
 
 import httpx
 
+from mem0_cli import __version__
 from mem0_cli.backend.base import Backend
 from mem0_cli.config import PlatformConfig
 
@@ -21,11 +22,17 @@ class PlatformBackend(Backend):
             headers={
                 "Authorization": f"Token {config.api_key}",
                 "Content-Type": "application/json",
+                "X-Mem0-Source": "cli",
+                "X-Mem0-Client-Language": "python",
+                "X-Mem0-Client-Version": __version__,
             },
             timeout=30.0,
         )
 
     def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        from mem0_cli.state import is_agent_mode
+
+        self._client.headers["X-Mem0-Caller-Type"] = "agent" if is_agent_mode() else "user"
         resp = self._client.request(method, path, **kwargs)
         if resp.status_code == 401:
             raise AuthError("Authentication failed. Your API key may be invalid or expired.")
@@ -57,7 +64,6 @@ class PlatformBackend(Backend):
         infer: bool = True,
         expires: str | None = None,
         categories: list[str] | None = None,
-        enable_graph: bool = False,
     ) -> dict:
         payload: dict[str, Any] = {}
 
@@ -84,10 +90,9 @@ class PlatformBackend(Backend):
             payload["expiration_date"] = expires
         if categories:
             payload["categories"] = categories
-        if enable_graph:
-            payload["enable_graph"] = True
+        payload["source"] = "CLI"
 
-        return self._request("POST", "/v1/memories/", json=payload)
+        return self._request("POST", "/v3/memories/add/", json=payload)
 
     def _build_filters(
         self,
@@ -98,7 +103,7 @@ class PlatformBackend(Backend):
         run_id: str | None = None,
         extra_filters: dict | None = None,
     ) -> dict | None:
-        """Build a filters dict for v2 API endpoints.
+        """Build a filters dict for v3 API endpoints.
 
         Entity IDs are ANDed (all provided IDs must match).
         Extra filters (date ranges, categories) are also ANDed.
@@ -144,7 +149,6 @@ class PlatformBackend(Backend):
         keyword: bool = False,
         filters: dict | None = None,
         fields: list[str] | None = None,
-        enable_graph: bool = False,
     ) -> list[dict]:
         payload: dict[str, Any] = {"query": query, "top_k": top_k, "threshold": threshold}
 
@@ -163,10 +167,9 @@ class PlatformBackend(Backend):
             payload["keyword_search"] = True
         if fields:
             payload["fields"] = fields
-        if enable_graph:
-            payload["enable_graph"] = True
+        payload["source"] = "CLI"
 
-        result = self._request("POST", "/v2/memories/search/", json=payload)
+        result = self._request("POST", "/v3/memories/search/", json=payload)
         return (
             result
             if isinstance(result, list)
@@ -174,7 +177,7 @@ class PlatformBackend(Backend):
         )
 
     def get(self, memory_id: str) -> dict:
-        return self._request("GET", f"/v1/memories/{memory_id}/")
+        return self._request("GET", f"/v1/memories/{memory_id}/", params={"source": "CLI"})
 
     def list_memories(
         self,
@@ -188,12 +191,11 @@ class PlatformBackend(Backend):
         category: str | None = None,
         after: str | None = None,
         before: str | None = None,
-        enable_graph: bool = False,
     ) -> list[dict]:
         payload: dict[str, Any] = {}
         params = {"page": str(page), "page_size": str(page_size)}
 
-        # Build filters for v2 API — entity IDs and date filters go inside "filters"
+        # Build filters — entity IDs and date filters go inside "filters"
         extra: dict[str, Any] = {}
         if category:
             extra["categories"] = {"contains": category}
@@ -211,10 +213,9 @@ class PlatformBackend(Backend):
         )
         if api_filters:
             payload["filters"] = api_filters
-        if enable_graph:
-            payload["enable_graph"] = True
+        payload["source"] = "CLI"
 
-        result = self._request("POST", "/v2/memories/", json=payload, params=params)
+        result = self._request("POST", "/v3/memories/", json=payload, params=params)
         return (
             result
             if isinstance(result, list)
@@ -229,6 +230,7 @@ class PlatformBackend(Backend):
             payload["text"] = content
         if metadata:
             payload["metadata"] = metadata
+        payload["source"] = "CLI"
         return self._request("PUT", f"/v1/memories/{memory_id}/", json=payload)
 
     def delete(
@@ -242,7 +244,7 @@ class PlatformBackend(Backend):
         run_id: str | None = None,
     ) -> dict:
         if all:
-            params: dict[str, str] = {}
+            params: dict[str, str] = {"source": "CLI"}
             if user_id:
                 params["user_id"] = user_id
             if agent_id:
@@ -253,7 +255,7 @@ class PlatformBackend(Backend):
                 params["run_id"] = run_id
             return self._request("DELETE", "/v1/memories/", params=params)
         elif memory_id:
-            return self._request("DELETE", f"/v1/memories/{memory_id}/")
+            return self._request("DELETE", f"/v1/memories/{memory_id}/", params={"source": "CLI"})
         else:
             raise ValueError("Either memory_id or --all is required")
 
@@ -265,18 +267,37 @@ class PlatformBackend(Backend):
         app_id: str | None = None,
         run_id: str | None = None,
     ) -> dict:
-        params: dict[str, str] = {}
-        if user_id:
-            params["user_id"] = user_id
-        if agent_id:
-            params["agent_id"] = agent_id
-        if app_id:
-            params["app_id"] = app_id
-        if run_id:
-            params["run_id"] = run_id
-        if not params:
+        # v2 endpoint: DELETE /v2/entities/{entity_type}/{entity_id}/
+        type_map = {
+            "user": user_id,
+            "agent": agent_id,
+            "app": app_id,
+            "run": run_id,
+        }
+        entities = {t: v for t, v in type_map.items() if v}
+        if not entities:
             raise ValueError("At least one entity ID is required for delete_entities.")
-        return self._request("DELETE", "/v1/entities/", params=params)
+        # Delete each provided entity via the v2 path-based endpoint
+        result: dict = {}
+        for entity_type, entity_id in entities.items():
+            result = self._request(
+                "DELETE", f"/v2/entities/{entity_type}/{entity_id}/", params={"source": "CLI"}
+            )
+        return result
+
+    def ping(self, timeout: float | None = None) -> dict:
+        """Call the ping endpoint and return the raw response.
+
+        When *timeout* is given it overrides the client-level timeout so that
+        validation pings can fail fast without blocking the user.
+        """
+        if timeout is not None:
+            resp = self._client.get("/v1/ping/", timeout=timeout)
+            if resp.status_code == 401:
+                raise AuthError("Authentication failed. Your API key may be invalid or expired.")
+            resp.raise_for_status()
+            return resp.json()
+        return self._request("GET", "/v1/ping/")
 
     def status(
         self,
@@ -284,19 +305,9 @@ class PlatformBackend(Backend):
         user_id: str | None = None,
         agent_id: str | None = None,
     ) -> dict[str, Any]:
-        """Check connectivity by making a lightweight API call."""
+        """Check connectivity using the ping endpoint."""
         try:
-            # If entity IDs are available, validate with a minimal memories list
-            if user_id or agent_id:
-                payload: dict[str, Any] = {}
-                params = {"page": "1", "page_size": "1"}
-                api_filters = self._build_filters(user_id=user_id, agent_id=agent_id)
-                if api_filters:
-                    payload["filters"] = api_filters
-                self._request("POST", "/v2/memories/", json=payload, params=params)
-            else:
-                # No entity IDs — use entities endpoint to validate API key
-                self._request("GET", "/v1/entities/")
+            self.ping()
             return {"connected": True, "backend": "platform", "base_url": self.base_url}
         except Exception as e:
             return {"connected": False, "backend": "platform", "error": str(e)}
@@ -311,6 +322,12 @@ class PlatformBackend(Backend):
             items = [e for e in items if e.get("type", "").lower() == target_type]
         return items
 
+    def list_events(self) -> list[dict]:
+        result = self._request("GET", "/v1/events/")
+        return result if isinstance(result, list) else result.get("results", [])
+
+    def get_event(self, event_id: str) -> dict:
+        return self._request("GET", f"/v1/event/{event_id}/")
 
 
 class AuthError(Exception):

cli/python/src/mem0_cli/branding.py

@@ -43,6 +43,10 @@ def _sym(fancy: str, plain: str) -> str:
 
 def print_banner(console: Console) -> None:
     """Print the mem0 welcome banner."""
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return
     logo_text = Text(LOGO, style=f"bold {BRAND_COLOR}")
     tagline = Text(f"  {TAGLINE}\n", style=f"{ACCENT_COLOR}")
 
@@ -61,11 +65,28 @@ def print_banner(console: Console) -> None:
 
 
 def print_success(console: Console, message: str) -> None:
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return
     sym = _sym("✓", "[ok]")
     console.print(f"[{SUCCESS_COLOR}]{sym}[/] {message}")
 
 
 def print_error(console: Console, message: str, hint: str | None = None) -> None:
+    from mem0_cli.state import get_current_command, is_agent_mode
+
+    if is_agent_mode():
+        import json as _json
+
+        envelope = {
+            "status": "error",
+            "command": get_current_command(),
+            "error": message,
+            "data": None,
+        }
+        print(_json.dumps(envelope))
+        return
     sym = _sym("✗", "[error]")
     console.print(f"[{ERROR_COLOR}]{sym} Error:[/] {message}")
     if hint:
@@ -73,11 +94,19 @@ def print_error(console: Console, message: str, hint: str | None = None) -> None
 
 
 def print_warning(console: Console, message: str) -> None:
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return
     sym = _sym("⚠", "[warn]")
     console.print(f"[{WARNING_COLOR}]{sym}[/] {message}")
 
 
 def print_info(console: Console, message: str) -> None:
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return
     sym = _sym("◆", "*")
     console.print(f"[{BRAND_COLOR}]{sym}[/] {message}")
 
@@ -89,7 +118,9 @@ def timed_status(console: Console, message: str):
     The spinner and timing output are sent to stderr (via ``_err``) so they
     never contaminate machine-readable stdout.  The *console* parameter is
     kept for backward compatibility but is not used for spinner output.
+    In agent mode the spinner is suppressed entirely.
     """
+    from mem0_cli.state import is_agent_mode
 
     class _Ctx:
         def __init__(self):
@@ -97,6 +128,13 @@ def timed_status(console: Console, message: str):
             self.error_msg = ""
 
     ctx = _Ctx()
+    if is_agent_mode():
+        try:
+            yield ctx
+        except Exception:
+            raise
+        return
+
     start = time.perf_counter()
     try:
         with Status(f"[{DIM_COLOR}]{message}[/]", console=_err):
@@ -105,6 +143,11 @@ def timed_status(console: Console, message: str):
         elapsed = time.perf_counter() - start
         if ctx.error_msg:
             print_error(_err, f"{ctx.error_msg} ({elapsed:.2f}s)")
+            if "Authentication failed" in ctx.error_msg:
+                _err.print(
+                    f"  [{DIM_COLOR}]Run [bold]mem0 init[/bold] to reconfigure your API key"
+                    f" · [bold]https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-python[/bold][/]"
+                )
         raise
     else:
         elapsed = time.perf_counter() - start
@@ -114,11 +157,14 @@ def timed_status(console: Console, message: str):
 
 def print_scope(console: Console, **ids: str | None) -> None:
     """Show active entity scope if any IDs are set."""
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return
     parts = []
     for key, val in ids.items():
         if val:
-            label = key.replace("_", " ").replace("id", "ID").strip()
-            parts.append(f"{label}={val}")
+            parts.append(f"{key}={val}")
     if parts:
         scope_str = ", ".join(parts)
         console.print(f"  [{DIM_COLOR}]Scope: {scope_str}[/]")

cli/python/src/mem0_cli/commands/config_cmd.py

@@ -20,12 +20,17 @@ err_console = Console(stderr=True)
 
 def cmd_config_show(*, output: str = "text") -> None:
     """Display current configuration (secrets redacted)."""
-    from mem0_cli.output import format_json_envelope
+    from mem0_cli.output import format_agent_envelope
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("config show")
+    if is_agent_mode():
+        output = "agent"
 
     config = load_config()
 
-    if output == "json":
-        format_json_envelope(
+    if output in ("json", "agent"):
+        format_agent_envelope(
             console,
             command="config show",
             data={
@@ -34,7 +39,6 @@ def cmd_config_show(*, output: str = "text") -> None:
                     "agent_id": config.defaults.agent_id or None,
                     "app_id": config.defaults.app_id or None,
                     "run_id": config.defaults.run_id or None,
-                    "enable_graph": config.defaults.enable_graph,
                 },
                 "platform": {
                     "api_key": redact_key(config.platform.api_key),
@@ -68,10 +72,6 @@ def cmd_config_show(*, output: str = "text") -> None:
         "defaults.run_id",
         config.defaults.run_id or f"[{DIM_COLOR}](not set)[/]",
     )
-    table.add_row(
-        "defaults.enable_graph",
-        str(config.defaults.enable_graph).lower(),
-    )
     table.add_row("", "")
 
     # Platform
@@ -84,25 +84,44 @@ def cmd_config_show(*, output: str = "text") -> None:
 
 def cmd_config_get(key: str) -> None:
     """Get a config value."""
+    from mem0_cli.output import format_agent_envelope
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("config get")
     config = load_config()
     value = get_nested_value(config, key)
 
     if value is None:
         print_error(err_console, f"Unknown config key: {key}")
+        return
+
+    display_value = (
+        redact_key(str(value)) if ("api_key" in key or "key" in key.split(".")[-1:]) else str(value)
+    )
+
+    if is_agent_mode():
+        format_agent_envelope(
+            console, command="config get", data={"key": key, "value": display_value}
+        )
     else:
-        # Redact secrets
-        if "api_key" in key or "key" in key.split(".")[-1:]:
-            console.print(redact_key(str(value)))
-        else:
-            console.print(str(value))
+        console.print(display_value)
 
 
 def cmd_config_set(key: str, value: str) -> None:
     """Set a config value."""
+    from mem0_cli.output import format_agent_envelope
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("config set")
     config = load_config()
     if set_nested_value(config, key, value):
         save_config(config)
         display = redact_key(value) if "key" in key else value
-        print_success(console, f"{key} = {display}")
+        if is_agent_mode():
+            format_agent_envelope(
+                console, command="config set", data={"key": key, "value": display}
+            )
+        else:
+            print_success(console, f"{key} = {display}")
     else:
         print_error(err_console, f"Unknown config key: {key}")

cli/python/src/mem0_cli/commands/entities.py

@@ -18,7 +18,7 @@ from mem0_cli.branding import (
     print_success,
     timed_status,
 )
-from mem0_cli.output import format_json
+from mem0_cli.output import format_agent_envelope, format_json
 
 console = Console()
 err_console = Console(stderr=True)
@@ -26,9 +26,16 @@ err_console = Console(stderr=True)
 
 def cmd_entities_list(backend: Backend, entity_type: str, *, output: str) -> None:
     """List entities of a given type."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("entity list")
+    if is_agent_mode():
+        output = "agent"
     valid_types = {"users", "agents", "apps", "runs"}
     if entity_type not in valid_types:
-        print_error(err_console, f"Invalid entity type: {entity_type}. Use: {', '.join(valid_types)}")
+        print_error(
+            err_console, f"Invalid entity type: {entity_type}. Use: {', '.join(valid_types)}"
+        )
         raise typer.Exit(1)
 
     _start = _time.perf_counter()
@@ -40,6 +47,16 @@ def cmd_entities_list(backend: Backend, entity_type: str, *, output: str) -> Non
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="entity list",
+            data=results,
+            count=len(results),
+            duration_ms=int(_elapsed * 1000),
+        )
+        return
+
     if output == "json":
         format_json(console, results)
         return
@@ -75,39 +92,39 @@ def cmd_entities_delete(
     output: str,
 ) -> None:
     """Delete an entity and all its memories (cascade delete)."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("entity delete")
+    if is_agent_mode():
+        output = "agent"
+        if not force:
+            print_error(err_console, "Destructive operation requires --force in agent mode.")
+            raise typer.Exit(1)
     if not any([user_id, agent_id, app_id, run_id]):
-        print_error(err_console, "Provide at least one of --user-id, --agent-id, --app-id, --run-id.")
+        print_error(
+            err_console, "Provide at least one of --user-id, --agent-id, --app-id, --run-id."
+        )
         raise typer.Exit(1)
 
+    scope_parts = []
+    if user_id:
+        scope_parts.append(f"user={user_id}")
+    if agent_id:
+        scope_parts.append(f"agent={agent_id}")
+    if app_id:
+        scope_parts.append(f"app={app_id}")
+    if run_id:
+        scope_parts.append(f"run={run_id}")
+    scope_str = ", ".join(scope_parts)
+
     if dry_run:
-        scope_parts = []
-        if user_id:
-            scope_parts.append(f"user={user_id}")
-        if agent_id:
-            scope_parts.append(f"agent={agent_id}")
-        if app_id:
-            scope_parts.append(f"app={app_id}")
-        if run_id:
-            scope_parts.append(f"run={run_id}")
-        scope = ", ".join(scope_parts)
-        print_info(console, f"Would delete entity {scope} and all its memories.")
+        print_info(console, f"Would delete entity {scope_str} and all its memories.")
         print_info(console, "No changes made (dry run).")
         return
 
     if not force:
-        scope_parts = []
-        if user_id:
-            scope_parts.append(f"user={user_id}")
-        if agent_id:
-            scope_parts.append(f"agent={agent_id}")
-        if app_id:
-            scope_parts.append(f"app={app_id}")
-        if run_id:
-            scope_parts.append(f"run={run_id}")
-        scope = ", ".join(scope_parts)
-
         confirm = typer.confirm(
-            f"\n  \u26a0  Delete entity {scope} AND all its memories? This cannot be undone."
+            f"\n  \u26a0  Delete entity {scope_str} AND all its memories? This cannot be undone."
         )
         if not confirm:
             print_info(console, "Cancelled.")
@@ -127,7 +144,25 @@ def cmd_entities_delete(
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
+    scope = {
+        k: v
+        for k, v in {
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "app_id": app_id,
+            "run_id": run_id,
+        }.items()
+        if v
+    }
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="entity delete",
+            data={"deleted": True},
+            scope=scope or None,
+            duration_ms=int(_elapsed * 1000),
+        )
+    elif output == "json":
         format_json(console, result)
     elif output != "quiet":
         print_success(console, f"Entity deleted with all memories ({_elapsed:.2f}s)")

cli/python/src/mem0_cli/commands/events_cmd.py

@@ -0,0 +1,176 @@
+"""Event commands: list and status."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from mem0_cli.backend.base import Backend
+from mem0_cli.branding import (
+    ACCENT_COLOR,
+    BRAND_COLOR,
+    DIM_COLOR,
+    ERROR_COLOR,
+    SUCCESS_COLOR,
+    WARNING_COLOR,
+    print_info,
+    timed_status,
+)
+from mem0_cli.output import format_agent_envelope, format_json
+
+console = Console()
+err_console = Console(stderr=True)
+
+_STATUS_STYLE = {
+    "SUCCEEDED": f"[{SUCCESS_COLOR}]SUCCEEDED[/]",
+    "PENDING": f"[{ACCENT_COLOR}]PENDING[/]",
+    "FAILED": f"[{ERROR_COLOR}]FAILED[/]",
+    "PROCESSING": f"[{WARNING_COLOR}]PROCESSING[/]",
+}
+
+
+def _status_styled(status: str) -> str:
+    return _STATUS_STYLE.get(status.upper(), status)
+
+
+def cmd_event_list(backend: Backend, *, output: str = "table") -> None:
+    """List recent background events."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("event list")
+    if is_agent_mode():
+        output = "agent"
+    import time as _time
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Fetching events...") as _ts:
+        try:
+            results = backend.list_events()
+        except Exception as e:
+            _ts.error_msg = str(e)
+            raise typer.Exit(1) from None
+
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="event list",
+            data=results,
+            count=len(results),
+            duration_ms=int(_elapsed * 1000),
+        )
+        return
+
+    if output == "json":
+        format_json(console, results)
+        return
+
+    if not results:
+        console.print()
+        print_info(console, "No events found.")
+        console.print()
+        return
+
+    table = Table(
+        border_style=BRAND_COLOR,
+        header_style=f"bold {ACCENT_COLOR}",
+        row_styles=["", "dim"],
+        padding=(0, 1),
+    )
+    table.add_column("Event ID", style="dim", max_width=10, no_wrap=True)
+    table.add_column("Type", max_width=14)
+    table.add_column("Status", max_width=12)
+    table.add_column("Latency", max_width=10, justify="right")
+    table.add_column("Created", max_width=20)
+
+    for ev in results:
+        ev_id = str(ev.get("id", ""))[:8]
+        ev_type = str(ev.get("event_type", "—"))
+        status = str(ev.get("status", "—"))
+        latency = ev.get("latency")
+        latency_str = f"{latency:.0f}ms" if isinstance(latency, (int, float)) else "—"
+        created = str(ev.get("created_at", "—"))[:19].replace("T", " ")
+        table.add_row(ev_id, ev_type, _status_styled(status), latency_str, created)
+
+    console.print()
+    console.print(table)
+    console.print(f"  [{DIM_COLOR}]{len(results)} event{'s' if len(results) != 1 else ''}[/]")
+    console.print()
+
+
+def cmd_event_status(backend: Backend, event_id: str, *, output: str = "text") -> None:
+    """Get the status of a specific background event."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("event status")
+    if is_agent_mode():
+        output = "agent"
+    import time as _time
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Fetching event...") as _ts:
+        try:
+            ev = backend.get_event(event_id)
+        except Exception as e:
+            _ts.error_msg = str(e)
+            raise typer.Exit(1) from None
+
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="event status",
+            data=ev,
+            duration_ms=int(_elapsed * 1000),
+        )
+        return
+
+    if output == "json":
+        format_json(console, ev)
+        return
+
+    status = str(ev.get("status", "—"))
+    ev_type = str(ev.get("event_type", "—"))
+    latency = ev.get("latency")
+    latency_str = f"{latency:.0f}ms" if isinstance(latency, (int, float)) else "—"
+    created = str(ev.get("created_at", "—"))[:19].replace("T", " ")
+    updated = str(ev.get("updated_at", "—"))[:19].replace("T", " ")
+    results = ev.get("results")
+
+    lines = []
+    lines.append(f"  [{DIM_COLOR}]Event ID:[/]     {event_id}")
+    lines.append(f"  [{DIM_COLOR}]Type:[/]         {ev_type}")
+    lines.append(f"  [{DIM_COLOR}]Status:[/]       {_status_styled(status)}")
+    lines.append(f"  [{DIM_COLOR}]Latency:[/]      {latency_str}")
+    lines.append(f"  [{DIM_COLOR}]Created:[/]      {created}")
+    lines.append(f"  [{DIM_COLOR}]Updated:[/]      {updated}")
+
+    if results:
+        lines.append("")
+        lines.append(f"  [{DIM_COLOR}]Results ({len(results)}):[/]")
+        for r in results:
+            mem_id = str(r.get("id", ""))[:8]
+            data = r.get("data", {})
+            memory = data.get("memory", "") if isinstance(data, dict) else str(data)
+            ev_name = str(r.get("event", ""))
+            user = str(r.get("user_id", ""))
+            detail = f"{ev_name}  {memory}"
+            if user:
+                detail += f"  [{DIM_COLOR}](user_id={user})[/]"
+            lines.append(f"    [{SUCCESS_COLOR}]·[/] {detail}  [{DIM_COLOR}]({mem_id})[/]")
+
+    content = "\n".join(lines)
+    panel = Panel(
+        content,
+        title=f"[{BRAND_COLOR}]Event Status[/]",
+        title_align="left",
+        border_style=BRAND_COLOR,
+        padding=(1, 1),
+    )
+    console.print()
+    console.print(panel)
+    console.print()

cli/python/src/mem0_cli/commands/init_cmd.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import os
+import re
 import sys
 
+import httpx
 import typer
 from rich.console import Console
 from rich.prompt import Prompt
@@ -16,7 +19,13 @@ from mem0_cli.branding import (
     print_info,
     print_success,
 )
-from mem0_cli.config import Mem0Config, save_config
+from mem0_cli.config import (
+    CONFIG_FILE,
+    DEFAULT_BASE_URL,
+    Mem0Config,
+    load_config,
+    save_config,
+)
 
 console = Console()
 err_console = Console(stderr=True)
@@ -84,7 +93,96 @@ def _prompt_secret(label: str) -> str:
     return "".join(chars)
 
 
-def run_init(*, api_key: str | None = None, user_id: str | None = None) -> None:
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+def _validate_email(email: str) -> None:
+    """Exit with an error if *email* doesn't look like a valid address."""
+    if not _EMAIL_RE.match(email):
+        print_error(err_console, f"Invalid email address: {email!r}")
+        raise typer.Exit(1)
+
+
+def _email_login(
+    email: str,
+    code: str | None,
+    base_url: str,
+) -> dict:
+    """Run the email verification code login flow.
+
+    Returns the parsed JSON response from the verify endpoint.
+    The caller expects at minimum an ``api_key`` field.
+    """
+    url = base_url.rstrip("/")
+    _source_headers = {
+        "X-Mem0-Source": "cli",
+        "X-Mem0-Client-Language": "python",
+    }
+
+    with httpx.Client(timeout=30.0) as client:
+        # If code is already provided, skip sending — user already has a code
+        if not code:
+            # Step 1: Request verification code
+            resp = client.post(
+                f"{url}/api/v1/auth/email_code/",
+                json={"email": email},
+                headers=_source_headers,
+            )
+            if resp.status_code == 429:
+                print_error(err_console, "Too many attempts. Try again in a few minutes.")
+                raise typer.Exit(1)
+            if resp.status_code != 200:
+                try:
+                    detail = resp.json().get("error", resp.text)
+                except Exception:
+                    detail = resp.text
+                print_error(err_console, f"Failed to send code: {detail}")
+                raise typer.Exit(1)
+
+            print_success(console, "Verification code sent! Check your email.")
+
+            # Step 2: Get code from user
+            if not sys.stdin.isatty():
+                print_error(
+                    err_console,
+                    "No --code provided and terminal is non-interactive.",
+                    hint="Run: mem0 init --email <email> --code <code>",
+                )
+                raise typer.Exit(1)
+            console.print()
+            code = Prompt.ask(f"  [{BRAND_COLOR}]Verification Code[/]")
+            if not code:
+                print_error(err_console, "Code is required.")
+                raise typer.Exit(1)
+
+        # Step 3: Verify code
+        resp = client.post(
+            f"{url}/api/v1/auth/email_code/verify/",
+            json={"email": email, "code": code.strip()},
+            headers=_source_headers,
+        )
+        if resp.status_code == 429:
+            print_error(err_console, "Too many attempts. Try again in a few minutes.")
+            raise typer.Exit(1)
+        if resp.status_code != 200:
+            try:
+                detail = resp.json().get("error", resp.text)
+            except Exception:
+                detail = resp.text
+            print_error(err_console, f"Verification failed: {detail}")
+            raise typer.Exit(1)
+
+        return resp.json()
+
+
+def run_init(
+    *,
+    api_key: str | None = None,
+    user_id: str | None = None,
+    email: str | None = None,
+    code: str | None = None,
+    force: bool = False,
+) -> None:
     """Interactive setup wizard for mem0 CLI.
 
     When both *api_key* and *user_id* are supplied, all prompts are skipped
@@ -93,6 +191,85 @@ def run_init(*, api_key: str | None = None, user_id: str | None = None) -> None:
     """
     config = Mem0Config()
 
+    base_url = os.environ.get("MEM0_BASE_URL", config.platform.base_url or DEFAULT_BASE_URL)
+
+    if code and not email:
+        print_error(err_console, "--code requires --email.")
+        raise typer.Exit(1)
+
+    # Warn if an existing config with an API key would be overwritten
+    if not force and CONFIG_FILE.exists():
+        existing = load_config()
+        if existing.platform.api_key:
+            from mem0_cli.config import redact_key
+
+            console.print(
+                f"\n  [{BRAND_COLOR}]Existing configuration found[/] "
+                f"[{DIM_COLOR}](API key: {redact_key(existing.platform.api_key)})[/]"
+            )
+            if sys.stdin.isatty():
+                confirm = typer.confirm("  Overwrite existing config? This cannot be undone.")
+                if not confirm:
+                    print_info(console, "Cancelled. Use --force to skip this check.")
+                    raise typer.Exit(0)
+            else:
+                print_error(
+                    err_console,
+                    "Existing config would be overwritten.",
+                    hint="Use --force to overwrite.",
+                )
+                raise typer.Exit(1)
+
+    # ── Email login flow ──────────────────────────────────────────────
+    if email:
+        if api_key:
+            print_error(err_console, "Cannot use both --api-key and --email.")
+            raise typer.Exit(1)
+
+        email = email.strip().lower()
+        _validate_email(email)
+
+        print_banner(console)
+        console.print()
+        print_info(console, f"Logging in as {email}...\n")
+
+        result = _email_login(email, code, base_url)
+
+        api_key_val = result.get("api_key")
+        if not api_key_val:
+            print_error(err_console, "Auth succeeded but no API key was returned. Contact support.")
+            raise typer.Exit(1)
+        config.platform.api_key = api_key_val
+        config.platform.base_url = base_url
+        config.platform.user_email = email
+        config.defaults.user_id = (
+            user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
+        )
+
+        save_config(config)
+
+        console.print()
+        print_success(console, "Authenticated! Configuration saved to ~/.mem0/config.json")
+        console.print()
+        console.print(f"  [{DIM_COLOR}]Get started:[/]")
+        console.print(f'  [{DIM_COLOR}]  mem0 add "I prefer dark mode"[/]')
+        console.print(f'  [{DIM_COLOR}]  mem0 search "preferences"[/]')
+        console.print()
+        return
+
+    # ── API key flow (existing) ───────────────────────────────────────
+
+    # Non-TTY: resolve defaults so partial flags work in pipelines / CI
+    if not sys.stdin.isatty():
+        if not api_key:
+            print_error(
+                err_console,
+                "Non-interactive terminal detected and --api-key is required.",
+                hint="Run: mem0 init --api-key <key> [--user-id <id>]",
+            )
+            raise typer.Exit(1)
+        user_id = user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
+
     # Fully non-interactive when both flags provided
     if api_key and user_id:
         config.platform.api_key = api_key
@@ -102,20 +279,56 @@ def run_init(*, api_key: str | None = None, user_id: str | None = None) -> None:
         print_success(console, "Configuration saved to ~/.mem0/config.json")
         return
 
-    # Non-TTY without full flags -> error
-    if not sys.stdin.isatty() and (not api_key or not user_id):
-        print_error(
-            err_console,
-            "Non-interactive terminal detected and required flags missing.",
-            hint="Run: mem0 init --api-key <key> --user-id <id>",
-        )
-        raise typer.Exit(1)
-
     print_banner(console)
     console.print()
     print_info(console, "Welcome! Let's set up your mem0 CLI.\n")
 
-    # Use provided flags or prompt
+    # If no flags at all, ask user how they want to authenticate
+    if not api_key:
+        console.print(f"  [{BRAND_COLOR}]How would you like to authenticate?[/]")
+        console.print(f"  [{DIM_COLOR}]1.[/] Login with email [{DIM_COLOR}](recommended)[/]")
+        console.print(f"  [{DIM_COLOR}]2.[/] Enter API key manually")
+        console.print()
+        choice = Prompt.ask(f"  [{BRAND_COLOR}]Choose[/]", choices=["1", "2"], default="1")
+
+        if choice == "1":
+            console.print()
+            email_addr = Prompt.ask(f"  [{BRAND_COLOR}]Email[/]")
+            if not email_addr:
+                print_error(err_console, "Email is required.")
+                raise typer.Exit(1)
+
+            email_addr = email_addr.strip().lower()
+            _validate_email(email_addr)
+            print_info(console, f"Logging in as {email_addr}...\n")
+
+            result = _email_login(email_addr, None, base_url)
+
+            api_key_val = result.get("api_key")
+            if not api_key_val:
+                print_error(
+                    err_console, "Auth succeeded but no API key was returned. Contact support."
+                )
+                raise typer.Exit(1)
+            config.platform.api_key = api_key_val
+            config.platform.base_url = base_url
+            config.platform.user_email = email_addr
+            config.defaults.user_id = (
+                user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
+            )
+
+            save_config(config)
+
+            console.print()
+            print_success(console, "Authenticated! Configuration saved to ~/.mem0/config.json")
+            console.print()
+            console.print(f"  [{DIM_COLOR}]Get started:[/]")
+            console.print(f'  [{DIM_COLOR}]  mem0 add "I prefer dark mode"[/]')
+            console.print(f'  [{DIM_COLOR}]  mem0 search "preferences"[/]')
+            console.print()
+            return
+
+    # API key flow
     if api_key:
         config.platform.api_key = api_key
     else:
@@ -145,7 +358,9 @@ def run_init(*, api_key: str | None = None, user_id: str | None = None) -> None:
 def _setup_platform(config: Mem0Config) -> None:
     """Platform setup flow."""
     console.print()
-    console.print(f"  [{DIM_COLOR}]Get your API key at https://app.mem0.ai/dashboard/api-keys[/]")
+    console.print(
+        f"  [{DIM_COLOR}]Get your API key at https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-python[/]"
+    )
     console.print()
 
     console.print(f"  [{BRAND_COLOR}]API Key[/]: ", end="")
@@ -162,9 +377,10 @@ def _setup_defaults(config: Mem0Config) -> None:
     console.print()
     print_info(console, "Set default entity IDs (press Enter to skip).\n")
 
+    _default_user = os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
     user_id = Prompt.ask(
         f"  [{BRAND_COLOR}]Default User ID[/] [{DIM_COLOR}](recommended)[/]",
-        default="mem0-cli",
+        default=_default_user,
     )
     if user_id:
         config.defaults.user_id = user_id
@@ -184,11 +400,19 @@ def _validate_platform(config: Mem0Config) -> None:
         )
         if status.get("connected"):
             print_success(console, "Connected to mem0 Platform!")
+            # Cache user_email from ping response for telemetry distinct_id
+            try:
+                ping_data = backend.ping()
+                user_email = ping_data.get("user_email") if isinstance(ping_data, dict) else None
+                if user_email:
+                    config.platform.user_email = user_email
+            except Exception:
+                pass
         else:
             print_error(
                 err_console,
                 f"Could not connect: {status.get('error', 'Unknown error')}",
-                hint="Check your API key and try again.",
+                hint="Visit https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-python to get a new key, then run mem0 init again.",
             )
     except Exception as e:
         print_error(err_console, f"Connection test failed: {e}")

cli/python/src/mem0_cli/commands/memory.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import json
+import os
+import stat as _stat_mod
 import sys
 import time as _time
 from pathlib import Path
@@ -20,6 +22,7 @@ from mem0_cli.branding import (
 )
 from mem0_cli.output import (
     format_add_result,
+    format_agent_envelope,
     format_json,
     format_memories_table,
     format_memories_text,
@@ -31,6 +34,19 @@ console = Console()
 err_console = Console(stderr=True)
 
 
+def _stdin_is_piped() -> bool:
+    """Return True only when stdin is an actual pipe or file redirect."""
+    from mem0_cli.state import is_agent_mode
+
+    if is_agent_mode():
+        return False
+    try:
+        mode = os.fstat(sys.stdin.fileno()).st_mode
+        return _stat_mod.S_ISFIFO(mode) or _stat_mod.S_ISREG(mode)
+    except Exception:
+        return False
+
+
 def cmd_add(
     backend: Backend,
     text: str | None,
@@ -46,10 +62,14 @@ def cmd_add(
     no_infer: bool,
     expires: str | None,
     categories: str | None,
-    enable_graph: bool = False,
     output: str = "text",
 ) -> None:
     """Add a memory."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("add")
+    if is_agent_mode():
+        output = "agent"
     msgs = None
     content = text
 
@@ -70,8 +90,8 @@ def cmd_add(
             print_error(err_console, f"Invalid JSON in --messages: {e}")
             raise typer.Exit(1) from None
 
-    # Read from stdin if no text and stdin is piped
-    elif not content and not sys.stdin.isatty():
+    # Read from stdin only if stdin is an actual pipe or file redirect
+    elif not content and _stdin_is_piped():
         content = sys.stdin.read().strip()
 
     if not content and not msgs:
@@ -95,6 +115,21 @@ def cmd_add(
         except json.JSONDecodeError:
             cats = [c.strip() for c in categories.split(",")]
 
+    # Validate --expires
+    if expires:
+        import re
+
+        if not re.match(r"^\d{4}-\d{2}-\d{2}$", expires):
+            print_error(
+                err_console, "Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31)."
+            )
+            raise typer.Exit(1)
+        from datetime import date
+
+        if date.fromisoformat(expires) <= date.today():
+            print_error(err_console, "--expires date must be in the future.")
+            raise typer.Exit(1)
+
     with timed_status(err_console, "Adding memory...") as ts:
         try:
             result = backend.add(
@@ -109,28 +144,69 @@ def cmd_add(
                 infer=not no_infer,
                 expires=expires,
                 categories=cats,
-                enable_graph=enable_graph,
             )
         except Exception as e:
             ts.error_msg = str(e)
-            print_error(err_console, str(e))
             raise typer.Exit(1) from None
 
     if output == "quiet":
         return
 
+    # Deduplicate PENDING entries sharing the same event_id across all output modes
+    results_list = result if isinstance(result, list) else result.get("results", [result])
+    seen_events: set[str] = set()
+    deduped: list[dict] = []
+    for r in results_list:
+        if r.get("status") == "PENDING":
+            eid = r.get("event_id", "")
+            if eid and eid in seen_events:
+                continue
+            if eid:
+                seen_events.add(eid)
+        deduped.append(r)
+    # Write back so downstream formatters see deduplicated data
+    if isinstance(result, dict) and "results" in result:
+        result = {**result, "results": deduped}
+    else:
+        result = deduped
+
+    if output == "agent":
+        scope = {
+            k: v
+            for k, v in {
+                "user_id": user_id,
+                "agent_id": agent_id,
+                "app_id": app_id,
+                "run_id": run_id,
+            }.items()
+            if v
+        }
+        format_agent_envelope(
+            console,
+            command="add",
+            data=deduped,
+            scope=scope or None,
+            count=len(deduped),
+        )
+        return
+
     if output == "json":
         format_add_result(console, result, output)
         return
 
     console.print()
     print_scope(console, user_id=user_id, agent_id=agent_id, app_id=app_id, run_id=run_id)
-    # Count results
-    results = result if isinstance(result, list) else result.get("results", [result])
-    count = len(results) if results else 0
-    print_success(
-        console, f"Memory processed — {count} memor{'y' if count == 1 else 'ies'} extracted"
-    )
+    count = len(deduped)
+    all_pending = count > 0 and all(r.get("status") == "PENDING" for r in deduped)
+    if all_pending:
+        print_success(
+            console,
+            f"Memory queued — {count} event{'s' if count != 1 else ''} pending",
+        )
+    else:
+        print_success(
+            console, f"Memory processed — {count} memor{'y' if count == 1 else 'ies'} extracted"
+        )
     format_add_result(console, result, output)
 
 
@@ -148,10 +224,14 @@ def cmd_search(
     keyword: bool,
     filter_json: str | None,
     fields: str | None,
-    enable_graph: bool = False,
     output: str = "text",
 ) -> None:
     """Search memories."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("search")
+    if is_agent_mode():
+        output = "agent"
     filters = None
     if filter_json:
         try:
@@ -164,6 +244,13 @@ def cmd_search(
     if fields:
         field_list = [f.strip() for f in fields.split(",")]
 
+    if top_k < 1:
+        print_error(err_console, "--top-k must be >= 1.")
+        raise typer.Exit(1)
+    if not (0.0 <= threshold <= 1.0):
+        print_error(err_console, "--threshold must be between 0.0 and 1.0.")
+        raise typer.Exit(1)
+
     _start = _time.perf_counter()
     with timed_status(err_console, "Searching memories...") as _ts:
         try:
@@ -179,18 +266,41 @@ def cmd_search(
                 keyword=keyword,
                 filters=filters,
                 fields=field_list,
-                enable_graph=enable_graph,
             )
         except Exception as e:
             print_error(err_console, str(e))
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
+    if output == "quiet":
+        return
+
+    if output == "agent":
+        scope = {
+            k: v
+            for k, v in {
+                "user_id": user_id,
+                "agent_id": agent_id,
+                "app_id": app_id,
+                "run_id": run_id,
+            }.items()
+            if v
+        }
+        format_agent_envelope(
+            console,
+            command="search",
+            data=results,
+            scope=scope or None,
+            count=len(results),
+            duration_ms=int(_elapsed * 1000),
+        )
+        return
+
     if output == "json":
         format_json(console, results)
     elif output == "table":
         if results:
-            format_memories_table(console, results)
+            format_memories_table(console, results, show_score=True)
             print_result_summary(
                 console, len(results), duration_secs=_elapsed, user_id=user_id, agent_id=agent_id
             )
@@ -212,6 +322,11 @@ def cmd_search(
 
 def cmd_get(backend: Backend, memory_id: str, *, output: str) -> None:
     """Get a specific memory by ID."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("get")
+    if is_agent_mode():
+        output = "agent"
     with timed_status(err_console, "Fetching memory...") as _ts:
         try:
             result = backend.get(memory_id)
@@ -219,7 +334,10 @@ def cmd_get(backend: Backend, memory_id: str, *, output: str) -> None:
             print_error(err_console, str(e))
             raise typer.Exit(1) from None
 
-    format_single_memory(console, result, output)
+    if output == "agent":
+        format_agent_envelope(console, command="get", data=result)
+    else:
+        format_single_memory(console, result, output)
 
 
 def cmd_list(
@@ -234,10 +352,21 @@ def cmd_list(
     category: str | None,
     after: str | None,
     before: str | None,
-    enable_graph: bool = False,
     output: str = "table",
 ) -> None:
     """List memories."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("list")
+    if is_agent_mode():
+        output = "agent"
+    if page_size < 1:
+        print_error(err_console, "--page-size must be >= 1.")
+        raise typer.Exit(1)
+    if page < 1:
+        print_error(err_console, "--page must be >= 1.")
+        raise typer.Exit(1)
+
     _start = _time.perf_counter()
     with timed_status(err_console, "Listing memories...") as _ts:
         try:
@@ -251,15 +380,34 @@ def cmd_list(
                 category=category,
                 after=after,
                 before=before,
-                enable_graph=enable_graph,
             )
         except Exception as e:
             print_error(err_console, str(e))
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
-        format_json(console, results)
+    if output == "quiet":
+        return
+
+    if output in ("json", "agent"):
+        scope = {
+            k: v
+            for k, v in {
+                "user_id": user_id,
+                "agent_id": agent_id,
+                "app_id": app_id,
+                "run_id": run_id,
+            }.items()
+            if v
+        }
+        format_agent_envelope(
+            console,
+            command="list",
+            data=results,
+            scope=scope or None,
+            count=len(results),
+            duration_ms=int(_elapsed * 1000),
+        )
     elif output == "table":
         if results:
             format_memories_table(console, results)
@@ -301,6 +449,11 @@ def cmd_update(
     output: str,
 ) -> None:
     """Update a memory."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("update")
+    if is_agent_mode():
+        output = "agent"
     meta = None
     if metadata:
         try:
@@ -318,7 +471,14 @@ def cmd_update(
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="update",
+            data=result,
+            duration_ms=int(_elapsed * 1000),
+        )
+    elif output == "json":
         format_json(console, result)
     elif output != "quiet":
         print_success(console, f"Memory {memory_id[:8]} updated ({_elapsed:.2f}s)")
@@ -333,6 +493,11 @@ def cmd_delete(
     output: str,
 ) -> None:
     """Delete a single memory by ID."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("delete")
+    if is_agent_mode():
+        output = "agent"
     if dry_run:
         # Fetch and display what would be deleted
         try:
@@ -353,7 +518,14 @@ def cmd_delete(
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="delete",
+            data={"id": memory_id, "deleted": True},
+            duration_ms=int(_elapsed * 1000),
+        )
+    elif output == "json":
         format_json(console, result)
     elif output != "quiet":
         print_success(console, f"Memory {memory_id[:8]} deleted ({_elapsed:.2f}s)")
@@ -372,12 +544,17 @@ def cmd_delete_all(
     output: str,
 ) -> None:
     """Delete all memories matching a scope."""
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("delete-all")
+    if is_agent_mode():
+        output = "agent"
+        if not force:
+            print_error(err_console, "Destructive operation requires --force in agent mode.")
+            raise typer.Exit(1)
     if all_:
         # Project-wide wipe using wildcard entity IDs
-        if dry_run:
-            print_info(console, "Would delete ALL memories project-wide.")
-            print_info(console, "No changes made (dry run).")
-            return
+        # Note: --dry-run is ignored here because the API has no count-before-delete endpoint.
 
         if not force:
             confirm = typer.confirm(
@@ -402,7 +579,14 @@ def cmd_delete_all(
                 raise typer.Exit(1) from None
         _elapsed = _time.perf_counter() - _start
 
-        if output == "json":
+        if output == "agent":
+            format_agent_envelope(
+                console,
+                command="delete-all",
+                data={"deleted": True, "scope": "project"},
+                duration_ms=int(_elapsed * 1000),
+            )
+        elif output == "json":
             format_json(console, result)
         elif output != "quiet":
             if isinstance(result, dict) and "message" in result:
@@ -460,7 +644,25 @@ def cmd_delete_all(
             raise typer.Exit(1) from None
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
+    scope = {
+        k: v
+        for k, v in {
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "app_id": app_id,
+            "run_id": run_id,
+        }.items()
+        if v
+    }
+    if output == "agent":
+        format_agent_envelope(
+            console,
+            command="delete-all",
+            data={"deleted": True},
+            scope=scope or None,
+            duration_ms=int(_elapsed * 1000),
+        )
+    elif output == "json":
         format_json(console, result)
     elif output != "quiet":
         if isinstance(result, dict) and "message" in result:

cli/python/src/mem0_cli/commands/utils.py

@@ -35,22 +35,26 @@ def cmd_status(
     output: str = "text",
 ) -> None:
     """Check connectivity and auth."""
-    from mem0_cli.output import format_json_envelope
+    from mem0_cli.output import format_agent_envelope
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("status")
+    if is_agent_mode():
+        output = "agent"
 
     _start = _time.perf_counter()
     with timed_status(err_console, "Checking connection...") as _ts:
         result = backend.status(user_id=user_id, agent_id=agent_id)
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
-        format_json_envelope(
+    if output in ("json", "agent"):
+        format_agent_envelope(
             console,
             command="status",
             data={
                 "connected": result.get("connected", False),
                 "backend": result.get("backend", "?"),
                 "base_url": result.get("base_url", ""),
-                "latency_ms": int(_elapsed * 1000),
             },
             duration_ms=int(_elapsed * 1000),
         )
@@ -67,6 +71,14 @@ def cmd_status(
         lines.append(f"  [{DIM_COLOR}]API URL:[/]  {result['base_url']}")
     if result.get("error"):
         lines.append(f"  [{ERROR_COLOR}]Error:[/]    {result['error']}")
+        if "Authentication failed" in str(result["error"]):
+            lines.append("")
+            lines.append(
+                f"  [{DIM_COLOR}]Run [bold]mem0 init[/bold] to reconfigure your API key[/]"
+            )
+            lines.append(
+                f"  [{DIM_COLOR}]Get a key at [bold]https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-python[/bold][/]"
+            )
     lines.append(f"  [{DIM_COLOR}]Latency:[/]  {_elapsed:.2f}s")
 
     content = "\n".join(lines)
@@ -96,7 +108,12 @@ def cmd_import(
     output: str = "text",
 ) -> None:
     """Import memories from a JSON file."""
-    from mem0_cli.output import format_json_envelope
+    from mem0_cli.output import format_agent_envelope
+    from mem0_cli.state import is_agent_mode, set_current_command
+
+    set_current_command("import")
+    if is_agent_mode():
+        output = "agent"
 
     try:
         data = json.loads(Path(file_path).read_text())
@@ -110,7 +127,9 @@ def cmd_import(
     added = 0
     failed = 0
     _start = _time.perf_counter()
-    for item in track(data, description=f"[{DIM_COLOR}]Importing memories...[/]", console=err_console):
+    for item in track(
+        data, description=f"[{DIM_COLOR}]Importing memories...[/]", console=err_console
+    ):
         content = item.get("memory", item.get("text", item.get("content", "")))
         if not content:
             failed += 1
@@ -127,11 +146,13 @@ def cmd_import(
             failed += 1
     _elapsed = _time.perf_counter() - _start
 
-    if output == "json":
-        format_json_envelope(
+    if output in ("json", "agent"):
+        scope = {k: v for k, v in {"user_id": user_id, "agent_id": agent_id}.items() if v}
+        format_agent_envelope(
             console,
             command="import",
-            data={"added": added, "failed": failed, "duration_s": round(_elapsed, 2)},
+            data={"added": added, "failed": failed},
+            scope=scope or None,
             duration_ms=int(_elapsed * 1000),
         )
         return

cli/python/src/mem0_cli/config.py

@@ -27,6 +27,7 @@ CONFIG_VERSION = 1
 class PlatformConfig:
     api_key: str = ""
     base_url: str = DEFAULT_BASE_URL
+    user_email: str = ""
 
 
 @dataclass
@@ -35,7 +36,11 @@ class DefaultsConfig:
     agent_id: str = ""
     app_id: str = ""
     run_id: str = ""
-    enable_graph: bool = False
+
+
+@dataclass
+class TelemetryConfig:
+    anonymous_id: str = ""
 
 
 @dataclass
@@ -43,6 +48,18 @@ class Mem0Config:
     version: int = CONFIG_VERSION
     defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
     platform: PlatformConfig = field(default_factory=PlatformConfig)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
+
+
+SHORT_KEY_ALIASES: dict[str, str] = {
+    "api_key": "platform.api_key",
+    "base_url": "platform.base_url",
+    "user_email": "platform.user_email",
+    "user_id": "defaults.user_id",
+    "agent_id": "defaults.agent_id",
+    "app_id": "defaults.app_id",
+    "run_id": "defaults.run_id",
+}
 
 
 def ensure_config_dir() -> Path:
@@ -65,13 +82,15 @@ def load_config() -> Mem0Config:
         plat = data.get("platform", {})
         config.platform.api_key = plat.get("api_key", "")
         config.platform.base_url = plat.get("base_url", DEFAULT_BASE_URL)
+        config.platform.user_email = plat.get("user_email", "")
 
         defaults = data.get("defaults", {})
         config.defaults.user_id = defaults.get("user_id", "")
         config.defaults.agent_id = defaults.get("agent_id", "")
         config.defaults.app_id = defaults.get("app_id", "")
         config.defaults.run_id = defaults.get("run_id", "")
-        config.defaults.enable_graph = defaults.get("enable_graph", False)
+        telemetry = data.get("telemetry", {})
+        config.telemetry.anonymous_id = telemetry.get("anonymous_id", "")
 
     # Environment variable overrides
     env_key = os.environ.get("MEM0_API_KEY")
@@ -98,10 +117,6 @@ def load_config() -> Mem0Config:
     if env_run_id:
         config.defaults.run_id = env_run_id
 
-    env_graph = os.environ.get("MEM0_ENABLE_GRAPH")
-    if env_graph:
-        config.defaults.enable_graph = env_graph.lower() in ("true", "1", "yes")
-
     return config
 
 
@@ -116,11 +131,14 @@ def save_config(config: Mem0Config) -> None:
             "agent_id": config.defaults.agent_id,
             "app_id": config.defaults.app_id,
             "run_id": config.defaults.run_id,
-            "enable_graph": config.defaults.enable_graph,
         },
         "platform": {
             "api_key": config.platform.api_key,
             "base_url": config.platform.base_url,
+            "user_email": config.platform.user_email,
+        },
+        "telemetry": {
+            "anonymous_id": config.telemetry.anonymous_id,
         },
     }
 
@@ -140,7 +158,8 @@ def redact_key(key: str) -> str:
 
 
 def get_nested_value(config: Mem0Config, dotted_key: str) -> Any:
-    """Get a config value by dotted path, e.g. 'platform.api_key'."""
+    """Get a config value by dotted path, e.g. 'platform.api_key' or short form 'api_key'."""
+    dotted_key = SHORT_KEY_ALIASES.get(dotted_key, dotted_key)
     parts = dotted_key.split(".")
     obj: Any = config
     for part in parts:
@@ -153,6 +172,7 @@ def get_nested_value(config: Mem0Config, dotted_key: str) -> Any:
 
 def set_nested_value(config: Mem0Config, dotted_key: str, value: str) -> bool:
     """Set a config value by dotted path. Returns True on success."""
+    dotted_key = SHORT_KEY_ALIASES.get(dotted_key, dotted_key)
     parts = dotted_key.split(".")
     obj: Any = config
     for part in parts[:-1]:

cli/python/src/mem0_cli/output.py

@@ -49,7 +49,9 @@ def format_memories_text(console: Console, memories: list[dict], title: str = "m
         console.print()
 
 
-def format_memories_table(console: Console, memories: list[dict]) -> None:
+def format_memories_table(
+    console: Console, memories: list[dict], *, show_score: bool = False
+) -> None:
     """Render memories in a rich table."""
     table = Table(
         border_style=BRAND_COLOR,
@@ -57,20 +59,34 @@ def format_memories_table(console: Console, memories: list[dict]) -> None:
         row_styles=["", "dim"],
         padding=(0, 1),
     )
-    table.add_column("ID", style="dim", max_width=10)
+    table.add_column("ID", style="dim", max_width=38, no_wrap=True)
+    if show_score:
+        table.add_column("Score", max_width=7, justify="right")
     table.add_column("Memory", max_width=50, no_wrap=False)
     table.add_column("Category", max_width=14)
     table.add_column("Created", max_width=12)
 
     for mem in memories:
-        mem_id = mem.get("id", "")[:8]
+        mem_id = mem.get("id", "")
         memory_text = mem.get("memory", mem.get("text", ""))
         if len(memory_text) > 60:
             memory_text = memory_text[:57] + "..."
         categories = mem.get("categories", [])
-        cat = categories[0] if isinstance(categories, list) and categories else "—"
+        if isinstance(categories, list) and categories:
+            cat = (
+                categories[0]
+                if len(categories) == 1
+                else f"{categories[0]} (+{len(categories) - 1})"
+            )
+        else:
+            cat = "—"
         created = _format_date(mem.get("created_at")) or "—"
-        table.add_row(mem_id, memory_text, cat, created)
+        if show_score:
+            score = mem.get("score")
+            score_str = f"{score:.2f}" if score is not None else "—"
+            table.add_row(mem_id, score_str, memory_text, cat, created)
+        else:
+            table.add_row(mem_id, memory_text, cat, created)
 
     console.print()
     console.print(table)
@@ -139,16 +155,23 @@ def format_add_result(console: Console, result: dict | list, output: str = "text
         return
 
     console.print()
+    seen_pending_events: set[str] = set()
     for r in results:
         # Detect async PENDING response from Platform API
         if r.get("status") == "PENDING":
-            event_id = r.get("event_id", "")[:8]
+            event_id = r.get("event_id", "")
+            # Deduplicate PENDING entries with the same event_id
+            if event_id and event_id in seen_pending_events:
+                continue
+            if event_id:
+                seen_pending_events.add(event_id)
             icon = f"[{ACCENT_COLOR}]{_sym('⧗', '...')}[/]"
             parts = [f"  {icon} [{DIM_COLOR}]{'Queued':<10}[/]"]
             parts.append("[white]Processing in background[/]")
-            if event_id:
-                parts.append(f"[{DIM_COLOR}](event {event_id})[/]")
             console.print("  ".join(parts))
+            if event_id:
+                console.print(f"  [{DIM_COLOR}]  event_id: {event_id}[/]")
+                console.print(f"  [{DIM_COLOR}]  → Check status: mem0 event status {event_id}[/]")
             continue
 
         event = r.get("event", "ADD")
@@ -209,6 +232,100 @@ def format_json_envelope(
     console.print_json(json.dumps(envelope, default=str))
 
 
+def sanitize_agent_data(command: str, data: Any) -> Any:
+    """Project API response data to minimal relevant fields for agent consumption."""
+
+    def pick(obj: dict, keys: list) -> dict:
+        return {k: obj[k] for k in keys if k in obj}
+
+    if data is None:
+        return data
+
+    if command == "add":
+        items = data if isinstance(data, list) else [data]
+        result = []
+        for item in items:
+            if item.get("status") == "PENDING":
+                result.append(pick(item, ["status", "event_id"]))
+            else:
+                result.append(pick(item, ["id", "memory", "event"]))
+        return result
+
+    if command == "search":
+        return [pick(r, ["id", "memory", "score", "created_at", "categories"]) for r in data]
+
+    if command == "list":
+        return [pick(r, ["id", "memory", "created_at", "categories"]) for r in data]
+
+    if command == "get":
+        return pick(data, ["id", "memory", "created_at", "updated_at", "categories", "metadata"])
+
+    if command == "update":
+        return pick(data, ["id", "memory"])
+
+    if command in ("delete", "delete-all", "entity delete"):
+        return data
+
+    if command == "entity list":
+        result = []
+        for r in data:
+            item = pick(r, ["type", "count"])
+            item["name"] = r.get("name") or r.get("id", "")
+            result.append(item)
+        return result
+
+    if command == "event list":
+        return [pick(r, ["id", "event_type", "status", "latency", "created_at"]) for r in data]
+
+    if command == "event status":
+        ev = data
+        raw_results = ev.get("results") or []
+        sanitized_results = []
+        for r in raw_results:
+            nested = r.get("data") or {}
+            memory = nested.get("memory") if isinstance(nested, dict) else None
+            sanitized_results.append(
+                {
+                    "id": r.get("id"),
+                    "event": r.get("event"),
+                    "user_id": r.get("user_id"),
+                    "memory": memory,
+                }
+            )
+        result = pick(ev, ["id", "event_type", "status", "latency", "created_at", "updated_at"])
+        result["results"] = sanitized_results
+        return result
+
+    # Pass-through: status, import, config show/get/set
+    return data
+
+
+def format_agent_envelope(
+    console: Console,
+    *,
+    command: str,
+    data: Any,
+    duration_ms: int | None = None,
+    scope: dict | None = None,
+    count: int | None = None,
+) -> None:
+    """Output structured JSON envelope for agent/programmatic use (--json/--agent mode)."""
+    envelope: dict[str, Any] = {
+        "status": "success",
+        "command": command,
+    }
+    if duration_ms is not None:
+        envelope["duration_ms"] = duration_ms
+    if scope:
+        filtered = {k: v for k, v in scope.items() if v}
+        if filtered:
+            envelope["scope"] = filtered
+    if count is not None:
+        envelope["count"] = count
+    envelope["data"] = sanitize_agent_data(command, data)
+    console.print_json(json.dumps(envelope, default=str))
+
+
 def print_result_summary(
     console: Console,
     count: int,
@@ -221,7 +338,7 @@ def print_result_summary(
     parts = [f"{count} result{'s' if count != 1 else ''}"]
     if page is not None:
         parts.append(f"page {page}")
-    scope_parts = [f"{k.replace('_', ' ')}={v}" for k, v in scope_ids.items() if v]
+    scope_parts = [f"{k}={v}" for k, v in scope_ids.items() if v]
     if scope_parts:
         parts.append(", ".join(scope_parts))
     if duration_secs is not None:

cli/python/src/mem0_cli/state.py

@@ -0,0 +1,24 @@
+"""Agent mode state — set by the root callback, read by commands and branding."""
+
+from __future__ import annotations
+
+_agent_mode: bool = False
+_current_command: str = ""
+
+
+def is_agent_mode() -> bool:
+    return _agent_mode
+
+
+def set_agent_mode(val: bool) -> None:
+    global _agent_mode
+    _agent_mode = val
+
+
+def get_current_command() -> str:
+    return _current_command
+
+
+def set_current_command(name: str) -> None:
+    global _current_command
+    _current_command = name

cli/python/src/mem0_cli/telemetry.py

@@ -0,0 +1,146 @@
+"""CLI telemetry — anonymous usage tracking via PostHog.
+
+Sends fire-and-forget events to PostHog by spawning a detached subprocess
+(telemetry_sender.py). The parent CLI process exits immediately; the
+subprocess handles email resolution, caching, and the HTTP POST.
+
+Disable with: MEM0_TELEMETRY=false
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import platform
+import subprocess
+import sys
+import uuid
+from typing import Any
+
+POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX"
+POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/"
+
+
+def _is_telemetry_enabled() -> bool:
+    val = os.environ.get("MEM0_TELEMETRY", "true").lower()
+    return val not in ("false", "0", "no")
+
+
+def _get_or_create_anonymous_id() -> str:
+    """Return a persistent per-machine anonymous ID, generating one if needed.
+
+    Stored in ~/.mem0/config.json under `telemetry.anonymous_id` so that
+    repeat runs on the same machine share one PostHog identity instead of
+    collapsing into a single shared fallback string.
+    """
+    from mem0_cli.config import load_config, save_config
+
+    config = load_config()
+    if config.telemetry.anonymous_id:
+        return config.telemetry.anonymous_id
+
+    new_id = f"cli-anon-{uuid.uuid4().hex}"
+    config.telemetry.anonymous_id = new_id
+    with contextlib.suppress(Exception):
+        save_config(config)
+    return new_id
+
+
+def _get_distinct_id() -> str:
+    """Return a stable anonymous identifier for the current user.
+
+    Priority: cached user_email (from /v1/ping/) > MD5(api_key) >
+    persistent per-machine anonymous ID.
+    """
+    try:
+        from mem0_cli.config import load_config
+
+        config = load_config()
+        if config.platform.user_email:
+            return config.platform.user_email
+        if config.platform.api_key:
+            return hashlib.md5(config.platform.api_key.encode()).hexdigest()
+    except Exception:
+        pass
+    try:
+        return _get_or_create_anonymous_id()
+    except Exception:
+        return f"cli-anon-{uuid.uuid4().hex}"
+
+
+def capture_event(
+    event_name: str,
+    properties: dict[str, Any] | None = None,
+    pre_resolved_email: str | None = None,
+) -> None:
+    """Fire a PostHog event via a detached subprocess (non-blocking).
+
+    When *pre_resolved_email* is provided (e.g. from an upfront ping
+    validation), it is used directly as the PostHog distinct ID and the
+    subprocess skips its own ``/v1/ping/`` call.
+    """
+    if not _is_telemetry_enabled():
+        return
+
+    try:
+        from mem0_cli import __version__
+        from mem0_cli.config import CONFIG_FILE, load_config, save_config
+        from mem0_cli.state import is_agent_mode
+
+        config = load_config()
+        distinct_id = pre_resolved_email or _get_distinct_id()
+
+        # Detect anonymous → identified transition. If a stored anonymous_id
+        # exists and we just resolved to a real identity, fire a one-shot
+        # $identify event so PostHog stitches the pre-signup history onto
+        # the authenticated profile. Clear the stored id so we don't re-alias.
+        anon_id_to_alias: str | None = None
+        if (
+            distinct_id
+            and not distinct_id.startswith("cli-anon-")
+            and config.telemetry.anonymous_id
+        ):
+            anon_id_to_alias = config.telemetry.anonymous_id
+            config.telemetry.anonymous_id = ""
+            with contextlib.suppress(Exception):
+                save_config(config)
+
+        payload = {
+            "api_key": POSTHOG_API_KEY,
+            "distinct_id": distinct_id,
+            "event": event_name,
+            "properties": {
+                "source": "CLI",
+                "language": "python",
+                "cli_version": __version__,
+                "agent_mode": is_agent_mode(),
+                "python_version": sys.version,
+                "os": sys.platform,
+                "os_version": platform.version(),
+                "$process_person_profile": False,
+                "$lib": "posthog-python",
+                **(properties or {}),
+            },
+        }
+
+        context = {
+            "payload": payload,
+            "posthog_host": POSTHOG_HOST,
+            "needs_email": not distinct_id or "@" not in distinct_id,
+            "mem0_api_key": config.platform.api_key or "",
+            "mem0_base_url": config.platform.base_url or "https://api.mem0.ai",
+            "config_path": str(CONFIG_FILE),
+            "anon_distinct_id_to_alias": anon_id_to_alias,
+        }
+
+        subprocess.Popen(
+            [sys.executable, "-m", "mem0_cli.telemetry_sender", json.dumps(context)],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+            close_fds=True,
+        )
+    except Exception:
+        pass

cli/python/src/mem0_cli/telemetry_sender.py

@@ -0,0 +1,108 @@
+"""Standalone telemetry sender — runs as a detached subprocess.
+
+Usage: python -m mem0_cli.telemetry_sender '<json context>'
+
+This module is spawned by telemetry.capture_event() and runs independently
+of the parent CLI process. It:
+
+1. Resolves the user's email via /v1/ping/ if not already cached
+2. Caches the email in ~/.mem0/config.json for future runs
+3. Sends the PostHog event
+
+All errors are silently swallowed — this process must never produce output
+or affect the user experience.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.request
+
+
+def main() -> None:
+    ctx = json.loads(sys.argv[1])
+    payload = ctx["payload"]
+
+    if ctx.get("needs_email") and ctx.get("mem0_api_key"):
+        _resolve_and_cache_email(ctx, payload)
+
+    # Fire $identify *after* email resolution so PostHog links the stored
+    # anonymous id directly to the final identity (email, not the api-key
+    # hash). The regular event is sent next so it lands under the merged
+    # profile.
+    anon_id = ctx.get("anon_distinct_id_to_alias")
+    if anon_id:
+        _send_identify_event(ctx, payload, anon_id)
+
+    _send_posthog_event(ctx["posthog_host"], payload)
+
+
+def _send_identify_event(ctx: dict, payload: dict, anon_id: str) -> None:
+    """Send a PostHog $identify event aliasing anon_id → payload['distinct_id']."""
+    identify_payload = {
+        "api_key": payload["api_key"],
+        "event": "$identify",
+        "distinct_id": payload["distinct_id"],
+        "properties": {
+            "$anon_distinct_id": anon_id,
+            "$lib": payload.get("properties", {}).get("$lib", "posthog-python"),
+        },
+    }
+    _send_posthog_event(ctx["posthog_host"], identify_payload)
+
+
+def _resolve_and_cache_email(ctx: dict, payload: dict) -> None:
+    """Call /v1/ping/ to get the user's email, update the payload, and cache it."""
+    try:
+        ping_url = ctx["mem0_base_url"].rstrip("/") + "/v1/ping/"
+        req = urllib.request.Request(
+            ping_url,
+            headers={
+                "Authorization": "Token " + ctx["mem0_api_key"],
+                "Content-Type": "application/json",
+            },
+        )
+        resp = urllib.request.urlopen(req, timeout=10)
+        data = json.loads(resp.read())
+        email = data.get("user_email")
+        if email:
+            payload["distinct_id"] = email
+            _cache_email(ctx.get("config_path"), email)
+    except Exception:
+        pass
+
+
+def _cache_email(config_path: str | None, email: str) -> None:
+    """Write user_email into the config file for future runs."""
+    if not config_path:
+        return
+    try:
+        with open(config_path) as f:
+            cfg = json.load(f)
+        cfg.setdefault("platform", {})["user_email"] = email
+        with open(config_path, "w") as f:
+            json.dump(cfg, f, indent=2)
+    except Exception:
+        pass
+
+
+def _send_posthog_event(posthog_host: str, payload: dict) -> None:
+    """POST the event to PostHog."""
+    try:
+        body = json.dumps(payload).encode()
+        req = urllib.request.Request(
+            posthog_host,
+            data=body,
+            headers={"Content-Type": "application/json"},
+        )
+        urllib.request.urlopen(req, timeout=10)
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":
+    import contextlib
+
+    with contextlib.suppress(Exception):
+        main()

cli/python/tests/conftest.py

@@ -96,6 +96,43 @@ def mock_backend():
         {"name": "alice", "count": 5},
         {"name": "bob", "count": 3},
     ]
+    backend.list_events.return_value = [
+        {
+            "id": "evt-abc-123-def-456",
+            "event_type": "ADD",
+            "status": "SUCCEEDED",
+            "graph_status": None,
+            "latency": 1234.5,
+            "created_at": "2026-04-01T10:00:00Z",
+            "updated_at": "2026-04-01T10:00:01Z",
+        },
+        {
+            "id": "evt-def-456-ghi-789",
+            "event_type": "SEARCH",
+            "status": "PENDING",
+            "graph_status": None,
+            "latency": None,
+            "created_at": "2026-04-01T10:01:00Z",
+            "updated_at": "2026-04-01T10:01:00Z",
+        },
+    ]
+    backend.get_event.return_value = {
+        "id": "evt-abc-123-def-456",
+        "event_type": "ADD",
+        "status": "SUCCEEDED",
+        "graph_status": "SUCCEEDED",
+        "latency": 1234.5,
+        "created_at": "2026-04-01T10:00:00Z",
+        "updated_at": "2026-04-01T10:00:01Z",
+        "results": [
+            {
+                "id": "mem-abc-123",
+                "event": "ADD",
+                "user_id": "alice",
+                "data": {"memory": "User prefers dark mode"},
+            }
+        ],
+    }
 
     return backend
 

cli/python/tests/test_cli_integration.py

@@ -8,11 +8,19 @@ boundaries).
 from __future__ import annotations
 
 import os
+import re
 import subprocess
 import sys
 
 import pytest
 
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[mKJHABCDfsu]")
+
+
+def _strip_ansi(text: str) -> str:
+    """Remove ANSI escape codes so substring checks work regardless of color mode."""
+    return _ANSI_RE.sub("", text)
+
 
 def _run(
     args: list[str],
@@ -28,22 +36,35 @@ def _run(
             reads config from ``<home_dir>/.mem0/config.json`` instead
             of the user's real config.  This is critical for tests that
             depend on a clean (no API key) or custom config state.
+
+    Returns a CompletedProcess whose stdout/stderr have ANSI escape codes
+    stripped.  GitHub Actions sets FORCE_COLOR=1 which causes Rich/Typer to
+    fragment option names like --user-id into separately-styled ANSI segments,
+    making plain ``in`` checks fail.  Stripping here is version-agnostic and
+    ensures all assertions see the same plain text regardless of terminal env.
     """
     env = os.environ.copy()
     # Strip all MEM0_ env vars so tests start clean
     for key in list(env.keys()):
         if key.startswith("MEM0_"):
             del env[key]
+    env.pop("FORCE_COLOR", None)
     if home_dir:
         env["HOME"] = home_dir
     if env_override:
         env.update(env_override)
-    return subprocess.run(
+    result = subprocess.run(
         [sys.executable, "-m", "mem0_cli", *args],
         capture_output=True,
         text=True,
         env=env,
     )
+    return subprocess.CompletedProcess(
+        args=result.args,
+        returncode=result.returncode,
+        stdout=_strip_ansi(result.stdout),
+        stderr=_strip_ansi(result.stderr),
+    )
 
 
 @pytest.fixture
@@ -62,12 +83,6 @@ class TestCLIIntegration:
         assert "add" in result.stdout
         assert "search" in result.stdout
 
-    def test_version_flag(self):
-        result = _run(["--version"])
-        assert result.returncode == 0
-        assert "0.1.0" in result.stdout
-
-
     def test_add_help(self):
         result = _run(["add", "--help"])
         assert result.returncode == 0
@@ -161,7 +176,12 @@ class TestCLIIsolated:
         )
         assert result.returncode != 0
         combined = result.stderr + result.stdout
-        assert "memory ID" in combined.lower() or "--all" in combined or "--entity" in combined or "Error" in combined
+        assert (
+            "memory ID" in combined.lower()
+            or "--all" in combined
+            or "--entity" in combined
+            or "Error" in combined
+        )
 
     def test_config_show_clean(self, clean_home):
         """config show with no config should still work."""
@@ -204,24 +224,13 @@ class TestCLIIsolated:
 
 
 class TestCLINewFeatures:
-    """Tests for MCP parity features: --graph, --limit, entities delete."""
+    """Tests for MCP parity features: --limit, entities delete."""
 
-    def test_add_help_has_graph(self):
-        result = _run(["add", "--help"])
-        assert result.returncode == 0
-        assert "--graph" in result.stdout
-
-    def test_search_help_has_graph_and_limit(self):
+    def test_search_help_has_limit(self):
         result = _run(["search", "--help"])
         assert result.returncode == 0
-        assert "--graph" in result.stdout
         assert "--limit" in result.stdout
 
-    def test_list_help_has_graph(self):
-        result = _run(["list", "--help"])
-        assert result.returncode == 0
-        assert "--graph" in result.stdout
-
     def test_delete_entity_via_delete_flag(self):
         """delete --entity should appear in help output."""
         result = _run(["delete", "--help"])

cli/python/tests/test_commands.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import typing
 from io import StringIO
 from unittest.mock import patch
 
@@ -16,6 +17,7 @@ from mem0_cli.commands.config_cmd import (
     cmd_config_show,
 )
 from mem0_cli.commands.entities import cmd_entities_delete, cmd_entities_list
+from mem0_cli.commands.events_cmd import cmd_event_list, cmd_event_status
 from mem0_cli.commands.memory import (
     cmd_add,
     cmd_delete,
@@ -28,7 +30,6 @@ from mem0_cli.commands.memory import (
 from mem0_cli.commands.utils import (
     cmd_import,
     cmd_status,
-    cmd_version,
 )
 
 
@@ -62,7 +63,7 @@ class TestAddCommand:
                 metadata=None,
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="text",
             )
@@ -88,7 +89,7 @@ class TestAddCommand:
                 metadata=None,
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="text",
             )
@@ -113,7 +114,7 @@ class TestAddCommand:
                 metadata='{"source": "test"}',
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="text",
             )
@@ -139,7 +140,7 @@ class TestAddCommand:
                 metadata=None,
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="json",
             )
@@ -165,7 +166,7 @@ class TestAddCommand:
                 metadata=None,
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="quiet",
             )
@@ -176,30 +177,28 @@ class TestAddCommand:
     def test_add_no_content_exits(self, mock_backend):
         console, _buf = _make_console()
         err_console, _err_buf = _make_err_console()
-        # Patch stdin.isatty to return True so it doesn't try to read stdin
         with (
             patch("mem0_cli.commands.memory.console", console),
             patch("mem0_cli.commands.memory.err_console", err_console),
-            patch("mem0_cli.commands.memory.sys") as mock_sys,
+            patch("mem0_cli.commands.memory._stdin_is_piped", return_value=False),
+            pytest.raises((SystemExit, ClickExit)),
         ):
-            mock_sys.stdin.isatty.return_value = True
-            with pytest.raises((SystemExit, ClickExit)):
-                cmd_add(
-                    mock_backend,
-                    None,
-                    user_id="alice",
-                    agent_id=None,
-                    app_id=None,
-                    run_id=None,
-                    messages=None,
-                    file=None,
-                    metadata=None,
-                    immutable=False,
-                    no_infer=False,
-                                expires=None,
-                    categories=None,
-                    output="text",
-                )
+            cmd_add(
+                mock_backend,
+                None,
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata=None,
+                immutable=False,
+                no_infer=False,
+                expires=None,
+                categories=None,
+                output="text",
+            )
 
     def test_add_invalid_metadata_json(self, mock_backend):
         console, _buf = _make_console()
@@ -221,7 +220,7 @@ class TestAddCommand:
                 metadata="not-json",
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="text",
             )
@@ -247,7 +246,7 @@ class TestAddCommand:
                 metadata=None,
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories=None,
                 output="text",
             )
@@ -272,13 +271,73 @@ class TestAddCommand:
                 metadata=None,
                 immutable=False,
                 no_infer=False,
-                        expires=None,
+                expires=None,
                 categories="health,prefs",
                 output="text",
             )
         mock_backend.add.assert_called_once()
 
 
+class TestAddDeduplicatesPending:
+    """Ensure duplicate PENDING entries with the same event_id are collapsed."""
+
+    DUPLICATE_PENDING: typing.ClassVar[dict] = {
+        "results": [
+            {"status": "PENDING", "event_id": "evt-dup"},
+            {"status": "PENDING", "event_id": "evt-dup"},
+        ]
+    }
+
+    def _run_add(self, mock_backend, output):
+        mock_backend.add.return_value = self.DUPLICATE_PENDING
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_add(
+                mock_backend,
+                "test",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata=None,
+                immutable=False,
+                no_infer=False,
+                expires=None,
+                categories=None,
+                output=output,
+            )
+        return buf.getvalue()
+
+    def test_text_shows_one_pending(self, mock_backend):
+        raw = self._run_add(mock_backend, "text")
+        assert raw.count("Queued") == 1
+
+    def test_json_shows_one_pending(self, mock_backend):
+        raw = self._run_add(mock_backend, "json")
+        data = json.loads(raw)
+        results = data.get("results", data)
+        pending = [r for r in results if r.get("status") == "PENDING"]
+        assert len(pending) == 1
+
+    def test_agent_shows_one_pending(self, mock_backend):
+        from mem0_cli.state import set_agent_mode
+
+        set_agent_mode(True)
+        try:
+            raw = self._run_add(mock_backend, "agent")
+        finally:
+            set_agent_mode(False)
+        data = json.loads(raw)
+        assert data["count"] == 1
+        assert len(data["data"]) == 1
+
+
 class TestSearchCommand:
     def test_search_text(self, mock_backend):
         console, buf = _make_console()
@@ -618,28 +677,6 @@ class TestDeleteAllCommand:
             run_id="*",
         )
 
-    def test_delete_all_project_wide_dry_run(self, mock_backend):
-        console, buf = _make_console()
-        err_console, _err_buf = _make_err_console()
-        with (
-            patch("mem0_cli.commands.memory.console", console),
-            patch("mem0_cli.commands.memory.err_console", err_console),
-        ):
-            cmd_delete_all(
-                mock_backend,
-                force=True,
-                all_=True,
-                dry_run=True,
-                user_id=None,
-                agent_id=None,
-                app_id=None,
-                run_id=None,
-                output="text",
-            )
-        output = buf.getvalue()
-        assert "project-wide" in output.lower()
-        mock_backend.delete.assert_not_called()
-
     def test_delete_all_project_wide_async_response(self, mock_backend):
         mock_backend.delete.return_value = {"message": "Memories deletion started..."}
         console, buf = _make_console()
@@ -704,15 +741,6 @@ class TestStatusCommand:
         assert '"status"' in output
 
 
-class TestVersionCommand:
-    def test_version(self):
-        console, buf = _make_console()
-        with patch("mem0_cli.commands.utils.console", console):
-            cmd_version()
-        output = buf.getvalue()
-        assert "0.1.0" in output
-
-
 class TestImportCommand:
     def test_import_json(self, mock_backend, tmp_path):
         file_path = tmp_path / "import.json"
@@ -888,6 +916,28 @@ class TestEntitiesDeleteCommand:
         output = buf.getvalue()
         assert "deleted" in output.lower()
 
+    def test_delete_entity_agent_id(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.entities.console", console),
+            patch("mem0_cli.commands.entities.err_console", err_console),
+        ):
+            cmd_entities_delete(
+                mock_backend,
+                user_id=None,
+                agent_id="bot1",
+                app_id=None,
+                run_id=None,
+                force=True,
+                output="text",
+            )
+        mock_backend.delete_entities.assert_called_once_with(
+            user_id=None, agent_id="bot1", app_id=None, run_id=None
+        )
+        output = buf.getvalue()
+        assert "deleted" in output.lower()
+
     def test_delete_entity_no_id_exits(self, mock_backend):
         console, _buf = _make_console()
         err_console, _err_buf = _make_err_console()
@@ -947,9 +997,88 @@ class TestEntitiesDeleteCommand:
         mock_backend.delete_entities.assert_not_called()
 
 
-class TestEnableGraph:
-    def test_add_with_graph(self, mock_backend):
-        console, _buf = _make_console()
+class TestEventCommands:
+    def test_event_list_table(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_list(mock_backend, output="table")
+        out = buf.getvalue()
+        assert "evt-abc-" in out
+        assert "ADD" in out
+        assert "SUCCEEDED" in out
+
+    def test_event_list_json(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_list(mock_backend, output="json")
+        out = buf.getvalue()
+        assert "evt-abc-123-def-456" in out
+        assert "evt-def-456-ghi-789" in out
+
+    def test_event_list_empty(self, mock_backend):
+        mock_backend.list_events.return_value = []
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_list(mock_backend, output="table")
+        out = buf.getvalue()
+        assert "No events" in out
+
+    def test_event_status_text(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_status(mock_backend, "evt-abc-123-def-456", output="text")
+        out = buf.getvalue()
+        assert "evt-abc-123-def-456" in out
+        assert "SUCCEEDED" in out
+
+    def test_event_status_json(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_status(mock_backend, "evt-abc-123-def-456", output="json")
+        out = buf.getvalue()
+        assert "evt-abc-123-def-456" in out
+        assert "ADD" in out
+
+
+class TestAgentMode:
+    """Tests for --json/--agent mode: structured JSON envelope output."""
+
+    def setup_method(self):
+        """Enable agent mode before each test."""
+        from mem0_cli.state import set_agent_mode
+
+        set_agent_mode(True)
+
+    def teardown_method(self):
+        """Reset agent mode after each test."""
+        from mem0_cli.state import set_agent_mode
+
+        set_agent_mode(False)
+
+    # ── add ──────────────────────────────────────────────────────────────────
+
+    def test_add_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
         err_console, _err_buf = _make_err_console()
         with (
             patch("mem0_cli.commands.memory.console", console),
@@ -957,7 +1086,7 @@ class TestEnableGraph:
         ):
             cmd_add(
                 mock_backend,
-                "test",
+                "I prefer dark mode",
                 user_id="alice",
                 agent_id=None,
                 app_id=None,
@@ -969,14 +1098,48 @@ class TestEnableGraph:
                 no_infer=False,
                 expires=None,
                 categories=None,
-                enable_graph=True,
+                output="text",  # will be overridden to "agent"
+            )
+        raw = buf.getvalue()
+        data = json.loads(raw)
+        assert data["status"] == "success"
+        assert data["command"] == "add"
+        assert "data" in data
+        assert isinstance(data["data"], list)
+        assert data["count"] == 1
+        assert set(data["data"][0].keys()) == {"id", "memory", "event"}
+
+    def test_add_agent_mode_scope(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_add(
+                mock_backend,
+                "test",
+                user_id="bob",
+                agent_id="agent1",
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata=None,
+                immutable=False,
+                no_infer=False,
+                expires=None,
+                categories=None,
                 output="text",
             )
-        call_kwargs = mock_backend.add.call_args
-        assert call_kwargs.kwargs.get("enable_graph") is True
+        data = json.loads(buf.getvalue())
+        assert data["scope"]["user_id"] == "bob"
+        assert data["scope"]["agent_id"] == "agent1"
 
-    def test_search_with_graph(self, mock_backend):
-        console, _buf = _make_console()
+    # ── search ───────────────────────────────────────────────────────────────
+
+    def test_search_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
         err_console, _err_buf = _make_err_console()
         with (
             patch("mem0_cli.commands.memory.console", console),
@@ -984,7 +1147,7 @@ class TestEnableGraph:
         ):
             cmd_search(
                 mock_backend,
-                "test",
+                "dark mode",
                 user_id="alice",
                 agent_id=None,
                 app_id=None,
@@ -995,14 +1158,20 @@ class TestEnableGraph:
                 keyword=False,
                 filter_json=None,
                 fields=None,
-                enable_graph=True,
                 output="text",
             )
-        call_kwargs = mock_backend.search.call_args
-        assert call_kwargs.kwargs.get("enable_graph") is True
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "search"
+        assert isinstance(data["data"], list)
+        assert data["count"] == 2
+        assert "duration_ms" in data
+        assert set(data["data"][0].keys()) == {"id", "memory", "score", "created_at", "categories"}
 
-    def test_list_with_graph(self, mock_backend):
-        console, _buf = _make_console()
+    # ── list ─────────────────────────────────────────────────────────────────
+
+    def test_list_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
         err_console, _err_buf = _make_err_console()
         with (
             patch("mem0_cli.commands.memory.console", console),
@@ -1019,8 +1188,195 @@ class TestEnableGraph:
                 category=None,
                 after=None,
                 before=None,
-                enable_graph=True,
-                output="table",
+                output="table",  # will be overridden to "agent"
             )
-        call_kwargs = mock_backend.list_memories.call_args
-        assert call_kwargs.kwargs.get("enable_graph") is True
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "list"
+        assert isinstance(data["data"], list)
+        assert data["count"] == 2
+        assert data["scope"]["user_id"] == "alice"
+        assert set(data["data"][0].keys()) == {"id", "memory", "created_at", "categories"}
+
+    # ── get ──────────────────────────────────────────────────────────────────
+
+    def test_get_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_get(mock_backend, "abc-123-def-456", output="text")
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "get"
+        assert isinstance(data["data"], dict)
+        assert data["data"]["id"] == "abc-123-def-456"
+        assert "memory" in data["data"]
+        assert set(data["data"].keys()) >= {"id", "memory"}
+
+    # ── update ───────────────────────────────────────────────────────────────
+
+    def test_update_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_update(mock_backend, "abc-123", "Updated content", metadata=None, output="text")
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "update"
+        assert isinstance(data["data"], dict)
+        assert "memory" in data["data"]
+        assert "duration_ms" in data
+
+    # ── delete ───────────────────────────────────────────────────────────────
+
+    def test_delete_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_delete(mock_backend, "abc-123-def-456", output="text")
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "delete"
+        assert data["data"]["id"] == "abc-123-def-456"
+        assert data["data"]["deleted"] is True
+        assert "duration_ms" in data
+
+    # ── event list ───────────────────────────────────────────────────────────
+
+    def test_event_list_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_list(mock_backend, output="table")
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "event list"
+        assert isinstance(data["data"], list)
+        assert data["count"] == 2
+        assert "duration_ms" in data
+        assert set(data["data"][0].keys()) == {
+            "id",
+            "event_type",
+            "status",
+            "latency",
+            "created_at",
+        }
+
+    # ── event status ─────────────────────────────────────────────────────────
+
+    def test_event_status_agent_mode_envelope(self, mock_backend):
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.events_cmd.console", console),
+            patch("mem0_cli.commands.events_cmd.err_console", err_console),
+        ):
+            cmd_event_status(mock_backend, "evt-abc-123-def-456", output="text")
+        data = json.loads(buf.getvalue())
+        assert data["status"] == "success"
+        assert data["command"] == "event status"
+        assert isinstance(data["data"], dict)
+        assert data["data"]["id"] == "evt-abc-123-def-456"
+        assert "duration_ms" in data
+        assert set(data["data"]["results"][0].keys()) == {"id", "event", "user_id", "memory"}
+        assert "data" not in data["data"]["results"][0]
+
+    # ── error handling ───────────────────────────────────────────────────────
+
+    def test_error_in_agent_mode_produces_json_to_stdout(self, mock_backend):
+        """Errors in agent mode must emit a JSON envelope to stdout, not stderr."""
+        from io import StringIO
+
+        mock_backend.get.side_effect = Exception("Memory not found")
+        console, _buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+
+        captured_stdout = StringIO()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+            patch("sys.stdout", captured_stdout),
+            pytest.raises((SystemExit, ClickExit)),
+        ):
+            cmd_get(mock_backend, "bad-id", output="text")
+
+        stdout_output = captured_stdout.getvalue()
+        # The error JSON envelope must be on stdout
+        error_data = json.loads(stdout_output)
+        assert error_data["status"] == "error"
+        assert "error" in error_data
+        assert error_data["data"] is None
+
+    def test_branding_suppressed_in_agent_mode(self, mock_backend):
+        """Scope line and success message must be absent in agent mode output."""
+        console, buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_add(
+                mock_backend,
+                "branding test",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata=None,
+                immutable=False,
+                no_infer=False,
+                expires=None,
+                categories=None,
+                output="text",
+            )
+        output = buf.getvalue()
+        # Must be valid JSON only — no human-readable branding
+        data = json.loads(output)
+        assert data["status"] == "success"
+        # "Scope:" and "Memory processed" must NOT appear in the raw output
+        assert "Scope:" not in output
+        assert "Memory processed" not in output
+        assert "spinner" not in output.lower()
+
+    def test_no_spinner_in_agent_mode(self, mock_backend):
+        """timed_status must not emit spinner output in agent mode."""
+        err_buf = StringIO()
+        err_console_buf = Console(file=err_buf, force_terminal=False, no_color=True, width=120)
+        console, _buf = _make_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console_buf),
+        ):
+            cmd_search(
+                mock_backend,
+                "query",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                top_k=5,
+                threshold=0.3,
+                rerank=False,
+                keyword=False,
+                filter_json=None,
+                fields=None,
+                output="text",
+            )
+        # The err_buf captures what would have been spinner/timing noise
+        # In agent mode it should be empty (no status lines printed)
+        err_output = err_buf.getvalue()
+        assert "Searching" not in err_output

cli/python/tests/test_config.py

@@ -121,46 +121,6 @@ class TestConfig:
         assert config.defaults.agent_id == ""
         assert config.defaults.app_id == ""
         assert config.defaults.run_id == ""
-        assert config.defaults.enable_graph is False
-
-    def test_enable_graph_save_and_load(self, isolate_config):
-        config = Mem0Config()
-        config.defaults.enable_graph = True
-        save_config(config)
-        loaded = load_config()
-        assert loaded.defaults.enable_graph is True
-
-    def test_enable_graph_env_var_true(self, isolate_config, monkeypatch):
-        monkeypatch.setenv("MEM0_ENABLE_GRAPH", "true")
-        loaded = load_config()
-        assert loaded.defaults.enable_graph is True
-
-    def test_enable_graph_env_var_false(self, isolate_config, monkeypatch):
-        config = Mem0Config()
-        config.defaults.enable_graph = True
-        save_config(config)
-        monkeypatch.setenv("MEM0_ENABLE_GRAPH", "false")
-        loaded = load_config()
-        assert loaded.defaults.enable_graph is False
-
-    def test_backward_compat_no_enable_graph_key(self, isolate_config):
-        """Old config files without 'enable_graph' key should default to False."""
-        import json
-
-        from mem0_cli.config import CONFIG_FILE, ensure_config_dir
-
-        ensure_config_dir()
-        data = {
-            "version": 1,
-            "defaults": {"user_id": "alice"},
-            "platform": {"api_key": "m0-test", "base_url": "https://api.mem0.ai"},
-        }
-        with open(CONFIG_FILE, "w") as f:
-            json.dump(data, f)
-
-        loaded = load_config()
-        assert loaded.defaults.enable_graph is False
-        assert loaded.defaults.user_id == "alice"
 
 
 class TestNestedAccess:
@@ -192,11 +152,6 @@ class TestNestedAccess:
         assert set_nested_value(config, "defaults.user_id", "bob")
         assert config.defaults.user_id == "bob"
 
-    def test_set_defaults_enable_graph(self):
-        config = Mem0Config()
-        assert set_nested_value(config, "defaults.enable_graph", "true")
-        assert config.defaults.enable_graph is True
-
 
 class TestResolveIds:
     def test_cli_flag_overrides_default(self):

cli/python/tests/test_output.py

@@ -11,6 +11,7 @@ from mem0_cli.output import (
     format_memories_table,
     format_memories_text,
     format_single_memory,
+    sanitize_agent_data,
 )
 
 
@@ -129,8 +130,153 @@ class TestAddResult:
         output = buf.getvalue()
         assert output.strip() == ""
 
+    def test_format_add_result_deduplicates_pending_by_event_id(self):
+        console, buf = _make_console()
+        result = {
+            "results": [
+                {"status": "PENDING", "event_id": "evt-dup"},
+                {"status": "PENDING", "event_id": "evt-dup"},
+            ]
+        }
+        format_add_result(console, result, "text")
+        output = buf.getvalue()
+        # Should show only one PENDING block despite two entries with same event_id
+        assert output.count("evt-dup") == 2  # event_id line + status hint line
+        assert output.count("Queued") == 1
+
     def test_format_add_result_empty(self):
         console, buf = _make_console()
         format_add_result(console, {"results": []}, "text")
         output = buf.getvalue()
         assert "No memories extracted" in output
+
+
+class TestSanitizeAgentData:
+    def test_add_projects_fields(self):
+        raw = [
+            {
+                "id": "abc",
+                "memory": "test",
+                "event": "ADD",
+                "metadata": {"x": 1},
+                "categories": ["a"],
+            }
+        ]
+        result = sanitize_agent_data("add", raw)
+        assert result == [{"id": "abc", "memory": "test", "event": "ADD"}]
+
+    def test_add_pending_passthrough(self):
+        raw = [{"status": "PENDING", "event_id": "evt-123", "metadata": "noise"}]
+        result = sanitize_agent_data("add", raw)
+        assert result == [{"status": "PENDING", "event_id": "evt-123"}]
+
+    def test_search_projects_fields(self):
+        raw = [
+            {
+                "id": "abc",
+                "memory": "test",
+                "score": 0.9,
+                "created_at": "2026-01-01",
+                "categories": ["a"],
+                "user_id": "u1",
+                "agent_id": None,
+            }
+        ]
+        result = sanitize_agent_data("search", raw)
+        assert result == [
+            {
+                "id": "abc",
+                "memory": "test",
+                "score": 0.9,
+                "created_at": "2026-01-01",
+                "categories": ["a"],
+            }
+        ]
+
+    def test_list_projects_fields(self):
+        raw = [
+            {
+                "id": "abc",
+                "memory": "test",
+                "created_at": "2026-01-01",
+                "categories": ["a"],
+                "user_id": "u1",
+            }
+        ]
+        result = sanitize_agent_data("list", raw)
+        assert result == [
+            {"id": "abc", "memory": "test", "created_at": "2026-01-01", "categories": ["a"]}
+        ]
+
+    def test_get_projects_fields(self):
+        raw = {
+            "id": "abc",
+            "memory": "test",
+            "created_at": "2026-01-01",
+            "updated_at": "2026-01-02",
+            "categories": ["a"],
+            "metadata": {"k": "v"},
+            "user_id": "u1",
+        }
+        result = sanitize_agent_data("get", raw)
+        assert "user_id" not in result
+        assert "id" in result and "memory" in result
+
+    def test_update_projects_fields(self):
+        raw = {"id": "abc", "memory": "updated", "extra": "noise"}
+        result = sanitize_agent_data("update", raw)
+        assert result == {"id": "abc", "memory": "updated"}
+
+    def test_event_list_projects_fields(self):
+        raw = [
+            {
+                "id": "evt-1",
+                "event_type": "ADD",
+                "status": "SUCCEEDED",
+                "graph_status": None,
+                "latency": 100.0,
+                "created_at": "2026-01-01",
+                "updated_at": "2026-01-02",
+            }
+        ]
+        result = sanitize_agent_data("event list", raw)
+        assert result == [
+            {
+                "id": "evt-1",
+                "event_type": "ADD",
+                "status": "SUCCEEDED",
+                "latency": 100.0,
+                "created_at": "2026-01-01",
+            }
+        ]
+        assert "updated_at" not in result[0]
+        assert "graph_status" not in result[0]
+
+    def test_event_status_flattens_results(self):
+        raw = {
+            "id": "evt-1",
+            "event_type": "ADD",
+            "status": "SUCCEEDED",
+            "latency": 100.0,
+            "created_at": "2026-01-01",
+            "updated_at": "2026-01-02",
+            "results": [
+                {"id": "mem-1", "event": "ADD", "user_id": "alice", "data": {"memory": "dark mode"}}
+            ],
+        }
+        result = sanitize_agent_data("event status", raw)
+        assert result["results"][0] == {
+            "id": "mem-1",
+            "event": "ADD",
+            "user_id": "alice",
+            "memory": "dark mode",
+        }
+        assert "data" not in result["results"][0]
+
+    def test_passthrough_commands(self):
+        for cmd in ("status", "import", "config show", "config get", "config set"):
+            data = {"key": "value", "other": "stuff"}
+            assert sanitize_agent_data(cmd, data) == data
+
+    def test_none_data(self):
+        assert sanitize_agent_data("add", None) is None

cookbooks/helper/mem0_teachability.py

@@ -56,7 +56,7 @@ class Mem0Teachability(AgentCapability):
 
     def process_last_received_message(self, text: Union[Dict, str]):
         expanded_text = text
-        if self.memory.get_all(agent_id=self.agent_id):
+        if self.memory.get_all(filters={"agent_id": self.agent_id}):
             expanded_text = self._consider_memo_retrieval(text)
         self._consider_memo_storage(text)
         return expanded_text
@@ -139,7 +139,7 @@ class Mem0Teachability(AgentCapability):
         return comment + self._concatenate_memo_texts(memo_list)
 
     def _retrieve_relevant_memos(self, input_text: str) -> list:
-        search_results = self.memory.search(input_text, agent_id=self.agent_id, limit=self.max_num_retrievals)
+        search_results = self.memory.search(input_text, filters={"agent_id": self.agent_id}, top_k=self.max_num_retrievals)
         memo_list = [result["memory"] for result in search_results if result["score"] <= self.recall_threshold]
 
         if self.verbosity >= 1 and not memo_list:

docs/_snippets/paper-release.mdx

@@ -1,3 +0,0 @@
-<Note type="info">
-  <strong>🎉 Mem0 1.0.0 is here!</strong> Enhanced filtering, reranking, and smarter memory management.
-</Note>

docs/api-reference.mdx

@@ -10,7 +10,7 @@ description: "REST APIs for memory management, search, and entity operations"
 Mem0 provides a comprehensive REST API for integrating advanced memory capabilities into your applications. Create, search, update, and manage memories across users, agents, and custom entities with simple HTTP requests.
 
 <Info>
-**Quick start:** Get your API key from the [Mem0 Dashboard](https://app.mem0.ai/dashboard/api-keys) and make your first memory operation in minutes.
+**Quick start:** Get your API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=api-reference" rel="nofollow">Mem0 Dashboard</a> and make your first memory operation in minutes.
 </Info>
 
 ---
@@ -87,7 +87,7 @@ All API requests require authentication using Token-based authentication. Includ
 Authorization: Token <your-api-key>
 ```
 
-Get your API key from the [Mem0 Dashboard](https://app.mem0.ai/dashboard/api-keys).
+Get your API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=api-reference" rel="nofollow">Mem0 Dashboard</a>.
 
 <Warning>
 **Keep your API key secure.** Never expose it in client-side code or public repositories. Use environment variables and server-side requests only.

docs/api-reference/memory/add-memories.mdx

@@ -1,18 +1,18 @@
 ---
-title: 'Add Memories'
-description: "Add facts, messages, or metadata to a user memory store with support for async processing and event tracking."
-openapi: post /v1/memories/
+title: Add Memories
+description: "Add facts, messages, or metadata to a user memory store with async processing and event tracking via the V3 additive pipeline."
+openapi: post /v3/memories/add/
 ---
 
-Add new facts, messages, or metadata to a user’s memory store. The Add Memories endpoint accepts either raw text or conversational turns and commits them asynchronously so the memory is ready for later search, retrieval, and graph queries.
+Extract and store memories from a conversation using the V3 additive pipeline. The endpoint uses single-pass ADD-only extraction — one LLM call, no UPDATE/DELETE. Memories accumulate over time; nothing is overwritten.
 
 ## Endpoint
 
 - **Method**: `POST`
-- **URL**: `/v1/memories/`
+- **URL**: `/v3/memories/add/`
 - **Content-Type**: `application/json`
 
-Memories are processed asynchronously by default. The response contains queued events you can track while the platform finalizes enrichment.
+Processing is asynchronous. The response returns an `event_id` you can poll via `GET /v1/event/{event_id}/`.
 
 ## Required headers
 
@@ -23,7 +23,7 @@ Memories are processed asynchronously by default. The response contains queued e
 
 ## Request body
 
-Provide at least one message or direct memory string. Most callers supply `messages` so Mem0 can infer structured memories as part of ingestion.
+Provide conversation messages for Mem0 to extract memories from. At least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`) is required so the memory is scoped to a session. Entity IDs are accepted at the top level.
 
 <CodeGroup>
 ```json Basic request
@@ -43,14 +43,15 @@ Provide at least one message or direct memory string. Most callers supply `messa
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
-| `user_id` | string | No* | Associates the memory with a user. Provide when you want the memory scoped to a specific identity. |
-| `messages` | array | No* | Conversation turns for Mem0 to infer memories from. Each object should include `role` and `content`. |
+| `messages` | array | Yes | Conversation turns for Mem0 to extract memories from. Each object should include `role` and `content`. |
+| `user_id` | string | No* | Associates the memory with a user. |
+| `agent_id` | string | No* | Associates the memory with an agent. |
+| `run_id` | string | No* | Associates the memory with a run. |
+| `app_id` | string | No* | Associates the memory with an app. |
 | `metadata` | object | Optional | Custom key/value metadata (e.g., `{"topic": "preferences"}`). |
 | `infer` | boolean (default `true`) | Optional | Set to `false` to skip inference and store the provided text as-is. |
-| `async_mode` | boolean (default `true`) | Optional | Controls asynchronous processing. Most clients leave this enabled. |
-| `output_format` | string (default `v1.1`) | Optional | Response format. `v1.1` wraps results in a `results` array. |
 
-> \* Provide at least one `messages` entry to describe what you are storing. For scoped memories, include `user_id`. You can also attach `agent_id`, `app_id`, `run_id`, `project_id`, or `org_id` to refine ownership.
+> \* At least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`) is required.
 
 <Tip>
   Need more details? See [all request parameters](#body-messages) below for complete field descriptions, types, and constraints.
@@ -58,19 +59,15 @@ Provide at least one message or direct memory string. Most callers supply `messa
 
 ## Response
 
-Successful requests return an array of events queued for processing. Each event includes the generated memory text and an identifier you can persist for auditing.
+The request is queued for background processing. The response contains an `event_id` for tracking status.
 
 <CodeGroup>
 ```json 200 response
-[
-  {
-    "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
-    "event": "ADD",
-    "data": {
-      "memory": "The user moved to Austin in 2025."
-    }
-  }
-]
+{
+  "message": "Memory processing has been queued for background execution",
+  "status": "PENDING",
+  "event_id": "evt-uuid"
+}
 ```
 
 ```json 400 response
@@ -83,20 +80,7 @@ Successful requests return an array of events queued for processing. Each event
 ```
 </CodeGroup>
 
-## Graph relationships
+<Info>
+Poll the event status via `GET /v1/event/{event_id}/`. Status will be `SUCCEEDED` or `FAILED` once processing completes.
+</Info>
 
-Add Memories can enrich the knowledge graph on write. Set `enable_graph: true` to create entity nodes and relationships for the stored memory. Use this when you want downstream `get_all` or search calls to traverse connected entities.
-
-<CodeGroup>
-```json Graph-aware request
-{
-  "user_id": "alice",
-  "messages": [
-    { "role": "user", "content": "I met with Dr. Lee at General Hospital." }
-  ],
-  "enable_graph": true
-}
-```
-</CodeGroup>
-
-The response follows the same format, and related entities become available in [Graph Memory](/platform/features/graph-memory) queries.

docs/api-reference/memory/get-memories.mdx

@@ -1,10 +1,12 @@
 ---
 title: "Get Memories"
-description: "Retrieve memories with advanced filtering using logical operators like AND, OR, NOT, and comparison queries."
-openapi: post /v2/memories/
+description: "Retrieve memories with paginated results and advanced filtering using logical operators like AND, OR, NOT, and comparison queries."
+openapi: post /v3/memories/
 ---
 
-The v2 get memories API is powerful and flexible, allowing for more precise memory listing without the need for a search query. It supports complex logical operations (AND, OR, NOT) and comparison operators for advanced filtering capabilities. The comparison operators include:
+List memories scoped by filters with paginated results. Entity IDs (`user_id`, `agent_id`, `app_id`, `run_id`) **must** be passed inside the `filters` object — top-level entity IDs are rejected with 400.
+
+The `filters` object supports complex logical operations (AND, OR, NOT) and comparison operators:
 
 - `in`: Matches any of the values specified
 - `gte`: Greater than or equal to
@@ -15,6 +17,8 @@ The v2 get memories API is powerful and flexible, allowing for more precise memo
 - `icontains`: Case-insensitive containment check
 - `*`: Wildcard character that matches everything
 
+Pass `page` and `page_size` as query parameters to paginate through results.
+
 <CodeGroup>
 ```python Code
 memories = client.get_all(
@@ -27,12 +31,17 @@ memories = client.get_all(
                 "created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}
             }
         ]
-    }
+    },
+    page=1,
+    page_size=50
 )
 ```
 
 ```python Output
 {
+    "count": 2,
+    "next": null,
+    "previous": null,
     "results": [
         {
             "id": "f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c",
@@ -46,55 +55,13 @@ memories = client.get_all(
             "created_at": "2024-07-05T15:30:00Z",
             "updated_at": "2024-07-05T15:30:00Z"
         }
-    ],
-    "total": 2
-}
-```
-
-</CodeGroup>
-
-## Graph Memory
-
-To retrieve graph memory relationships between entities, pass `output_format="v1.1"` in your request. This will return memories with entity and relationship information from the knowledge graph.
-
-<CodeGroup>
-```python Code
-memories = client.get_all(
-    filters={
-        "user_id": "alex"
-    },
-    output_format="v1.1"
-)
-```
-
-```python Output
-{
-    "results": [
-        {
-            "id": "f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c",
-            "memory": "Alex is planning a trip to San Francisco",
-            "entities": [
-                {
-                    "id": "entity-1",
-                    "name": "Alex",
-                    "type": "person"
-                },
-                {
-                    "id": "entity-2",
-                    "name": "San Francisco",
-                    "type": "location"
-                }
-            ],
-            "relations": [
-                {
-                    "source": "entity-1",
-                    "target": "entity-2",
-                    "relationship": "traveling_to"
-                }
-            ]
-        }
     ]
 }
 ```
 
 </CodeGroup>
+
+<Info>
+The response is a paginated envelope with `count`, `next`, `previous`, and `results`. Use `page` and `page_size` query params to step through results.
+</Info>
+

docs/api-reference/memory/search-memories.mdx

@@ -1,10 +1,14 @@
 ---
 title: 'Search Memories'
-description: "Search memories with semantic queries and advanced filtering using logical and comparison operators."
-openapi: post /v2/memories/search/
+description: "Search memories with hybrid retrieval (semantic + BM25 + entity matching) and advanced filtering using logical and comparison operators."
+openapi: post /v3/memories/search/
 ---
 
-The v2 search API is powerful and flexible, allowing for more precise memory retrieval. It supports complex logical operations (AND, OR, NOT) and comparison operators for advanced filtering capabilities. The comparison operators include:
+Relevance-ranked hybrid search across stored memories. V3 uses multi-signal retrieval — semantic, BM25 keyword, and entity matching scored in parallel and fused. The returned `score` is a combined `[0, 1]` value.
+
+Entity IDs (`user_id`, `agent_id`, `app_id`, `run_id`) **must** be passed inside the `filters` object — top-level entity IDs are rejected with 400. At least one entity ID is required.
+
+The `filters` object supports complex logical operations (AND, OR, NOT) and comparison operators:
 - `in`: Matches any of the values specified
 - `gte`: Greater than or equal to
 - `lte`: Less than or equal to
@@ -14,6 +18,14 @@ The v2 search API is powerful and flexible, allowing for more precise memory ret
 - `icontains`: Case-insensitive containment check
 - `*`: Wildcard character that matches everything
 
+### Search parameter defaults
+
+| Parameter | V1/V2 | V3 |
+| --- | --- | --- |
+| `top_k` | Supported (default 10) | Supported (1-1000, default 10) |
+| `threshold` | No default | Default `0.1` (pass `0.0` to disable) |
+| `rerank` | Default `true` | Default `false` (pass `true` to enable) |
+
 <CodeGroup>
 ```python Platform API Example
 related_memories = client.search(
@@ -33,20 +45,19 @@ related_memories = client.search(
 
 ```json Output
 {
-  "memories": [
+  "results": [
     {
       "id": "ea925981-272f-40dd-b576-be64e4871429",
       "memory": "Likes to play cricket and plays cricket on weekends.",
       "metadata": {
         "category": "hobbies"
       },
-      "score": 0.32116443111457704,
+      "score": 0.82,
       "created_at": "2024-07-26T10:29:36.630547-07:00",
       "updated_at": null,
-      "user_id": "alice",
-      "agent_id": "sports-agent"
+      "categories": ["hobbies"]
     }
-  ],
+  ]
 }
 ```
 </CodeGroup>

docs/api-reference/organizations-projects.mdx

@@ -32,7 +32,7 @@ Example with the mem0 Python package:
 
 ```python
 from mem0 import MemoryClient
-client = MemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
+client = MemoryClient(api_key="your-api-key")
 ```
 
   </Tab>
@@ -41,10 +41,7 @@ client = MemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
 
 ```javascript
 import { MemoryClient } from "mem0ai";
-const client = new MemoryClient({
-  organizationId: "YOUR_ORG_ID",
-  projectId: "YOUR_PROJECT_ID"
-});
+const client = new MemoryClient({ apiKey: "your-api-key" });
 ```
 
   </Tab>
@@ -82,7 +79,7 @@ new_project = client.project.create(
 
 ### Update Project Settings
 
-Modify project configuration including custom instructions, categories, and graph settings:
+Modify project configuration including custom instructions, categories, graph settings, and language preferences:
 
 ```python
 # Update project with custom categories
@@ -98,8 +95,8 @@ client.project.update(
     custom_instructions="..."
 )
 
-# Enable graph memory for the project
-client.project.update(enable_graph=True)
+# Use the input language for memory storage and retrieval
+client.project.update(multilingual=True)
 
 # Update multiple settings at once
 client.project.update(
@@ -108,7 +105,7 @@ client.project.update(
         {"personal_info": "User personal information and preferences"},
         {"work_context": "Professional context and work-related information"}
     ],
-    enable_graph=True
+    multilingual=True
 )
 ```
 
@@ -168,11 +165,11 @@ All project methods are available in async mode:
 from mem0 import AsyncMemoryClient
 
 async def manage_project():
-    client = AsyncMemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
+    client = AsyncMemoryClient(api_key="your-api-key")
 
     # All methods support async/await
     project_info = await client.project.get()
-    await client.project.update(enable_graph=True)
+    await client.project.update(multilingual=True)
     members = await client.project.get_members()
 
 # To call the async function properly

docs/changelog/highlights.mdx

@@ -0,0 +1,102 @@
+---
+title: "Highlights"
+description: "Major product launches, headline features, and milestones for Mem0."
+mode: "wide"
+---
+
+<Update label="2026-04-14" description="Mem0 SDK v2.0.0 / v3.0.0">
+
+**New Memory Algorithm — State-of-the-Art Accuracy at ~3-4x Lower Cost**
+
+Ground-up rewrite of the memory pipeline with 20+ point benchmark improvements:
+
+- **LoCoMo:** 71.4 → **91.6** (+20) — multi-turn conversation recall
+- **LongMemEval:** 67.8 → **93.4** (+26) — long-term memory across sessions
+- **BEAM (1M tokens):** **64.1** — production-scale memory evaluation
+- **Agent memories are first-class** — Previous algorithm: 46% on assistant recall. New: **100%**
+- **Temporal reasoning works** — "Where did I live before SF?" Previous: 51%. New: **93%**
+- **~3-4x fewer tokens** — Under 7K tokens per retrieval vs 25K+ for full-context approaches
+- **ADD-only extraction** — Memories accumulate; nothing is overwritten or deleted
+- **Hybrid retrieval** — Semantic + BM25 keyword + entity boost, scored in parallel
+- **Entity linking** — Entities extracted, embedded, and linked across memories
+
+Breaking changes: Graph memory removed from OSS, `search()` defaults changed, deprecated params removed. See [migration guide](/migration/oss-v2-to-v3).
+
+</Update>
+
+<Update label="2026-04-06" description="Mem0 Skill Graph">
+
+**Mem0 Skill Graph — In-Context Documentation for AI Agents**
+
+AI coding agents in Claude Code, Cursor, and Codex can now access Mem0 knowledge directly in their workflow — no doc searching required. Three interconnected skills launched:
+
+- **mem0 Core Skill** — Complete Python and TypeScript SDK reference, REST API patterns, and integration guides for LangChain, CrewAI, Autogen, and more
+- **mem0-cli Skill** — Terminal command reference, configuration walkthroughs, and CI/CD recipes
+- **mem0-vercel-ai-sdk Skill** — Vercel AI SDK provider API, memory-augmented generation patterns, and multi-provider setup
+
+</Update>
+
+<Update label="2026-04-06" description="Mem0 CLI v0.2.2">
+
+**Official Mem0 CLI — Now on PyPI and npm**
+
+A full-featured command-line interface for Mem0, available in both Python and Node.js:
+
+- **Install:** `pip install mem0-cli` or `npm install -g @mem0/cli`
+- **Full command suite** — `add`, `search`, `list`, `get`, `update`, `delete`, `import`, `config`, `init`, `status`, `entity`, `event`
+- **Interactive setup** — `mem0 init` with email verification or direct API key entry
+- **Works everywhere** — Platform (Mem0 Cloud) and self-hosted OSS modes
+- **Scriptable** — `--json` flag for CI/CD pipelines and automation
+- **Dual SDK** — Same commands, same experience across Python and Node.js
+
+</Update>
+
+<Update label="2026-04-06" description="OpenClaw v1.0.4">
+
+**OpenClaw Plugin — Production-Ready**
+
+The OpenClaw Mem0 plugin went from initial release to production-ready in one week (v1.0.0 → v1.0.4):
+
+- **Skills-based memory architecture** — New extraction pipeline with skill-loader, batched extraction, and domain-aware memory triage
+- **Dream gate** — Automatic memory consolidation during idle periods for higher-quality long-term recall
+- **Interactive CLI** — `openclaw mem0 init`, `status`, `config`, `import`, and `event` commands
+- **Unified tool naming** — `memory_add` and `memory_delete` replace 4 legacy tools, matching the platform API
+- **Security hardened** — Path traversal protection, pinned dependencies, 329 tests across 10 files
+
+</Update>
+
+<Update label="2026-04-02" description="Mem0 Plugin for AI Editors">
+
+**Mem0 Plugin for Claude Code, Cursor, and Codex**
+
+Launched a unified Mem0 plugin across three major AI development environments — Claude Code and Cursor first (March 25), then Codex (April 2):
+
+- **9 MCP memory tools** — add, search, get, update, delete, bulk delete, entity management via `mcp.mem0.ai`
+- **Lifecycle hooks** — Automatic memory capture at session start, context compaction, task completion, and session end
+- **Cloud MCP server** — Managed endpoint replaces local MCP and Smithery setup
+- **Streamable HTTP transport** — New MCP transport protocol for real-time streaming
+- **Codex-specific skill** — Dedicated skill in `mem0-plugin/skills/mem0-codex` for Codex workflows
+
+</Update>
+
+<Update label="2026-03-21" description="New Providers">
+
+**Apache AGE, Turbopuffer, MiniMax, and pgvector for Node.js**
+
+Major expansion of the provider ecosystem:
+
+- **Apache AGE** — New graph store support, bringing the total to 4 graph store backends (Neo4j, Memgraph, Kuzu, Apache AGE)
+- **Turbopuffer** — New vector database provider for Python SDK
+- **MiniMax** — New LLM provider with dedicated AWS Bedrock support
+- **pgvector for Node.js** — PostgreSQL vector support added to the TypeScript OSS SDK
+- **Reasoning models** — `reasoning_effort` parameter for OpenAI o1/o3-style models
+
+</Update>
+
+<Update label="2026-03-14" description="Mem0 Platform Skill">
+
+**Mem0 Platform Skill on skills.sh**
+
+First skill launch — a dedicated Mem0 skill providing platform API reference, quickstart patterns, and integration examples directly inside agent sessions. Available on [skills.sh](https://skills.sh) for any compatible AI coding agent.
+
+</Update>

docs/changelog/openclaw.mdx

@@ -0,0 +1,273 @@
+---
+title: "OpenClaw"
+description: "Release notes for the OpenClaw plugin and agent harness."
+mode: "wide"
+---
+
+<Update label="2026-04-23" description="v1.0.10">
+
+**Security:**
+- Telemetry `distinct_id` now uses SHA-256 instead of MD5 — prevents rainbow-table reversal of API key hashes
+- User email is now SHA-256 hashed before sending as `distinct_id` — no PII in telemetry payloads
+- Declared PostHog telemetry endpoint (`us.i.posthog.com`) in `providerEndpoints`
+
+**Fixes:**
+- Fixed version-pinned install records preventing plugin updates. `ensureInstallRecord()` now detects semver-pinned specs (e.g. `@mem0/openclaw-mem0@1.0.7`) and rewrites them to `@latest` or `clawhub:` prefix so `openclaw plugins update` resolves to the newest release
+- Fixed `searchThreshold` default inconsistency: standardized to `0.3` across docs, README, and manifest
+- `PLUGIN_VERSION` now injected at build time via tsup `define` from `package.json` — no more hardcoded version strings
+
+**Manifest Compliance:**
+- Removed non-spec fields: `requiredEnvVars`, `dataLocations`, `privacy`, `setup` (with `externalEndpoints`, `providers`, `requiresRuntime`, `postInstallHint`)
+- Replaced `setup.externalEndpoints` with spec-compliant `providerEndpoints` using `endpointClass` + `hosts` format
+- Env var declarations now rely solely on `providerAuthEnvVars` (already spec-compliant)
+
+**Docs:**
+- Fixed `openclaw plugins update` command: uses plugin ID (`openclaw-mem0`), not npm package name (`@mem0/openclaw-mem0`)
+- Added update section to README
+- Removed redundant "Key Features" and "Conclusion" sections from integration docs
+
+</Update>
+
+<Update label="2026-04-22" description="v1.0.9">
+
+**Security & Compliance:**
+- Added top-level `requiredEnvVars` to plugin manifest, declaring env vars per mode (platform, OSS OpenAI, OSS Anthropic, OSS Ollama). Fixes ClaHub scanner "required env vars: none" mismatch
+- Added `sensitive: true` and descriptions to `apiKey` and `userEmail` in `configSchema` — previously only declared in `uiHints`
+- Added `default: false` with descriptions to `autoCapture` and `autoRecall` in `configSchema` so scanner can confirm opt-in defaults
+- Added `dataLocations` field to manifest declaring all persistence paths (config, vectorStore, historyDb, dreamState)
+- Added `privacy` field to manifest documenting data flow for platform vs open-source mode and credential storage guidance
+- Added `externalEndpoints` to `setup` section declaring api.mem0.ai and app.mem0.ai with purpose and requirement context
+
+**Tests:**
+- Replaced direct `process.env` access in `tests/cli-commands.test.ts` and `tests/fs-safe.test.ts` with `vi.stubEnv`/`vi.unstubAllEnvs`. Fixes ClaHub static analysis flag for "environment variable access combined with network send"
+- 421 tests across 15 test files
+
+</Update>
+
+<Update label="2026-04-21" description="v1.0.8">
+
+**New Features:**
+- **OSS Onboarding Wizard:** New guided 4-step interactive setup for open-source mode — walks through LLM provider, embedding provider, vector store, and user ID selection with prefilled defaults
+- **Agent-Friendly CLI:** Added `--json` flag to all 16 CLI commands for machine-readable output. Agents can call `openclaw mem0 help --json` to discover every command and flag
+- **Non-Interactive OSS Setup:** Added `--mode open-source` with `--oss-llm`, `--oss-embedder`, `--oss-vector` flags for fully automated OSS configuration without prompts
+- **JSON Helpers Module:** New `cli/json-helpers.ts` with `jsonOut`, `jsonErr`, and `redactSecrets` utilities for consistent structured output
+
+**Improvements:**
+- **Init Flow Redesigned:** Replaced 3-option flat menu with 2-level structure: Platform (email login or API key) and Open Source (guided wizard)
+- **Provider Selection:** LLM providers: OpenAI, Ollama, Anthropic. Embedding providers: OpenAI, Ollama. Vector stores: Qdrant, PGVector
+- **Input Prefill:** All prompts with defaults (base URL, user ID) now prefill the input field instead of showing defaults in brackets
+- **Smart Reuse:** When LLM and embedder use the same provider, API key and base URL are automatically reused from the LLM step
+- **Default Model:** Updated default LLM model to `gpt-5-mini`
+- **Manifest Compliance:** Removed undocumented fields, aligned env var declarations between SKILL.md and manifest, fixed `configSchema.required` for clean installs
+
+**Tests:**
+- 404 tests across 15 test files (+3 new: `json-helpers.test.ts`, `oss-wizard.test.ts`, `cli-commands.test.ts`)
+
+</Update>
+
+<Update label="2026-04-20" description="v1.0.7">
+
+**New Features:**
+- **Chat-Based Setup:** Added chat-based Platform setup flow — users can now configure the plugin conversationally instead of editing config files manually
+- **Installation Docs Rewrite:** Rewrote README and integration docs with chat-first setup, numbered manual steps.
+
+**Improvements:**
+- **SDK Upgrade:** Bumped `mem0ai` dependency to 3.0.1 for V3 API compatibility
+- **Config Cleanup:** Dropped deprecated `orgId`, `projectId`, `enableGraph` config options; updated CLI prompts ([#4734](https://github.com/mem0ai/mem0/pull/4734), [#4764](https://github.com/mem0ai/mem0/pull/4764))
+- **Noise Filtering:** Expanded noise patterns in memory add tool; handle leading text in JSON extraction
+
+</Update>
+
+<Update label="2026-04-11" description="v1.0.6">
+
+**Bug Fixes:**
+- **Telemetry:** Replaced shared `"anonymous-openclaw"` fallback with a persistent per-machine random hash (`openclaw-anon-<uuid>`), so anonymous plugin users are counted individually in PostHog ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Added PostHog `$identify` event on first authenticated run to stitch anonymous history onto the authenticated profile ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Fixed event loss on short-lived CLI invocations — added `beforeExit` handler to flush queued events before the process exits ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Added lazy `/v1/ping/` email resolution so users who configure API key outside `mem0 init` show as their email in PostHog, not an md5 hash ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Unified CLI event prefix from `openclaw.<cmd>` to `openclaw.cli.<cmd>` on the needsSetup branch to match the authenticated branch ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+
+**Improvements:**
+- **API:** Added `source: "OPENCLAW"` to all provider calls (`add`, `search`, `getAll`) across tools, CLI commands, recall, and the OSS backend adapter ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+
+</Update>
+
+<Update label="2026-04-07" description="v1.0.5">
+
+**Bug Fixes:**
+- **Init interactive choice bug**: Fixed number selection in `openclaw mem0 init` — entering 1/2/3 now correctly selects the corresponding option (was broken by readline prefill concatenating with user input)
+- **OSS pgvector crash** ([#4727](https://github.com/mem0ai/mem0/issues/4727)): Fixed "Client has already been connected" cascade when using pgvector in OSS mode. The warmup call swallowed errors leaving a half-initialized pg client; concurrent recall/capture then all hit `client.connect()` on the same client. Fix: let warmup errors propagate (so `initPromise` resets and retries with a fresh Memory + fresh pg client) and build fresh config objects per attempt instead of mutating shared state.
+
+**Removed:**
+- **`orgId` / `projectId` config parameters**: Removed from config schema, CLI (`config show/get/set`), init display, and providers. The API key is project-scoped, so separate org/project IDs are unnecessary and could cause access errors if mismatched.
+- **`enableGraph` config parameter**: Removed from all config surfaces, providers, backend, and tools. Graph memory is being deprecated — removing the flag avoids unnecessary exposure.
+
+</Update>
+
+<Update label="2026-04-04" description="v1.0.4">
+
+**New Features:**
+- **Interactive init flow**: `openclaw mem0 init` with interactive menu (email verification or direct API key). Non-interactive modes: `--api-key`, `--email`, `--email --code`
+- **`memory_add` tool**: Replaces `memory_store` — name now matches `mem0` CLI and platform API
+- **`memory_delete` tool**: Unified delete — single ID, search-then-delete, bulk, entity cascade. Replaces `memory_forget` and `memory_delete_all`
+- **CLI subcommands**: `openclaw mem0 init`, `openclaw mem0 status`, `openclaw mem0 config show`, `openclaw mem0 config set`
+- **`import` CLI command**: Bulk-import memories from a JSON file with `--user-id` and `--agent-id` overrides
+- **`event list` / `event status` CLI commands**: Monitor background processing events
+- **`fs-safe.ts` module**: Isolated filesystem wrappers in a separate entry point
+- **`backend/` module**: `PlatformBackend` with direct HTTP API access for CLI commands
+- **Plugin manifest**: Added `contracts.tools`, `configSchema`, and `uiHints` to `openclaw.plugin.json`
+- **Test suite**: 329 tests across 10 test files
+
+**Changes:**
+- **Modular architecture**: Extracted tools into `tools/` directory (6 files) and CLI into `cli/commands.ts`
+- **Code splitting**: tsup builds with `splitting: true` and two entry points
+- **Skills updated**: All SKILL.md files reference new tool names (`memory_add`, `memory_delete`)
+- **Auto-recall timeout**: Recall wrapped in 8-second `Promise.race`
+- **Auto-capture fire-and-forget**: `provider.add()` runs in background via `.then()/.catch()`
+- **Auto-capture minimum content gate**: Skips extraction when total user content is fewer than 50 chars
+
+**Removed:**
+- `memory_store` tool — replaced by `memory_add`
+- `memory_forget` tool — replaced by `memory_delete`
+- `memory_delete_all` tool — merged into `memory_delete`
+- `memory_history` tool and `history` CLI command — deprecated
+
+</Update>
+
+<Update label="2026-04-03" description="v1.0.3">
+
+**Bug Fixes:**
+- **Security**: Added `safePath()` containment helper to `readSkillFile` and `readDomainOverlay` in `skill-loader.ts` — prevents directory traversal
+- **Noise filter**: Reverted incorrect `After-Compaction` regex rename back to `Post-Compaction`
+
+**Changes:**
+- **Supply-chain hardening**: Pinned `mem0ai` dependency to exact `2.3.0` (was `^2.3.0`)
+
+**Tests:**
+- 12 new tests covering `safePath`, `readSkillFile`, `readDomainOverlay`, and `loadSkill` with traversal inputs
+
+</Update>
+
+<Update label="2026-04-02" description="v1.0.2">
+
+**Bug Fixes:**
+- **Security**: Removed `resolveEnvVars()` and `resolveEnvVarsDeep()` from `config.ts` — plugin-side env resolution was redundant and triggered static analysis warnings ([#4676](https://github.com/mem0ai/mem0/pull/4676))
+
+</Update>
+
+<Update label="2026-04-02" description="v1.0.1">
+
+**New Features:**
+- **CD workflow**: Added continuous deployment workflow with OIDC trusted publishing ([#4672](https://github.com/mem0ai/mem0/pull/4672))
+- **Plugin configuration manifest**: Added `compat` and `build` metadata to `package.json` ([#4667](https://github.com/mem0ai/mem0/pull/4667))
+- **LICENSE**: Added Apache-2.0 license file ([#4667](https://github.com/mem0ai/mem0/pull/4667))
+
+**Bug Fixes:**
+- **Dream gate**: Fixed cheap-first ordering, session isolation, and verified completion ([#4666](https://github.com/mem0ai/mem0/pull/4666))
+- **Graceful startup**: Plugin now starts gracefully when no API key is configured ([#4669](https://github.com/mem0ai/mem0/pull/4669))
+
+</Update>
+
+<Update label="2026-04-01" description="v1.0.0">
+
+**New Features:**
+- **Skills-based memory architecture**: New skill-loader and skill-based extraction pipeline with batched extraction ([#4624](https://github.com/mem0ai/mem0/pull/4624))
+- **Dream gate**: Memory consolidation and dream-cycle processing during idle periods
+- **Enhanced recall**: New `recall.ts` module with improved recall logic and skill-aware retrieval
+- **Memory triage skill**: Domain-aware memory triage with companion domain support and recall protocol
+- **Memory dream skill**: Skill for memory consolidation during idle periods
+- **Plugin configuration**: Added `openclaw.plugin.json` manifest and `scripts/configure.py` setup helper
+
+**Changes:**
+- Extraction pipeline refactored to use skills-based architecture for more contextual and higher quality memory capture
+
+</Update>
+
+<Update label="2026-03-26" description="v0.4.1">
+
+**New Features:**
+- **Improved extraction quality**: Enhanced noise filtering, deduplication, and better extraction instructions
+
+**Bug Fixes:**
+- **Credential detection**: Improved detection of credentials, API keys, and secrets in extraction instructions (#4552)
+- **Standalone timestamps**: Prevented extraction of standalone timestamps as memories (#4550)
+
+</Update>
+
+<Update label="2026-03-16" description="v0.4.0">
+
+**New Features:**
+- **Non-interactive trigger filtering**: Skips recall and capture for `cron`, `heartbeat`, `automation`, and `schedule` triggers
+- **Subagent hallucination prevention**: Detects ephemeral subagent sessions and routes recall to parent namespace
+- **Dynamic recall thresholding**: Memories scoring less than 50% of top result are dropped
+- **SQLite resilience**: Init error recovery with automatic retry for OSS mode
+- **`disableHistory` config option**: New `oss.disableHistory` flag
+- 78 unit tests covering filtering, isolation, trigger filtering, subagent detection, and SQLite resilience
+
+**Changes:**
+- Auto-recall threshold raised from 0.5 to 0.6 for stricter precision
+- Recall candidate pool increased to `topK * 2` for better filtering headroom
+- Relaxed extraction instructions: related facts kept together to preserve context
+
+**Bug Fixes:**
+- **Concurrent session race condition**: Lifecycle hooks now use `ctx.sessionKey` directly instead of a shared mutable variable
+
+</Update>
+
+<Update label="2026-03-12" description="v0.3.1">
+
+**New Features:**
+- **Message filtering pipeline**: Multi-stage noise removal before extraction
+- **Broad recall for new sessions**: Short or new-session prompts trigger secondary broad search
+- **Client-side threshold filtering**: Safety net that drops low-relevance results
+- **Temporal anchoring**: Extraction instructions now include current date
+- 55 unit tests covering filtering and isolation helpers
+
+**Changes:**
+- Extraction window expanded from last 10 to last 20 messages
+- Rewritten custom extraction instructions for conciseness and deduplication
+- Refactored monolithic `index.ts` (1772 lines) into 6 focused modules
+
+</Update>
+
+<Update label="2026-03-10" description="v0.3.0">
+
+**Bug Fixes:**
+- Updated `mem0ai` dependency with sqlite3 to better-sqlite3 migration (#4270)
+
+</Update>
+
+<Update label="2026-03-09" description="v0.2.0">
+
+**New Features:**
+- Per-agent memory isolation for multi-agent setups via `agentId`
+- "Understanding userId" section in docs
+
+**Changes:**
+- Updated config examples to use concrete `userId` values instead of placeholders
+
+**Bug Fixes:**
+- Migrated platform search to Mem0 v2 API
+
+</Update>
+
+<Update label="2026-02-19" description="v0.1.2">
+
+**New Features:**
+- Source field for openclaw memory entries
+
+**Bug Fixes:**
+- Auto-recall injection and auto-capture message drop
+
+</Update>
+
+<Update label="2026-02-02" description="v0.1.0">
+
+**New Features:**
+- Initial release of the OpenClaw Mem0 plugin
+- Platform mode (Mem0 Cloud) and open-source mode support
+- Auto-recall: inject relevant memories before each turn
+- Auto-capture: store facts after each turn
+- Configurable `topK`, `threshold`, and `apiVersion` options
+
+</Update>

docs/changelog/platform.mdx

@@ -0,0 +1,297 @@
+---
+title: "Platform"
+description: "Release notes for the Mem0 hosted platform — backend, dashboard, billing, and infrastructure changes."
+mode: "wide"
+---
+
+<Update label="2026-04-16" description="">
+
+**Improvements:**
+- **UI:** Removed Graph Memory tab, page, and all references from dashboard, sidebar, project settings, playground, and billing
+
+</Update>
+
+<Update label="2025-07-23" description="">
+
+**Bug Fixes:**
+- **Memory:** Fixed ADD functionality
+
+</Update>
+
+<Update label="2025-07-19" description="">
+
+**New Features:**
+- **UI:** Added Settings UI and latency display
+- **Performance:** Neo4j query optimization
+
+**Bug Fixes:**
+- **OpenMemory:** Fixed OMM raising unnecessary exceptions
+
+</Update>
+
+<Update label="2025-07-18" description="">
+
+**Improvements:**
+- **UI:** Updated Event UI
+- **Performance:** Fixed N+1 query issue in semantic_search_v2 by optimizing MemorySerializer field selection
+
+**Bug Fixes:**
+- **Memory:** Fixed duplicate memory index sentry error
+
+</Update>
+
+<Update label="2025-07-17" description="">
+
+**New Features:**
+- **UI:** New Settings Page
+- **Memory:** Duplicate memories entities support
+
+**Improvements:**
+- **Performance:** Optimized semantic search and get_all APIs by eliminating N+1 queries
+
+</Update>
+
+<Update label="2025-07-16" description="">
+
+**New Features:**
+- **Database:** Implemented read replica routing with enhanced logging and app-specific DB routing
+
+**Improvements:**
+- **Performance:** Improved query performance in search v2 and get all v2 endpoints
+
+**Bug Fixes:**
+- **API:** Fixed pagination for get all API
+
+</Update>
+
+<Update label="2025-07-12" description="">
+
+**Bug Fixes:**
+- **Graph:** Fixed social graph bugs and connection issues
+
+</Update>
+
+<Update label="2025-07-11" description="">
+
+**Improvements:**
+- **Rate Limiting:** New rate limit for V2 Search
+
+**Bug Fixes:**
+- **Slack:** Fixed Slack rate limit error with backend improvements
+
+</Update>
+
+<Update label="2025-07-10" description="">
+
+**Improvements:**
+- **Performance:** 
+  - Changed connection pooling time to 5 minutes
+  - Separated graph lambdas for better performance
+
+</Update>
+
+<Update label="2025-07-09" description="">
+
+**Improvements:**
+- **Graph:** Graph Optimizations V2 and memory improvements
+
+</Update>
+
+<Update label="2025-07-08" description="">
+
+**New Features:**
+- **Database:** Added read replica support for improved database performance
+- **UI:** Implemented UI changes for Users Page
+- **Feedback:** Enabled feedback functionality
+
+**Bug Fixes:**
+- **Serializer:** Fixed GET ALL Serializer
+
+</Update>
+
+<Update label="2025-07-05" description="">
+
+**New Features:**
+- **UI:** User Page Revamp and New Users Page
+
+</Update>
+
+<Update label="2025-07-04" description="">
+
+**New Features:**
+- **Users:** New Users Page implementation
+- **Tools:** Added script to backfill memory categories
+
+**Bug Fixes:**
+- **Filters:** Fixed Filters Get All functionality
+
+</Update>
+
+<Update label="2025-07-03" description="">
+
+**Improvements:**
+- **Graph:** Graph Memory optimization
+- **Memory:** Fixed exact memories and semantically similar memories retrieval
+
+</Update>
+
+<Update label="2025-07-02" description="">
+
+**Improvements:**
+- **Categorization:** Refactored categorization logic to utilize Gemini 2.5 Flash and improve message handling
+
+</Update>
+
+<Update label="2025-07-01" description="">
+
+**Bug Fixes:**
+- **Memory:** Fixed old_memory issue in Async memory addition lambda
+- **Events:** Fixed missing events
+
+</Update>
+
+<Update label="2025-06-30" description="">
+
+**Improvements:**
+- **Graph:** Improvements to graph memory and added user to LTM-STM
+
+</Update>
+
+<Update label="2025-06-28" description="">
+
+**New Features:**
+- **Graph:** Added support for SQS in graph memory addition
+- **Testing:** Added Locust load testing script and Grafana Dashboard
+
+</Update>
+
+<Update label="2025-06-27" description="">
+
+**Improvements:**
+- **Rate Limiting:** Updated rate limiting for ADD API to 1000/min
+- **Performance:** Improved Neo4j performance
+
+</Update>
+
+<Update label="2025-06-26" description="">
+
+**New Features:**
+- **Memory:** Edit Memory From Drawer functionality
+- **API:** Added Topic Suggestions API Endpoint
+
+</Update>
+
+<Update label="2025-06-25" description="">
+
+**New Features:**
+- **Group Chat:** Group-Chat v2 with Actor-Aware Memories
+- **Memory:** Editable Metadata in Memories
+- **UI:** Memory Actions Badges
+
+</Update>
+
+<Update label="2025-06-19" description="">
+
+**New Features:**
+- **Rate Limiting:** Implemented comprehensive rate limiting system
+
+**Improvements:**
+- **Performance:** Added performance indexes for memory stats query
+
+**Bug Fixes:**
+- **Search:** Fixed search events not respecting top-k parameter
+
+</Update>
+
+<Update label="2025-06-18" description="">
+
+**New Features:**
+- **Memory Management:** Implemented OpenAI Batch API for Memory Cleaning with fallback
+- **Playground:** Added Claude 4 support on Playground
+
+**Improvements:**
+- **Memory:** Added ability to update memory metadata
+
+</Update>
+
+<Update label="2025-06-17" description="">
+
+**New Features:**
+- **UI:** New Memories Page UI design
+
+</Update>
+
+<Update label="2025-06-16" description="">
+
+**Improvements:**
+- **Infrastructure:** Migrated to Application Load Balancer (ALB)
+
+</Update>
+
+<Update label="2025-06-13" description="">
+
+**Improvements:**
+- **Memory Management:** Enhanced Memory Management with Cosine Similarity Fallback
+
+</Update>
+
+<Update label="2025-06-11" description="">
+
+**New Features:**
+- **OMM:** Added OMM Script and UI functionality
+
+**Improvements:**
+- **API:** Added filters validation to semantic_search_v2 endpoint
+
+</Update>
+
+<Update label="2025-06-09" description="">
+
+**New Features:**
+- **Intercom:** Set Intercom events for ADD and SEARCH operations
+- **OpenMemory:** Added Posthog integration and feedback functionality
+- **MCP:** New JavaScript MCP Server with feedback support
+
+**Improvements:**
+- **Structured Data:** Enhanced structured data handling in memory management
+
+</Update>
+
+<Update label="2025-06-06" description="">
+
+**New Features:**
+- **OAuth:** Added Mem0 OAuth integration
+- **OMM:** Added OMM-Mem0 sync for deleted memories
+
+</Update>
+
+<Update label="2025-06-05" description="">
+
+**New Features:**
+- **Filters:** Implemented Wildcard Filters and refactored filter logic in V2 Views
+
+</Update>
+
+<Update label="2025-06-02" description="">
+
+**New Features:**
+- **OpenMemory Cloud:** Added OpenMemory Cloud support
+- **Structured Data:** Added 'structured_attributes' field to Memory model
+
+</Update>
+
+<Update label="2025-05-30" description="">
+
+**New Features:**
+- **Projects:** Added version and enable_graph to project views
+- **OpenMemory:** Added Postgres support for OpenMemory
+
+</Update>
+
+<Update label="2025-05-19" description="">
+
+**Bug Fixes:**
+- **Core:** Fixed unicode error in user_id, agent_id, run_id and app_id
+
+</Update>
+

docs/changelog/sdk.mdx

@@ -1,13 +1,107 @@
 ---
-title: "Product Updates"
-description: "Latest releases, bug fixes, and improvements for the Mem0 Python and TypeScript SDKs."
+title: "SDK & Tools"
+description: "Release notes for the Mem0 Python SDK, TypeScript SDK, Vercel AI SDK, CLI, and editor plugins."
 mode: "wide"
 ---
 
- 
 <Tabs>
 <Tab title="Python">
 
+<Update label="2026-04-25" description="v2.0.1">
+
+**Bug Fixes:**
+- **Client:** Map `user_id`, `agent_id`, `run_id` entity params to filters in `GET /memories` ([#4960](https://github.com/mem0ai/mem0/pull/4960))
+- **Memory:** Honor `prompt` param in vector store extraction pipeline ([#4914](https://github.com/mem0ai/mem0/pull/4914))
+- **Memory:** Add missing `text_lemmatized` field in `AsyncMemory._create_memory` ([#4886](https://github.com/mem0ai/mem0/pull/4886))
+- **Memory:** Merge same-key operator dicts in AND metadata filters ([#4853](https://github.com/mem0ai/mem0/pull/4853))
+- **LLMs:** Narrow `_is_reasoning_model` check to not match `gpt-5.x` variants ([#4746](https://github.com/mem0ai/mem0/pull/4746))
+- **Vector Stores:** Add `ca_certs` config option for Elasticsearch vector store ([#3993](https://github.com/mem0ai/mem0/pull/3993))
+- **Vector Stores:** Add `agent_id` and `run_id` to Elasticsearch/OpenSearch default mappings ([#4906](https://github.com/mem0ai/mem0/pull/4906))
+- **Embeddings:** Set FastEmbed `embedding_dims` from model metadata at init ([#4711](https://github.com/mem0ai/mem0/pull/4711))
+
+**Security:**
+- Bump vulnerable dependencies to patched versions ([#4835](https://github.com/mem0ai/mem0/pull/4835))
+
+</Update>
+
+<Update label="2026-04-14" description="v2.0.0">
+
+**Major Release** — Python SDK with V3 memory pipeline, ADD-only extraction, and cleaned-up API surface.
+
+**New Features:**
+- **Single-Pass Extraction:** Replaced 2-LLM-call pipeline with additive extraction using `ADDITIVE_EXTRACTION_PROMPT`. Memories accumulate via `linked_memory_ids` — no more UPDATE/DELETE events ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Hybrid Search:** Combined semantic + BM25 keyword matching + entity boost with additive scoring. Native `keyword_search()` added to 15 vector store adapters (Qdrant, Elasticsearch, OpenSearch, Azure AI Search, Weaviate, Redis, PGVector, Pinecone, Databricks, MongoDB, Milvus, Baidu, Upstash, Azure MySQL, Vertex AI) ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Entity Extraction & Linking:** spaCy-based entity extraction with second vector collection (`{collection}_entities`) for cross-memory relationship retrieval. Optional dependency: `pip install mem0ai[nlp]` ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Batch Operations:** Batch embedding, batch persist, and batch entity linking (8-phase pipeline) for both sync `Memory` and async `AsyncMemory` at full parity ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Message Persistence:** SQLite-based rolling window (10 messages per session scope) for LLM context ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Valkey Cluster Mode:** Added `cluster_mode` parameter for Valkey Cluster Mode Enabled (CME) deployments ([#4759](https://github.com/mem0ai/mem0/pull/4759))
+- **V3 API Endpoints:** `MemoryClient.add()` now posts to `/v3/memories/add/`; `MemoryClient.get_all()` posts to `/v3/memories/` and returns a paginated envelope `{"count": int, "next": str | None, "previous": str | None, "results": [...]}` ([#4856](https://github.com/mem0ai/mem0/pull/4856))
+- **Default model:** `gpt-5-mini` is now the default across `OpenAILLM`, `OpenAIStructuredLLM`, `AzureOpenAILLM`, `AzureOpenAIStructuredLLM`, and `LiteLLM` fallback ([#4829](https://github.com/mem0ai/mem0/pull/4829))
+
+**Breaking Changes:**
+- **`add()` returns ADD-only events** — No more `"UPDATE"` or `"DELETE"` events. Memories accumulate; nothing is overwritten ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`search()` default `threshold` is now `0.1`** — Pass `threshold=0.0` for previous behavior ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`search()` `score` is now a combined multi-signal score** — The top-level `score` fuses semantic similarity, BM25 keyword match, and entity boost into one value. Absolute numbers shift versus the old raw cosine score; retune any hard thresholds against representative queries. Per-signal scores are not exposed on the response ([#4805](https://github.com/mem0ai/mem0/pull/4805), [#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **`search()` default `rerank` is now `False`** — Pass `rerank=True` for previous behavior ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`top_k` default changed 100 → 20** in `Memory.get_all()` and `Memory.search()` (sync + async). Pass `top_k=100` explicitly to restore the old behavior ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Entity ID validation:** `user_id` / `agent_id` / `run_id` are trimmed; empty-string and whitespace-only values now raise `ValueError` ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Search params validation:** `threshold` must be a number in `[0, 1]`; `top_k` must be a non-negative integer — invalid inputs raise `ValueError` ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`messages` in `Memory.add()` rejects invalid types:** Passing `None` or non-`(str | dict | list)` values raises `Mem0ValidationError` (`error_code="VALIDATION_003"`) ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`qdrant-client>=1.12.0` required** — Upgrade from `>=1.9.1` ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`org_id` and `project_id` removed** — Removed from `MemoryClient` constructor and all method signatures ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **Graph Memory Removed (OSS):** `mem0/memory/graph_memory.py`, `memgraph_memory.py`, `kuzu_memory.py`, `apache_age_memory.py`, and `mem0/graphs/` (Neo4j / Memgraph / Kuzu / Apache AGE / Neptune drivers) deleted — ~4,000 lines. Graph memory is no longer supported in the OSS SDK; graph drivers (neo4j, memgraph, kuzu, etc.) can be uninstalled. Use the Platform API for graph features. Remove `enable_graph` and `graph_store` from your config ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`enable_graph` removed from Client SDK** — Graph memory is now a project-level setting on the Platform. Remove `enable_graph` from `MemoryClient.add()` / `search()` / `get_all()` / `update_project()` calls ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+- **`custom_fact_extraction_prompt` renamed to `custom_instructions`** — Update config and memory module references ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **Typed option classes** — Added Pydantic v2 typed classes: `AddMemoryOptions`, `SearchMemoryOptions`, `GetAllMemoryOptions`, `DeleteAllMemoryOptions`, `UpdateMemoryOptions`, `ProjectUpdateOptions` ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+
+**Security:**
+- **FAISS:** Prevent arbitrary code execution via pickle deserialization in `FAISS` vector store ([#4833](https://github.com/mem0ai/mem0/pull/4833))
+
+**Bug Fixes:**
+- **V3 migration crashes:** Fixed crashes in the v3 migration path; entity linking on OSS is now functional across Qdrant and Milvus backends ([#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **Qdrant entity store:** Entity store now shares the existing Qdrant client when using embedded mode (`path=...`), eliminating RocksDB lock contention between the main and entity collections ([#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **Reranker:** Fixed incorrect use of SentenceTransformer for cross-encoder reranker models — switched to CrossEncoder API for proper scoring ([#4806](https://github.com/mem0ai/mem0/pull/4806))
+- **S3 Vectors:** Handle `vector=None` in `update()` to prevent boto3 validation error when `event=NONE` ([#4594](https://github.com/mem0ai/mem0/pull/4594))
+- **LLMs:** Made OpenAI `store` parameter opt-in to prevent leaking to non-OpenAI backends like Google Gemini ([#4757](https://github.com/mem0ai/mem0/pull/4757))
+- **LLMs:** Forward `response_format` to Azure OpenAI API to prevent JSON parsing failures ([#4689](https://github.com/mem0ai/mem0/pull/4689))
+- **Core:** Guard `temp_uuid_mapping` lookups against LLM-hallucinated IDs with safe `.get()` and warnings ([#4674](https://github.com/mem0ai/mem0/pull/4674))
+- **Client:** Prevent `MemoryClient.feedback()` telemetry TypeError by merging feedback data into single payload ([#4795](https://github.com/mem0ai/mem0/pull/4795))
+
+**Improvements:**
+- **Telemetry:** Sample OSS hot-path events at 10% via PostHog `before_send` hook to reduce event volume ([#4771](https://github.com/mem0ai/mem0/pull/4771))
+
+See the [OSS v1 to v2 migration guide](https://docs.mem0.ai/migration/oss-v1-to-v2) and [Platform migration guide](https://docs.mem0.ai/migration/platform-v2-to-v3) for upgrade instructions.
+
+</Update>
+
+<Update label="2026-04-06" description="v1.0.11">
+
+**New Features & Updates:**
+- **SDK:** Added `multilingual` parameter to project update ([#4314](https://github.com/mem0ai/mem0/pull/4314))
+
+**Bug Fixes:**
+- **LLMs:** Fixed Groq model configuration ([#4700](https://github.com/mem0ai/mem0/pull/4700))
+- **Core:** Prevented thread and memory leaks from PostHog telemetry ([#4535](https://github.com/mem0ai/mem0/pull/4535))
+- **Vector Stores:** Used `DatetimeRange` for datetime string values in Qdrant range filters ([#4659](https://github.com/mem0ai/mem0/pull/4659))
+- **Configs:** Added missing `ConfigDict` to vector store configs (Elasticsearch, MongoDB, Neptune, OpenSearch, PGVector, Supabase, Valkey) ([#4656](https://github.com/mem0ai/mem0/pull/4656))
+
+</Update>
+
+<Update label="2026-04-01" description="v1.0.10">
+
+**New Features & Updates:**
+- **LLMs:** Added MiniMax provider support for AWS Bedrock ([#4609](https://github.com/mem0ai/mem0/pull/4609))
+
+**Bug Fixes:**
+- **Configs:** Migrated CassandraConfig and AzureMySQLConfig to pydantic v2 ConfigDict ([#4646](https://github.com/mem0ai/mem0/pull/4646))
+- **LLMs:** Forward `response_format` to OpenAI-compatible API for DeepSeek ([#4635](https://github.com/mem0ai/mem0/pull/4635))
+- **LLMs:** Forward `response_format` to OpenAI-compatible API for vLLM ([#4608](https://github.com/mem0ai/mem0/pull/4608))
+- **Vector Stores:** Only list authorized collections when listing MongoDB collections ([#3888](https://github.com/mem0ai/mem0/pull/3888))
+- **Core:** Reset graph database in `Memory.reset()` ([#4185](https://github.com/mem0ai/mem0/pull/4185))
+- **Core:** Make `AsyncMemory.from_config` a regular classmethod ([#4183](https://github.com/mem0ai/mem0/pull/4183))
+
+</Update>
+
 <Update label="2026-03-28" description="v1.0.9">
 
 **New Features & Updates:**
@@ -816,6 +910,91 @@ mode: "wide"
 </Tab>
 
 <Tab title="TypeScript">
+<Update label="2026-04-25" description="v3.0.2">
+
+**Bug Fixes:**
+- **LLMs:** Forward `timeout` config to OpenAI client in JS OSS LLM providers ([#4770](https://github.com/mem0ai/mem0/pull/4770))
+
+**Improvements:**
+- **Telemetry:** Harden TS telemetry version injection and require changelog entry on version bump ([#4900](https://github.com/mem0ai/mem0/pull/4900))
+- **Docs:** Update memory tool list, CLI usage, and config file reading logic ([#4861](https://github.com/mem0ai/mem0/pull/4861))
+
+</Update>
+
+<Update label="2026-04-20" description="v3.0.1">
+
+**Bug Fixes:**
+- **Telemetry:** SDK version is now injected into telemetry at build time via esbuild's `define`, replacing the two hardcoded version strings in `src/client/telemetry.ts` and `src/oss/src/utils/telemetry.ts`. Previously these were stuck at `2.1.36` and `2.1.34` while the published package was on `3.x`, so every telemetry event was reporting the wrong `client_version`. The placeholder is substituted with a string literal at bundle time — no runtime `require("./package.json")` in the shipped bundle ([#4897](https://github.com/mem0ai/mem0/pull/4897)).
+
+</Update>
+
+<Update label="2026-04-14" description="v3.0.0">
+
+**Major Release** — TypeScript SDK with V3 memory pipeline, camelCase parameters, and cleaned-up API surface.
+
+**V3 Memory Pipeline (OSS):**
+- **Single-Pass Extraction:** Additive extraction pipeline aligned with Python SDK — memories accumulate, no UPDATE/DELETE events ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Entity Extraction & Linking:** New `entity_extraction.ts` module (720+ lines) with cross-memory relationship retrieval ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Message Persistence:** SQLite-based message history via new `SQLiteManager.ts` with rolling window for LLM context ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Batch Embeddings:** `embedBatch()` support in OpenAI and Azure embedding providers ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Scoring & Lemmatization:** New `scoring.ts` and `lemmatization.ts` utilities for hybrid search ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **New Prompts:** `prompts/index.ts` (592+ lines) with additive extraction prompt aligned with Python SDK ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **V3 API Endpoints:** `MemoryClient.add()` now posts to `/v3/memories/add/`; `MemoryClient.getAll()` posts to `/v3/memories/` with paginated envelope `{ count, next, previous, results }` ([#4856](https://github.com/mem0ai/mem0/pull/4856))
+- **Default model:** `gpt-5-mini` is now the default in `OpenAI`, `OpenAIStructured`, and `Azure` LLM providers ([#4829](https://github.com/mem0ai/mem0/pull/4829))
+
+**Breaking Changes:**
+- **Graph Memory Removed (OSS):** `graph_memory.ts` (675 lines), `graphs/tools.ts` (267 lines), `graphs/utils.ts` (116 lines), `graphs/configs.ts` (30 lines) deleted. Graph memory is no longer supported in the OSS SDK — use Platform API for graph features ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **camelCase Parameters (Client SDK):** All user-facing parameters converted from snake_case to camelCase. Mapping is transparent at API boundary via `camelToSnakeKeys()` / `snakeToCamelKeys()` ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+  ```typescript
+  // Before
+  client.add(messages, { user_id: "alice", top_k: 5 });
+  // After
+  client.add(messages, { userId: "alice", topK: 5 });
+  ```
+- **Per-Method Option Types:** Replaced monolithic `MemoryOptions` with typed interfaces: `AddMemoryOptions`, `SearchMemoryOptions`, `GetAllMemoryOptions`, `DeleteAllMemoryOptions` ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **Removed Deprecated Parameters:** `org_id`, `project_id`, `api_version`, `output_format`, `async_mode`, `enable_graph`, `limit` removed from client method signatures. `ClientOptions` reduced to `{ apiKey, host }` only ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **`limit` renamed to `topK` (OSS):** Update all search calls ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **`topK` default changed 100 → 20** in `Memory.getAll()` and `Memory.search()`. Pass `topK: 100` explicitly to restore the old behavior ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Entity ID validation:** `userId` / `agentId` / `runId` are trimmed; empty-string and whitespace-only values now throw ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Search params validation:** `threshold` must be in `[0, 1]`; `topK` must be a non-negative integer — invalid inputs throw ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`messages` in `Memory.add()` is required:** Passing `undefined` or `null` now throws ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`customPrompt` renamed to `customInstructions` (OSS):** Update memory and vector store configurations ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **`enableGraph` removed (OSS):** Config option removed — graph memory no longer available in OSS ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+
+**New Features:**
+- **LLMs:** Added DeepSeek LLM provider with OpenAI-compatible integration using custom baseURL to `api.deepseek.com` ([#4613](https://github.com/mem0ai/mem0/pull/4613))
+- **Entity store isolation:** `MemoryVectorStore` now uses a dedicated `_entities.db` file, preventing entity/memory store collisions ([#4829](https://github.com/mem0ai/mem0/pull/4829), [#4841](https://github.com/mem0ai/mem0/pull/4841))
+- **Payload backward compatibility:** Legacy camelCase payload keys normalized to snake_case on read ([#4841](https://github.com/mem0ai/mem0/pull/4841))
+
+**Bug Fixes:**
+- **V3 migration:** Fixed crashes in the OSS migration path; entity linking works end-to-end ([#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **PGVector init race:** `PGVector.initialize()` now memoises the in-flight init promise ([#4841](https://github.com/mem0ai/mem0/pull/4841))
+- **Redis module detection:** Handles both node-redis v4+ and legacy `moduleList` response shapes ([#4841](https://github.com/mem0ai/mem0/pull/4841))
+- **Config:** Fixed `ConfigManager.mergeConfig()` to only include `graphStore` when explicitly provided by user, preventing default Neo4j connection attempts ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+- **LLMs:** Config manager now falls back to `userConf.url` for `baseURL` — prevents custom LLM providers (Ollama, LMStudio) from silently connecting to OpenAI ([#4761](https://github.com/mem0ai/mem0/pull/4761))
+
+**Improvements:**
+- **Telemetry:** Sample OSS hot-path events at 10% to reduce PostHog event volume ([#4771](https://github.com/mem0ai/mem0/pull/4771))
+
+See the [TypeScript SDK migration guide](https://docs.mem0.ai/migration/ts-v2-to-v3) for upgrade instructions.
+
+</Update>
+
+<Update label="2026-04-06" description="v2.4.6">
+
+**New Features & Updates:**
+- **Client:** Added `multilingual` parameter to project update types ([#4314](https://github.com/mem0ai/mem0/pull/4314))
+
+</Update>
+
+<Update label="2026-04-01" description="v2.4.5">
+
+**Bug Fixes:**
+- **OSS:** Replace `.single()` with `.maybeSingle()` in SupabaseDB.get() to handle missing rows ([#4599](https://github.com/mem0ai/mem0/pull/4599))
+- **Embeddings:** Pass dimensions parameter to OpenAI embeddings API ([#4632](https://github.com/mem0ai/mem0/pull/4632))
+- **OSS:** Extract JSON from chatty LLM responses in fact retrieval ([#4533](https://github.com/mem0ai/mem0/pull/4533))
+
+</Update>
 
 <Update label="2026-03-28" description="v2.4.4">
 
@@ -1116,352 +1295,162 @@ mode: "wide"
 
 </Tab>
 
-<Tab title="Platform">
+<Tab title="CLI">
 
-<Update label="2025-07-23" description="">
+<Update label="2026-04-22" description="Python v0.2.4 / Node v0.2.4">
+
+**New Features:**
+- **V3 API Routes:** Migrated `add`, `search`, and `list` commands from v1/v2 to v3 API endpoints — `POST /v3/memories/add/`, `POST /v3/memories/search/`, `POST /v3/memories/`. Aligns both CLIs with the Python and TypeScript SDKs which already use v3 ([#4916](https://github.com/mem0ai/mem0/pull/4916))
+
+**Breaking Changes:**
+- **`--graph` / `--no-graph` removed:** The `enable_graph` config option, `--graph` and `--no-graph` CLI flags, and `MEM0_ENABLE_GRAPH` environment variable have been removed from both CLIs. Graph memory is now a project-level setting on the Platform ([#4916](https://github.com/mem0ai/mem0/pull/4916))
+
+</Update>
+
+<Update label="2026-04-11" description="Python v0.2.3 / Node v0.2.3">
 
 **Bug Fixes:**
-- **Memory:** Fixed ADD functionality
+- **Telemetry:** Replaced shared `"anonymous-cli"` fallback with a persistent per-machine random hash (`cli-anon-<uuid>`), so anonymous CLI users are counted individually in PostHog instead of collapsing into one identity ([#4789](https://github.com/mem0ai/mem0/pull/4789))
+- **Telemetry:** Added PostHog `$identify` event on first authenticated run to stitch pre-signup anonymous history onto the authenticated user profile ([#4789](https://github.com/mem0ai/mem0/pull/4789))
+
+**Improvements:**
+- **API:** All API calls now include `source=CLI` in request bodies (POST/PUT) and query params (GET/DELETE) for server-side attribution ([#4789](https://github.com/mem0ai/mem0/pull/4789))
 
 </Update>
 
-<Update label="2025-07-19" description="">
+<Update label="2026-04-06" description="Python v0.2.2 / Node v0.2.2">
 
 **New Features:**
-- **UI:** Added Settings UI and latency display
-- **Performance:** Neo4j query optimization
+- **Telemetry:** Added PostHog telemetry and source tracking to both Python and Node CLIs ([#4699](https://github.com/mem0ai/mem0/pull/4699))
+- **Validation:** API key validated upfront via `/v1/ping/` on startup — fail-fast with a helpful error instead of cryptic 401s ([#4701](https://github.com/mem0ai/mem0/pull/4701))
 
 **Bug Fixes:**
-- **OpenMemory:** Fixed OMM raising unnecessary exceptions
+- **CD:** Fixed OIDC trusted publishing with `npx npm@latest` ([#4724](https://github.com/mem0ai/mem0/pull/4724))
+- **CD:** Removed npm self-upgrade from CD workflows ([#4723](https://github.com/mem0ai/mem0/pull/4723))
 
 </Update>
 
-<Update label="2025-07-18" description="">
+<Update label="2026-04-03" description="Python v0.2.1 / Node v0.2.1">
 
-**Improvements:**
-- **UI:** Updated Event UI
-- **Performance:** Fixed N+1 query issue in semantic_search_v2 by optimizing MemorySerializer field selection
+**New Features:**
+- **Docs:** Comprehensive README with installation, usage examples, and purple branding ([#4680](https://github.com/mem0ai/mem0/pull/4680))
 
 **Bug Fixes:**
-- **Memory:** Fixed duplicate memory index sentry error
+- **npm:** Added `repository` field to Node packages for npm provenance ([#4671](https://github.com/mem0ai/mem0/pull/4671))
+- **CD:** Added CD workflows for Node SDK packages with OIDC trusted publishing ([#4670](https://github.com/mem0ai/mem0/pull/4670))
 
 </Update>
 
-<Update label="2025-07-17" description="">
+<Update label="2026-04-02" description="Python v0.2.0 / Node v0.1.1">
 
 **New Features:**
-- **UI:** New Settings Page
-- **Memory:** Duplicate memories entities support
-
-**Improvements:**
-- **Performance:** Optimized semantic search and get_all APIs by eliminating N+1 queries
-
-</Update>
-
-<Update label="2025-07-16" description="">
-
-**New Features:**
-- **Database:** Implemented read replica routing with enhanced logging and app-specific DB routing
-
-**Improvements:**
-- **Performance:** Improved query performance in search v2 and get all v2 endpoints
+- **`event` commands:** `mem0 event list` shows recent background processing events in a table; `mem0 event status <id>` shows full detail including nested memory results ([#4649](https://github.com/mem0ai/mem0/pull/4649))
+- **`--json` / `--agent` flag:** Root-level flag switches all command output to a structured JSON envelope for programmatic/agent consumption. Envelope format: `{"status", "command", "duration_ms", "scope", "count", "data"}` ([#4649](https://github.com/mem0ai/mem0/pull/4649))
+- **Agent output sanitization:** Raw API responses projected to only relevant fields per command (e.g., `add` → `{id, memory, event}`, `search` → `{id, memory, score, created_at, categories}`) ([#4649](https://github.com/mem0ai/mem0/pull/4649))
+- **Email login:** Added email verification code login to `mem0 init` ([#4623](https://github.com/mem0ai/mem0/pull/4623))
+- **Brand update:** Updated color palette from purple to golden ([#4664](https://github.com/mem0ai/mem0/pull/4664))
+- **CI/CD:** Added CI pipelines and CD workflows for both CLIs ([#4640](https://github.com/mem0ai/mem0/pull/4640), [#4653](https://github.com/mem0ai/mem0/pull/4653))
 
 **Bug Fixes:**
-- **API:** Fixed pagination for get all API
-
-</Update>
-
-<Update label="2025-07-12" description="">
-
-**Bug Fixes:**
-- **Graph:** Fixed social graph bugs and connection issues
-
-</Update>
-
-<Update label="2025-07-11" description="">
+- **Node:** Fixed critical `MODULE_NOT_FOUND` crash on `status`, `import`, and all commands when installed globally — replaced runtime `createRequire` with build-time version injection ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- **Node:** API errors now show full response detail instead of bare "Bad Request" ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- **Python:** Fixed double error printing on all commands ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- **`status` command:** Replaced heavyweight `/v1/entities/` check with dedicated `GET /v1/ping/` endpoint ([#4649](https://github.com/mem0ai/mem0/pull/4649))
+- **`add` command:** Deduplicated PENDING results from API; changed misleading count message ([#4649](https://github.com/mem0ai/mem0/pull/4649))
+- **`init` command:** Partial flags now work in non-TTY; warns before overwriting existing config; added `--force` flag ([#4649](https://github.com/mem0ai/mem0/pull/4649))
+- **`delete` command:** Fixed entity delete via v2 API for all entity types ([#4649](https://github.com/mem0ai/mem0/pull/4649))
 
 **Improvements:**
-- **Rate Limiting:** New rate limit for V2 Search
-
-**Bug Fixes:**
-- **Slack:** Fixed Slack rate limit error with backend improvements
+- Tables now show full UUIDs (was truncated to 8 chars, making `mem0 get <id>` fail) ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- Search table includes Score column ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- `config get api_key` short-form aliases added ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- Client-side validation for `--expires`, `--page-size`, `--page`, `--top-k`, `--threshold`, and empty content ([#4636](https://github.com/mem0ai/mem0/pull/4636))
+- `printInfo` / `printScope` moved to stderr to avoid contaminating JSON piping ([#4636](https://github.com/mem0ai/mem0/pull/4636))
 
 </Update>
 
-<Update label="2025-07-10" description="">
+<Update label="2026-03-26" description="Python v0.1.0 / Node v0.1.0">
 
-**Improvements:**
-- **Performance:** 
-  - Changed connection pooling time to 5 minutes
-  - Separated graph lambdas for better performance
+**Initial Release — Official Mem0 CLI**
 
-</Update>
+A full-featured command-line interface for Mem0, available in both Python and Node.js:
 
-<Update label="2025-07-09" description="">
-
-**Improvements:**
-- **Graph:** Graph Optimizations V2 and memory improvements
-
-</Update>
-
-<Update label="2025-07-08" description="">
-
-**New Features:**
-- **Database:** Added read replica support for improved database performance
-- **UI:** Implemented UI changes for Users Page
-- **Feedback:** Enabled feedback functionality
-
-**Bug Fixes:**
-- **Serializer:** Fixed GET ALL Serializer
-
-</Update>
-
-<Update label="2025-07-05" description="">
-
-**New Features:**
-- **UI:** User Page Revamp and New Users Page
-
-</Update>
-
-<Update label="2025-07-04" description="">
-
-**New Features:**
-- **Users:** New Users Page implementation
-- **Tools:** Added script to backfill memory categories
-
-**Bug Fixes:**
-- **Filters:** Fixed Filters Get All functionality
-
-</Update>
-
-<Update label="2025-07-03" description="">
-
-**Improvements:**
-- **Graph:** Graph Memory optimization
-- **Memory:** Fixed exact memories and semantically similar memories retrieval
-
-</Update>
-
-<Update label="2025-07-02" description="">
-
-**Improvements:**
-- **Categorization:** Refactored categorization logic to utilize Gemini 2.5 Flash and improve message handling
-
-</Update>
-
-<Update label="2025-07-01" description="">
-
-**Bug Fixes:**
-- **Memory:** Fixed old_memory issue in Async memory addition lambda
-- **Events:** Fixed missing events
-
-</Update>
-
-<Update label="2025-06-30" description="">
-
-**Improvements:**
-- **Graph:** Improvements to graph memory and added user to LTM-STM
-
-</Update>
-
-<Update label="2025-06-28" description="">
-
-**New Features:**
-- **Graph:** Added support for SQS in graph memory addition
-- **Testing:** Added Locust load testing script and Grafana Dashboard
-
-</Update>
-
-<Update label="2025-06-27" description="">
-
-**Improvements:**
-- **Rate Limiting:** Updated rate limiting for ADD API to 1000/min
-- **Performance:** Improved Neo4j performance
-
-</Update>
-
-<Update label="2025-06-26" description="">
-
-**New Features:**
-- **Memory:** Edit Memory From Drawer functionality
-- **API:** Added Topic Suggestions API Endpoint
-
-</Update>
-
-<Update label="2025-06-25" description="">
-
-**New Features:**
-- **Group Chat:** Group-Chat v2 with Actor-Aware Memories
-- **Memory:** Editable Metadata in Memories
-- **UI:** Memory Actions Badges
-
-</Update>
-
-<Update label="2025-06-19" description="">
-
-**New Features:**
-- **Rate Limiting:** Implemented comprehensive rate limiting system
-
-**Improvements:**
-- **Performance:** Added performance indexes for memory stats query
-
-**Bug Fixes:**
-- **Search:** Fixed search events not respecting top-k parameter
-
-</Update>
-
-<Update label="2025-06-18" description="">
-
-**New Features:**
-- **Memory Management:** Implemented OpenAI Batch API for Memory Cleaning with fallback
-- **Playground:** Added Claude 4 support on Playground
-
-**Improvements:**
-- **Memory:** Added ability to update memory metadata
-
-</Update>
-
-<Update label="2025-06-17" description="">
-
-**New Features:**
-- **UI:** New Memories Page UI design
-
-</Update>
-
-<Update label="2025-06-16" description="">
-
-**Improvements:**
-- **Infrastructure:** Migrated to Application Load Balancer (ALB)
-
-</Update>
-
-<Update label="2025-06-13" description="">
-
-**Improvements:**
-- **Memory Management:** Enhanced Memory Management with Cosine Similarity Fallback
-
-</Update>
-
-<Update label="2025-06-11" description="">
-
-**New Features:**
-- **OMM:** Added OMM Script and UI functionality
-
-**Improvements:**
-- **API:** Added filters validation to semantic_search_v2 endpoint
-
-</Update>
-
-<Update label="2025-06-09" description="">
-
-**New Features:**
-- **Intercom:** Set Intercom events for ADD and SEARCH operations
-- **OpenMemory:** Added Posthog integration and feedback functionality
-- **MCP:** New JavaScript MCP Server with feedback support
-
-**Improvements:**
-- **Structured Data:** Enhanced structured data handling in memory management
-
-</Update>
-
-<Update label="2025-06-06" description="">
-
-**New Features:**
-- **OAuth:** Added Mem0 OAuth integration
-- **OMM:** Added OMM-Mem0 sync for deleted memories
-
-</Update>
-
-<Update label="2025-06-05" description="">
-
-**New Features:**
-- **Filters:** Implemented Wildcard Filters and refactored filter logic in V2 Views
-
-</Update>
-
-<Update label="2025-06-02" description="">
-
-**New Features:**
-- **OpenMemory Cloud:** Added OpenMemory Cloud support
-- **Structured Data:** Added 'structured_attributes' field to Memory model
-
-</Update>
-
-<Update label="2025-05-30" description="">
-
-**New Features:**
-- **Projects:** Added version and enable_graph to project views
-- **OpenMemory:** Added Postgres support for OpenMemory
-
-</Update>
-
-<Update label="2025-05-19" description="">
-
-**Bug Fixes:**
-- **Core:** Fixed unicode error in user_id, agent_id, run_id and app_id
+- **Install:** `pip install mem0-cli` (Python) or `npm install -g @mem0/cli` (Node.js)
+- **Full command suite:** `add`, `search`, `list`, `get`, `update`, `delete`, `import`, `config`, `init`, `status`, `entity`
+- **Interactive setup:** `mem0 init` with API key entry and user ID configuration
+- **Works everywhere:** Platform (Mem0 Cloud) and self-hosted OSS modes
+- **Scriptable:** `-o json` flag for CI/CD pipelines and automation
+- **Dual SDK:** Same commands, same experience across Python and Node.js
+- **Shared spec:** Both implementations driven by a single `cli-spec.json` ensuring identical behavior ([#4575](https://github.com/mem0ai/mem0/pull/4575))
 
 </Update>
 
 </Tab>
 
-<Tab title="Vercel AI SDK">
+<Tab title="Plugins">
 
-<Update label="2025-12-26" description="v2.0.5">
+<Update label="2026-04-02" description="mem0-plugin v1.0.0">
+
+**Mem0 Plugin for Claude Code, Cursor, and Codex**
+
+The unified Mem0 plugin for AI development environments:
+
+- **9 MCP memory tools:** `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities` — all via `mcp.mem0.ai`
+- **Lifecycle hooks:** Automatic memory capture at session start, context compaction, task completion, and session end
+- **Cloud MCP server:** Managed endpoint replaces local MCP and Smithery setup
+- **Streamable HTTP transport:** New MCP transport protocol for real-time streaming
+- **Codex-specific skill:** Dedicated skill in `mem0-plugin/skills/mem0-codex` for Codex workflows
+- **Supported editors:** Claude Code, Claude Cowork, Cursor, Codex
+
+</Update>
+
+<Update label="2025-12-26" description="Vercel AI SDK v2.0.5">
 **Bug Fix:**
-- **Vercel AI SDK:** Removed unnecessary dependencies to make the package lighter.
+- Removed unnecessary dependencies to make the package lighter.
 </Update>
 
-<Update label="2025-09-25" description="v2.0.4">
+<Update label="2025-09-25" description="Vercel AI SDK v2.0.3 – v2.0.4">
+**New Features:**
+- Added file support for multimodal capabilities with memory context (v2.0.3)
+
 **Bug Fix:**
-- **Vercel AI SDK:** Fixed version parameter in the AI SDK to use V2 for addition.
+- Fixed version parameter to use V2 for addition (v2.0.4)
 </Update>
 
-<Update label="2025-09-25" description="v2.0.3">
-**New Features:**
-- **Vercel AI SDK:** Added file support for multimodal capabilities with memory context
-</Update>
-
-<Update label="2025-09-03" description="v2.0.2">
+<Update label="2025-09-03" description="Vercel AI SDK v2.0.2">
 **Bug Fix:**
-- **Vercel AI SDK:** Fixed streaming response in the AI SDK.
+- Fixed streaming response in the AI SDK.
 </Update>
 
-<Update label="2025-08-05" description="v2.0.1">
+<Update label="2025-08-05" description="Vercel AI SDK v2.0.0 – v2.0.1">
 **New Features:**
-- **Vercel AI SDK:** Added a new param `host` to the config.
+- Migration to AI SDK V5 (v2.0.0)
+- Added `host` param to the config (v2.0.1)
 </Update>
 
-<Update label="2025-08-05" description="v2.0.0">
+<Update label="2025-06-15" description="Vercel AI SDK v1.0.6">
 **New Features:**
-- **Vercel AI SDK:** Migration to AI SDK V5.
+- Added `filter_memories` param.
 </Update>
 
-<Update label="2025-06-15" description="v1.0.6">
+<Update label="2025-05-23" description="Vercel AI SDK v1.0.5">
 **New Features:**
-- **Vercel AI SDK:** Added param `filter_memories`.
+- Added support for Google provider.
 </Update>
 
-<Update label="2025-05-23" description="v1.0.5">
+<Update label="2025-05-10" description="Vercel AI SDK v1.0.3 – v1.0.4">
 **New Features:**
-- **Vercel AI SDK:** Added support for Google provider.
-</Update>
+- Added support for `output_format` param (v1.0.4)
 
-<Update label="2025-05-10" description="v1.0.4">
-**New Features:**
-- **Vercel AI SDK:** Added support for new param `output_format`.
-</Update>
-
-<Update label="2025-05-08" description="v1.0.3">
 **Improvements:**
-- **Vercel AI SDK:** Added support for graceful failure in cases services are down.
+- Added graceful failure handling when services are down (v1.0.3)
 </Update>
 
-<Update label="2025-05-01" description="v1.0.1">
+<Update label="2025-05-01" description="Vercel AI SDK v1.0.1">
 **New Features:**
-- **Vercel AI SDK:** Added support for graph memories
+- Added support for graph memories.
 </Update>
 
 </Tab>
 
 </Tabs>
-

docs/components/llms/models/google_AI.mdx

@@ -24,6 +24,7 @@ config = {
         "provider": "gemini",
         "config": {
             "model": "gemini-2.0-flash-001",
+            "api_key": "your-gemini-api-key",
             "temperature": 0.2,
             "max_tokens": 2000,
             "top_p": 1.0
@@ -52,6 +53,7 @@ const config = {
         provider: "gemini",
         config: {
             model: "gemini-2.0-flash-001",
+            apiKey: process.env.GOOGLE_API_KEY || '',
             temperature: 0.1
         }
     }

docs/components/llms/models/langchain.mdx

@@ -21,7 +21,7 @@ os.environ["OPENAI_API_KEY"] = "your-api-key"
 
 # Initialize a LangChain model directly
 openai_model = ChatOpenAI(
-    model="gpt-4.1-nano-2025-04-14",
+    model="gpt-5-mini",
     temperature=0.2,
     max_tokens=2000
 )

docs/components/llms/models/litellm.mdx

@@ -16,7 +16,7 @@ config = {
     "llm": {
         "provider": "litellm",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
             "temperature": 0.2,
             "max_tokens": 2000,
         }

docs/components/llms/models/openai.mdx

@@ -20,7 +20,7 @@ config = {
     "llm": {
         "provider": "openai",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
             "temperature": 0.2,
             "max_tokens": 2000,
         }
@@ -86,7 +86,7 @@ config = {
     "llm": {
         "provider": "openai_structured",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
             "temperature": 0.0,
         }
     }

docs/components/rerankers/config.mdx

@@ -91,7 +91,7 @@ config = {
     "llm": {
         "provider": "openai",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14"
+            "model": "gpt-5-mini"
         }
     },
     "reranker": {

docs/components/rerankers/custom-prompts.mdx

@@ -189,7 +189,7 @@ for i, prompt in enumerate(prompts):
     config["reranker"]["config"]["scoring_prompt"] = prompt
     memory = Memory.from_config(config)
 
-    results = memory.search("test query", user_id="test_user")
+    results = memory.search("test query", filters={"user_id": "test_user"})
     print(f"Prompt {i+1} results: {results}")
 ```
 

docs/components/rerankers/models/cohere.mdx

@@ -35,7 +35,7 @@ config = {
     "llm": {
         "provider": "openai",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14"
+            "model": "gpt-5-mini"
         }
     },
     "reranker": {
@@ -95,7 +95,7 @@ messages = [
 memory.add(messages, user_id="bob")
 
 # Search with reranking
-results = memory.search("What is the user's profession?", user_id="bob")
+results = memory.search("What is the user's profession?", filters={"user_id": "bob"})
 
 for result in results['results']:
     print(f"Memory: {result['memory']}")

docs/components/rerankers/models/huggingface.mdx

@@ -175,7 +175,7 @@ queries = [
 
 results = []
 for query in queries:
-    result = m.search(query, user_id="alice", rerank=True)
+    result = m.search(query, filters={"user_id": "alice"}, rerank=True)
     results.append(result)
 ```
 

docs/components/rerankers/models/llm.mdx

@@ -111,7 +111,7 @@ messages = [
 memory.add(messages, user_id="david")
 
 # Search with LLM reranking
-results = memory.search("What programming topics is the user studying?", user_id="david")
+results = memory.search("What programming topics is the user studying?", filters={"user_id": "david"})
 
 for result in results['results']:
     print(f"Memory: {result['memory']}")

docs/components/rerankers/models/llm_reranker.mdx

@@ -283,12 +283,12 @@ for result in results["results"]:
 def safe_llm_rerank_search(query, user_id, max_retries=3):
     for attempt in range(max_retries):
         try:
-            return m.search(query, user_id=user_id, rerank=True)
+            return m.search(query, filters={"user_id": user_id}, rerank=True)
         except Exception as e:
             print(f"Attempt {attempt + 1} failed: {e}")
             if attempt == max_retries - 1:
                 # Fall back to vector search
-                return m.search(query, user_id=user_id, rerank=False)
+                return m.search(query, filters={"user_id": user_id}, rerank=False)
 
 # Use the safe function
 results = safe_llm_rerank_search("What are my preferences?", "alice")
@@ -376,19 +376,19 @@ class RobustLLMReranker:
         # Try primary LLM reranker
         for attempt in range(max_retries):
             try:
-                return self.primary.search(query, user_id=user_id, rerank=True)
+                return self.primary.search(query, filters={"user_id": user_id}, rerank=True)
             except Exception as e:
                 print(f"Primary reranker attempt {attempt + 1} failed: {e}")
 
         # Try fallback reranker
         if self.fallback:
             try:
-                return self.fallback.search(query, user_id=user_id, rerank=True)
+                return self.fallback.search(query, filters={"user_id": user_id}, rerank=True)
             except Exception as e:
                 print(f"Fallback reranker failed: {e}")
 
         # Final fallback: vector search only
-        return self.primary.search(query, user_id=user_id, rerank=False)
+        return self.primary.search(query, filters={"user_id": user_id}, rerank=False)
 
 # Usage
 primary_config = {

docs/components/rerankers/models/sentence_transformer.mdx

@@ -101,7 +101,7 @@ messages = [
 memory.add(messages, user_id="charlie")
 
 # Search with local reranking
-results = memory.search("What books does the user like?", user_id="charlie")
+results = memory.search("What books does the user like?", filters={"user_id": "charlie"})
 
 for result in results['results']:
     print(f"Memory: {result['memory']}")

docs/components/rerankers/models/zero_entropy.mdx

@@ -86,7 +86,7 @@ messages = [
 memory.add(messages, user_id="alice")
 
 # Search with reranking
-results = memory.search("What Italian food does the user like?", user_id="alice")
+results = memory.search("What Italian food does the user like?", filters={"user_id": "alice"})
 
 for result in results['results']:
     print(f"Memory: {result['memory']}")

docs/components/rerankers/optimization.mdx

@@ -153,7 +153,7 @@ def measure_reranker_performance(config, queries, user_id):
     latencies = []
     for query in queries:
         start_time = time.time()
-        results = memory.search(query, user_id=user_id)
+        results = memory.search(query, filters={"user_id": user_id})
         latency = time.time() - start_time
         latencies.append(latency)
 
@@ -191,7 +191,7 @@ class CachedReranker:
 
     @lru_cache(maxsize=1000)
     def search_cached(self, query_hash, user_id):
-        return self.memory.search(query, user_id=user_id)
+        return self.memory.search(query, filters={"user_id": user_id})
 
     def search(self, query, user_id):
         query_hash = hashlib.md5(f"{query}_{user_id}".encode()).hexdigest()