chore: update changelog, bump SDK versions to Python 2.0.12 and TypeScript 3.1.0 (#6281)

Co-authored-by: kartik-mem0 <kartik.labhshetwar@mem0.ai>

.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
       "name": "mem0",
       "source": {
         "source": "local",
-        "path": "./mem0-plugin"
+        "path": "./integrations/mem0-plugin"
       },
       "policy": {
         "installation": "AVAILABLE",

.claude-plugin/marketplace.json

@@ -10,9 +10,9 @@
   "plugins": [
     {
       "name": "mem0",
-      "source": "./mem0-plugin",
+      "source": "./integrations/mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
-      "version": "0.1.2"
+      "version": "0.2.12"
     }
   ]
 }

.codex-plugin/marketplace.json

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

.cursor-plugin/marketplace.json

@@ -10,9 +10,9 @@
   "plugins": [
     {
       "name": "mem0",
-      "source": "./mem0-plugin",
+      "source": "./integrations/mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
-      "version": "0.1.1"
+      "version": "0.2.12"
     }
   ]
 }

.github/workflows/cd.yml

@@ -1,18 +1,33 @@
 name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI
 
+# Dispatched by release.yml (Release Router) when a release tagged v* is
+# published. Can also be dispatched manually to re-publish a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. v1.2.3)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Unused for PyPI (pre-releases are expressed in the version itself); accepted for router uniformity'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
-    if: startsWith(github.event.release.tag_name, 'v')
+    # Pure SDK version tags only (v1.2.3) — excludes package-prefixed tags
+    # like vercel-ai-v* that also start with 'v'
+    if: startsWith(inputs.tag, 'v') && !contains(inputs.tag, '-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     steps:
       - uses: actions/checkout@v2
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Set up Python
         uses: actions/setup-python@v2
@@ -39,7 +54,6 @@ jobs:
       #     packages_dir: dist/
 
       - name: Publish distribution 📦 to PyPI
-        if: startsWith(github.ref, 'refs/tags/v')
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages_dir: dist/

.github/workflows/ci-gate.yml

@@ -0,0 +1,171 @@
+name: CI Gate
+
+# Single required status check for all PRs.
+#
+# Path-filtered CI workflows can't be marked as required in branch
+# protection: on a PR that doesn't touch their paths they never report, and
+# the required check hangs at "Expected" forever. This gate solves that. It
+# runs on every PR, detects which packages changed, calls only the relevant
+# package CI workflows (as reusable workflows), and the final "CI Gate" job
+# reports the aggregate result — success when every invoked pipeline passed
+# (skipped pipelines are fine), failure when any failed.
+#
+# Branch protection should require exactly one status check: "CI Gate".
+#
+# Package CI workflows keep their own push-to-main and workflow_dispatch
+# triggers; only their pull_request triggers moved here. To wire in a new
+# package: add a filter under the `changes` job, a call job that `uses:` the
+# package workflow, and list the call job in the gate's `needs`.
+
+on:
+  pull_request:
+
+concurrency:
+  group: ci-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  changes:
+    name: Detect changed packages
+    runs-on: ubuntu-latest
+    outputs:
+      python_sdk: ${{ steps.filter.outputs.python_sdk }}
+      ts_sdk: ${{ steps.filter.outputs.ts_sdk }}
+      cli_python: ${{ steps.filter.outputs.cli_python }}
+      cli_node: ${{ steps.filter.outputs.cli_node }}
+      openclaw: ${{ steps.filter.outputs.openclaw }}
+      opencode_plugin: ${{ steps.filter.outputs.opencode_plugin }}
+      pi_agent_plugin: ${{ steps.filter.outputs.pi_agent_plugin }}
+      docs_llms_txt: ${{ steps.filter.outputs.docs_llms_txt }}
+    steps:
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          # Each filter mirrors the package workflow's old pull_request
+          # paths, plus the package workflow file itself and this gate file
+          # (changing either must re-exercise the pipeline).
+          filters: |
+            python_sdk:
+              - 'mem0/**'
+              - 'tests/**'
+              - 'pyproject.toml'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            ts_sdk:
+              - 'mem0-ts/**'
+              - '.github/workflows/ts-sdk-ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            cli_python:
+              - 'cli/python/**'
+              - '.github/workflows/cli-python-ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            cli_node:
+              - 'cli/node/**'
+              - '.github/workflows/cli-node-ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            openclaw:
+              - 'integrations/openclaw/**'
+              - '.github/workflows/openclaw-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            opencode_plugin:
+              - 'integrations/mem0-plugin/.opencode-plugin/**'
+              - '.github/workflows/opencode-plugin-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            pi_agent_plugin:
+              - 'integrations/pi-agent-plugin/**'
+              - '.github/workflows/pi-agent-plugin-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            docs_llms_txt:
+              - 'docs/**/*.mdx'
+              - 'docs/llms.txt'
+              - 'scripts/check-llms-txt-coverage.py'
+              - 'scripts/llms-txt-ignore.txt'
+              - '.github/workflows/docs-llms-txt-check.yml'
+              - '.github/workflows/ci-gate.yml'
+
+  python-sdk:
+    name: Python SDK
+    needs: changes
+    if: needs.changes.outputs.python_sdk == 'true'
+    uses: ./.github/workflows/ci.yml
+    secrets: inherit
+
+  ts-sdk:
+    name: TypeScript SDK
+    needs: changes
+    if: needs.changes.outputs.ts_sdk == 'true'
+    uses: ./.github/workflows/ts-sdk-ci.yml
+    secrets: inherit
+
+  cli-python:
+    name: Python CLI
+    needs: changes
+    if: needs.changes.outputs.cli_python == 'true'
+    uses: ./.github/workflows/cli-python-ci.yml
+    secrets: inherit
+
+  cli-node:
+    name: Node CLI
+    needs: changes
+    if: needs.changes.outputs.cli_node == 'true'
+    uses: ./.github/workflows/cli-node-ci.yml
+    secrets: inherit
+
+  openclaw:
+    name: OpenClaw
+    needs: changes
+    if: needs.changes.outputs.openclaw == 'true'
+    uses: ./.github/workflows/openclaw-checks.yml
+    secrets: inherit
+
+  opencode-plugin:
+    name: OpenCode Plugin
+    needs: changes
+    if: needs.changes.outputs.opencode_plugin == 'true'
+    uses: ./.github/workflows/opencode-plugin-checks.yml
+    secrets: inherit
+
+  pi-agent-plugin:
+    name: Pi Agent Plugin
+    needs: changes
+    if: needs.changes.outputs.pi_agent_plugin == 'true'
+    uses: ./.github/workflows/pi-agent-plugin-checks.yml
+    secrets: inherit
+
+  docs-llms-txt:
+    name: docs llms.txt
+    needs: changes
+    if: needs.changes.outputs.docs_llms_txt == 'true'
+    uses: ./.github/workflows/docs-llms-txt-check.yml
+    secrets: inherit
+
+  gate:
+    name: CI Gate
+    needs:
+      - changes
+      - python-sdk
+      - ts-sdk
+      - cli-python
+      - cli-node
+      - openclaw
+      - opencode-plugin
+      - pi-agent-plugin
+      - docs-llms-txt
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate pipeline results
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          echo "$NEEDS" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'
+          failed=$(echo "$NEEDS" | jq -r '[to_entries[] | select(.value.result == "failure" or .value.result == "cancelled") | .key] | join(", ")')
+          if [ -n "$failed" ]; then
+            echo "::error::Failing pipelines: $failed"
+            exit 1
+          fi
+          echo "All pipelines relevant to this change passed."

.github/workflows/ci.yml

@@ -1,20 +1,11 @@
 name: ci
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main runs remain standalone.
 on:
   push:
     branches: [main]
-    paths:
-      - 'mem0/**'
-      - 'tests/**'
-      - 'embedchain/**'
-      - '.github/workflows/**'
-      - 'pyproject.toml'
-  pull_request:
-    paths:
-      - 'mem0/**'
-      - 'tests/**'
-      - 'embedchain/**'
-      - 'pyproject.toml'
+  workflow_call:
 
 jobs:
   changelog_check:
@@ -60,9 +51,8 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       mem0_changed: ${{ steps.filter.outputs.mem0 }}
-      embedchain_changed: ${{ steps.filter.outputs.embedchain }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: dorny/paths-filter@v2
       id: filter
       with:
@@ -70,25 +60,28 @@ jobs:
           mem0:
             - 'mem0/**'
             - 'tests/**'
-            - '.github/workflows/**'
+            - '.github/workflows/ci.yml'
             - 'pyproject.toml'
-          embedchain:
-            - 'embedchain/**'
 
   build_mem0:
     needs: check_changes
-    if: needs.check_changes.outputs.mem0_changed == 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v3
+      - name: Skip — no relevant changes
+        if: needs.check_changes.outputs.mem0_changed != 'true'
+        run: echo "No changes in mem0/, tests/, pyproject.toml, or ci.yml — skipping"
+      - uses: actions/checkout@v4
+        if: needs.check_changes.outputs.mem0_changed == 'true'
       - name: Set up Python ${{ matrix.python-version }}
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Clean up disk space
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: |
           df -h
           sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
@@ -96,61 +89,27 @@ jobs:
           sudo docker builder prune -a
           df -h
       - name: Install Hatch
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: pip install hatch
       - name: Load cached venv
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         id: cached-hatch-dependencies
         uses: actions/cache@v3
         with:
           path: .venv
           key: venv-mem0-${{ runner.os }}-${{ hashFiles('**/pyproject.toml') }}
       - name: Install GEOS Libraries
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: sudo apt-get update && sudo apt-get install -y libgeos-dev
       - name: Install dependencies
+        if: needs.check_changes.outputs.mem0_changed == 'true' && steps.cached-hatch-dependencies.outputs.cache-hit != 'true'
         run: |
           pip install --upgrade pip
           pip install -e ".[test,graph,vector_stores,llms,extras]"
           pip install ruff
-        if: steps.cached-hatch-dependencies.outputs.cache-hit != 'true'
       - name: Run Linting
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: make lint
       - name: Run tests and generate coverage report
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: make test
-
-  build_embedchain:
-    needs: check_changes
-    if: needs.check_changes.outputs.embedchain_changed == 'true'
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
-    steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install Hatch
-        run: pip install hatch
-      - name: Load cached venv
-        id: cached-hatch-dependencies
-        uses: actions/cache@v3
-        with:
-          path: .venv
-          key: venv-embedchain-${{ runner.os }}-${{ hashFiles('**/pyproject.toml') }}
-      - name: Install dependencies
-        run: cd embedchain && make install_all
-        if: steps.cached-hatch-dependencies.outputs.cache-hit != 'true'
-      - name: Run Formatting
-        run: |
-          mkdir -p embedchain/.ruff_cache && chmod -R 777 embedchain/.ruff_cache
-          cd embedchain && hatch run format
-      - name: Lint with ruff
-        run: cd embedchain && make lint
-      - name: Run tests and generate coverage report
-        run: cd embedchain && make coverage
-      - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v3
-        with:
-          file: coverage.xml
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

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

@@ -1,13 +1,25 @@
 name: Publish @mem0/cli 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged
+# cli-node-v* is published. Can also be dispatched manually to re-publish
+# a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. cli-node-v0.2.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish @mem0/cli 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'cli-node-v')
+    if: startsWith(inputs.tag, 'cli-node-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +28,8 @@ jobs:
         working-directory: cli/node
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -38,7 +52,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

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

@@ -1,5 +1,7 @@
 name: CLI Node CI
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
@@ -7,10 +9,7 @@ on:
     paths:
       - 'cli/node/**'
       - '.github/workflows/cli-node-ci.yml'
-  pull_request:
-    paths:
-      - 'cli/node/**'
-      - '.github/workflows/cli-node-ci.yml'
+  workflow_call:
 
 jobs:
   lint:

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

@@ -1,13 +1,24 @@
 name: Publish mem0-cli 🐍 distributions 📦 to PyPI
 
+# Dispatched by release.yml (Release Router) when a release tagged cli-v* is
+# published. Can also be dispatched manually to re-publish a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. cli-v0.2.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Unused for PyPI (pre-releases are expressed in the version itself); accepted for router uniformity'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish mem0-cli 📦 to PyPI
-    if: startsWith(github.event.release.tag_name, 'cli-v')
+    if: startsWith(inputs.tag, 'cli-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +27,8 @@ jobs:
         working-directory: cli/python
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Set up Python
         uses: actions/setup-python@v5

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

@@ -1,5 +1,7 @@
 name: CLI Python CI
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
@@ -7,10 +9,7 @@ on:
     paths:
       - 'cli/python/**'
       - '.github/workflows/cli-python-ci.yml'
-  pull_request:
-    paths:
-      - 'cli/python/**'
-      - '.github/workflows/cli-python-ci.yml'
+  workflow_call:
 
 jobs:
   lint:

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

@@ -6,13 +6,10 @@ name: docs - llms.txt check
 #   python scripts/check-llms-txt-coverage.py           # read-only
 #   python scripts/check-llms-txt-coverage.py --write   # scaffold placeholders
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# manual runs remain standalone.
 on:
-  pull_request:
-    paths:
-      - 'docs/**/*.mdx'
-      - 'docs/llms.txt'
-      - 'scripts/check-llms-txt-coverage.py'
-      - 'scripts/llms-txt-ignore.txt'
+  workflow_call:
   workflow_dispatch: {}
 
 permissions:

.github/workflows/openclaw-cd.yml

@@ -1,21 +1,35 @@
 name: Publish @mem0/openclaw-mem0 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged
+# openclaw-v* is published. Can also be dispatched manually to re-publish
+# a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. openclaw-v0.5.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish @mem0/openclaw-mem0 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'openclaw-v')
+    if: startsWith(inputs.tag, 'openclaw-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     defaults:
       run:
-        working-directory: openclaw
+        working-directory: integrations/openclaw
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -28,7 +42,7 @@ jobs:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -38,7 +52,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

.github/workflows/openclaw-checks.yml

@@ -1,16 +1,15 @@
 name: openclaw checks
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
     branches: [main]
     paths:
-      - 'openclaw/**'
-      - '.github/workflows/openclaw-checks.yml'
-  pull_request:
-    paths:
-      - 'openclaw/**'
+      - 'integrations/openclaw/**'
       - '.github/workflows/openclaw-checks.yml'
+  workflow_call:
 
 jobs:
   lint:
@@ -28,13 +27,13 @@ jobs:
         with:
           node-version: 20
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd openclaw && pnpm install --frozen-lockfile
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
 
       - name: Type check
-        run: cd openclaw && pnpm exec tsc --noEmit
+        run: cd integrations/openclaw && pnpm exec tsc --noEmit
 
   test:
     runs-on: ubuntu-latest
@@ -54,20 +53,20 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd openclaw && pnpm install --frozen-lockfile
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
 
       - name: Run tests with coverage
-        run: cd openclaw && pnpm exec vitest run --coverage
+        run: cd integrations/openclaw && pnpm exec vitest run --coverage
 
       - name: Upload coverage to Codecov
         if: matrix.node-version == 20
         uses: codecov/codecov-action@v4
         with:
           flags: openclaw
-          directory: openclaw/coverage
+          directory: integrations/openclaw/coverage
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
@@ -86,15 +85,15 @@ jobs:
         with:
           node-version: 20
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd openclaw && pnpm install --frozen-lockfile
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
 
       - name: Build
-        run: cd openclaw && pnpm build
+        run: cd integrations/openclaw && pnpm build
 
       - name: Verify dist output exists
         run: |
-          test -f openclaw/dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)
-          test -f openclaw/dist/index.d.ts || (echo "Build output missing: dist/index.d.ts" && exit 1)
+          test -f integrations/openclaw/dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)
+          test -f integrations/openclaw/dist/index.d.ts || (echo "Build output missing: dist/index.d.ts" && exit 1)

.github/workflows/opencode-plugin-cd.yml

@@ -0,0 +1,58 @@
+name: Publish @mem0/opencode-plugin 📦 to npm
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# opencode-v* is published. Can also be dispatched manually to re-publish
+# a tag.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. opencode-v0.2.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/opencode-plugin 📦 to npm
+    if: startsWith(inputs.tag, 'opencode-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/mem0-plugin/.opencode-plugin
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ inputs.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/opencode-plugin-checks.yml

@@ -0,0 +1,39 @@
+name: opencode-plugin checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/mem0-plugin/.opencode-plugin/**'
+      - '.github/workflows/opencode-plugin-checks.yml'
+  workflow_call:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/mem0-plugin/.opencode-plugin
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run type-check
+
+      - name: Build
+        run: bun run build
+
+      - name: Verify dist output exists
+        run: |
+          test -f dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)

.github/workflows/pi-agent-plugin-cd.yml

@@ -0,0 +1,60 @@
+name: Publish @mem0/pi-agent-plugin 📦 to npm
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# pi-agent-v* is published. Can also be dispatched manually to re-publish
+# a tag.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. pi-agent-v0.1.1)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/pi-agent-plugin 📦 to npm
+    if: startsWith(inputs.tag, 'pi-agent-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/pi-agent-plugin
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - 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: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ inputs.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/pi-agent-plugin-checks.yml

@@ -0,0 +1,92 @@
+name: pi-agent-plugin checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/pi-agent-plugin/**'
+      - '.github/workflows/pi-agent-plugin-checks.yml'
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/pi-agent-plugin && pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: cd integrations/pi-agent-plugin && pnpm exec tsc --noEmit
+
+  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: 9
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/pi-agent-plugin && pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: cd integrations/pi-agent-plugin && pnpm exec vitest run
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/pi-agent-plugin && pnpm install --frozen-lockfile
+
+      - name: Build
+        run: cd integrations/pi-agent-plugin && pnpm build
+
+      - name: Verify dist output exists
+        run: |
+          test -f integrations/pi-agent-plugin/dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)
+          test -f integrations/pi-agent-plugin/dist/index.d.ts || (echo "Build output missing: dist/index.d.ts" && exit 1)
+          test -f integrations/pi-agent-plugin/dist/entry.js || (echo "Build output missing: dist/entry.js" && exit 1)
+          test -f integrations/pi-agent-plugin/dist/entry.d.ts || (echo "Build output missing: dist/entry.d.ts" && exit 1)

.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release Router 🚦
+
+# Single entry point for all release publishing.
+#
+# Package CD workflows no longer listen to release events themselves — this
+# router inspects the release tag and dispatches only the matching pipeline,
+# so each release produces one routed run instead of one real run plus seven
+# skipped ones.
+#
+# Re-publishing a release (e.g. after fixing registry settings) does NOT
+# require deleting and recreating it anymore — manually dispatch the
+# package's CD workflow from the tag instead:
+#
+#   gh workflow run <package>-cd.yml --ref refs/tags/<tag> -f tag=<tag>
+#
+# Note: dispatching runs the workflow file as it exists at the given ref, so
+# this router can only dispatch tags created after the workflow_dispatch
+# conversion landed on main. For older tags, dispatch manually from main.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  actions: write
+
+jobs:
+  route:
+    name: Route ${{ github.event.release.tag_name }} to its CD pipeline
+    runs-on: ubuntu-latest
+    steps:
+      - name: Match tag prefix to CD workflow
+        id: match
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          # Specific package prefixes first; the bare v* (Python SDK) arm
+          # must stay last so prefixed tags that also start with 'v'
+          # (vercel-ai-v*) can never be routed to the Python pipeline.
+          case "$TAG" in
+            ts-v*)        workflow="ts-sdk-cd.yml" ;;
+            cli-node-v*)  workflow="cli-node-cd.yml" ;;
+            cli-v*)       workflow="cli-python-cd.yml" ;;
+            vercel-ai-v*) workflow="vercel-ai-cd.yml" ;;
+            openclaw-v*)  workflow="openclaw-cd.yml" ;;
+            opencode-v*)  workflow="opencode-plugin-cd.yml" ;;
+            pi-agent-v*)  workflow="pi-agent-plugin-cd.yml" ;;
+            v*)           workflow="cd.yml" ;;
+            *)
+              echo "::error::Release tag '$TAG' does not match any known package prefix — nothing will be published. See the tag prefix table in AGENTS.md."
+              exit 1
+              ;;
+          esac
+          echo "workflow=$workflow" >> "$GITHUB_OUTPUT"
+          echo ":outbox_tray: Routed \`$TAG\` → \`$workflow\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Dispatch ${{ steps.match.outputs.workflow }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          # --ref points at the tag so the dispatched run builds (and signs
+          # provenance for) the exact tagged commit.
+          gh workflow run "${{ steps.match.outputs.workflow }}" \
+            --repo "$GITHUB_REPOSITORY" \
+            --ref "refs/tags/$TAG" \
+            -f tag="$TAG" \
+            -f prerelease="${{ github.event.release.prerelease }}"

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

@@ -1,13 +1,24 @@
 name: Publish mem0ai 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged ts-v* is
+# published. Can also be dispatched manually to re-publish a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. ts-v2.1.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish mem0ai 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'ts-v')
+    if: startsWith(inputs.tag, 'ts-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +27,8 @@ jobs:
         working-directory: mem0-ts
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -38,7 +51,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

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

@@ -1,14 +1,14 @@
 name: TypeScript SDK CI
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main runs remain standalone.
 on:
   push:
     branches: [main]
     paths:
       - 'mem0-ts/**'
       - '.github/workflows/ts-sdk-ci.yml'
-  pull_request:
-    paths:
-      - 'mem0-ts/**'
+  workflow_call:
 
 jobs:
   check_changes:

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

@@ -1,21 +1,35 @@
 name: Publish @mem0/vercel-ai-provider 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged
+# vercel-ai-v* is published. Can also be dispatched manually to re-publish
+# a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. vercel-ai-v2.0.7)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish @mem0/vercel-ai-provider 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'vercel-ai-v')
+    if: startsWith(inputs.tag, 'vercel-ai-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     defaults:
       run:
-        working-directory: vercel-ai-sdk
+        working-directory: integrations/vercel-ai-sdk
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -28,7 +42,7 @@ jobs:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
-          cache-dependency-path: vercel-ai-sdk/pnpm-lock.yaml
+          cache-dependency-path: integrations/vercel-ai-sdk/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -38,7 +52,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

.gitignore

@@ -170,7 +170,6 @@ cython_debug/
 # Database
 db
 test-db
-!embedchain/embedchain/core/db/
 
 .vscode
 .idea/
@@ -190,3 +189,5 @@ eval/
 qdrant_storage/
 .crossnote
 testing.ipynb
+.weave/
+

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "evaluation"]
+	path = evaluation
+	url = https://github.com/mem0ai/memory-benchmarks
+	branch = main

AGENTS.md

@@ -12,7 +12,7 @@ This file provides context for AI coding assistants (Claude Code, Cursor, GitHub
 
 ## Repository Structure
 
-This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs, servers, plugins, documentation, and evaluation tooling.
+This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs, servers, plugins, and documentation.
 
 ### Key Directories
 
@@ -22,18 +22,18 @@ This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs,
 | `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 |
+| `integrations/` | **Agent & editor integrations**, one directory per integration (see "Adding a New Integration") |
+| `integrations/mem0-plugin/` | AI editor plugins (Claude Code, Cursor, Codex) — MCP server connection, lifecycle hooks, skills. Contains nested `.opencode-plugin/` (`@mem0/opencode-plugin`) |
+| `integrations/openclaw/` | `@mem0/openclaw-mem0` — OpenClaw plugin for Claude Code / AI editors |
+| `integrations/pi-agent-plugin/` | `@mem0/pi-agent-plugin` — Pi Agent plugin |
+| `integrations/vercel-ai-sdk/` | `@mem0/vercel-ai-provider` — Vercel AI SDK memory provider |
 | `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. Reference skills (SDK knowledge, always-on): `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/`. Pipeline skills (run on demand): `mem0-integrate/`, `mem0-test-integration/` |
+| `skills/` | Claude Code skill definitions. Reference skills (SDK knowledge, always-on): `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/`. Pipeline skills (run on demand): `mem0-integrate/`, `mem0-test-integration/`, `mem0-oss-to-platform/` |
 | `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) |
+| `evaluation/` | Submodule → [`mem0ai/memory-benchmarks`](https://github.com/mem0ai/memory-benchmarks) — benchmarking (LOCOMO, LongMemEval, BEAM) lives in that repo |
+| `examples/` | Sample projects & runnable demos — apps, Chrome extension, multi-agent patterns, and Jupyter notebooks (`notebooks/`) |
 | `pr-reviews/` | Pull request review materials |
 | `scripts/` | Repo-wide utility scripts (e.g., `check-llms-txt-coverage.py` for docs/llms.txt sync) |
 
@@ -50,8 +50,8 @@ mem0 (Python SDK)          mem0-ts (TypeScript SDK)
 
 cli/python/ ──▶ mem0ai (optional, for OSS mode)
 cli/node/   ──▶ mem0ai (npm, for API calls)
-vercel-ai-sdk/ ──▶ ai, @ai-sdk/* providers
-openclaw/   ──▶ mem0ai (npm)
+integrations/vercel-ai-sdk/ ──▶ ai, @ai-sdk/* providers
+integrations/openclaw/ ──▶ mem0ai (npm)
 ```
 
 ## Development Setup
@@ -74,8 +74,8 @@ 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
+cd integrations/vercel-ai-sdk && pnpm install  # Vercel AI provider
+cd integrations/openclaw && pnpm install       # OpenClaw plugin
 ```
 
 ## Build, Lint, and Test Commands
@@ -163,10 +163,10 @@ pnpm run dev                       # tsx src/index.ts (development)
 - **Test:** vitest (not jest)
 - **Framework:** Commander + Chalk + ora + cli-table3
 
-### Vercel AI SDK Provider (`vercel-ai-sdk/`)
+### Vercel AI SDK Provider (`integrations/vercel-ai-sdk/`)
 
 ```bash
-cd vercel-ai-sdk
+cd integrations/vercel-ai-sdk
 pnpm install
 pnpm run build                     # tsup
 pnpm run lint                      # eslint
@@ -181,10 +181,10 @@ pnpm run test:node                 # vitest (node runtime)
 - **Lint:** ESLint + Prettier
 - **Test:** jest + vitest (edge/node configs)
 
-### OpenClaw Plugin (`openclaw/`)
+### OpenClaw Plugin (`integrations/openclaw/`)
 
 ```bash
-cd openclaw
+cd integrations/openclaw
 pnpm install
 pnpm run build                     # tsup
 pnpm run test                      # vitest run
@@ -246,18 +246,19 @@ make docs                          # or: cd docs && mintlify dev
 - **API spec:** `docs/openapi.json`
 - **Structure:** `api-reference/`, `open-source/`, `platform/`, `integrations/`, `cookbooks/`, `core-concepts/`
 
-### Evaluation (`evaluation/`)
+### Evaluation / Benchmarking
+
+Benchmarking lives in the external [`mem0ai/memory-benchmarks`](https://github.com/mem0ai/memory-benchmarks) repo (LOCOMO + LongMemEval + BEAM). The in-repo `evaluation/` path is a **git submodule** pinned to that repo's `main` — populate it with `git submodule update --init evaluation` (or clone mem0 with `--recurse-submodules`), or clone the benchmarks repo standalone:
 
 ```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
+git clone https://github.com/mem0ai/memory-benchmarks.git
+cd memory-benchmarks
+pip install -r requirements.txt
+
+# Run a benchmark (Mem0 Cloud; use docker compose for OSS)
+python -m benchmarks.locomo.run --project-name my-test --backend cloud --mem0-api-key $MEM0_API_KEY
+python -m benchmarks.longmemeval.run --project-name my-test --backend cloud --mem0-api-key $MEM0_API_KEY --all-questions
+python -m benchmarks.beam.run --project-name my-test --backend cloud --mem0-api-key $MEM0_API_KEY --chat-sizes 100K --conversations 0-9
 ```
 
 ## Core APIs
@@ -330,7 +331,7 @@ make run-openai                    # OpenAI comparison
   - 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.
+- Ruff excludes `openmemory/` from root config.
 
 ### TypeScript Conventions
 
@@ -343,8 +344,8 @@ make run-openai                    # OpenAI comparison
 |---------|--------|-----------|---------------|
 | `mem0-ts/` | — | Prettier | jest |
 | `cli/node/` | Biome | Biome | vitest |
-| `vercel-ai-sdk/` | ESLint | Prettier | jest + vitest |
-| `openclaw/` | — | — | vitest |
+| `integrations/vercel-ai-sdk/` | ESLint | Prettier | jest + vitest |
+| `integrations/openclaw/` | — | — | vitest |
 
 ### Type Checking
 
@@ -382,14 +383,14 @@ 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:** MCP tools in `integrations/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.
+- `integrations/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, split into two categories:
   - **Reference skills** (always-on SDK knowledge): `mem0` (Python + TS SDKs, framework integrations), `mem0-cli` (terminal workflows), `mem0-vercel-ai-sdk` (Vercel AI provider).
-  - **Pipeline skills** (run on demand): `mem0-integrate` wires Mem0 into an existing repo via a TDD pipeline; `mem0-test-integration` verifies what the integrator produced on the same branch. The two are loosely coupled via `.mem0-integration/` artifacts.
+  - **Pipeline skills** (run on demand): `mem0-integrate` wires Mem0 into an existing repo via a TDD pipeline; `mem0-test-integration` verifies what the integrator produced on the same branch (the two are loosely coupled via `.mem0-integration/` artifacts); `mem0-oss-to-platform` migrates an existing project from Mem0 OSS to the hosted Platform SDK (plan, then execute on approval).
 
 ### Adding a New Provider
 
@@ -403,32 +404,58 @@ To add a new LLM, embedding, vector store, or reranker provider:
 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
 
+### Adding a New Integration
+
+Agent/editor integrations live under `integrations/`. Each is a self-contained directory (its own `package.json`/lockfile, build, and tests). To add one:
+
+1. Create `integrations/<name>/` and build the integration there.
+2. If it publishes to a registry, set `repository.directory: "integrations/<name>"` in its `package.json` so npm provenance links to the correct subdirectory.
+3. Add CI/CD under `.github/workflows/` (`<name>-checks.yml`, `<name>-cd.yml`). Use `integrations/<name>` in `paths:` triggers, `working-directory`, and `cache-dependency-path`. Register the release tag prefix in the `case` block in `release.yml` (keep the bare `v*` arm last). Keep workflow **filenames** stable — npm OIDC trusted publishing is pinned to repo + workflow filename.
+4. If it is a Claude Code / editor marketplace plugin, register its path in the five `marketplace.json` files (root + `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.agents/plugins/`).
+5. Document it under `docs/integrations/` and add the page to `docs/docs.json` and `docs/llms.txt`.
+6. Add rows to the "Key Directories" table and the CI/CD tables in this file.
+
 ## 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 |
+PR testing is orchestrated by a single entry point: **`ci-gate.yml` (CI Gate)** runs on every PR, detects which packages changed, and invokes only the relevant package workflows below as reusable workflows (`workflow_call`). Its final **`CI Gate`** job aggregates the results (skipped pipelines pass; failed or cancelled ones fail) and is the **only status check that needs to be required** in branch protection. Package workflows keep their own push-to-main and manual triggers; their `pull_request` triggers moved into the gate's path filters.
+
+| Workflow | File | Standalone Triggers | Tests |
+|----------|------|---------------------|-------|
+| CI Gate | `ci-gate.yml` | All PRs | Routes to and aggregates the workflows below |
+| Python SDK | `ci.yml` | Push to main | Ruff lint + pytest on Python 3.10, 3.11, 3.12 |
+| TypeScript SDK | `ts-sdk-ci.yml` | Push to main (on `mem0-ts/`) | Prettier + build + jest on Node 20, 22 |
+| Python CLI | `cli-python-ci.yml` | Push to main (on `cli/python/`), manual | Ruff lint + pytest + hatch build on Python 3.10, 3.11, 3.12 |
+| Node CLI | `cli-node-ci.yml` | Push to main (on `cli/node/`), manual | Biome lint + tsc + vitest + tsup build on Node 20, 22 |
+| OpenClaw | `openclaw-checks.yml` | Push to main (on `integrations/openclaw/`), manual | tsc + vitest (with Codecov) + tsup build on Node 20, 22 |
+| OpenCode Plugin | `opencode-plugin-checks.yml` | Push to main (on `integrations/mem0-plugin/.opencode-plugin/`), manual | Bun: tsc type-check + build + dist artifact check |
+| Pi Agent Plugin | `pi-agent-plugin-checks.yml` | Push to main (on `integrations/pi-agent-plugin/`), manual | tsc + vitest + tsup build (dist artifact check) on Node 20, 22 |
+| docs llms.txt | `docs-llms-txt-check.yml` | Manual | `docs/llms.txt` coverage check |
+
+When adding a new package CI workflow: give it `workflow_call` (plus `push`/`workflow_dispatch` as needed, but no `pull_request` trigger), then register it in `ci-gate.yml` — a path filter under the `changes` job, a call job, and an entry in the gate job's `needs` list.
 
 ### CD Workflows (automated publishing)
 
+Publishing is routed through a single entry point: **`release.yml` (Release Router)** is the only workflow that listens to `release: published` events. It matches the release tag prefix and dispatches the corresponding package workflow via `workflow_dispatch`, so each release produces exactly one routed run (no skipped runs from the other pipelines).
+
 | Workflow | File | Tag Prefix | Target |
 |----------|------|------------|--------|
+| Release Router | `release.yml` | (all releases) | dispatches the matching workflow below |
 | 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`) |
+| OpenCode Plugin | `opencode-plugin-cd.yml` | `opencode-v*` | npm (`@mem0/opencode-plugin`) |
+| Pi Agent Plugin | `pi-agent-plugin-cd.yml` | `pi-agent-v*` | npm (`@mem0/pi-agent-plugin`) |
 
+- Package CD workflows are `workflow_dispatch`-only (inputs: `tag`, `prerelease`); they check out and build the given tag. Registry trusted-publisher settings stay pinned to each package's own workflow filename.
 - 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.
+- To re-publish a release (e.g. after a registry settings fix), do **not** delete/recreate the GitHub release — manually dispatch the package workflow instead: `gh workflow run <package>-cd.yml --ref refs/tags/<tag> -f tag=<tag>`.
+- When adding a new package: add its CD workflow (`workflow_dispatch` with `tag`/`prerelease` inputs), then register its tag prefix in the `case` block in `release.yml`. Keep the bare `v*` arm last.
 
 ### Utility Workflows
 
@@ -576,7 +603,6 @@ N/A
 - 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.

CONTRIBUTING.md

@@ -1,72 +1,157 @@
-# Contributing to mem0
+# Contributing to Mem0
 
-Let us make contribution easy, collaborative and fun.
+First off, thank you for taking the time to contribute! 🎉 Mem0 is a
+community-driven project and we welcome contributions of all kinds — bug fixes,
+new features, documentation, examples, and integrations.
 
-## Submit your Contribution through PR
+Mem0 is a polyglot monorepo, and this guide covers contributing to both the
+**Python SDK** and the **TypeScript SDK** (and the rest of the repository).
 
-To make a contribution, follow these steps:
+## Before You Start
 
-1. Fork and clone this repository
-2. Do the changes on your fork with dedicated feature branch `feature/f1`
-3. If you modified the code (new feature or bug-fix), please add tests for it
-4. Include proper documentation / docstring and examples to run the feature
-5. Ensure that all tests pass
-6. Submit a pull request
+### 1. Open an Issue First
 
-For more details about pull requests, please read [GitHub's guides](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+**Always open an issue before opening a pull request.** This lets us discuss the
+change, avoid duplicate effort, and agree on the approach before you invest time
+in code.
 
+- Search [existing issues](https://github.com/mem0ai/mem0/issues) first to see if
+  your bug or idea already exists.
+- If it doesn't, open a
+  [bug report](https://github.com/mem0ai/mem0/issues/new?template=bug_report.yml) or
+  [feature request](https://github.com/mem0ai/mem0/issues/new?template=feature_request.yml).
+- For anything beyond a trivial fix, wait for a maintainer to confirm the approach
+  before starting significant work.
 
-### 📦 Development Environment
+Every pull request must link to an issue using `Closes #<issue-number>`.
 
-We use `hatch` for managing development environments. To set up:
+### 2. Sign the Contributor License Agreement (CLA)
+
+**We cannot accept or merge any pull request until you have signed our Contributor
+License Agreement (CLA).**
+
+When you open your first PR, the CLA bot will automatically comment with a link to
+sign. Signing takes less than a minute and only needs to be done once. Pull
+requests from contributors who have not signed the CLA will be blocked from
+merging.
+
+## Repository Layout
+
+The two most common contribution targets are the SDKs:
+
+| Package               | Path       | Language     | Package manager |
+| --------------------- | ---------- | ------------ | --------------- |
+| Python SDK (`mem0ai`) | `mem0/`    | Python 3.9+  | `hatch`         |
+| TypeScript SDK (`mem0ai`) | `mem0-ts/` | TypeScript | `pnpm`        |
+
+Other packages include the CLIs (`cli/python/`, `cli/node/`), integrations
+(`integrations/`), the self-hosted `server/`, `openmemory/`, and the docs site
+(`docs/`). See [AGENTS.md](./AGENTS.md) for a full map of the repository.
+
+## Development Workflow
+
+1. **Fork** the repository and **clone** your fork.
+2. Create a **feature branch** from `main` (e.g. `feature/my-new-feature` or
+   `fix/issue-1234`).
+3. Make your changes — add **tests**, **documentation**, and **examples** as
+   appropriate.
+4. Run **linting and tests** for every package you touched (see below).
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/)
+   (e.g. `feat:`, `fix:`, `docs:`, `refactor:`, `test:`).
+6. Push and open a **pull request** against `main`, linking the issue with
+   `Closes #<number>` and filling out the
+   [PR template](./.github/PULL_REQUEST_TEMPLATE.md).
+
+### Contributing to the Python SDK (`mem0/`)
+
+We use [`hatch`](https://hatch.pypa.io/latest/install/) to manage environments.
+**Do not use `pip` or `conda` for dependency management.**
 
 ```bash
-# Activate environment for specific Python version:
-hatch shell dev_py_3_9   # Python 3.9
-hatch shell dev_py_3_10  # Python 3.10  
-hatch shell dev_py_3_11  # Python 3.11
-hatch shell dev_py_3_12  # Python 3.12
+# Activate a dev environment (3.9 / 3.10 / 3.11 / 3.12)
+hatch shell dev_py_3_11
 
-# The environment will automatically install all dev dependencies
-# Run tests within the activated shell:
-make test
-```
-
-### 📌 Pre-commit
-
-To ensure our standards, make sure to install pre-commit before starting to contribute.
-
-```bash
+# Install pre-commit hooks (runs ruff + isort on commit)
 pre-commit install
+
+# Lint, format, and sort imports
+make lint
+make format
+make sort
+
+# Run the test suite (run `make install_all` first if deps are missing)
+make test
 ```
 
-### 🧪 Testing
+- **Linter / formatter:** Ruff (line length **120**)
+- **Import sorting:** isort (`profile = "black"`)
+- **Tests:** pytest (in `tests/`)
 
-We use `pytest` to test our code across multiple Python versions. You can run tests using:
+See the full [Development guide](https://docs.mem0.ai/contributing/development) for
+environment details.
+
+### Contributing to the TypeScript SDK (`mem0-ts/`)
+
+We use [`pnpm`](https://pnpm.io/) (v10+) for all TypeScript packages. **Do not use
+`npm` or `yarn`.**
 
 ```bash
-# Run tests with default Python version
-make test
+cd mem0-ts
+pnpm install
 
-# Test specific Python versions:
-make test-py-3.9   # Python 3.9 environment
-make test-py-3.10  # Python 3.10 environment
-make test-py-3.11  # Python 3.11 environment
-make test-py-3.12  # Python 3.12 environment
-
-# When using hatch shells, run tests with:
-make test  # After activating a shell with hatch shell test_XX
+pnpm run build        # tsup (CJS + ESM)
+pnpm run test         # jest (all tests)
+pnpm run test:unit    # unit tests with coverage
 ```
 
-Make sure that all tests pass across all supported Python versions before submitting a pull request.
+- **Build:** tsup
+- **Formatter:** Prettier
+- **Tests:** jest
+- Always run type checking after changes: `pnpm run typecheck` (or `tsc --noEmit`).
+- Use ES module `import` syntax — never `require()`.
 
-We look forward to your pull requests and can't wait to see your contributions!
+## Good Contribution Practices
 
-### 🚀 Releasing
+- **Keep PRs small and focused.** One logical change per PR is easier to review and
+  merge.
+- **Follow existing patterns.** Match the style, structure, and conventions of the
+  code around you. Don't introduce new frameworks or abstractions without
+  discussion.
+- **Write tests** that would fail without your change — regression tests for bugs,
+  coverage for new features.
+- **Update documentation** in `docs/` for any user-facing change. New `.mdx` pages
+  must be added to `docs/llms.txt` (run
+  `python scripts/check-llms-txt-coverage.py --write` to scaffold entries).
+- **Add examples** when introducing new user-facing behavior.
+- **Run linters and tests locally** before pushing — CI re-runs them on every PR
+  via the CI Gate.
+- **Never commit secrets** — no `.env` files, API keys, or credentials.
+- **Don't add core dependencies lightly.** New Python dependencies belong in an
+  optional group in `pyproject.toml`, not the core `dependencies` list.
+- **Be responsive** to review feedback and keep your branch up to date with `main`.
 
-All packages are published automatically via GitHub Actions when a GitHub Release is created with the correct tag prefix.
+## Pull Request Checklist
 
-#### Tag Prefixes
+Before requesting review, make sure:
+
+- [ ] An issue exists and is linked with `Closes #<number>`
+- [ ] You have signed the CLA
+- [ ] Your code follows the project's style guidelines (lint passes)
+- [ ] You performed a self-review of your changes
+- [ ] Tests are added/updated and pass locally
+- [ ] Documentation is updated if needed
+
+## Reporting Security Issues
+
+**Do not report security vulnerabilities through public issues or pull requests.**
+Please follow our [Security Policy](./SECURITY.md) to report them privately.
+
+## 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 |
 |---------|----------|------------|---------|
@@ -77,15 +162,17 @@ All packages are published automatically via GitHub Actions when a GitHub Releas
 | `@mem0/vercel-ai-provider` | npm | `vercel-ai-v*` | `vercel-ai-v2.0.6` |
 | `@mem0/openclaw-mem0` | npm | `openclaw-v*` | `openclaw-v1.0.1` |
 
-#### How to Release
+### How to Release
 
 1. Bump the version in `pyproject.toml` (Python) or `package.json` (Node)
 2. Create a [GitHub Release](https://github.com/mem0ai/mem0/releases/new) with the matching tag prefix
 3. The correct workflow will trigger automatically — verify in the [Actions tab](https://github.com/mem0ai/mem0/actions)
 
-#### Publishing Details
+### Publishing Details
 
 - **PyPI packages** use OIDC trusted publishing via `pypa/gh-action-pypi-publish`
 - **npm packages** use OIDC trusted publishing via npm CLI (>= 11.5.1) — no tokens or secrets required
 - All workflows require `permissions: id-token: write` for OIDC authentication
 - First publish of a new npm package must be done manually; OIDC works for subsequent versions
+
+We look forward to your pull requests and can't wait to see your contributions!

LLM.md

@@ -1026,7 +1026,8 @@ def get_user_preferences(user_id: str):
 ### AutoGen Integration
 
 ```python
-from cookbooks.helper.mem0_teachability import Mem0Teachability
+# Mem0Teachability lives in examples/notebooks/helper/ — see examples/notebooks/mem0-autogen.ipynb
+from helper.mem0_teachability import Mem0Teachability
 from mem0 import Memory
 
 # Add memory capability to AutoGen agents

MIGRATION_GUIDE_v1.0.md

@@ -1,221 +0,0 @@
-# Migration Guide: Upgrading to mem0 1.0.0
-
-## TL;DR
-
-**What changed?** We simplified the API by removing confusing version parameters. Now everything returns a consistent format: `{"results": [...]}`.
-
-**What you need to do:**
-1. Upgrade: `pip install mem0ai==1.0.0`
-2. Remove `version` and `output_format` parameters from your code
-3. Update response handling to use `result["results"]` instead of treating responses as lists
-
-**Time needed:** ~5-10 minutes for most projects
-
----
-
-## Quick Migration Guide
-
-### 1. Install the Update
-
-```bash
-pip install mem0ai==1.0.0
-```
-
-### 2. Update Your Code
-
-**If you're using the Memory API:**
-
-```python
-# Before
-memory = Memory(config=MemoryConfig(version="v1.1"))
-result = memory.add("I like pizza")
-
-# After
-memory = Memory()  # That's it - version is automatic now
-result = memory.add("I like pizza")
-```
-
-**If you're using the Client API:**
-
-```python
-# Before
-client.add(messages, output_format="v1.1")
-client.search(query, version="v2", output_format="v1.1")
-
-# After
-client.add(messages)  # Just remove those extra parameters
-client.search(query)
-```
-
-### 3. Update How You Handle Responses
-
-All responses now use the same format: a dictionary with `"results"` key.
-
-```python
-# Before - you might have done this
-result = memory.add("I like pizza")
-for item in result:  # Treating it as a list
-    print(item)
-
-# After - do this instead
-result = memory.add("I like pizza")
-for item in result["results"]:  # Access the results key
-    print(item)
-
-# Graph relations (if you use them)
-if "relations" in result:
-    for relation in result["relations"]:
-        print(relation)
-```
-
----
-
-## Enhanced Message Handling
-
-The platform client (MemoryClient) now supports the same flexible message formats as the OSS version:
-
-```python
-from mem0 import MemoryClient
-
-client = MemoryClient(api_key="your-key")
-
-# All three formats now work:
-
-# 1. Single string (automatically converted to user message)
-client.add("I like pizza", user_id="alice")
-
-# 2. Single message dictionary
-client.add({"role": "user", "content": "I like pizza"}, user_id="alice")
-
-# 3. List of messages (conversation)
-client.add([
-    {"role": "user", "content": "I like pizza"},
-    {"role": "assistant", "content": "I'll remember that!"}
-], user_id="alice")
-```
-
-### Async Mode Configuration
-
-The `async_mode` parameter now defaults to `True` but can be configured:
-
-```python
-# Default behavior (async_mode=True)
-client.add(messages, user_id="alice")
-
-# Explicitly set async mode
-client.add(messages, user_id="alice", async_mode=True)
-
-# Disable async mode if needed
-client.add(messages, user_id="alice", async_mode=False)
-```
-
-**Note:** `async_mode=True` provides better performance for most use cases. Only set it to `False` if you have specific synchronous processing requirements.
-
----
-
-## That's It!
-
-For most users, that's all you need to know. The changes are:
-- ✅ No more `version` or `output_format` parameters
-- ✅ Consistent `{"results": [...]}` response format
-- ✅ Cleaner, simpler API
-
----
-
-## Common Issues
-
-**Getting `KeyError: 'results'`?**
-
-Your code is still treating the response as a list. Update it:
-```python
-# Change this:
-for memory in response:
-
-# To this:
-for memory in response["results"]:
-```
-
-**Getting `TypeError: unexpected keyword argument`?**
-
-You're still passing old parameters. Remove them:
-```python
-# Change this:
-client.add(messages, output_format="v1.1")
-
-# To this:
-client.add(messages)
-```
-
-**Seeing deprecation warnings?**
-
-Remove any explicit `version="v1.0"` from your config:
-```python
-# Change this:
-memory = Memory(config=MemoryConfig(version="v1.0"))
-
-# To this:
-memory = Memory()
-```
-
----
-
-## What's New in 1.0.0
-
-- **Better vector stores:** Fixed OpenSearch and improved reliability across all stores
-- **Cleaner API:** One way to do things, no more confusing options
-- **Enhanced GCP support:** Better Vertex AI configuration options
-- **Flexible message input:** Platform client now accepts strings, dicts, and lists (aligned with OSS)
-- **Configurable async_mode:** Now defaults to `True` but users can override if needed
-
----
-
-## Need Help?
-
-- Check [GitHub Issues](https://github.com/mem0ai/mem0/issues)
-- Read the [documentation](https://docs.mem0.ai/)
-- Open a new issue if you're stuck
-
----
-
-## Advanced: Configuration Changes
-
-**If you configured vector stores with version:**
-
-```python
-# Before
-config = MemoryConfig(
-    version="v1.1",
-    vector_store=VectorStoreConfig(...)
-)
-
-# After
-config = MemoryConfig(
-    vector_store=VectorStoreConfig(...)
-)
-```
-
----
-
-## Testing Your Migration
-
-Quick sanity check:
-
-```python
-from mem0 import Memory
-
-memory = Memory()
-
-# Add should return a dict with "results"
-result = memory.add("I like pizza", user_id="test")
-assert "results" in result
-
-# Search should return a dict with "results"
-search = memory.search("food", user_id="test")
-assert "results" in search
-
-# Get all should return a dict with "results"
-all_memories = memory.get_all(user_id="test")
-assert "results" in all_memories
-
-print("✅ Migration successful!")
-```

README.md

@@ -46,12 +46,12 @@
 
 | Benchmark | Old | New  | Tokens  | Latency p50  |
 | --- | --- | --- | --- | --- |
-| **LoCoMo** | 71.4 | **91.6** | 7.0K  | 0.88s  |
-| **LongMemEval** | 67.8 | **94.8** | 6.8K  | 1.09s  |
+| **LoCoMo** | 71.4 | **92.5** | 7.0K  | 0.88s  |
+| **LongMemEval** | 67.8 | **94.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).
+All benchmarks run on the same production-representative model stack. Single-pass retrieval (one call, no agentic loops) at a top_200 retrieval budget. Scores reflect Mem0's managed platform, which includes proprietary optimizations not available in the open-source SDK; open-source users should expect directionally similar gains but not identical numbers.
 
 **What changed:**
 - **Single-pass ADD-only extraction** -- one LLM call, no UPDATE/DELETE. Memories accumulate; nothing is overwritten.
@@ -63,8 +63,8 @@ All benchmarks run on the same production-representative model stack. Single-pas
 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
-- **94.8 on LongMemEval** -- +27 points, with +53.6 on assistant memory recall
+- **92.5 on LoCoMo** -- +21 points over the previous algorithm
+- **94.4 on LongMemEval** -- +27 points, with 98.2 on assistant memory recall
 - **64.1 on BEAM (1M)** -- production-scale memory evaluation at 1M tokens
 - [Read the full paper](https://mem0.ai/research)
 
@@ -86,6 +86,26 @@ See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for upgra
 
 ## 🚀 Quickstart Guide <a name="quickstart"></a>
 
+### Sign up as an agent
+
+AI agents can mint a working Mem0 API key in under five seconds — no email, no dashboard, no OTP. Four commands end-to-end:
+
+```bash
+# 1. Install
+npm install -g @mem0/cli      # or: pip install mem0-cli
+
+# 2. Sign up as an agent (replace `claude-code` with your name)
+mem0 init --agent --agent-caller claude-code
+
+# 3. Add a memory
+mem0 add "I am using mem0"
+
+# 4. Search
+mem0 search "am I using mem0"
+```
+
+The human owner can claim the account later with `mem0 init --email <their-email>` — same key, memories preserved. Full guide: [Sign up as an agent](https://docs.mem0.ai/platform/agent-signup).
+
 | | Library | Self-Hosted Server | Cloud Platform |
 |---|---------|-------------------|----------------|
 | **Best for** | Testing, prototyping | Teams running on their own infrastructure | Zero-ops production use |
@@ -133,6 +153,7 @@ See the [self-hosted docs](https://docs.mem0.ai/open-source/overview) for config
 
 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
+3. Using hosted Qdrant vectors? See the [Platform migration guide](https://docs.mem0.ai/migration/oss-to-platform) to import them into Mem0 Platform.
 
 ### CLI
 
@@ -165,9 +186,10 @@ npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk
 ```bash
 npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
 npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform
 ```
 
-Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture.
+Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. Use `/mem0-oss-to-platform` to migrate an existing project from Mem0 OSS to the hosted Platform SDK. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture.
 
 ### Basic Usage
 

SECURITY.md

@@ -0,0 +1,48 @@
+# Security Policy
+
+We take the security of Mem0 and our community seriously. Thank you for helping
+keep Mem0 and its users safe by disclosing vulnerabilities responsibly.
+
+## Reporting a Vulnerability
+
+Please **do not** report security vulnerabilities through public GitHub issues,
+pull requests, or discussions.
+
+If you believe you have found a security vulnerability in Mem0, please report it
+privately through one of the following channels:
+
+1. **GitHub Private Vulnerability Reporting** — open a
+   [private security advisory](https://github.com/mem0ai/mem0/security/advisories/new)
+   directly on this repository.
+2. **Email** the maintainers at **support@mem0.ai** with the subject line:
+
+   `SECURITY: Mem0 vulnerability report`
+
+To help us triage and resolve the issue quickly, please include as much of the
+following as you can:
+
+- Affected component or package (e.g. Python SDK, TypeScript SDK, server, OpenMemory)
+- Affected version, tag, or commit
+- Clear, step-by-step reproduction instructions
+- The security impact and a proof of concept, if available
+- Any suggested fix or mitigation
+
+## Response Process
+
+- We will acknowledge receipt of your report within **72 hours**.
+- We will work with you privately to confirm the issue and assess its impact.
+- Once a fix or mitigation is ready, we will coordinate a disclosure timeline
+  with you and credit you for the discovery, unless you prefer to remain anonymous.
+
+## Public Disclosure
+
+Please avoid sharing technical details of the vulnerability publicly until the
+maintainers have reviewed the issue and a fix or mitigation has been released. We
+are committed to resolving valid reports promptly and keeping you informed
+throughout the process.
+
+## Supported Versions
+
+We release security fixes against the latest published version of each package.
+Whenever possible, please reproduce the issue on the most recent release before
+reporting.

cli/cli-spec.json

@@ -503,7 +503,7 @@
     },
     {
       "name": "init",
-      "description": "Setup wizard for mem0 CLI. Supports email login (--email) or manual API key (--api-key).",
+      "description": "Setup wizard for mem0 CLI. Supports Agent Mode bootstrap (--agent), email login (--email), or manual API key (--api-key).",
       "usage": "mem0 init [OPTIONS]",
       "needsBackend": false,
       "needsConfig": false,
@@ -516,7 +516,9 @@
         { "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": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Overwrite existing config without confirmation." },
+        { "name": "agent", "flags": ["--agent"], "type": "boolean", "default": false, "help": "Bootstrap an unattended Agent Mode account (no email required)." },
+        { "name": "source", "flags": ["--source"], "type": "string", "default": null, "help": "Channel attribution for signup (e.g. github, hn, ph)." }
       ]
     },
     {

cli/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/cli",
-  "version": "0.2.4",
+  "version": "0.2.11",
   "description": "The official CLI for mem0 — the memory layer for AI agents",
   "type": "module",
   "bin": {
@@ -40,8 +40,19 @@
     "typescript": "^5.4.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
-    "vitest": "^1.5.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.0",
     "@biomejs/biome": "^1.7.0",
     "@types/node": "^20.0.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "jws@4.0.0": "4.0.1",
+      "langsmith@<0.6.0": "^0.6.0",
+      "tar-fs@>=2.0.0 <2.1.4": "^2.1.4",
+      "picomatch@<2.3.2": "^2.3.2",
+      "postcss@<8.5.10": ">=8.5.10",
+      "esbuild": ">=0.28.1"
+    }
   }
 }

cli/node/pnpm-workspace.yaml

@@ -0,0 +1,14 @@
+packages:
+  - '.'
+
+onlyBuiltDependencies:
+  - "@biomejs/biome"
+  - esbuild
+
+overrides:
+  jws@4.0.0: 4.0.1
+  langsmith@<0.6.0: ^0.6.0
+  tar-fs@>=2.0.0 <2.1.4: ^2.1.4
+  picomatch@<2.3.2: ^2.3.2
+  "postcss@<8.5.10": ">=8.5.10"
+  "esbuild": ">=0.28.1"

cli/node/src/agent-detect.ts

@@ -0,0 +1,32 @@
+/**
+ * Detect whether the CLI is being invoked from inside an AI-agent context.
+ *
+ * Used by `mem0 init` to auto-enter Agent Mode (Rule 3 bootstrap) when an
+ * agent runtime env var is present. The return value is a context **trigger
+ * only** — the canonical agent identity is self-declared by the agent via
+ * `--agent-caller <name>` (Proof Editor-style) and never sniffed from env
+ * vars to fill the `agent_caller` field on the APIKey row.
+ *
+ * Returns a short name or null. Honest reporting depends on `--agent-caller`;
+ * this list is just enough to enable the zero-friction auto-bootstrap UX.
+ */
+
+const AGENT_CALLER_ENV: ReadonlyArray<readonly [string, readonly string[]]> = [
+	["claude-code", ["CLAUDECODE", "CLAUDE_CODE"]],
+	["cursor", ["CURSOR_AGENT", "CURSOR_SESSION_ID"]],
+	["codex", ["CODEX_CLI", "OPENAI_CODEX"]],
+	["cline", ["CLINE_AGENT", "CLINE"]],
+	["continue", ["CONTINUE_AGENT", "CONTINUE_SESSION"]],
+	["aider", ["AIDER_SESSION"]],
+	["goose", ["GOOSE_AGENT"]],
+	["windsurf", ["WINDSURF_AGENT"]],
+] as const;
+
+export function detectAgentCaller(): string | null {
+	for (const [name, envVars] of AGENT_CALLER_ENV) {
+		if (envVars.some((v) => process.env[v])) {
+			return name;
+		}
+	}
+	return null;
+}

cli/node/src/backend/platform.ts

@@ -3,7 +3,7 @@
  */
 
 import type { PlatformConfig } from "../config.js";
-import { isAgentMode } from "../state.js";
+import { captureNotice, isAgentMode } from "../state.js";
 import { CLI_VERSION } from "../version.js";
 import {
 	APIError,
@@ -17,6 +17,10 @@ import {
 	type SearchOptions,
 } from "./base.js";
 
+function encodePathSegment(value: unknown): string {
+	return encodeURIComponent(String(value));
+}
+
 export class PlatformBackend implements Backend {
 	private baseUrl: string;
 	private headers: Record<string, string>;
@@ -90,7 +94,39 @@ export class PlatformBackend implements Backend {
 		if (resp.status === 204) {
 			return {};
 		}
-		return resp.json();
+
+		const data = await resp.json();
+
+		// Pull the unclaimed-Agent-Mode notice out of the body (or the header
+		// fallback for endpoints returning non-dict / non-dict-leading payloads)
+		// and stash for end-of-command surfacing.
+		let notice: string | null = null;
+		if (
+			data &&
+			typeof data === "object" &&
+			!Array.isArray(data) &&
+			"mem0_notice" in data
+		) {
+			notice = (data as Record<string, unknown>).mem0_notice as string;
+			// biome-ignore lint/performance/noDelete: intentional strip so downstream consumers don't see duplicate notice
+			delete (data as Record<string, unknown>).mem0_notice;
+		} else if (
+			Array.isArray(data) &&
+			data.length > 0 &&
+			typeof data[0] === "object" &&
+			data[0] !== null &&
+			"mem0_notice" in data[0]
+		) {
+			notice = (data[0] as Record<string, unknown>).mem0_notice as string;
+			// biome-ignore lint/performance/noDelete: see above.
+			delete (data[0] as Record<string, unknown>).mem0_notice;
+		}
+		if (!notice) {
+			notice = resp.headers.get("X-Mem0-Notice-Message") ?? null;
+		}
+		captureNotice(notice);
+
+		return data;
 	}
 
 	async add(
@@ -186,9 +222,13 @@ export class PlatformBackend implements Backend {
 	}
 
 	async get(memoryId: string): Promise<Record<string, unknown>> {
-		return (await this._request("GET", `/v1/memories/${memoryId}/`, {
-			params: { source: "CLI" },
-		})) as Record<string, unknown>;
+		return (await this._request(
+			"GET",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				params: { source: "CLI" },
+			},
+		)) as Record<string, unknown>;
 	}
 
 	async listMemories(
@@ -245,9 +285,13 @@ export class PlatformBackend implements Backend {
 		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>;
+		return (await this._request(
+			"PUT",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				json: payload,
+			},
+		)) as Record<string, unknown>;
 	}
 
 	async delete(
@@ -265,9 +309,13 @@ export class PlatformBackend implements Backend {
 			})) as Record<string, unknown>;
 		}
 		if (memoryId) {
-			return (await this._request("DELETE", `/v1/memories/${memoryId}/`, {
-				params: { source: "CLI" },
-			})) as Record<string, unknown>;
+			return (await this._request(
+				"DELETE",
+				`/v1/memories/${encodePathSegment(memoryId)}/`,
+				{
+					params: { source: "CLI" },
+				},
+			)) as Record<string, unknown>;
 		}
 		throw new Error("Either memoryId or --all is required");
 	}
@@ -284,16 +332,18 @@ export class PlatformBackend implements Backend {
 		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> = {};
+		// Delete each provided entity via the v2 path-based endpoint. Key each
+		// response by entity type so a multi-entity delete (e.g. --user-id and
+		// --agent-id together) doesn't discard everything but the last result.
+		const results: Record<string, unknown> = {};
 		for (const [entityType, entityId] of entities) {
-			result = (await this._request(
+			results[entityType] = (await this._request(
 				"DELETE",
-				`/v2/entities/${entityType}/${entityId}/`,
+				`/v2/entities/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/`,
 				{ params: { source: "CLI" } },
 			)) as Record<string, unknown>;
 		}
-		return result;
+		return results;
 	}
 
 	async ping(): Promise<Record<string, unknown>> {
@@ -352,9 +402,9 @@ export class PlatformBackend implements Backend {
 	}
 
 	async getEvent(eventId: string): Promise<Record<string, unknown>> {
-		return (await this._request("GET", `/v1/event/${eventId}/`)) as Record<
-			string,
-			unknown
-		>;
+		return (await this._request(
+			"GET",
+			`/v1/event/${encodePathSegment(eventId)}/`,
+		)) as Record<string, unknown>;
 	}
 }

cli/node/src/commands/agent-mode.ts

@@ -0,0 +1,285 @@
+/**
+ * Agent Mode commands — bootstrap (unattended signup) and OTP-based claim.
+ */
+
+import readline from "node:readline";
+import { colors, printError, printInfo, printSuccess } from "../branding.js";
+import { type Mem0Config, saveConfig } from "../config.js";
+
+const { brand, dim } = colors;
+
+const SOURCE_HEADERS = {
+	"X-Mem0-Source": "cli",
+	"X-Mem0-Client-Language": "node",
+} as const;
+
+export interface BootstrapEnvelope {
+	api_key: string;
+	default_user_id: string;
+	org_id: string;
+	project_id: string;
+	mcp_url?: string;
+	smoke_test_url?: string;
+	claim_command?: string;
+	mem0_notice?: string;
+}
+
+function isValidEnvelope(v: unknown): v is BootstrapEnvelope {
+	return (
+		!!v &&
+		typeof v === "object" &&
+		typeof (v as BootstrapEnvelope).api_key === "string" &&
+		(v as BootstrapEnvelope).api_key.length > 0 &&
+		typeof (v as BootstrapEnvelope).default_user_id === "string" &&
+		(v as BootstrapEnvelope).default_user_id.length > 0
+	);
+}
+
+/**
+ * POST /api/v1/auth/agent_mode/ and mutate config in place.
+ *
+ * @param config - Mem0Config mutated in place with the new platform values.
+ * @param source - `--source` flag passthrough (analytics tag, free-form).
+ * @param agentCaller - Self-declared agent identity passed via `--agent-caller`
+ *   (e.g. `claude-code`, `cursor`). May be null when the caller omitted the
+ *   flag; the agent can backfill later via `mem0 identify <name>`. Sent to the
+ *   backend in the request body and saved into `platform.agentCaller` for
+ *   local introspection.
+ */
+export async function bootstrapViaBackend(
+	config: Mem0Config,
+	{
+		source,
+		agentCaller,
+	}: { source?: string | null; agentCaller?: string | null } = {},
+): Promise<void> {
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+	const body: Record<string, unknown> = {};
+	if (source) body.source = source;
+	if (agentCaller) body.agent_caller = agentCaller;
+
+	let resp: Response;
+	try {
+		resp = await fetch(`${baseUrl}/api/v1/auth/agent_mode/`, {
+			method: "POST",
+			headers: {
+				...SOURCE_HEADERS,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(30_000),
+		});
+	} catch (err) {
+		printError(
+			`Network error contacting Mem0: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		process.exit(1);
+	}
+
+	if (resp.status === 429) {
+		printError("Rate-limited. Try again in a few minutes.");
+		process.exit(1);
+	}
+	if (resp.status === 503) {
+		printError("Agent Mode is temporarily disabled. Try again later.");
+		process.exit(1);
+	}
+	if (!resp.ok) {
+		let detail: string = resp.statusText;
+		try {
+			const errBody = (await resp.json()) as {
+				error?: string;
+				detail?: string;
+			};
+			detail = errBody.error ?? errBody.detail ?? resp.statusText;
+		} catch {
+			/* leave detail as statusText */
+		}
+		// Backend's @ratelimit decorator raises PermissionDenied, which DRF
+		// translates to a generic 403 "You do not have permission to perform
+		// this action." That's opaque — surface it as the rate-limit message
+		// it actually is.
+		if (resp.status === 403 && /permission/i.test(detail)) {
+			printError(
+				"Daily Agent Mode signup limit reached for this network (5/day). Try again from a different IP or after midnight UTC.",
+			);
+			process.exit(1);
+		}
+		printError(`Bootstrap failed: ${detail}`);
+		process.exit(1);
+	}
+
+	const envelope = (await resp.json()) as BootstrapEnvelope;
+	if (!isValidEnvelope(envelope)) {
+		// Defend against partial/malformed backend responses (e.g. {api_key: null}).
+		// Without this guard, the typed `string` field is silently set to
+		// undefined/null and persisted, producing confusing downstream errors.
+		printError(
+			"Bootstrap response missing required fields — please update the CLI.",
+		);
+		process.exit(1);
+	}
+
+	config.platform.apiKey = envelope.api_key;
+	config.platform.baseUrl = baseUrl;
+	config.platform.agentMode = true;
+	config.platform.createdVia = "agent_mode";
+	config.platform.agentCaller = agentCaller ?? "";
+	config.platform.claimedAt = "";
+	config.platform.defaultUserId = envelope.default_user_id;
+	// Adopt the slug-derived user_id as the default scope for memory ops.
+	config.defaults.userId = envelope.default_user_id;
+	saveConfig(config);
+
+	printSuccess(
+		`Agent Mode active. Default user_id: ${envelope.default_user_id}`,
+	);
+	if (envelope.mem0_notice) {
+		console.log(`\n\x1b[33m🔔 ${envelope.mem0_notice}\x1b[0m\n`);
+	} else {
+		// Fallback for older backends without the unified notice field.
+		const claimCmd = envelope.claim_command ?? "mem0 init --email <your-email>";
+		console.log(`  ${dim(`To claim this account later: ${claimCmd}`)}`);
+	}
+
+	if (!agentCaller) {
+		console.log(
+			`  ${dim("If you are an AI agent, identify yourself: `mem0 identify <your-name>` (e.g. claude-code, cursor).")}`,
+		);
+	}
+}
+
+/**
+ * Claim an existing Agent Mode account via OTP — no browser, no polling.
+ *
+ * Hits /api/v1/auth/email_code/ to send a verification code, prompts for it
+ * interactively (or accepts via `code`), then sends it to /verify/ alongside
+ * `agent_mode_api_key`. Backend's verify_email_code runs upgrade-in-place
+ * inline and returns the claim result.
+ */
+export async function claimViaOtp(
+	config: Mem0Config,
+	{ email, code }: { email: string; code?: string },
+): Promise<void> {
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+	if (!config.platform.apiKey || !config.platform.agentMode) {
+		printError(
+			"This command requires an active Agent Mode config. Run `mem0 init` first.",
+		);
+		process.exit(1);
+	}
+
+	const rawKey = config.platform.apiKey;
+
+	// Step 1: request OTP (unless --code was supplied)
+	if (!code) {
+		const sendResp = await fetch(`${baseUrl}/api/v1/auth/email_code/`, {
+			method: "POST",
+			headers: { ...SOURCE_HEADERS, "Content-Type": "application/json" },
+			body: JSON.stringify({ email }),
+			signal: AbortSignal.timeout(30_000),
+		});
+		if (sendResp.status === 429) {
+			printError("Too many attempts. Try again in a few minutes.");
+			process.exit(1);
+		}
+		if (!sendResp.ok) {
+			let detail: string = sendResp.statusText;
+			try {
+				const errBody = (await sendResp.json()) as { error?: string };
+				if (errBody.error) detail = errBody.error;
+			} catch {
+				/* leave as statusText */
+			}
+			printError(`Failed to send code: ${detail}`);
+			process.exit(1);
+		}
+
+		printSuccess(`Verification code sent to ${email}. Check your inbox.`);
+
+		if (!process.stdin.isTTY) {
+			printError(
+				"No --code provided and terminal is non-interactive.",
+				`Re-run: mem0 init --email ${email} --code <code>`,
+			);
+			process.exit(1);
+		}
+
+		console.log();
+		code = await promptLine(`  ${brand("Verification Code")}`);
+		if (!code) {
+			printError("Code is required.");
+			process.exit(1);
+		}
+	}
+
+	// Step 2: verify + claim atomically
+	const verifyResp = await fetch(`${baseUrl}/api/v1/auth/email_code/verify/`, {
+		method: "POST",
+		headers: { ...SOURCE_HEADERS, "Content-Type": "application/json" },
+		body: JSON.stringify({
+			email,
+			code: code.trim(),
+			agent_mode_api_key: rawKey,
+		}),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	if (!verifyResp.ok) {
+		let detail: string = verifyResp.statusText;
+		let errCode = "";
+		try {
+			const errBody = (await verifyResp.json()) as {
+				error?: string;
+				code?: string;
+			};
+			if (errBody.error) detail = errBody.error;
+			if (errBody.code) errCode = errBody.code;
+		} catch {
+			/* leave as statusText */
+		}
+		printError(`Claim failed: ${detail}`);
+		if (errCode === "email_already_claimed") {
+			console.log(
+				`  ${dim("Tip: this email already has a Mem0 account. Sign in at app.mem0.ai with your existing credentials.")}`,
+			);
+		}
+		process.exit(1);
+	}
+
+	const claimBody = (await verifyResp.json()) as {
+		claimed?: boolean;
+		claimed_at?: string;
+	};
+	if (!claimBody.claimed) {
+		printError(`Unexpected verify response: ${JSON.stringify(claimBody)}`);
+		process.exit(1);
+	}
+
+	config.platform.agentMode = false;
+	config.platform.claimedAt = claimBody.claimed_at ?? new Date().toISOString();
+	config.platform.userEmail = email;
+	config.platform.createdVia = "email";
+	saveConfig(config);
+
+	printSuccess(`Agent claimed to ${email}. Your API key is unchanged.`);
+}
+
+function promptLine(label: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) => {
+		rl.question(`${label}: `, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}

cli/node/src/commands/agent-rush.ts

@@ -0,0 +1,147 @@
+/**
+ * `mem0 agent-rush <add|search> "..."` — wraps the AGENTRUSH platform endpoints.
+ * Project routing is implicit (server-side); zero flags needed.
+ */
+
+import readline from "node:readline";
+import { colors, printError, printSuccess } from "../branding.js";
+import { loadConfig, saveConfig } from "../config.js";
+import { CLI_VERSION } from "../version.js";
+
+const PII_WARNING = [
+	"",
+	"⚠️  AGENTRUSH memories are PUBLIC — visible to any other player.",
+	"   Do not include real names, emails, secrets, work content, or PII.",
+	"",
+].join("\n");
+
+const ERROR_HINTS: Record<string, string> = {
+	agentrush_search_first:
+		"Run 3 'mem0 agent-rush search' commands before adding.",
+	agentrush_search_quota: "You've used your 3 lifetime searches.",
+	agentrush_add_quota: "You've used your 3 lifetime adds.",
+	agentrush_not_agent_mode:
+		"Re-run 'mem0 init --agent' to bootstrap an agent-mode key.",
+	agentrush_length: "Memory text must be 50-1000 characters.",
+	agentrush_no_urls: "URLs are not allowed.",
+	agentrush_blocklist: "Content contains a blocked term.",
+	agentrush_global_quota: "Event-wide cap reached. Try again later.",
+	agentrush_not_provisioned:
+		"AGENTRUSH is not provisioned in this environment.",
+};
+
+async function callEndpoint(
+	path: string,
+	body: Record<string, unknown>,
+): Promise<unknown> {
+	const config = loadConfig();
+	const baseUrl = (config.platform?.baseUrl ?? "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+
+	if (!config.platform?.apiKey) {
+		printError("Not initialized. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+
+	const resp = await fetch(`${baseUrl}${path}`, {
+		method: "POST",
+		headers: {
+			Authorization: `Token ${config.platform.apiKey}`,
+			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
+			"X-Mem0-Mode": "agent-rush",
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	const json = await resp.json().catch(() => ({}));
+
+	if (!resp.ok) {
+		const code =
+			(json as { error?: { code?: string } }).error?.code ?? "unknown";
+		printError(`AGENTRUSH error: ${code}`);
+		if (ERROR_HINTS[code]) {
+			console.log(`  ${colors.dim(ERROR_HINTS[code])}`);
+		}
+		process.exit(1);
+	}
+
+	return json;
+}
+
+function promptLine(question: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}
+
+/**
+ * Ensure the human has acknowledged that AGENTRUSH memories are PUBLIC.
+ *
+ * Interactive (TTY): show the prompt; on "y" persist `agentRush.acknowledgedAt`
+ * so we never ask the same machine twice. On anything else, abort.
+ *
+ * Non-interactive (agent invocation, no TTY): print the warning to stderr
+ * for the human reading the agent's transcript and proceed — agents can't
+ * answer y/N prompts.
+ */
+async function ensureWarningAcknowledged(): Promise<void> {
+	const config = loadConfig();
+	if (config.agentRush?.acknowledgedAt) return;
+
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		// Agent context: surface the warning to stderr, don't block.
+		console.error(PII_WARNING);
+		return;
+	}
+
+	console.log(PII_WARNING);
+	const answer = (await promptLine("   Continue? [y/N]: ")).toLowerCase();
+	if (answer !== "y" && answer !== "yes") {
+		printError("Aborted.");
+		process.exit(1);
+	}
+
+	config.agentRush.acknowledgedAt = new Date().toISOString();
+	saveConfig(config);
+}
+
+export async function cmdAgentRushAdd(content: string): Promise<void> {
+	await ensureWarningAcknowledged();
+	const result = await callEndpoint("/v1/agent-rush/memories/", { content });
+	printSuccess(
+		`Memory submitted (event_id: ${(result as { event_id?: string }).event_id ?? "?"})`,
+	);
+}
+
+export async function cmdAgentRushSearch(query: string): Promise<void> {
+	const result = (await callEndpoint("/v1/agent-rush/memories/search/", {
+		query,
+	})) as {
+		results?: Array<{ memory?: string }>;
+		memories?: Array<{ memory?: string }>;
+	};
+
+	const memories = result.results ?? result.memories ?? [];
+
+	if (memories.length === 0) {
+		console.log(colors.dim("(no results)"));
+		return;
+	}
+
+	memories.slice(0, 5).forEach((m, i) => {
+		console.log(`  ${i + 1}. ${m.memory ?? JSON.stringify(m)}`);
+	});
+}

cli/node/src/commands/identify.ts

@@ -0,0 +1,75 @@
+/**
+ * mem0 identify — declare which agent owns the current agent-mode key.
+ *
+ * Used when `mem0 init --agent` ran without --agent-caller, so the backend
+ * saved agent_caller=NULL. The agent re-runs `mem0 identify <name>` to PATCH
+ * its own row with its real identity. Idempotent.
+ */
+
+import { printError, printSuccess } from "../branding.js";
+import { loadConfig, saveConfig } from "../config.js";
+
+const SOURCE_HEADERS = {
+	"X-Mem0-Source": "cli",
+	"X-Mem0-Client-Language": "node",
+} as const;
+
+export async function runIdentify(name: string): Promise<void> {
+	const config = loadConfig();
+	if (!config.platform.apiKey) {
+		printError("No API key configured. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+	if (!config.platform.agentMode) {
+		printError("This command only works on unclaimed agent-mode keys.");
+		process.exit(1);
+	}
+
+	const clean = (name ?? "").trim();
+	if (!clean) {
+		printError("Agent name is required.");
+		process.exit(1);
+	}
+
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+
+	let resp: Response;
+	try {
+		resp = await fetch(`${baseUrl}/api/v1/auth/agent_mode/caller/`, {
+			method: "PATCH",
+			headers: {
+				...SOURCE_HEADERS,
+				Authorization: `Token ${config.platform.apiKey}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ agent_caller: clean }),
+			signal: AbortSignal.timeout(30_000),
+		});
+	} catch (err) {
+		printError(
+			`Network error: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		process.exit(1);
+	}
+
+	if (!resp.ok) {
+		let detail: string = resp.statusText;
+		try {
+			const body = (await resp.json()) as { error?: string };
+			if (body.error) detail = body.error;
+		} catch {
+			/* leave as statusText */
+		}
+		printError(`Identify failed: ${detail}`);
+		process.exit(1);
+	}
+
+	const body = (await resp.json()) as { agent_caller?: string };
+	const canonical = body.agent_caller ?? clean;
+	config.platform.agentCaller = canonical;
+	saveConfig(config);
+	printSuccess(`Identified as ${canonical}.`);
+}

cli/node/src/commands/init.ts

@@ -21,6 +21,8 @@ import {
 	redactKey,
 	saveConfig,
 } from "../config.js";
+import { formatJsonEnvelope } from "../output.js";
+import { isAgentMode } from "../state.js";
 
 const { brand, dim } = colors;
 
@@ -33,6 +35,65 @@ function validateEmail(email: string): void {
 	}
 }
 
+/** @internal — exported for unit tests. */
+export async function pingKey(
+	apiKey: string,
+	baseUrl: string,
+	timeoutMs = 5000,
+): Promise<boolean> {
+	// Returns false ONLY on a definitive "invalid key" signal (HTTP 401/403).
+	// Network errors, timeouts, and 5xx responses return true so we prefer
+	// reusing an existing key over silently minting a new shadow on a transient
+	// blip (which would also clobber config + plugin-sync targets).
+	try {
+		const resp = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/ping/`, {
+			headers: { Authorization: `Token ${apiKey}` },
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		return resp.status !== 401 && resp.status !== 403;
+	} catch {
+		return true; // unknown — prefer reuse
+	}
+}
+
+async function maybeIdentify(
+	key: string,
+	baseUrl: string,
+	agentCaller: string | undefined,
+): Promise<void> {
+	// Best-effort PATCH agent_caller when --agent-caller is supplied on a
+	// reused key. Silent no-op on any failure — reuse must not break.
+	if (!agentCaller) return;
+	try {
+		const resp = await fetch(
+			`${baseUrl.replace(/\/+$/, "")}/api/v1/auth/agent_mode/caller/`,
+			{
+				method: "PATCH",
+				headers: {
+					Authorization: `Token ${key}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ agent_caller: agentCaller }),
+				signal: AbortSignal.timeout(10_000),
+			},
+		);
+		if (resp.ok) {
+			try {
+				const body = (await resp.json()) as { agent_caller?: string };
+				if (fs.existsSync(CONFIG_FILE)) {
+					const cfg = loadConfig();
+					cfg.platform.agentCaller = body.agent_caller ?? agentCaller;
+					saveConfig(cfg);
+				}
+			} catch {
+				/* swallow — best effort */
+			}
+		}
+	} catch {
+		/* swallow — best effort */
+	}
+}
+
 async function emailLogin(
 	email: string,
 	code: string | undefined,
@@ -196,6 +257,7 @@ async function setupPlatform(config: Mem0Config): Promise<void> {
 		process.exit(1);
 	}
 	config.platform.apiKey = apiKey;
+	config.platform.createdVia = "api_key";
 }
 
 async function setupDefaults(config: Mem0Config): Promise<void> {
@@ -249,14 +311,35 @@ export async function runInit(
 		email?: string;
 		code?: string;
 		force?: boolean;
+		agent?: boolean;
+		source?: string;
+		agentCaller?: string;
 	} = {},
 ): Promise<void> {
+	const { detectAgentCaller } = await import("../agent-detect.js");
+	const { bootstrapViaBackend, claimViaOtp } = await import("./agent-mode.js");
+	const { isAgentMode } = await import("../state.js");
+	const { captureEvent } = await import("../telemetry.js");
+
+	const fireInit = (
+		mode: "agent" | "email" | "api_key" | "existing_key",
+		claimed = false,
+	) => {
+		const props: Record<string, unknown> = { command: "init", mode };
+		// Self-declared via --agent-caller; not sniffed from env vars.
+		if (opts.agentCaller) props.agent_caller = opts.agentCaller;
+		if (opts.source) props.signup_source = opts.source;
+		if (claimed) props.claimed_agent_mode = true;
+		captureEvent("cli.init", props);
+	};
+
 	const config = createDefaultConfig();
 	const savedConfig = loadConfig();
 	const baseUrl =
 		process.env.MEM0_BASE_URL ||
 		savedConfig.platform.baseUrl ||
 		DEFAULT_BASE_URL;
+	config.platform.baseUrl = baseUrl;
 
 	// Guards
 	if (opts.code && !opts.email) {
@@ -268,6 +351,84 @@ export async function runInit(
 		process.exit(1);
 	}
 
+	// ── Claim flow: --email against an existing agent-mode config ───────────
+	if (
+		opts.email &&
+		fs.existsSync(CONFIG_FILE) &&
+		savedConfig.platform.agentMode &&
+		savedConfig.platform.apiKey
+	) {
+		const email = opts.email.trim().toLowerCase();
+		validateEmail(email);
+		printInfo(`Claiming Agent Mode account to ${email}...`);
+		await claimViaOtp(savedConfig, { email, code: opts.code });
+		fireInit("email", true);
+		return;
+	}
+
+	// ── Agent Mode path runs BEFORE the existing-config guard ──────────────
+	// Rule 1/2 will REUSE a valid existing key (not overwrite), so we must
+	// short-circuit before the guard prompts the user about overwriting.
+	// Rule 3 only mints when there's no valid key to reuse — in that case
+	// overwriting is what the user wants.
+	const agentCtx =
+		opts.agent === true || isAgentMode() || detectAgentCaller() !== null;
+	if (!opts.apiKey && !opts.email && agentCtx) {
+		const emitReuseEnvelope = (source: "env" | "config") => {
+			if (isAgentMode()) {
+				formatJsonEnvelope({
+					command: "init",
+					data: {
+						api_key_saved: false,
+						api_key_source: source,
+						agent_mode: false,
+						message:
+							"Existing Mem0 API key found and reused. No Agent Mode key was created.",
+					},
+				});
+			} else {
+				printSuccess(
+					source === "env"
+						? "Existing MEM0_API_KEY is valid; reusing it. No new Agent Mode key was minted."
+						: "Existing API key in config is valid; reusing it. No new Agent Mode key was minted.",
+				);
+			}
+		};
+		// Rule 1: env MEM0_API_KEY valid → reuse, no new key.
+		const envKey = (process.env.MEM0_API_KEY || "").trim();
+		if (envKey && (await pingKey(envKey, baseUrl))) {
+			await maybeIdentify(envKey, baseUrl, opts.agentCaller);
+			emitReuseEnvelope("env");
+			fireInit("existing_key");
+			return;
+		}
+		// Rule 2: existing config api_key valid → reuse.
+		if (
+			savedConfig.platform.apiKey &&
+			(await pingKey(savedConfig.platform.apiKey, baseUrl))
+		) {
+			await maybeIdentify(
+				savedConfig.platform.apiKey,
+				baseUrl,
+				opts.agentCaller,
+			);
+			emitReuseEnvelope("config");
+			fireInit("existing_key");
+			return;
+		}
+		// Rule 3: mint a fresh shadow (no valid key to reuse).
+		// agent_caller is self-declared via --agent-caller (Proof Editor-style),
+		// not derived from env-var sniffing. detectAgentCaller() above is still
+		// used as a context trigger (does this look like an agent?) but never
+		// to fill identity.
+		await bootstrapViaBackend(config, {
+			source: opts.source ?? null,
+			agentCaller: opts.agentCaller ?? null,
+		});
+		fireInit("agent");
+		return;
+	}
+
 	// Warn if an existing config with an API key would be overwritten
 	if (
 		!opts.force &&
@@ -324,6 +485,7 @@ export async function runInit(
 		config.platform.apiKey = apiKeyVal;
 		config.platform.baseUrl = baseUrl;
 		config.platform.userEmail = email;
+		config.platform.createdVia = "email";
 		config.defaults.userId =
 			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
 
@@ -339,13 +501,15 @@ export async function runInit(
 	}
 
 	// ── API key flow ──────────────────────────────────────────────────────────
+	// (Agent Mode branch runs earlier — see above, before the existing-config
+	// guard, so Rules 1/2 can REUSE a valid key without prompting overwrite.)
 
 	// 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>]",
+				"Usage: mem0 init --api-key <key>, --email <addr>, or --agent for unattended Agent Mode bootstrap.",
 			);
 			process.exit(1);
 		}
@@ -356,6 +520,7 @@ export async function runInit(
 	// Non-interactive: both flags provided
 	if (opts.apiKey && opts.userId) {
 		config.platform.apiKey = opts.apiKey;
+		config.platform.createdVia = "api_key";
 		config.defaults.userId = opts.userId;
 		await validatePlatform(config);
 		saveConfig(config);
@@ -403,6 +568,7 @@ export async function runInit(
 			config.platform.apiKey = apiKeyVal;
 			config.platform.baseUrl = baseUrl;
 			config.platform.userEmail = email;
+			config.platform.createdVia = "email";
 			config.defaults.userId =
 				opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
 

cli/node/src/commands/memory.ts

@@ -46,7 +46,7 @@ export async function cmdAdd(
 		file?: string;
 		metadata?: string;
 		immutable: boolean;
-		noInfer: boolean;
+		infer?: boolean;
 		expires?: string;
 		categories?: string;
 		output: string;
@@ -136,7 +136,7 @@ export async function cmdAdd(
 				runId: opts.runId,
 				metadata: meta,
 				immutable: opts.immutable,
-				infer: !opts.noInfer,
+				infer: opts.infer !== false,
 				expires: opts.expires,
 				categories: cats,
 			});

cli/node/src/commands/whoami.ts

@@ -0,0 +1,18 @@
+/**
+ * `mem0 whoami` — print the active agent's default_user_id (AGENTRUSH identifier).
+ * Reads from local config; no network call.
+ */
+
+import { colors, printError, printInfo } from "../branding.js";
+import { loadConfig } from "../config.js";
+
+export async function cmdWhoami(): Promise<void> {
+	const config = loadConfig();
+	const sessionId = config.platform?.defaultUserId;
+	if (!sessionId) {
+		printError("No default_user_id found. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+	console.log(`Your AGENTRUSH identifier:  ${colors.brand(sessionId)}`);
+	printInfo("Find your row at https://mem0.ai/agentrush");
+}

cli/node/src/config.ts

@@ -21,6 +21,12 @@ export interface PlatformConfig {
 	apiKey: string;
 	baseUrl: string;
 	userEmail: string;
+	// Agent Mode (unclaimed-shadow signup)
+	agentMode: boolean; // true while the key is an unclaimed agent-mode key
+	createdVia: string; // "agent_mode" | "email" | "api_key" | "existing_key"
+	agentCaller: string; // canonical agent name when createdVia === "agent_mode" (e.g. "claude-code")
+	claimedAt: string; // ISO timestamp once the agent has been claimed
+	defaultUserId: string; // `user_<slug>` returned by bootstrap; auto-default scope
 }
 
 export interface DefaultsConfig {
@@ -34,11 +40,18 @@ export interface TelemetryConfig {
 	anonymousId: string;
 }
 
+export interface AgentRushConfig {
+	// ISO timestamp the human acknowledged the "memories are public" warning.
+	// Empty until first interactive `mem0 agent-rush add`.
+	acknowledgedAt: string;
+}
+
 export interface Mem0Config {
 	version: number;
 	defaults: DefaultsConfig;
 	platform: PlatformConfig;
 	telemetry: TelemetryConfig;
+	agentRush: AgentRushConfig;
 }
 
 export function createDefaultConfig(): Mem0Config {
@@ -54,10 +67,18 @@ export function createDefaultConfig(): Mem0Config {
 			apiKey: "",
 			baseUrl: DEFAULT_BASE_URL,
 			userEmail: "",
+			agentMode: false,
+			createdVia: "",
+			agentCaller: "",
+			claimedAt: "",
+			defaultUserId: "",
 		},
 		telemetry: {
 			anonymousId: "",
 		},
+		agentRush: {
+			acknowledgedAt: "",
+		},
 	};
 }
 
@@ -79,6 +100,11 @@ export function loadConfig(): Mem0Config {
 		config.platform.apiKey = plat.api_key ?? "";
 		config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
 		config.platform.userEmail = plat.user_email ?? "";
+		config.platform.agentMode = Boolean(plat.agent_mode ?? false);
+		config.platform.createdVia = plat.created_via ?? "";
+		config.platform.agentCaller = plat.agent_caller ?? "";
+		config.platform.claimedAt = plat.claimed_at ?? "";
+		config.platform.defaultUserId = plat.default_user_id ?? "";
 
 		const defaults = data.defaults ?? {};
 		config.defaults.userId = defaults.user_id ?? "";
@@ -87,6 +113,8 @@ export function loadConfig(): Mem0Config {
 		config.defaults.runId = defaults.run_id ?? "";
 		const telemetry = data.telemetry ?? {};
 		config.telemetry.anonymousId = telemetry.anonymous_id ?? "";
+		const agentRush = data.agent_rush ?? {};
+		config.agentRush.acknowledgedAt = agentRush.acknowledged_at ?? "";
 	}
 
 	// Environment variable overrides
@@ -118,14 +146,36 @@ export function saveConfig(config: Mem0Config): void {
 			api_key: config.platform.apiKey,
 			base_url: config.platform.baseUrl,
 			user_email: config.platform.userEmail,
+			agent_mode: config.platform.agentMode,
+			created_via: config.platform.createdVia,
+			agent_caller: config.platform.agentCaller,
+			claimed_at: config.platform.claimedAt,
+			default_user_id: config.platform.defaultUserId,
 		},
 		telemetry: {
 			anonymous_id: config.telemetry.anonymousId,
 		},
+		agent_rush: {
+			acknowledged_at: config.agentRush.acknowledgedAt,
+		},
 	};
 
 	fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
 	fs.chmodSync(CONFIG_FILE, 0o600);
+
+	// Propagate api_key to ecosystem touchpoints (Claude plugin env injection,
+	// shell rc exports). Idempotent — updates only EXISTING entries; never
+	// creates new ones. Best-effort: errors swallowed so config.json is
+	// always authoritative, never blocked by plugin-state issues.
+	if (config.platform.apiKey) {
+		try {
+			// eslint-disable-next-line @typescript-eslint/no-require-imports
+			const { syncApiKey } = require("./plugin-sync.js");
+			syncApiKey(config.platform.apiKey);
+		} catch {
+			/* swallow */
+		}
+	}
 }
 
 export function redactKey(key: string): string {

cli/node/src/index.ts

@@ -13,7 +13,12 @@ import { colors, printError, printWarning } from "./branding.js";
 import type { Mem0Config } from "./config.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { richFormatHelp } from "./help.js";
-import { setAgentMode } from "./state.js";
+import {
+	isAgentMode,
+	setAgentMode,
+	setCurrentCommand,
+	takeNotice,
+} from "./state.js";
 import { captureEvent } from "./telemetry.js";
 import { CLI_VERSION } from "./version.js";
 
@@ -141,6 +146,11 @@ program
 	.description(
 		`◆ Mem0 CLI v${CLI_VERSION} · Node.js SDK\n\nThe Memory Layer for AI Agents`,
 	)
+	// Positional options: flags AFTER a subcommand name belong to that
+	// subcommand, not the global program. Without this, `mem0 init --agent`
+	// routes `--agent` to the program-level alias (for --json) and init's own
+	// `--agent` (Agent Mode bootstrap) silently never fires.
+	.enablePositionalOptions()
 	.option("--version", "Show version and exit.")
 	.on("option:version", () => {
 		console.log(`  ${colors.brand("◆ Mem0")} CLI v${CLI_VERSION}`);
@@ -149,7 +159,7 @@ program
 	.option("--json", "Output as JSON for agent/programmatic use.")
 	.option(
 		"--agent",
-		"Output as JSON for agent/programmatic use. (alias: --json)",
+		"Output as JSON for agent/programmatic use. (alias: --json) Place BEFORE the subcommand: `mem0 --agent <cmd>`. On `init`, `mem0 init --agent` is the Agent Mode bootstrap flag instead.",
 	)
 	.usage("<command> [options]")
 	.helpOption("--help", "Show this message and exit.")
@@ -166,6 +176,14 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
 			parentName && parentName !== "mem0"
 				? `${parentName}.${commandName}`
 				: commandName;
+		// Stash the active command name in shared state so the JSON
+		// error envelope (printError) can report which command failed
+		// instead of an empty `"command": ""` field.
+		setCurrentCommand(fullCommand);
+		// init fires its own telemetry from runInit with full M1-M6 props
+		// (mode/agent_caller/signup_source/claimed_agent_mode); skip the
+		// auto-fire here so we don't double-count.
+		if (fullCommand === "init") return;
 		const isAgent = !!(program.opts().json || program.opts().agent);
 		captureEvent(
 			`cli.${fullCommand}`,
@@ -193,11 +211,32 @@ program
 		"Verification code (use with --email for non-interactive login).",
 	)
 	.option("--force", "Overwrite existing config without confirmation.", false)
+	.option(
+		"--agent",
+		"Bootstrap an unattended Agent Mode account (no email required).",
+		false,
+	)
+	.option(
+		"--source <channel>",
+		"Channel attribution for signup (e.g. github, hn, ph).",
+	)
+	.option(
+		"--agent-caller <name>",
+		"Self-declared agent identity (e.g. claude-code, cursor). Used with --agent to attribute Agent Mode signups.",
+	)
+	// Accept `--json` at the init level too so the PRD-documented form
+	// `mem0 init --agent --json` works without requiring users to move it
+	// before the subcommand. Effect is identical to the global `--json`:
+	// flip agent-mode output state.
+	.option("--json", "Output as JSON (alias for global `--json`).", false)
 	.addHelpText(
 		"after",
-		"\nExamples:\n  $ mem0 init\n  $ mem0 init --api-key m0-xxx --user-id alice\n  $ mem0 init --email you@example.com\n  $ mem0 init --email you@example.com --code 123456",
+		"\nExamples:\n  $ mem0 init\n  $ mem0 init --api-key m0-xxx --user-id alice\n  $ mem0 init --email you@example.com\n  $ mem0 init --email you@example.com --code 123456\n  $ mem0 init --agent             # Bootstrap an Agent Mode account (unattended)\n  $ mem0 init --email you@example.com  # Claims an existing Agent Mode key when one is present",
 	)
 	.action(async (opts) => {
+		// `--json` at init level mirrors the global flag — flip agent_mode
+		// state so downstream formatters use JSON envelopes.
+		if (opts.json) setAgentMode(true);
 		const { runInit } = await import("./commands/init.js");
 		await runInit({
 			apiKey: opts.apiKey,
@@ -205,9 +244,66 @@ program
 			email: opts.email,
 			code: opts.code,
 			force: opts.force,
+			agent: opts.agent,
+			source: opts.source,
+			agentCaller: opts.agentCaller,
 		});
 	});
 
+// ── Setup: identify (post-bootstrap agent self-tag) ──────────────────────
+
+program
+	.command("identify <name>")
+	.description(
+		"Tag your active Agent Mode key with the AI agent that's using it (e.g. claude-code, cursor).",
+	)
+	.action(async (name: string) => {
+		const { runIdentify } = await import("./commands/identify.js");
+		await runIdentify(name);
+	});
+
+// ── Setup: whoami (print active agent identifier) ────────────────────────
+
+program
+	.command("whoami")
+	.description("Print the active agent's AGENTRUSH identifier.")
+	.action(async () => {
+		const { cmdWhoami } = await import("./commands/whoami.js");
+		await cmdWhoami();
+	});
+
+// ── AGENTRUSH subcommand group ────────────────────────────────────────────
+
+const agentRush = program
+	.command("agent-rush")
+	.description("AGENTRUSH game commands.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+agentRush
+	.command("add <content...>")
+	.description("Submit a memory to AGENTRUSH.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 agent-rush add "I used mem0 to build a coding agent"\n  $ mem0 agent-rush add "Agents that remember are better agents"',
+	)
+	.action(async (parts: string[]) => {
+		const { cmdAgentRushAdd } = await import("./commands/agent-rush.js");
+		await cmdAgentRushAdd(parts.join(" "));
+	});
+
+agentRush
+	.command("search <query...>")
+	.description("Search AGENTRUSH memories.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 agent-rush search "agents and memory and tools"\n  $ mem0 agent-rush search "coding assistant"',
+	)
+	.action(async (parts: string[]) => {
+		const { cmdAgentRushSearch } = await import("./commands/agent-rush.js");
+		await cmdAgentRushSearch(parts.join(" "));
+	});
+
 // ── Memory: add ───────────────────────────────────────────────────────────
 
 program
@@ -769,4 +865,16 @@ program
 
 // ── Entrypoint ────────────────────────────────────────────────────────────
 
-program.parse();
+// Surface any unclaimed Agent Mode notice once per command, after the primary
+// output. In JSON/agent mode the notice is folded into the envelope by
+// formatJsonEnvelope, so skip the stderr banner there to avoid duplication.
+function surfaceNotice(): void {
+	const notice = takeNotice();
+	if (notice && !isAgentMode()) {
+		process.stderr.write(`\n\x1b[33m🔔 ${notice}\x1b[0m\n\n`);
+	}
+}
+
+program.parseAsync().finally(() => {
+	surfaceNotice();
+});

cli/node/src/output.ts

@@ -5,6 +5,7 @@
 import boxen from "boxen";
 import Table from "cli-table3";
 import { colors, sym } from "./branding.js";
+import { takeNotice } from "./state.js";
 
 const { brand, accent, success, error: errorColor, dim } = colors;
 
@@ -244,6 +245,15 @@ export function formatJsonEnvelope(opts: {
 	if (opts.count !== undefined) envelope.count = opts.count;
 	if (opts.error) envelope.error = opts.error;
 	envelope.data = opts.data;
+
+	// If the platform flagged this as an unclaimed Agent Mode account, surface
+	// the notice inside the JSON envelope so an agent consuming the output
+	// sees it without needing to inspect HTTP headers.
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const { takeNotice } = require("./state.js");
+	const notice = takeNotice();
+	if (notice) envelope.mem0_notice = notice;
+
 	console.log(JSON.stringify(envelope, null, 2));
 }
 
@@ -356,6 +366,12 @@ export function formatAgentEnvelope(opts: {
 	}
 	if (opts.count !== undefined) envelope.count = opts.count;
 	envelope.data = sanitizeAgentData(opts.command, opts.data);
+
+	// Surface the unclaimed-Agent-Mode notice (if any) in the envelope so an
+	// agent reading the JSON output sees it without inspecting HTTP headers.
+	const notice = takeNotice();
+	if (notice) envelope.mem0_notice = notice;
+
 	console.log(JSON.stringify(envelope, null, 2));
 }
 

cli/node/src/plugin-sync.ts

@@ -0,0 +1,120 @@
+/**
+ * Sync the active Mem0 API key into other ecosystem touchpoints.
+ *
+ * Why: the CLI canonical state is ~/.mem0/config.json. MCP servers
+ * (Claude Code plugin, Codex plugin) read MEM0_API_KEY from env or
+ * their own config files. Without a sync, agent-mode bootstrap mints a
+ * new key into config.json but the plugin's MCP keeps using the old
+ * key from env — silent surprise.
+ *
+ * Design:
+ *  - Update ONLY entries that already exist; never create new ones
+ *  - Preserve surrounding content, formatting, other keys
+ *  - Atomic writes (tmp + rename) so a crash mid-write doesn't corrupt
+ *  - Idempotent — re-running with the same key is a no-op
+ *
+ * Targets:
+ *  - ~/.claude/settings.json::env::MEM0_API_KEY (Claude Code env injection)
+ *  - ~/.zshrc / ~/.bashrc `export MEM0_API_KEY="..."` lines
+ *
+ * Out of scope: Codex / Cursor MCP configs and the plugin's own
+ * <plugin-dir>/.api_key file (plugin-managed, different schema).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CLAUDE_SETTINGS = path.join(os.homedir(), ".claude", "settings.json");
+const SHELL_RCS = [
+	path.join(os.homedir(), ".zshrc"),
+	path.join(os.homedir(), ".bashrc"),
+	path.join(os.homedir(), ".bash_profile"),
+];
+
+// Use [ \t]* (not \s*) so a trailing newline at end-of-file is preserved
+// when the MEM0_API_KEY export is the last line of the rc file.
+const RC_LINE_RE =
+	/^([ \t]*export[ \t]+MEM0_API_KEY[ \t]*=[ \t]*)(["']?)([^"'\n]*)(["']?)[ \t]*$/m;
+
+export function syncApiKey(apiKey: string): string[] {
+	if (!apiKey) return [];
+	const updated: string[] = [];
+	if (updateClaudeSettings(CLAUDE_SETTINGS, apiKey)) {
+		updated.push(CLAUDE_SETTINGS);
+	}
+	for (const rc of SHELL_RCS) {
+		if (updateShellRc(rc, apiKey)) updated.push(rc);
+	}
+	return updated;
+}
+
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateClaudeSettings(
+	filePath: string,
+	apiKey: string,
+): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	let raw: string;
+	let data: Record<string, unknown>;
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+		data = JSON.parse(raw);
+	} catch {
+		return false;
+	}
+	const env = data.env;
+	if (!env || typeof env !== "object" || !("MEM0_API_KEY" in env)) {
+		return false; // no existing entry — don't create one
+	}
+	const envObj = env as Record<string, string>;
+	if (envObj.MEM0_API_KEY === apiKey) return false; // already in sync
+	envObj.MEM0_API_KEY = apiKey;
+	atomicWriteText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+	return true;
+}
+
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateShellRc(filePath: string, apiKey: string): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	let text: string;
+	try {
+		text = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return false;
+	}
+	const match = text.match(RC_LINE_RE);
+	if (!match) return false; // no existing line
+	if (match[3] === apiKey) return false;
+	const newText = text.replace(
+		RC_LINE_RE,
+		(_full, prefix) => `${prefix}"${apiKey}"`,
+	);
+	atomicWriteText(filePath, newText);
+	return true;
+}
+
+function atomicWriteText(filePath: string, content: string): void {
+	const dir = path.dirname(filePath);
+	const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
+	try {
+		fs.writeFileSync(tmp, content, "utf-8");
+		// Preserve permissions if original existed.
+		if (fs.existsSync(filePath)) {
+			try {
+				const mode = fs.statSync(filePath).mode & 0o777;
+				fs.chmodSync(tmp, mode);
+			} catch {
+				/* best-effort */
+			}
+		}
+		fs.renameSync(tmp, filePath);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {
+			/* ignore */
+		}
+		throw err;
+	}
+}

cli/node/src/state.ts

@@ -5,6 +5,7 @@
 
 let _agentMode = false;
 let _currentCommand = "";
+let _pendingNotice = "";
 
 export function isAgentMode(): boolean {
 	return _agentMode;
@@ -21,3 +22,19 @@ export function getCurrentCommand(): string {
 export function setCurrentCommand(name: string): void {
 	_currentCommand = name;
 }
+
+/**
+ * Stash a Mem0 backend notice (Agent Mode unclaimed reminder) for end-of-
+ * command surfacing. Called from the platform backend after each response so
+ * the notice prints once per command regardless of how many sub-requests
+ * fired. Last-write-wins is fine — the message text is identical.
+ */
+export function captureNotice(notice: string | null | undefined): void {
+	if (notice) _pendingNotice = notice;
+}
+
+export function takeNotice(): string {
+	const msg = _pendingNotice;
+	_pendingNotice = "";
+	return msg;
+}

cli/node/src/telemetry.ts

@@ -115,6 +115,9 @@ export function captureEvent(
 			}
 		}
 
+		// M4: every cli.* event carries agent_mode based on the config flag
+		// (unclaimed Agent Mode key). This is the growth-doc property used to
+		// join init → add → search funnels in PostHog.
 		const payload = {
 			api_key: POSTHOG_API_KEY,
 			distinct_id: distinctId,
@@ -123,6 +126,7 @@ export function captureEvent(
 				source: "CLI",
 				language: "node",
 				cli_version: CLI_VERSION,
+				agent_mode: Boolean(config.platform.agentMode),
 				node_version: process.version,
 				os: process.platform,
 				...properties,
@@ -141,11 +145,11 @@ export function captureEvent(
 			anonDistinctIdToAlias: anonIdToAlias,
 		};
 
-		const child = spawn(
-			process.execPath,
-			[SENDER_SCRIPT, JSON.stringify(context)],
-			{ detached: true, stdio: "ignore" },
-		);
+		const child = spawn(process.execPath, [SENDER_SCRIPT], {
+			detached: true,
+			stdio: ["pipe", "ignore", "ignore"],
+		});
+		child.stdin?.end(JSON.stringify(context));
 		child.unref();
 	} catch {
 		/* silently swallow */

cli/node/telemetry-sender.cjs

@@ -1,7 +1,8 @@
 /**
  * Standalone telemetry sender — runs as a detached child process.
  *
- * Usage: node telemetry-sender.cjs '<json context>'
+ * Usage: node telemetry-sender.cjs   (JSON context is read from stdin; a single
+ * argv argument is still accepted as a legacy fallback)
  *
  * This script is spawned by telemetry.captureEvent() and runs independently
  * of the parent CLI process. It:
@@ -19,6 +20,31 @@
 const https = require("https");
 const fs = require("fs");
 
+function loadContext() {
+	return new Promise((resolve, reject) => {
+		if (process.argv[2]) {
+			try {
+				resolve(JSON.parse(process.argv[2]));
+			} catch (err) {
+				reject(err);
+			}
+			return;
+		}
+
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => (data += chunk));
+		process.stdin.on("end", () => {
+			try {
+				resolve(JSON.parse(data));
+			} catch (err) {
+				reject(err);
+			}
+		});
+		process.stdin.on("error", reject);
+	});
+}
+
 function httpsRequest(url, method, headers, body) {
 	return new Promise((resolve, reject) => {
 		const u = new URL(url);
@@ -108,7 +134,7 @@ async function sendIdentifyEvent(ctx, payload, anonId) {
 }
 
 async function main() {
-	const ctx = JSON.parse(process.argv[2]);
+	const ctx = await loadContext();
 	const payload = ctx.payload;
 
 	if (ctx.needsEmail && ctx.mem0ApiKey) {

cli/node/tests/agent-mode.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Parity tests for `mem0 init --agent` (Agent Mode bootstrap).
+ *
+ * Mirror of `cli/python/tests/test_agent_mode.py` — both files MUST stay
+ * in sync so that the Python and Node CLIs expose an identical surface
+ * for the Agent Mode entrypoint. If you add a flag here, add the same
+ * assertion on the Python side (and vice versa).
+ *
+ * Network-bound bootstrap is covered by the platform-side E2E suite
+ * (`backend/tests/e2e/test_05_agent_mode.py`); these tests only verify
+ * the CLI surface that ships in the binary.
+ */
+
+import { describe, it, expect } from "vitest";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function run(
+  args: string[],
+  opts: { home?: string; env?: Record<string, string> } = {},
+): { stdout: string; stderr: string; exitCode: number } {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("MEM0_")) delete env[key];
+  }
+  if (opts.home) env.HOME = opts.home;
+  if (opts.env) Object.assign(env, opts.env);
+
+  try {
+    const stdout = execSync(`npx tsx src/index.ts ${args.join(" ")}`, {
+      cwd: path.join(__dirname, ".."),
+      env,
+      encoding: "utf-8",
+      timeout: 15000,
+    });
+    return { stdout, stderr: "", exitCode: 0 };
+  } catch (e: any) {
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? "",
+      exitCode: e.status ?? 1,
+    };
+  }
+}
+
+function cleanHome(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+}
+
+describe("init flag surface", () => {
+  it("init --help lists --agent", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--agent");
+  });
+
+  it("init --help describes Agent Mode", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    // Description must mention what --agent actually does so an agent
+    // reading the help can self-discover the bootstrap entrypoint.
+    expect(
+      result.stdout.includes("Agent Mode") ||
+        result.stdout.toLowerCase().includes("unattended"),
+    ).toBe(true);
+  });
+
+  it("init --help lists --source", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--source");
+  });
+
+  it("init --help lists --email and --code", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--email");
+    expect(result.stdout).toContain("--code");
+  });
+});
+
+describe("argv preprocessing — --agent reaches init subcommand", () => {
+  // Regression for the bug where the global --agent JSON-alias swallowed
+  // the init-level --agent flag, making `mem0 init --agent` behave like
+  // the plain interactive wizard.
+
+  it("init --agent triggers bootstrap branch (not the wizard)", () => {
+    const home = cleanHome();
+    const result = run(["init", "--agent"], {
+      home,
+      env: {
+        MEM0_BASE_URL: "http://127.0.0.1:1", // blackhole
+        FORCE_COLOR: "0",
+      },
+    });
+    const combined = (result.stdout + result.stderr).toLowerCase();
+    // Either bootstrap-attempt error, or a connection/network error —
+    // both prove the --agent path executed (the wizard would prompt for
+    // input and succeed/hang, not surface a network error).
+    expect(
+      combined.includes("agent") ||
+        combined.includes("connect") ||
+        combined.includes("network") ||
+        combined.includes("fetch") ||
+        combined.includes("bootstrap"),
+    ).toBe(true);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+});
+
+describe("JSON envelope on network failure", () => {
+  it("init --agent --json does not leak a stack trace when backend is unreachable", () => {
+    const home = cleanHome();
+    const result = run(["init", "--agent", "--json"], {
+      home,
+      env: {
+        MEM0_BASE_URL: "http://127.0.0.1:1",
+        FORCE_COLOR: "0",
+      },
+    });
+    const combined = result.stdout + result.stderr;
+    // No raw Node stack should escape the agent-mode handler.
+    expect(combined).not.toMatch(/at \w+\s*\(.+\.ts:\d+/);
+    expect(combined).not.toContain("UnhandledPromiseRejection");
+    expect(result.exitCode).not.toBe(0);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+});
+
+describe("top-level help lists init", () => {
+  // `mem0 --help` must list `init` so agents walking the top-level help
+  // can discover the Agent Mode entrypoint without prior knowledge.
+
+  it("--help lists init", () => {
+    const result = run(["--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("init");
+  });
+});

cli/node/tests/commands.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Command } from "commander";
 import { createMockBackend } from "./setup.js";
 import type { Backend } from "../src/backend/base.js";
 import { setAgentMode } from "../src/state.js";
@@ -41,8 +42,6 @@ describe("cmdAdd", () => {
     await cmdAdd(mockBackend, "I prefer dark mode", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "text",
     });
     expect(mockBackend.add).toHaveBeenCalledOnce();
@@ -54,8 +53,6 @@ describe("cmdAdd", () => {
       userId: "alice",
       messages: JSON.stringify([{ role: "user", content: "I love Python" }]),
       immutable: false,
-      noInfer: false,
-
       output: "text",
     });
     expect(mockBackend.add).toHaveBeenCalledOnce();
@@ -66,8 +63,6 @@ describe("cmdAdd", () => {
     await cmdAdd(mockBackend, "test", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "json",
     });
     expect(output).toContain("results");
@@ -78,14 +73,59 @@ describe("cmdAdd", () => {
     await cmdAdd(mockBackend, "test", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "quiet",
     });
     expect(output).not.toContain("dark mode");
   });
 });
 
+describe("cmdAdd forwards --no-infer (regression for #5261)", () => {
+  it("forwards infer: false when --no-infer is set", async () => {
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    // `infer: false` is the shape Commander produces for `--no-infer`.
+    await cmdAdd(mockBackend, "store me verbatim", {
+      userId: "alice",
+      immutable: false,
+      infer: false,
+      output: "text",
+    });
+    expect(mockBackend.add).toHaveBeenCalledWith(
+      "store me verbatim",
+      undefined,
+      expect.objectContaining({ infer: false }),
+    );
+  });
+
+  it("forwards infer: true by default (flag absent)", async () => {
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "infer me", {
+      userId: "alice",
+      immutable: false,
+      output: "text",
+    });
+    expect(mockBackend.add).toHaveBeenCalledWith(
+      "infer me",
+      undefined,
+      expect.objectContaining({ infer: true }),
+    );
+  });
+
+  it("Commander stores --no-infer as opts.infer, not opts.noInfer", () => {
+    // Pins the assumption the fix relies on: Commander's `--no-X` option
+    // populates the positive camelCase key (`infer`), never `noInfer`.
+    const withFlag = new Command();
+    withFlag.option("--no-infer", "Skip inference, store raw.").action(() => {});
+    withFlag.parse(["--no-infer"], { from: "user" });
+    expect(withFlag.opts().infer).toBe(false);
+    expect(withFlag.opts().noInfer).toBeUndefined();
+
+    const withoutFlag = new Command();
+    withoutFlag.option("--no-infer", "Skip inference, store raw.").action(() => {});
+    withoutFlag.parse([], { from: "user" });
+    expect(withoutFlag.opts().infer).toBe(true);
+  });
+});
+
 describe("cmdAdd deduplicates PENDING", () => {
   const DUPLICATE_PENDING = {
     results: [
@@ -100,8 +140,6 @@ describe("cmdAdd deduplicates PENDING", () => {
     await cmdAdd(mockBackend, "test", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "text",
     });
     expect(output.match(/Queued/g)?.length).toBe(1);
@@ -113,8 +151,6 @@ describe("cmdAdd deduplicates PENDING", () => {
     await cmdAdd(mockBackend, "test", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "json",
     });
     const data = JSON.parse(output);
@@ -129,8 +165,6 @@ describe("cmdAdd deduplicates PENDING", () => {
     await cmdAdd(mockBackend, "test", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "agent",
     });
     const data = JSON.parse(output);
@@ -315,8 +349,6 @@ describe("agent mode", () => {
     await cmdAdd(mockBackend, "test preference", {
       userId: "alice",
       immutable: false,
-      noInfer: false,
-
       output: "agent",
     });
     const parsed = JSON.parse(output.trim());

cli/node/tests/init-internals.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for init internals — decision tree primitives + plugin sync.
+ *
+ * Mirror of `cli/python/tests/test_init_internals.py`. Both files MUST stay
+ * in sync — if you add a behavioral assertion here, mirror it on the Python
+ * side and vice versa.
+ *
+ *  - `pingKey` must NOT treat network errors as "invalid key" (else a VPN
+ *    flap silently mints a new shadow over a working key).
+ *  - `plugin_sync` must only update entries that already exist, preserve
+ *    trailing newlines, and never mangle other lines.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { pingKey } from "../src/commands/init.js";
+import { updateClaudeSettings, updateShellRc } from "../src/plugin-sync.js";
+
+// ── pingKey ──────────────────────────────────────────────────────────────
+
+describe("pingKey — network vs auth distinction", () => {
+	const origFetch = globalThis.fetch;
+	afterEach(() => {
+		globalThis.fetch = origFetch;
+		vi.restoreAllMocks();
+	});
+
+	it("returns true for 200", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 200 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+
+	it("returns false for 401 (definitively invalid)", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 401 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(false);
+	});
+
+	it("returns false for 403 (definitively invalid)", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 403 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(false);
+	});
+
+	it("returns true for 5xx (transient upstream — prefer reuse)", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 503 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+
+	it("returns true on network error (prefer reuse over re-mint)", async () => {
+		globalThis.fetch = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+
+	it("returns true on timeout (prefer reuse)", async () => {
+		globalThis.fetch = vi.fn().mockRejectedValue(new Error("aborted"));
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+});
+
+// ── updateShellRc ────────────────────────────────────────────────────────
+
+describe("updateShellRc — exists-only contract", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+	});
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("updates existing export and preserves trailing newline", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		fs.writeFileSync(rc, 'export MEM0_API_KEY="old"\n');
+		expect(updateShellRc(rc, "newkey")).toBe(true);
+		expect(fs.readFileSync(rc, "utf-8")).toBe('export MEM0_API_KEY="newkey"\n');
+	});
+
+	it("does NOT create a new export when none exists", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		fs.writeFileSync(rc, "alias ll='ls -la'\n");
+		expect(updateShellRc(rc, "newkey")).toBe(false);
+		expect(fs.readFileSync(rc, "utf-8")).toBe("alias ll='ls -la'\n");
+	});
+
+	it("preserves surrounding content", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		const original =
+			"# my zshrc\n" +
+			"alias ll='ls -la'\n" +
+			"export MEM0_API_KEY='old'\n" +
+			"export OTHER=keepme\n";
+		fs.writeFileSync(rc, original);
+		updateShellRc(rc, "newkey");
+		const after = fs.readFileSync(rc, "utf-8");
+		expect(after).toContain("alias ll='ls -la'\n");
+		expect(after).toContain("export OTHER=keepme\n");
+		expect(after).toContain("# my zshrc\n");
+		expect(after).toContain('export MEM0_API_KEY="newkey"\n');
+	});
+
+	it("is idempotent when value already matches", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		fs.writeFileSync(rc, 'export MEM0_API_KEY="same"\n');
+		expect(updateShellRc(rc, "same")).toBe(false);
+	});
+
+	it("is a no-op for missing files", () => {
+		const rc = path.join(tmpDir, ".zshrc"); // does not exist
+		expect(updateShellRc(rc, "x")).toBe(false);
+	});
+});
+
+// ── updateClaudeSettings ─────────────────────────────────────────────────
+
+describe("updateClaudeSettings — never creates entries", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+	});
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("does not create env block when none exists", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(settings, JSON.stringify({ otherKey: 1 }));
+		expect(updateClaudeSettings(settings, "newkey")).toBe(false);
+		expect(JSON.parse(fs.readFileSync(settings, "utf-8"))).toEqual({
+			otherKey: 1,
+		});
+	});
+
+	it("does not create MEM0_API_KEY entry in existing env block", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(settings, JSON.stringify({ env: { OTHER_KEY: "x" } }));
+		expect(updateClaudeSettings(settings, "newkey")).toBe(false);
+	});
+
+	it("updates existing entry and preserves siblings", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(
+			settings,
+			JSON.stringify({ env: { MEM0_API_KEY: "old", OTHER: "y" } }, null, 2),
+		);
+		expect(updateClaudeSettings(settings, "fresh")).toBe(true);
+		const data = JSON.parse(fs.readFileSync(settings, "utf-8"));
+		expect(data.env.MEM0_API_KEY).toBe("fresh");
+		expect(data.env.OTHER).toBe("y");
+	});
+
+	it("is idempotent when value already matches", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(
+			settings,
+			JSON.stringify({ env: { MEM0_API_KEY: "same" } }),
+		);
+		expect(updateClaudeSettings(settings, "same")).toBe(false);
+	});
+
+	it("is a no-op for malformed JSON", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(settings, "{ this is not json");
+		expect(updateClaudeSettings(settings, "x")).toBe(false);
+	});
+});

cli/node/tests/platform-backend.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for the Platform backend (mem0 Platform API client).
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PlatformBackend } from "../src/backend/platform.js";
+import { createDefaultConfig } from "../src/config.js";
+
+function makeBackend(): PlatformBackend {
+  // apiKey/baseUrl only build request headers; every test spies on _request,
+  // so no real network calls are made.
+  return new PlatformBackend(createDefaultConfig().platform);
+}
+
+function mockFetch() {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    headers: { get: vi.fn().mockReturnValue(null) },
+    json: vi.fn().mockResolvedValue({ message: "ok" }),
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("deleteEntities", () => {
+  it("returns all results keyed by entity type for a multi-entity delete", async () => {
+    const backend = makeBackend();
+    const responses: Record<string, unknown> = {
+      "/v2/entities/user/alice/": { message: "user deleted" },
+      "/v2/entities/agent/bob/": { message: "agent deleted" },
+    };
+    const spy = vi
+      // biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+      .spyOn(backend as any, "_request")
+      .mockImplementation(async (_method: string, path: string) => responses[path]);
+
+    const result = await backend.deleteEntities({ userId: "alice", agentId: "bob" });
+
+    // Regression: previously only the last entity's response survived.
+    expect(result).toEqual({
+      user: { message: "user deleted" },
+      agent: { message: "agent deleted" },
+    });
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it("keys a single-entity delete by its type", async () => {
+    const backend = makeBackend();
+    // biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+    vi.spyOn(backend as any, "_request").mockResolvedValue({ message: "user deleted" });
+
+    const result = await backend.deleteEntities({ userId: "alice" });
+    expect(result).toEqual({ user: { message: "user deleted" } });
+  });
+
+  it("throws when no entity id is provided", async () => {
+    const backend = makeBackend();
+    await expect(backend.deleteEntities({})).rejects.toThrow(
+      "At least one entity ID is required",
+    );
+  });
+});
+
+describe("PlatformBackend path encoding", () => {
+  it("encodes memory IDs before interpolating them into paths", async () => {
+    const fetchMock = mockFetch();
+    const backend = makeBackend();
+
+    await backend.get("mem/a?b#c");
+    await backend.update("mem/a?b#c", "updated");
+    await backend.delete("mem/a?b#c");
+
+    const urls = fetchMock.mock.calls.map((call) => call[0]);
+    expect(urls).toEqual([
+      "https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
+      "https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/",
+      "https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
+    ]);
+  });
+
+  it("encodes entity and event IDs before interpolating them into paths", async () => {
+    const fetchMock = mockFetch();
+    const backend = makeBackend();
+
+    await backend.deleteEntities({ userId: "org/team?active#frag" });
+    await backend.getEvent("evt/a?b#c");
+
+    const urls = fetchMock.mock.calls.map((call) => call[0]);
+    expect(urls).toEqual([
+      "https://api.mem0.ai/v2/entities/user/org%2Fteam%3Factive%23frag/?source=CLI",
+      "https://api.mem0.ai/v1/event/evt%2Fa%3Fb%23c/",
+    ]);
+  });
+});

cli/node/tests/telemetry.test.ts

@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockLoadConfig = vi.fn();
+const mockSaveConfig = vi.fn();
+const mockSpawn = vi.fn();
+
+vi.mock("../src/config.js", () => ({
+  CONFIG_FILE: "/tmp/mem0-config.json",
+  loadConfig: mockLoadConfig,
+  saveConfig: mockSaveConfig,
+}));
+
+vi.mock("node:child_process", () => ({
+  spawn: mockSpawn,
+}));
+
+describe("captureEvent", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    mockLoadConfig.mockReset();
+    mockSaveConfig.mockReset();
+    mockSpawn.mockReset();
+    delete process.env.MEM0_TELEMETRY;
+  });
+
+  it("pipes the telemetry context through stdin instead of argv", async () => {
+    mockLoadConfig.mockReturnValue({
+      platform: {
+        apiKey: "m0-node-secret",
+        baseUrl: "https://api.mem0.ai",
+        userEmail: "",
+      },
+      telemetry: {
+        anonymousId: "cli-anon-node",
+      },
+    });
+
+    const stdin = { end: vi.fn() };
+    const child = { stdin, unref: vi.fn() };
+    mockSpawn.mockReturnValue(child);
+
+    const { captureEvent } = await import("../src/telemetry.js");
+    captureEvent("node_test_event", { case: "stdin-secret" });
+
+    expect(mockSpawn).toHaveBeenCalledTimes(1);
+    const [execPath, args, options] = mockSpawn.mock.calls[0];
+    expect(execPath).toBe(process.execPath);
+    expect(args).toHaveLength(1);
+    expect(String(args[0])).toContain("telemetry-sender.cjs");
+    expect(JSON.stringify(args)).not.toContain("m0-node-secret");
+    expect(options).toMatchObject({ detached: true, stdio: ["pipe", "ignore", "ignore"] });
+
+    expect(stdin.end).toHaveBeenCalledTimes(1);
+    const payload = JSON.parse(stdin.end.mock.calls[0][0]);
+    expect(payload.mem0ApiKey).toBe("m0-node-secret");
+    expect(payload.payload.event).toBe("node_test_event");
+    expect(child.unref).toHaveBeenCalledTimes(1);
+  });
+});

cli/node/vitest.config.ts

@@ -8,4 +8,10 @@ export default defineConfig({
 	define: {
 		__CLI_VERSION__: JSON.stringify(pkg.version),
 	},
+	test: {
+		// Integration tests spawn the CLI via `npx tsx` (15s subprocess
+		// timeout); the first spawn in a file pays a cold-start cost that can
+		// exceed vitest's 5s default on CI runners.
+		testTimeout: 30_000,
+	},
 });

cli/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mem0-cli"
-version = "0.2.4"
+version = "0.2.10"
 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.2.4"
+__version__ = "0.2.10"

cli/python/src/mem0_cli/agent_detect.py

@@ -0,0 +1,36 @@
+"""Detect whether the CLI is being invoked from inside an AI-agent context.
+
+Used by `mem0 init` to auto-enter Agent Mode (Rule 3 bootstrap) when an
+agent runtime env var is present. The return value is a context **trigger
+only** — the canonical agent identity is self-declared by the agent via
+``--agent-caller <name>`` (Proof Editor-style) and never sniffed from env
+vars to fill the ``agent_caller`` field on the APIKey row.
+
+Returns a short name or None. The list is curated, not exhaustive — env
+vars we don't recognise fall through to None (caller treated as
+non-agent). Honest reporting depends on ``--agent-caller``; this list is
+just enough to enable the zero-friction auto-bootstrap UX.
+"""
+
+from __future__ import annotations
+
+import os
+
+_AGENT_CALLER_ENV: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("claude-code", ("CLAUDECODE", "CLAUDE_CODE")),
+    ("cursor", ("CURSOR_AGENT", "CURSOR_SESSION_ID")),
+    ("codex", ("CODEX_CLI", "OPENAI_CODEX")),
+    ("cline", ("CLINE_AGENT", "CLINE")),
+    ("continue", ("CONTINUE_AGENT", "CONTINUE_SESSION")),
+    ("aider", ("AIDER_SESSION",)),
+    ("goose", ("GOOSE_AGENT",)),
+    ("windsurf", ("WINDSURF_AGENT",)),
+)
+
+
+def detect_agent_caller() -> str | None:
+    """Return a canonical agent name if any agent env var is set, else None."""
+    for name, env_vars in _AGENT_CALLER_ENV:
+        if any(os.environ.get(v) for v in env_vars):
+            return name
+    return None

cli/python/src/mem0_cli/app.py

@@ -237,6 +237,14 @@ def main_callback(
         cmd_version()
         raise typer.Exit()
     if ctx.invoked_subcommand:
+        # Stash the active subcommand name so the JSON error envelope
+        # (print_error in agent mode) can report which command failed
+        # instead of an empty `"command": ""` field.
+        from mem0_cli.state import set_current_command
+
+        set_current_command(ctx.invoked_subcommand)
+    if ctx.invoked_subcommand and ctx.invoked_subcommand != "init":
+        # init fires its own telemetry from init_cmd.run_init with full M1-M6 props.
         _fire_telemetry(ctx.invoked_subcommand)
 
 
@@ -851,6 +859,19 @@ def init(
     force: bool = typer.Option(
         False, "--force", help="Overwrite existing config without confirmation."
     ),
+    agent_signal: bool = typer.Option(
+        False, "--agent", help="Bootstrap an unattended Agent Mode account (no email required)."
+    ),
+    source: str | None = typer.Option(
+        None,
+        "--source",
+        help="Channel attribution for signup (e.g. github, hn, ph).",
+    ),
+    agent_caller: str | None = typer.Option(
+        None,
+        "--agent-caller",
+        help="Self-declared agent identity (e.g. claude-code, cursor). Used with --agent to attribute Agent Mode signups.",
+    ),
 ) -> None:
     """Interactive setup wizard for mem0 CLI.
 
@@ -859,10 +880,97 @@ def init(
       mem0 init --api-key m0-xxx --user-id alice
       mem0 init --email alice@company.com
       mem0 init --email alice@company.com --code 482901
+      mem0 init --agent --agent-caller claude-code   # AI agent self-identifies on Agent Mode bootstrap
+      mem0 init --email alice@company.com  # Claims an existing Agent Mode key when one is present
     """
     from mem0_cli.commands.init_cmd import run_init
 
-    run_init(api_key=api_key, user_id=user_id, email=email, code=code, force=force)
+    run_init(
+        api_key=api_key,
+        user_id=user_id,
+        email=email,
+        code=code,
+        force=force,
+        source=source,
+        agent=agent_signal,
+        agent_caller=agent_caller,
+    )
+
+
+@app.command(rich_help_panel="Setup")
+def identify(
+    name: str = typer.Argument(..., help="Agent identity (e.g. claude-code, cursor, my-bot)."),
+) -> None:
+    """Tag your active Agent Mode key with the AI agent that's using it.
+
+    Run this once after `mem0 init --agent` if you didn't pass --agent-caller.
+    Idempotent — re-running just overwrites the value.
+
+    Example:
+      mem0 identify claude-code
+    """
+    from mem0_cli.commands.identify_cmd import run_identify
+
+    run_identify(name)
+
+
+@app.command(name="whoami", rich_help_panel="Setup")
+def whoami_cmd() -> None:
+    """Print your AGENTRUSH identifier (default_user_id).
+
+    Example:
+      mem0 whoami
+    """
+    from mem0_cli.commands.whoami_cmd import run_whoami
+
+    run_whoami()
+
+
+# ── AGENTRUSH sub-app ─────────────────────────────────────────────────────
+
+agent_rush_app = typer.Typer(
+    name="agent-rush",
+    help="AGENTRUSH game commands",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+@agent_rush_app.callback(invoke_without_command=True)
+def _agent_rush_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"agent-rush.{ctx.invoked_subcommand}")
+
+
+@agent_rush_app.command(name="add")
+def agent_rush_add(
+    content: str = typer.Argument(..., help="Memory content (50-1000 characters, no URLs)."),
+) -> None:
+    """Submit a memory to AGENTRUSH.
+
+    Example:
+      mem0 agent-rush add "I enjoy solving constraint-satisfaction problems."
+    """
+    from mem0_cli.commands.agent_rush_cmd import run_agent_rush_add
+
+    run_agent_rush_add(content)
+
+
+@agent_rush_app.command(name="search")
+def agent_rush_search(
+    query: str = typer.Argument(..., help="Search query."),
+) -> None:
+    """Search AGENTRUSH memories.
+
+    Example:
+      mem0 agent-rush search "constraint satisfaction"
+    """
+    from mem0_cli.commands.agent_rush_cmd import run_agent_rush_search
+
+    run_agent_rush_search(query)
+
+
+app.add_typer(agent_rush_app, name="agent-rush", rich_help_panel="Setup")
 
 
 # (entity_app registered at module level, below sub-group definitions)
@@ -1198,11 +1306,28 @@ 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:]):
+    # Special case: `mem0 init --agent` is a subcommand flag (Agent Mode bootstrap)
+    # consumed by init_cmd, not a global JSON-output toggle — leave it in argv.
+    argv_rest = sys.argv[1:]
+    is_init = "init" in argv_rest
+    _global_flags = {"--json"} if is_init else {"--json", "--agent"}
+    if any(a in _global_flags for a in argv_rest):
         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]
+        sys.argv = [sys.argv[0]] + [a for a in argv_rest if a not in _global_flags]
 
-    app()
+    try:
+        app()
+    finally:
+        # Surface any unclaimed Agent Mode notice once per command, after the
+        # primary output. In JSON/agent mode the notice is folded into the
+        # envelope by format_json_envelope, so skip the stderr banner there
+        # to avoid duplicate output.
+        from mem0_cli.state import is_agent_mode, take_notice
+
+        notice = take_notice()
+        if notice and not is_agent_mode():
+            from rich.console import Console
+
+            Console(stderr=True).print(f"\n[yellow]🔔 {notice}[/yellow]\n")

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from typing import Any
+from urllib.parse import quote
 
 import httpx
 
@@ -11,6 +12,10 @@ from mem0_cli.backend.base import Backend
 from mem0_cli.config import PlatformConfig
 
 
+def _encode_path_segment(value: Any) -> str:
+    return quote(str(value), safe="")
+
+
 class PlatformBackend(Backend):
     """Backend that talks to the mem0 Platform API."""
 
@@ -30,7 +35,7 @@ class PlatformBackend(Backend):
         )
 
     def _request(self, method: str, path: str, **kwargs: Any) -> Any:
-        from mem0_cli.state import is_agent_mode
+        from mem0_cli.state import capture_notice, is_agent_mode
 
         self._client.headers["X-Mem0-Caller-Type"] = "agent" if is_agent_mode() else "user"
         resp = self._client.request(method, path, **kwargs)
@@ -48,7 +53,26 @@ class PlatformBackend(Backend):
         resp.raise_for_status()
         if resp.status_code == 204:
             return {}
-        return resp.json()
+        data = resp.json()
+
+        # Pull the unclaimed-Agent-Mode notice out of the body (or the header
+        # fallback for endpoints that return non-dict / non-dict-leading
+        # payloads) and stash it for end-of-command surfacing.
+        notice = None
+        if isinstance(data, dict) and "mem0_notice" in data:
+            notice = data.pop("mem0_notice")
+        elif (
+            isinstance(data, list)
+            and data
+            and isinstance(data[0], dict)
+            and "mem0_notice" in data[0]
+        ):
+            notice = data[0].pop("mem0_notice")
+        if notice is None:
+            notice = resp.headers.get("X-Mem0-Notice-Message") or None
+        capture_notice(notice)
+
+        return data
 
     def add(
         self,
@@ -177,7 +201,11 @@ class PlatformBackend(Backend):
         )
 
     def get(self, memory_id: str) -> dict:
-        return self._request("GET", f"/v1/memories/{memory_id}/", params={"source": "CLI"})
+        return self._request(
+            "GET",
+            f"/v1/memories/{_encode_path_segment(memory_id)}/",
+            params={"source": "CLI"},
+        )
 
     def list_memories(
         self,
@@ -231,7 +259,11 @@ class PlatformBackend(Backend):
         if metadata:
             payload["metadata"] = metadata
         payload["source"] = "CLI"
-        return self._request("PUT", f"/v1/memories/{memory_id}/", json=payload)
+        return self._request(
+            "PUT",
+            f"/v1/memories/{_encode_path_segment(memory_id)}/",
+            json=payload,
+        )
 
     def delete(
         self,
@@ -255,7 +287,11 @@ 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}/", params={"source": "CLI"})
+            return self._request(
+                "DELETE",
+                f"/v1/memories/{_encode_path_segment(memory_id)}/",
+                params={"source": "CLI"},
+            )
         else:
             raise ValueError("Either memory_id or --all is required")
 
@@ -277,13 +313,17 @@ class PlatformBackend(Backend):
         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.")
-        # Delete each provided entity via the v2 path-based endpoint
-        result: dict = {}
+        # Delete each provided entity via the v2 path-based endpoint. Key each
+        # response by entity type so a multi-entity delete (e.g. --user-id and
+        # --agent-id together) doesn't discard everything but the last result.
+        results: dict = {}
         for entity_type, entity_id in entities.items():
-            result = self._request(
-                "DELETE", f"/v2/entities/{entity_type}/{entity_id}/", params={"source": "CLI"}
+            results[entity_type] = self._request(
+                "DELETE",
+                f"/v2/entities/{_encode_path_segment(entity_type)}/{_encode_path_segment(entity_id)}/",
+                params={"source": "CLI"},
             )
-        return result
+        return results
 
     def ping(self, timeout: float | None = None) -> dict:
         """Call the ping endpoint and return the raw response.
@@ -327,7 +367,7 @@ class PlatformBackend(Backend):
         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}/")
+        return self._request("GET", f"/v1/event/{_encode_path_segment(event_id)}/")
 
 
 class AuthError(Exception):

cli/python/src/mem0_cli/branding.py

@@ -87,10 +87,12 @@ def print_error(console: Console, message: str, hint: str | None = None) -> None
         }
         print(_json.dumps(envelope))
         return
+    from rich.markup import escape
+
     sym = _sym("✗", "[error]")
-    console.print(f"[{ERROR_COLOR}]{sym} Error:[/] {message}")
+    console.print(f"[{ERROR_COLOR}]{sym} Error:[/] {escape(str(message))}")
     if hint:
-        console.print(f"  [{DIM_COLOR}]{hint}[/]")
+        console.print(f"  [{DIM_COLOR}]{escape(str(hint))}[/]")
 
 
 def print_warning(console: Console, message: str) -> None:

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

@@ -0,0 +1,239 @@
+"""Agent Mode commands — bootstrap (unattended signup) and claim (OTP-based human upgrade)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from mem0_cli.branding import (
+    BRAND_COLOR,
+    DIM_COLOR,
+    print_error,
+    print_success,
+)
+from mem0_cli.config import Mem0Config, save_config
+
+console = Console()
+err_console = Console(stderr=True)
+
+_SOURCE_HEADERS = {
+    "X-Mem0-Source": "cli",
+    "X-Mem0-Client-Language": "python",
+}
+
+
+def _validate_envelope(envelope: Any) -> None:
+    """Defend against partial/malformed backend responses.
+
+    A backend regression that returns ``{"api_key": null}`` would otherwise be
+    silently persisted, producing confusing downstream errors far from the
+    source. Fail fast with a clear message if the required fields are missing.
+    """
+    if not isinstance(envelope, dict):
+        print_error(err_console, "Bootstrap response was not a JSON object.")
+        raise typer.Exit(1)
+    for field in ("api_key", "default_user_id"):
+        value = envelope.get(field)
+        if not isinstance(value, str) or not value:
+            print_error(
+                err_console,
+                f"Bootstrap response missing required field {field!r} — please update the CLI.",
+            )
+            raise typer.Exit(1)
+
+
+def bootstrap_via_backend(
+    config: Mem0Config,
+    *,
+    source: str | None = None,
+    agent_caller: str | None = None,
+) -> None:
+    """POST /api/v1/auth/agent_mode/ and mutate config in place.
+
+    Args:
+        config: Mem0Config mutated in place with the new platform values.
+        source: ``--source`` flag passthrough (analytics tag, free-form).
+        agent_caller: Self-declared agent identity passed via ``--agent-caller``
+            (e.g. ``claude-code``, ``cursor``). May be None when the caller
+            omitted the flag; the agent can backfill later via
+            ``mem0 identify <name>``. Sent to the backend in the request body
+            and saved into ``platform.agent_caller`` for local introspection.
+
+    Raises typer.Exit(1) on failure.
+    """
+    base_url = (config.platform.base_url or "https://api.mem0.ai").rstrip("/")
+    body: dict[str, Any] = {}
+    if source:
+        body["source"] = source
+    if agent_caller:
+        body["agent_caller"] = agent_caller
+
+    try:
+        with httpx.Client(timeout=30.0) as client:
+            resp = client.post(
+                f"{base_url}/api/v1/auth/agent_mode/",
+                headers={**_SOURCE_HEADERS, "Content-Type": "application/json"},
+                json=body,
+            )
+    except httpx.HTTPError as exc:
+        print_error(err_console, f"Network error contacting Mem0: {exc}")
+        raise typer.Exit(1) from exc
+
+    if resp.status_code == 429:
+        print_error(err_console, "Rate-limited. Try again in a few minutes.")
+        raise typer.Exit(1)
+    if resp.status_code == 503:
+        print_error(err_console, "Agent Mode is temporarily disabled. Try again later.")
+        raise typer.Exit(1)
+    if resp.status_code != 200:
+        detail = resp.text
+        try:
+            err_body = resp.json()
+            detail = err_body.get("error") or err_body.get("detail") or resp.text
+        except (json.JSONDecodeError, ValueError, AttributeError):
+            pass
+        # Backend's @ratelimit decorator raises PermissionDenied, which DRF
+        # translates to a generic 403 "You do not have permission to perform
+        # this action." That's opaque — surface as the rate-limit it actually is.
+        if resp.status_code == 403 and "permission" in str(detail).lower():
+            print_error(
+                err_console,
+                "Daily Agent Mode signup limit reached for this network (5/day). Try again from a different IP or after midnight UTC.",
+            )
+            raise typer.Exit(1)
+        print_error(err_console, f"Bootstrap failed: {detail}")
+        raise typer.Exit(1)
+
+    envelope = resp.json()
+    _validate_envelope(envelope)
+    config.platform.api_key = envelope["api_key"]
+    config.platform.base_url = base_url
+    config.platform.agent_mode = True
+    config.platform.created_via = "agent_mode"
+    config.platform.agent_caller = agent_caller or ""
+    config.platform.claimed_at = ""
+    config.platform.default_user_id = envelope["default_user_id"]
+    # Adopt the slug-derived user_id as the default scope for memory ops.
+    config.defaults.user_id = envelope["default_user_id"]
+    save_config(config)
+
+    print_success(console, f"Agent Mode active. Default user_id: {envelope['default_user_id']}")
+    notice = envelope.get("mem0_notice")
+    if notice:
+        console.print(f"\n[yellow]🔔 {notice}[/yellow]\n")
+    else:
+        # Fallback if the backend hasn't deployed the unified notice yet.
+        claim_cmd = envelope.get("claim_command", "mem0 init --email <your-email>")
+        console.print(f"  [{DIM_COLOR}]To claim this account later: {claim_cmd}[/]")
+
+    if not agent_caller:
+        console.print(
+            f"  [{DIM_COLOR}]If you are an AI agent, identify yourself: "
+            f"`mem0 identify <your-name>` (e.g. claude-code, cursor).[/]"
+        )
+
+
+def claim_via_otp(config: Mem0Config, *, email: str, code: str | None = None) -> None:
+    """Claim an existing Agent Mode account via OTP — no browser, no polling.
+
+    Reuses the standard email-code flow (`/api/v1/auth/email_code/` then
+    `/.../verify/`) and adds the local agent-mode API key in the verify body
+    as `agent_mode_api_key`. Backend's `verify_email_code` runs the
+    upgrade-in-place transaction inline and returns claim result.
+
+    On success: flips `platform.agent_mode=false`, sets `claimed_at`, stamps
+    `user_email`. The api_key value itself never changes.
+    """
+    base_url = (config.platform.base_url or "https://api.mem0.ai").rstrip("/")
+    if not config.platform.api_key or not config.platform.agent_mode:
+        print_error(
+            err_console,
+            "This command requires an active Agent Mode config. Run `mem0 init` first.",
+        )
+        raise typer.Exit(1)
+
+    raw_key = config.platform.api_key
+
+    with httpx.Client(timeout=30.0) as client:
+        # Step 1: request OTP (unless --code provided)
+        if not code:
+            send = client.post(
+                f"{base_url}/api/v1/auth/email_code/",
+                headers={**_SOURCE_HEADERS, "Content-Type": "application/json"},
+                json={"email": email},
+            )
+            if send.status_code == 429:
+                print_error(err_console, "Too many attempts. Try again in a few minutes.")
+                raise typer.Exit(1)
+            if send.status_code != 200:
+                try:
+                    detail = send.json().get("error", send.text)
+                except Exception:
+                    detail = send.text
+                print_error(err_console, f"Failed to send code: {detail}")
+                raise typer.Exit(1)
+
+            print_success(console, f"Verification code sent to {email}. Check your inbox.")
+
+            if not sys.stdin.isatty():
+                print_error(
+                    err_console,
+                    "No --code provided and terminal is non-interactive.",
+                    hint=f"Re-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 2: verify + claim in one shot
+        verify = client.post(
+            f"{base_url}/api/v1/auth/email_code/verify/",
+            headers={**_SOURCE_HEADERS, "Content-Type": "application/json"},
+            json={
+                "email": email,
+                "code": code.strip(),
+                "agent_mode_api_key": raw_key,
+            },
+        )
+
+    if verify.status_code != 200:
+        try:
+            err_body = verify.json()
+            detail = err_body.get("error", verify.text)
+            code_str = err_body.get("code", "")
+        except (json.JSONDecodeError, ValueError, AttributeError):
+            detail = verify.text
+            code_str = ""
+        print_error(err_console, f"Claim failed: {detail}")
+        if code_str == "email_already_claimed":
+            console.print(
+                f"  [{DIM_COLOR}]Tip: this email already has a Mem0 account. Sign in at app.mem0.ai with your existing credentials.[/]"
+            )
+        raise typer.Exit(1)
+
+    claim_body = verify.json()
+    if not claim_body.get("claimed"):
+        print_error(err_console, f"Unexpected verify response: {claim_body}")
+        raise typer.Exit(1)
+
+    config.platform.agent_mode = False
+    config.platform.claimed_at = claim_body.get("claimed_at") or _utcnow_iso()
+    config.platform.user_email = email
+    config.platform.created_via = "email"
+    save_config(config)
+    print_success(console, f"Agent claimed to {email}. Your API key is unchanged.")
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()

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

@@ -0,0 +1,132 @@
+"""mem0 agent-rush — AGENTRUSH game commands.
+
+Wraps the platform's /v1/agent-rush/{memories/, memories/search/} endpoints.
+Hardcoded routing; no flags needed.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+
+import httpx
+import typer
+from rich.console import Console
+
+from mem0_cli.branding import print_error, print_success
+from mem0_cli.config import load_config, save_config
+
+console = Console()
+err_console = Console(stderr=True)
+
+_PII_WARNING_LINES = (
+    "",
+    "[yellow]⚠️  AGENTRUSH memories are PUBLIC — visible to any other player.[/yellow]",
+    "[yellow]   Do not include real names, emails, secrets, work content, or PII.[/yellow]",
+    "",
+)
+
+_SOURCE_HEADERS = {
+    "X-Mem0-Source": "cli",
+    "X-Mem0-Client-Language": "python",
+    "X-Mem0-Mode": "agent-rush",
+}
+
+_ERROR_HINTS = {
+    "agentrush_search_first": "Run 3 'mem0 agent-rush search' commands before adding.",
+    "agentrush_search_quota": "You've used your 3 lifetime searches.",
+    "agentrush_add_quota": "You've used your 3 lifetime adds.",
+    "agentrush_not_agent_mode": "Re-run 'mem0 init --agent' to bootstrap an agent-mode key.",
+    "agentrush_length": "Memory text must be 50-1000 characters.",
+    "agentrush_no_urls": "URLs are not allowed.",
+    "agentrush_blocklist": "Content contains a blocked term.",
+    "agentrush_global_quota": "Event-wide cap reached. Try again later.",
+    "agentrush_not_provisioned": "AGENTRUSH is not provisioned in this environment.",
+}
+
+
+def _call(path: str, body: dict) -> dict:
+    config = load_config()
+    if not config.platform.api_key:
+        print_error(err_console, "Not initialized. Run `mem0 init --agent` first.")
+        raise typer.Exit(1)
+    base_url = (config.platform.base_url or "https://api.mem0.ai").rstrip("/")
+    try:
+        with httpx.Client(timeout=30.0) as client:
+            resp = client.post(
+                f"{base_url}{path}",
+                headers={
+                    **_SOURCE_HEADERS,
+                    "Authorization": f"Token {config.platform.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json=body,
+            )
+    except httpx.HTTPError as exc:
+        print_error(err_console, f"Network error: {exc}")
+        raise typer.Exit(1) from exc
+    try:
+        data = resp.json()
+    except Exception:
+        data = {}
+    if resp.status_code >= 400:
+        code = (
+            (data.get("error") or {}).get("code", "unknown")
+            if isinstance(data, dict)
+            else "unknown"
+        )
+        print_error(err_console, f"AGENTRUSH error: {code}")
+        hint = _ERROR_HINTS.get(code)
+        if hint:
+            console.print(f"  [dim]{hint}[/dim]")
+        raise typer.Exit(1)
+    return data
+
+
+def _ensure_warning_acknowledged() -> None:
+    """Block the first interactive add on the PII warning; pass-through for agents.
+
+    Interactive (TTY): show prompt, require explicit 'y', persist
+    `agent_rush.acknowledged_at` so we never ask the same machine twice.
+
+    Non-interactive (no TTY — typical when an agent runs the CLI): surface
+    the warning to stderr for the human reading the agent transcript and
+    proceed without prompting (agents can't answer y/N).
+    """
+    config = load_config()
+    if config.agent_rush.acknowledged_at:
+        return
+
+    is_tty = sys.stdin.isatty() and sys.stdout.isatty()
+    if not is_tty:
+        for line in _PII_WARNING_LINES:
+            err_console.print(line)
+        return
+
+    for line in _PII_WARNING_LINES:
+        console.print(line)
+    answer = typer.prompt("   Continue? [y/N]", default="N", show_default=False).strip().lower()
+    if answer not in ("y", "yes"):
+        print_error(err_console, "Aborted.")
+        raise typer.Exit(1)
+
+    config.agent_rush.acknowledged_at = datetime.now(timezone.utc).isoformat()
+    save_config(config)
+
+
+def run_agent_rush_add(content: str) -> None:
+    _ensure_warning_acknowledged()
+    result = _call("/v1/agent-rush/memories/", {"content": content})
+    event_id = result.get("event_id", "?")
+    print_success(console, f"Memory submitted (event_id: {event_id})")
+
+
+def run_agent_rush_search(query: str) -> None:
+    result = _call("/v1/agent-rush/memories/search/", {"query": query})
+    memories = result.get("results") or result.get("memories") or []
+    if not memories:
+        console.print("[dim](no results)[/dim]")
+        return
+    for i, m in enumerate(memories[:5], start=1):
+        text = m.get("memory") if isinstance(m, dict) else str(m)
+        console.print(f"  {i}. {text}")

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

@@ -0,0 +1,75 @@
+"""mem0 identify — declare which agent owns the current agent-mode key.
+
+Used when `mem0 init --agent` ran without --agent-caller, so the backend
+saved agent_caller=NULL. The agent re-runs `mem0 identify <name>` to PATCH
+its own row with its real identity. Idempotent — running it again just
+overwrites.
+"""
+
+from __future__ import annotations
+
+import httpx
+import typer
+from rich.console import Console
+
+from mem0_cli.branding import print_error, print_success
+from mem0_cli.config import load_config, save_config
+
+console = Console()
+err_console = Console(stderr=True)
+
+_SOURCE_HEADERS = {
+    "X-Mem0-Source": "cli",
+    "X-Mem0-Client-Language": "python",
+}
+
+
+def run_identify(name: str) -> None:
+    """PATCH the active agent-mode key's agent_caller field."""
+    config = load_config()
+    if not config.platform.api_key:
+        print_error(
+            err_console,
+            "No API key configured. Run `mem0 init --agent` first.",
+        )
+        raise typer.Exit(1)
+    if not config.platform.agent_mode:
+        print_error(
+            err_console,
+            "This command only works on unclaimed agent-mode keys.",
+        )
+        raise typer.Exit(1)
+
+    name = (name or "").strip()
+    if not name:
+        print_error(err_console, "Agent name is required.")
+        raise typer.Exit(1)
+
+    base_url = (config.platform.base_url or "https://api.mem0.ai").rstrip("/")
+    try:
+        with httpx.Client(timeout=30.0) as client:
+            resp = client.patch(
+                f"{base_url}/api/v1/auth/agent_mode/caller/",
+                headers={
+                    **_SOURCE_HEADERS,
+                    "Authorization": f"Token {config.platform.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={"agent_caller": name},
+            )
+    except httpx.HTTPError as exc:
+        print_error(err_console, f"Network error: {exc}")
+        raise typer.Exit(1) from exc
+
+    if resp.status_code != 200:
+        try:
+            detail = resp.json().get("error", resp.text)
+        except Exception:
+            detail = resp.text
+        print_error(err_console, f"Identify failed: {detail}")
+        raise typer.Exit(1)
+
+    canonical = resp.json().get("agent_caller", name)
+    config.platform.agent_caller = canonical
+    save_config(config)
+    print_success(console, f"Identified as {canonical}.")

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

@@ -103,6 +103,25 @@ def _validate_email(email: str) -> None:
         raise typer.Exit(1)
 
 
+def _ping_key(api_key: str, base_url: str, timeout: float = 5.0) -> bool:
+    """Validate api_key against /v1/ping/.
+
+    Returns False ONLY on a definitive "invalid key" signal (HTTP 401 / 403).
+    Network errors, timeouts, and 5xx responses return True so we prefer
+    reusing an existing key over silently minting a new shadow on a transient
+    blip (which would also clobber config + plugin-sync targets).
+    """
+    try:
+        resp = httpx.get(
+            f"{base_url.rstrip('/')}/v1/ping/",
+            headers={"Authorization": f"Token {api_key}"},
+            timeout=timeout,
+        )
+    except httpx.HTTPError:
+        return True  # unknown — prefer reuse
+    return resp.status_code not in (401, 403)
+
+
 def _email_login(
     email: str,
     code: str | None,
@@ -182,21 +201,143 @@ def run_init(
     email: str | None = None,
     code: str | None = None,
     force: bool = False,
+    source: str | None = None,
+    agent: bool = False,
+    agent_caller: str | None = None,
 ) -> None:
     """Interactive setup wizard for mem0 CLI.
 
     When both *api_key* and *user_id* are supplied, all prompts are skipped
     (non-interactive mode).  When running in a non-TTY without the required
     flags, an error message is printed.
+
+    Agent Mode dispatch (no email/api-key flags):
+      - If existing config has an active API key → reuse (existing_key path).
+      - Else if any positive agent signal (--agent, --json global, agent env
+        var, or `agent` flag) → POST /api/v1/auth/agent_mode/ and write config.
+      - Else fall through to the interactive wizard.
+
+    Claim dispatch:
+      - If `--email` is set AND existing config has `agent_mode=true`, run the
+        claim device-flow against the existing key instead of minting a new
+        email-based key.
     """
+    from mem0_cli.agent_detect import detect_agent_caller
+    from mem0_cli.commands.agent_mode_cmd import bootstrap_via_backend, claim_via_otp
+    from mem0_cli.state import is_agent_mode as _global_agent_mode
+    from mem0_cli.telemetry import capture_event
+
+    def _fire_init(mode: str, *, claimed: bool = False) -> None:
+        """Fire cli.init telemetry with M1-M6 properties."""
+        props: dict = {"command": "init", "mode": mode}
+        if agent_caller:
+            # Self-declared via --agent-caller; not sniffed from env vars.
+            props["agent_caller"] = agent_caller
+        if source:
+            props["signup_source"] = source
+        if claimed:
+            props["claimed_agent_mode"] = True
+        capture_event("cli.init", props)
+
     config = Mem0Config()
 
     base_url = os.environ.get("MEM0_BASE_URL", config.platform.base_url or DEFAULT_BASE_URL)
+    config.platform.base_url = base_url
 
     if code and not email:
         print_error(err_console, "--code requires --email.")
         raise typer.Exit(1)
 
+    # ── Email + existing agent-mode config → claim flow ─────────────────
+    if email and CONFIG_FILE.exists():
+        existing = load_config()
+        if existing.platform.agent_mode and existing.platform.api_key:
+            email = email.strip().lower()
+            _validate_email(email)
+            print_info(console, f"Claiming Agent Mode account to {email}...")
+            claim_via_otp(existing, email=email, code=code)
+            _fire_init("email", claimed=True)
+            return
+
+    # ── Agent Mode path runs BEFORE the existing-config guard ──────────
+    # Rules 1/2 REUSE a valid existing key (not overwrite), so we must
+    # short-circuit before the guard prompts. Rule 3 mints only when there
+    # is no valid key to reuse — in that case overwriting is correct.
+    _agent_ctx = agent or _global_agent_mode() or (detect_agent_caller() is not None)
+    if not api_key and not email and _agent_ctx:
+        from mem0_cli.output import format_json_envelope
+        from mem0_cli.state import is_agent_mode as _is_json_mode
+
+        def _emit_reuse(source: str) -> None:
+            if _is_json_mode():
+                format_json_envelope(
+                    console,
+                    command="init",
+                    data={
+                        "api_key_saved": False,
+                        "api_key_source": source,
+                        "agent_mode": False,
+                        "message": "Existing Mem0 API key found and reused. No Agent Mode key was created.",
+                    },
+                )
+            else:
+                msg = (
+                    "Existing MEM0_API_KEY is valid; reusing it. No new Agent Mode key was minted."
+                    if source == "env"
+                    else "Existing API key in config is valid; reusing it. No new Agent Mode key was minted."
+                )
+                print_success(console, msg)
+
+        def _maybe_identify(key: str) -> None:
+            """Best-effort PATCH agent_caller when --agent-caller is supplied on a
+            reused key. Silent no-op on any failure — reuse must not break.
+            """
+            if not agent_caller:
+                return
+            try:
+                resp = httpx.patch(
+                    f"{base_url.rstrip('/')}/api/v1/auth/agent_mode/caller/",
+                    headers={
+                        "Authorization": f"Token {key}",
+                        "Content-Type": "application/json",
+                    },
+                    json={"agent_caller": agent_caller},
+                    timeout=10.0,
+                )
+                # Also reflect in local config so introspection matches backend.
+                if resp.status_code == 200 and CONFIG_FILE.exists():
+                    try:
+                        cfg = load_config()
+                        cfg.platform.agent_caller = resp.json().get("agent_caller", agent_caller)
+                        save_config(cfg)
+                    except Exception:
+                        pass
+            except httpx.HTTPError:
+                pass
+
+        # Rule 1: env MEM0_API_KEY valid → reuse, no new key.
+        _env_key = (os.environ.get("MEM0_API_KEY") or "").strip()
+        if _env_key and _ping_key(_env_key, base_url):
+            _maybe_identify(_env_key)
+            _emit_reuse("env")
+            _fire_init("existing_key")
+            return
+        # Rule 2: existing config api_key valid → reuse.
+        if CONFIG_FILE.exists():
+            _existing = load_config()
+            if _existing.platform.api_key and _ping_key(_existing.platform.api_key, base_url):
+                _maybe_identify(_existing.platform.api_key)
+                _emit_reuse("config")
+                _fire_init("existing_key")
+                return
+        # Rule 3: mint a fresh shadow (no valid key to reuse).
+        # agent_caller is the agent's self-declared identity from --agent-caller
+        # (Proof Editor-style). Env-var auto-detect is still used above to
+        # decide we're in an agent context, but never to fill identity.
+        bootstrap_via_backend(config, source=source, agent_caller=agent_caller)
+        _fire_init("agent")
+        return
+
     # Warn if an existing config with an API key would be overwritten
     if not force and CONFIG_FILE.exists():
         existing = load_config()
@@ -242,6 +383,7 @@ def run_init(
         config.platform.api_key = api_key_val
         config.platform.base_url = base_url
         config.platform.user_email = email
+        config.platform.created_via = "email"
         config.defaults.user_id = (
             user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
         )
@@ -258,6 +400,8 @@ def run_init(
         return
 
     # ── API key flow (existing) ───────────────────────────────────────
+    # (Agent Mode branch runs earlier — see above, before the existing-config
+    # guard, so Rules 1/2 can REUSE a valid key without prompting overwrite.)
 
     # Non-TTY: resolve defaults so partial flags work in pipelines / CI
     if not sys.stdin.isatty():
@@ -265,7 +409,7 @@ def run_init(
             print_error(
                 err_console,
                 "Non-interactive terminal detected and --api-key is required.",
-                hint="Run: mem0 init --api-key <key> [--user-id <id>]",
+                hint="Run: mem0 init --api-key <key>, --email <addr>, or --agent for unattended Agent Mode bootstrap.",
             )
             raise typer.Exit(1)
         user_id = user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
@@ -273,6 +417,7 @@ def run_init(
     # Fully non-interactive when both flags provided
     if api_key and user_id:
         config.platform.api_key = api_key
+        config.platform.created_via = "api_key"
         config.defaults.user_id = user_id
         _validate_platform(config)
         save_config(config)
@@ -313,6 +458,7 @@ def run_init(
             config.platform.api_key = api_key_val
             config.platform.base_url = base_url
             config.platform.user_email = email_addr
+            config.platform.created_via = "email"
             config.defaults.user_id = (
                 user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
             )
@@ -331,6 +477,7 @@ def run_init(
     # API key flow
     if api_key:
         config.platform.api_key = api_key
+        config.platform.created_via = "api_key"
     else:
         _setup_platform(config)
 
@@ -370,6 +517,7 @@ def _setup_platform(config: Mem0Config) -> None:
         raise typer.Exit(1)
 
     config.platform.api_key = api_key
+    config.platform.created_via = "api_key"
 
 
 def _setup_defaults(config: Mem0Config) -> None:

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

@@ -0,0 +1,25 @@
+"""mem0 whoami — print the active agent's default_user_id (AGENTRUSH identifier)."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from mem0_cli.branding import BRAND_COLOR, print_error, print_info
+from mem0_cli.config import load_config
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def run_whoami() -> None:
+    config = load_config()
+    session_id = config.platform.default_user_id if config.platform else None
+    if not session_id:
+        print_error(
+            err_console,
+            "No default_user_id found. Run `mem0 init --agent` first.",
+        )
+        raise typer.Exit(1)
+    console.print(f"Your AGENTRUSH identifier:  [{BRAND_COLOR}]{session_id}[/{BRAND_COLOR}]")
+    print_info(console, "Find your row at https://mem0.ai/agentrush")

cli/python/src/mem0_cli/config.py

@@ -28,6 +28,14 @@ class PlatformConfig:
     api_key: str = ""
     base_url: str = DEFAULT_BASE_URL
     user_email: str = ""
+    # Agent Mode (unclaimed-shadow signup)
+    agent_mode: bool = False  # True while the key is an unclaimed agent-mode key
+    created_via: str = ""  # "agent_mode" | "email" | "api_key" | "existing_key"
+    agent_caller: str = (
+        ""  # canonical agent name when created_via == "agent_mode" (e.g. "claude-code")
+    )
+    claimed_at: str = ""  # ISO timestamp once the agent has been claimed by a human
+    default_user_id: str = ""  # `user_<slug>` returned by bootstrap; used as auto-default
 
 
 @dataclass
@@ -43,12 +51,20 @@ class TelemetryConfig:
     anonymous_id: str = ""
 
 
+@dataclass
+class AgentRushConfig:
+    # ISO timestamp the human acknowledged the "memories are public" warning.
+    # Empty until first interactive `mem0 agent-rush add`.
+    acknowledged_at: str = ""
+
+
 @dataclass
 class Mem0Config:
     version: int = CONFIG_VERSION
     defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
     platform: PlatformConfig = field(default_factory=PlatformConfig)
     telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
+    agent_rush: AgentRushConfig = field(default_factory=AgentRushConfig)
 
 
 SHORT_KEY_ALIASES: dict[str, str] = {
@@ -83,6 +99,11 @@ def load_config() -> Mem0Config:
         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", "")
+        config.platform.agent_mode = bool(plat.get("agent_mode", False))
+        config.platform.created_via = plat.get("created_via", "")
+        config.platform.agent_caller = plat.get("agent_caller", "")
+        config.platform.claimed_at = plat.get("claimed_at", "")
+        config.platform.default_user_id = plat.get("default_user_id", "")
 
         defaults = data.get("defaults", {})
         config.defaults.user_id = defaults.get("user_id", "")
@@ -92,6 +113,9 @@ def load_config() -> Mem0Config:
         telemetry = data.get("telemetry", {})
         config.telemetry.anonymous_id = telemetry.get("anonymous_id", "")
 
+        agent_rush = data.get("agent_rush", {})
+        config.agent_rush.acknowledged_at = agent_rush.get("acknowledged_at", "")
+
     # Environment variable overrides
     env_key = os.environ.get("MEM0_API_KEY")
     if env_key:
@@ -136,10 +160,18 @@ def save_config(config: Mem0Config) -> None:
             "api_key": config.platform.api_key,
             "base_url": config.platform.base_url,
             "user_email": config.platform.user_email,
+            "agent_mode": config.platform.agent_mode,
+            "created_via": config.platform.created_via,
+            "agent_caller": config.platform.agent_caller,
+            "claimed_at": config.platform.claimed_at,
+            "default_user_id": config.platform.default_user_id,
         },
         "telemetry": {
             "anonymous_id": config.telemetry.anonymous_id,
         },
+        "agent_rush": {
+            "acknowledged_at": config.agent_rush.acknowledged_at,
+        },
     }
 
     with open(CONFIG_FILE, "w") as f:
@@ -147,6 +179,19 @@ def save_config(config: Mem0Config) -> None:
 
     os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR)  # 0600
 
+    # Propagate the active api_key to ecosystem touchpoints (Claude Code
+    # plugin env injection, shell rc exports). Idempotent — only updates
+    # EXISTING entries; never creates new ones. Best-effort: any IOError
+    # in the sync is swallowed so config.json is always the authoritative
+    # write, never blocked by plugin-state issues.
+    if config.platform.api_key:
+        try:
+            from mem0_cli.plugin_sync import sync_api_key
+
+            sync_api_key(config.platform.api_key)
+        except Exception:
+            pass
+
 
 def redact_key(key: str) -> str:
     """Redact an API key for display: m0-xxx...xxx"""
@@ -190,7 +235,10 @@ def set_nested_value(config: Mem0Config, dotted_key: str, value: str) -> bool:
     if isinstance(current, bool):
         value = value.lower() in ("true", "1", "yes")  # type: ignore[assignment]
     elif isinstance(current, int):
-        value = int(value)  # type: ignore[assignment]
+        try:
+            value = int(value)  # type: ignore[assignment]
+        except ValueError:
+            return False
 
     setattr(obj, final_key, value)
     return True

cli/python/src/mem0_cli/output.py

@@ -20,8 +20,8 @@ def format_memories_text(console: Console, memories: list[dict], title: str = "m
     console.print(f"\n[{BRAND_COLOR}]Found {count} {title}:[/]\n")
 
     for i, mem in enumerate(memories, 1):
-        memory_text = mem.get("memory", mem.get("text", ""))
-        mem_id = mem.get("id", "")[:8]
+        memory_text = mem.get("memory") or mem.get("text") or ""
+        mem_id = (mem.get("id") or "")[:8]
         score = mem.get("score")
         created = _format_date(mem.get("created_at"))
         category = mem.get("categories", [None])
@@ -67,8 +67,8 @@ def format_memories_table(
     table.add_column("Created", max_width=12)
 
     for mem in memories:
-        mem_id = mem.get("id", "")
-        memory_text = mem.get("memory", mem.get("text", ""))
+        mem_id = mem.get("id") or ""
+        memory_text = mem.get("memory") or mem.get("text") or ""
         if len(memory_text) > 60:
             memory_text = memory_text[:57] + "..."
         categories = mem.get("categories", [])
@@ -104,8 +104,8 @@ def format_single_memory(console: Console, mem: dict, output: str = "text") -> N
         format_json(console, mem)
         return
 
-    memory_text = mem.get("memory", mem.get("text", ""))
-    mem_id = mem.get("id", "")
+    memory_text = mem.get("memory") or mem.get("text") or ""
+    mem_id = mem.get("id") or ""
 
     lines = []
     lines.append(f"  [white bold]{memory_text}[/]")
@@ -229,6 +229,16 @@ def format_json_envelope(
     if error:
         envelope["error"] = error
     envelope["data"] = data
+
+    # If the platform flagged this as an unclaimed Agent Mode account, surface
+    # the notice inside the JSON envelope so an agent consuming the output
+    # sees it without needing to inspect HTTP headers.
+    from mem0_cli.state import take_notice
+
+    notice = take_notice()
+    if notice:
+        envelope["mem0_notice"] = notice
+
     console.print_json(json.dumps(envelope, default=str))
 
 
@@ -323,6 +333,15 @@ def format_agent_envelope(
     if count is not None:
         envelope["count"] = count
     envelope["data"] = sanitize_agent_data(command, data)
+
+    # Surface the unclaimed-Agent-Mode notice (if any) in the envelope so an
+    # agent reading the JSON output sees it without inspecting HTTP headers.
+    from mem0_cli.state import take_notice
+
+    notice = take_notice()
+    if notice:
+        envelope["mem0_notice"] = notice
+
     console.print_json(json.dumps(envelope, default=str))
 
 

cli/python/src/mem0_cli/plugin_sync.py

@@ -0,0 +1,119 @@
+"""Sync the active Mem0 API key into other ecosystem touchpoints.
+
+Why this exists:
+  The CLI canonical state lives in ``~/.mem0/config.json``. But MCP servers
+  (Claude Code plugin, Codex plugin, etc.) read ``MEM0_API_KEY`` from env
+  vars or their own config files. Without a sync, an agent-mode bootstrap
+  mints a new key into config.json but the plugin's MCP keeps using the
+  old key from env — silent surprise.
+
+Design:
+  - Update ONLY entries that already exist (never create new ones)
+  - Preserve all surrounding content / formatting / other keys
+  - Atomic writes (tmpfile + rename) so a crash mid-write doesn't corrupt
+  - Idempotent — re-running with the same key is a no-op
+  - Skip on dry_run
+
+Targets currently handled:
+  - ``~/.claude/settings.json::env::MEM0_API_KEY`` (Claude Code env injection)
+  - ``~/.zshrc`` / ``~/.bashrc`` ``export MEM0_API_KEY="..."`` lines
+
+Out of scope (deliberately not touched):
+  - Codex / Cursor MCP configs — would require schema-aware edits and
+    those tools don't have mem0 entries by default
+  - Plugin's own ``<plugin-dir>/.api_key`` file — plugin-managed
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+# Files we know how to update safely.
+_CLAUDE_SETTINGS = Path.home() / ".claude" / "settings.json"
+_SHELL_RCS = [Path.home() / ".zshrc", Path.home() / ".bashrc", Path.home() / ".bash_profile"]
+
+
+def sync_api_key(api_key: str) -> list[str]:
+    """Propagate ``api_key`` into known ecosystem touchpoints.
+
+    Returns the list of paths actually updated. Empty list means nothing
+    needed updating (either targets didn't exist or already had this value).
+    """
+    if not api_key:
+        return []
+    updated: list[str] = []
+    if _update_claude_settings(_CLAUDE_SETTINGS, api_key):
+        updated.append(str(_CLAUDE_SETTINGS))
+    for rc in _SHELL_RCS:
+        if _update_shell_rc(rc, api_key):
+            updated.append(str(rc))
+    return updated
+
+
+def _update_claude_settings(path: Path, api_key: str) -> bool:
+    """Update ``env.MEM0_API_KEY`` in path. Returns True if file was changed."""
+    if not path.is_file():
+        return False
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return False
+    env = data.get("env")
+    if not isinstance(env, dict) or "MEM0_API_KEY" not in env:
+        # No existing entry — don't create one.
+        return False
+    if env["MEM0_API_KEY"] == api_key:
+        return False  # already in sync
+    env["MEM0_API_KEY"] = api_key
+    _atomic_write_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return True
+
+
+# Match `export MEM0_API_KEY="..."` (or single quotes, or no quotes).
+# Use [ \t]* (not \s*) for trailing whitespace so a trailing newline at
+# end-of-file is preserved when MEM0_API_KEY is the last line.
+_RC_LINE = re.compile(
+    r'^([ \t]*export[ \t]+MEM0_API_KEY[ \t]*=[ \t]*)(["\']?)([^"\'\n]*)(["\']?)[ \t]*$',
+    re.MULTILINE,
+)
+
+
+def _update_shell_rc(path: Path, api_key: str) -> bool:
+    """Update an existing ``export MEM0_API_KEY=...`` line in path."""
+    if not path.is_file():
+        return False
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    match = _RC_LINE.search(text)
+    if not match:
+        return False  # no existing line
+    if match.group(3) == api_key:
+        return False
+    new_text = _RC_LINE.sub(lambda m: f'{m.group(1)}"{api_key}"', text, count=1)
+    _atomic_write_text(path, new_text)
+    return True
+
+
+def _atomic_write_text(path: Path, content: str) -> None:
+    """Write content to path atomically (temp + rename)."""
+    dirname = path.parent
+    fd, tmp_path = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=dirname)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        # Preserve mode if the original existed.
+        if path.exists():
+            os.chmod(tmp_path, path.stat().st_mode & 0o777)
+        os.replace(tmp_path, path)
+    except Exception:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_path)
+        raise

cli/python/src/mem0_cli/state.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 _agent_mode: bool = False
 _current_command: str = ""
+_pending_notice: str = ""
 
 
 def is_agent_mode() -> bool:
@@ -22,3 +23,23 @@ def get_current_command() -> str:
 def set_current_command(name: str) -> None:
     global _current_command
     _current_command = name
+
+
+def capture_notice(notice: str | None) -> None:
+    """Stash a Mem0 backend notice for end-of-command surfacing.
+
+    Called from the platform backend after each response so the notice can
+    be printed once per command (regardless of how many sub-requests fired).
+    Last-write-wins is fine — the message text is identical across requests.
+    """
+    global _pending_notice
+    if notice:
+        _pending_notice = notice
+
+
+def take_notice() -> str:
+    """Return and clear the pending notice."""
+    global _pending_notice
+    msg = _pending_notice
+    _pending_notice = ""
+    return msg

cli/python/src/mem0_cli/telemetry.py

@@ -87,7 +87,6 @@ def capture_event(
     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()
@@ -107,6 +106,9 @@ def capture_event(
             with contextlib.suppress(Exception):
                 save_config(config)
 
+        # M4: every cli.* event carries agent_mode based on the config flag
+        # (unclaimed Agent Mode key). This is the growth-doc property used to
+        # join init → add → search funnels in PostHog.
         payload = {
             "api_key": POSTHOG_API_KEY,
             "distinct_id": distinct_id,
@@ -115,7 +117,7 @@ def capture_event(
                 "source": "CLI",
                 "language": "python",
                 "cli_version": __version__,
-                "agent_mode": is_agent_mode(),
+                "agent_mode": bool(config.platform.agent_mode),
                 "python_version": sys.version,
                 "os": sys.platform,
                 "os_version": platform.version(),
@@ -135,12 +137,19 @@ def capture_event(
             "anon_distinct_id_to_alias": anon_id_to_alias,
         }
 
-        subprocess.Popen(
-            [sys.executable, "-m", "mem0_cli.telemetry_sender", json.dumps(context)],
+        child = subprocess.Popen(
+            [sys.executable, "-m", "mem0_cli.telemetry_sender"],
+            stdin=subprocess.PIPE,
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
             start_new_session=True,
             close_fds=True,
+            text=True,
         )
+        if child.stdin:
+            with contextlib.suppress(Exception):
+                child.stdin.write(json.dumps(context))
+            with contextlib.suppress(Exception):
+                child.stdin.close()
     except Exception:
         pass

cli/python/src/mem0_cli/telemetry_sender.py

@@ -1,6 +1,7 @@
 """Standalone telemetry sender — runs as a detached subprocess.
 
-Usage: python -m mem0_cli.telemetry_sender '<json context>'
+Usage: python -m mem0_cli.telemetry_sender   (JSON context is read from stdin;
+a single argv argument is still accepted as a legacy fallback)
 
 This module is spawned by telemetry.capture_event() and runs independently
 of the parent CLI process. It:
@@ -20,8 +21,18 @@ import sys
 import urllib.request
 
 
+def _load_context() -> dict:
+    """Load telemetry context from stdin, falling back to argv for compatibility."""
+    raw = ""
+    if not sys.stdin.isatty():
+        raw = sys.stdin.read().strip()
+    if not raw and len(sys.argv) > 1:
+        raw = sys.argv[1]
+    return json.loads(raw)
+
+
 def main() -> None:
-    ctx = json.loads(sys.argv[1])
+    ctx = _load_context()
     payload = ctx["payload"]
 
     if ctx.get("needs_email") and ctx.get("mem0_api_key"):

cli/python/tests/test_agent_mode.py

@@ -0,0 +1,160 @@
+"""Parity tests for `mem0 init --agent` (Agent Mode bootstrap).
+
+Mirror of ``cli/node/tests/agent-mode.test.ts`` — both files MUST stay in
+sync so that the Python and Node CLIs expose an identical surface for the
+Agent Mode entrypoint. If you add a flag here, add the same assertion on
+the Node side (and vice versa).
+
+Network-bound bootstrap is covered by the platform-side E2E suite
+(``backend/tests/e2e/test_05_agent_mode.py``); these tests only verify
+the CLI surface that ships in the binary.
+"""
+
+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:
+    return _ANSI_RE.sub("", text)
+
+
+def _run(args: list[str], home_dir: str | None = None) -> subprocess.CompletedProcess:
+    env = os.environ.copy()
+    for key in list(env.keys()):
+        if key.startswith("MEM0_"):
+            del env[key]
+    env.pop("FORCE_COLOR", None)
+    env["PYTHONIOENCODING"] = "utf-8"
+    if home_dir:
+        env["HOME"] = home_dir
+    result = subprocess.run(
+        [sys.executable, "-m", "mem0_cli", *args],
+        capture_output=True,
+        encoding="utf-8",
+        env=env,
+        timeout=15,
+    )
+    return subprocess.CompletedProcess(
+        args=result.args,
+        returncode=result.returncode,
+        stdout=_strip_ansi(result.stdout),
+        stderr=_strip_ansi(result.stderr),
+    )
+
+
+@pytest.fixture
+def clean_home(tmp_path):
+    return str(tmp_path)
+
+
+class TestInitFlagSurface:
+    """`mem0 init --help` must expose the Agent Mode flags."""
+
+    def test_init_help_lists_agent_flag(self):
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        assert "--agent" in result.stdout
+
+    def test_init_help_describes_agent_mode(self):
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        # Description must mention what --agent actually does so an agent
+        # reading the help can self-discover the bootstrap entrypoint.
+        assert "Agent Mode" in result.stdout or "unattended" in result.stdout.lower()
+
+    def test_init_help_lists_source_flag(self):
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        assert "--source" in result.stdout
+
+    def test_init_help_lists_email_and_code(self):
+        # Claim flow flags must remain present alongside Agent Mode flags.
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        assert "--email" in result.stdout
+        assert "--code" in result.stdout
+
+
+class TestArgvPreprocessing:
+    """`--agent` on `init` must reach init_cmd, not be eaten by the global preprocessor.
+
+    Regression for the bug where the top-level `--agent` JSON-alias was
+    stripped from ``sys.argv`` before Typer could bind it to the init
+    subcommand, making ``mem0 init --agent`` indistinguishable from a
+    plain ``mem0 init`` (interactive wizard).
+    """
+
+    def test_init_with_agent_reaches_subcommand(self, clean_home):
+        # We can't hit a real backend in unit tests, so we point the CLI at
+        # a guaranteed-dead URL and assert the failure is the bootstrap
+        # request failing — proving the --agent flag was honored and the
+        # bootstrap branch ran, not the interactive wizard.
+        result = subprocess.run(
+            [sys.executable, "-m", "mem0_cli", "init", "--agent"],
+            capture_output=True,
+            encoding="utf-8",
+            env={
+                **{k: v for k, v in os.environ.items() if not k.startswith("MEM0_")},
+                "HOME": clean_home,
+                "MEM0_BASE_URL": "http://127.0.0.1:1",  # blackhole
+                "FORCE_COLOR": "0",
+                "PYTHONIOENCODING": "utf-8",
+            },
+            timeout=15,
+        )
+        combined = _strip_ansi(result.stdout + result.stderr).lower()
+        # Either we got a connection/network error from the bootstrap POST,
+        # or the CLI surfaced an Agent Mode-specific failure message.
+        assert (
+            "agent" in combined
+            or "connect" in combined
+            or "network" in combined
+            or "fetch" in combined
+            or "bootstrap" in combined
+        ), f"Expected bootstrap attempt, got: {combined!r}"
+
+
+class TestJsonEnvelopeParity:
+    """`mem0 init --agent --json` should produce a JSON envelope on success.
+
+    Without a live backend we can only assert the failure shape: when the
+    backend is unreachable, the CLI must still exit non-zero AND not crash
+    on a Python traceback (which would mean we leaked an exception past
+    the agent-mode handler).
+    """
+
+    def test_init_agent_json_no_traceback_on_network_failure(self, clean_home):
+        result = subprocess.run(
+            [sys.executable, "-m", "mem0_cli", "init", "--agent", "--json"],
+            capture_output=True,
+            encoding="utf-8",
+            env={
+                **{k: v for k, v in os.environ.items() if not k.startswith("MEM0_")},
+                "HOME": clean_home,
+                "MEM0_BASE_URL": "http://127.0.0.1:1",
+                "FORCE_COLOR": "0",
+                "PYTHONIOENCODING": "utf-8",
+            },
+            timeout=15,
+        )
+        combined = _strip_ansi(result.stdout + result.stderr)
+        assert "Traceback (most recent call last)" not in combined
+        assert result.returncode != 0
+
+
+class TestInitInCommandList:
+    """`mem0 --help` must list `init` so agents walking the top-level help
+    can discover the Agent Mode entrypoint without prior knowledge."""
+
+    def test_top_level_help_lists_init(self):
+        result = _run(["--help"])
+        assert result.returncode == 0
+        assert "init" in result.stdout

cli/python/tests/test_cli_integration.py

@@ -49,6 +49,7 @@ def _run(
         if key.startswith("MEM0_"):
             del env[key]
     env.pop("FORCE_COLOR", None)
+    env["PYTHONIOENCODING"] = "utf-8"
     if home_dir:
         env["HOME"] = home_dir
     if env_override:
@@ -56,7 +57,7 @@ def _run(
     result = subprocess.run(
         [sys.executable, "-m", "mem0_cli", *args],
         capture_output=True,
-        text=True,
+        encoding="utf-8",
         env=env,
     )
     return subprocess.CompletedProcess(

cli/python/tests/test_commands.py

@@ -8,8 +8,8 @@ from io import StringIO
 from unittest.mock import patch
 
 import pytest
-from click.exceptions import Exit as ClickExit
 from rich.console import Console
+from typer import Exit as TyperExit
 
 from mem0_cli.commands.config_cmd import (
     cmd_config_get,
@@ -181,7 +181,7 @@ class TestAddCommand:
             patch("mem0_cli.commands.memory.console", console),
             patch("mem0_cli.commands.memory.err_console", err_console),
             patch("mem0_cli.commands.memory._stdin_is_piped", return_value=False),
-            pytest.raises((SystemExit, ClickExit)),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_add(
                 mock_backend,
@@ -206,7 +206,7 @@ class TestAddCommand:
         with (
             patch("mem0_cli.commands.memory.console", console),
             patch("mem0_cli.commands.memory.err_console", err_console),
-            pytest.raises((SystemExit, ClickExit)),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_add(
                 mock_backend,
@@ -764,7 +764,7 @@ class TestImportCommand:
         with (
             patch("mem0_cli.commands.utils.console", console),
             patch("mem0_cli.commands.utils.err_console", err_console),
-            pytest.raises((SystemExit, ClickExit)),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_import(mock_backend, "/nonexistent/file.json", user_id=None, agent_id=None)
 
@@ -801,7 +801,7 @@ class TestEntitiesListCommand:
         with (
             patch("mem0_cli.commands.entities.console", console),
             patch("mem0_cli.commands.entities.err_console", err_console),
-            pytest.raises((SystemExit, ClickExit)),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_entities_list(mock_backend, "invalid", output="table")
 
@@ -944,7 +944,7 @@ class TestEntitiesDeleteCommand:
         with (
             patch("mem0_cli.commands.entities.console", console),
             patch("mem0_cli.commands.entities.err_console", err_console),
-            pytest.raises((SystemExit, ClickExit)),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_entities_delete(
                 mock_backend,
@@ -1308,7 +1308,7 @@ class TestAgentMode:
             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)),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_get(mock_backend, "bad-id", output="text")
 

cli/python/tests/test_config.py

@@ -67,7 +67,8 @@ class TestConfig:
         from mem0_cli.config import CONFIG_FILE
 
         mode = os.stat(CONFIG_FILE).st_mode & 0o777
-        assert mode == 0o600
+        if os.name != "nt":
+            assert mode == 0o600
 
     def test_defaults_save_and_load(self, isolate_config):
         config = Mem0Config()
@@ -138,6 +139,11 @@ class TestNestedAccess:
         assert set_nested_value(config, "platform.api_key", "new-key")
         assert config.platform.api_key == "new-key"
 
+    def test_set_int_value_rejects_invalid_input(self):
+        config = Mem0Config()
+        assert set_nested_value(config, "version", "abc") is False
+        assert config.version == 1
+
     def test_set_nonexistent_key(self):
         config = Mem0Config()
         assert set_nested_value(config, "nonexistent.key", "val") is False

cli/python/tests/test_init_internals.py

@@ -0,0 +1,206 @@
+"""Unit tests for init internals — decision tree primitives + plugin sync.
+
+These tests exercise the units that the high-level subprocess parity tests in
+``test_agent_mode.py`` deliberately can't reach:
+
+  - ``_ping_key`` must NOT treat network errors as "invalid key" (else a VPN
+    flap silently mints a new shadow over a working key).
+  - ``plugin_sync`` must only update entries that already exist, preserve
+    trailing newlines, and never mangle other lines.
+  - The 403→ratelimit translation in ``bootstrap_via_backend`` surfaces the
+    real cause instead of DRF's opaque "You do not have permission" string.
+
+Mirror surface lives in ``cli/node/tests/agent-mode.test.ts``; if you add a
+behavioral assertion here, mirror it on the Node side and vice versa.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import httpx
+import pytest
+
+from mem0_cli.commands.init_cmd import _ping_key
+from mem0_cli.plugin_sync import _update_claude_settings, _update_shell_rc
+
+# ── _ping_key ──────────────────────────────────────────────────────────────
+
+
+class _Resp:
+    def __init__(self, status_code: int) -> None:
+        self.status_code = status_code
+
+
+def test_ping_key_200_is_valid(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(httpx, "get", lambda *a, **kw: _Resp(200))
+    assert _ping_key("k", "http://x") is True
+
+
+def test_ping_key_401_is_invalid(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(httpx, "get", lambda *a, **kw: _Resp(401))
+    assert _ping_key("k", "http://x") is False
+
+
+def test_ping_key_403_is_invalid(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(httpx, "get", lambda *a, **kw: _Resp(403))
+    assert _ping_key("k", "http://x") is False
+
+
+def test_ping_key_5xx_is_not_definitively_invalid(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Transient upstream failure must NOT cause a shadow to be minted.
+    monkeypatch.setattr(httpx, "get", lambda *a, **kw: _Resp(503))
+    assert _ping_key("k", "http://x") is True
+
+
+def test_ping_key_connect_error_prefers_reuse(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Network blip (DNS, captive portal, etc.) — must NOT trigger a re-mint.
+    def boom(*a, **kw):
+        raise httpx.ConnectError("nope")
+
+    monkeypatch.setattr(httpx, "get", boom)
+    assert _ping_key("k", "http://x") is True
+
+
+def test_ping_key_timeout_prefers_reuse(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(*a, **kw):
+        raise httpx.ReadTimeout("slow")
+
+    monkeypatch.setattr(httpx, "get", boom)
+    assert _ping_key("k", "http://x") is True
+
+
+# ── plugin_sync._update_shell_rc ──────────────────────────────────────────
+
+
+def test_shell_rc_updates_existing_export_preserves_trailing_newline(tmp_path) -> None:
+    rc = tmp_path / ".zshrc"
+    rc.write_text('export MEM0_API_KEY="old"\n', encoding="utf-8")
+    changed = _update_shell_rc(rc, "newkey")
+    assert changed is True
+    assert rc.read_text(encoding="utf-8") == 'export MEM0_API_KEY="newkey"\n'
+
+
+def test_shell_rc_does_not_create_new_export(tmp_path) -> None:
+    rc = tmp_path / ".zshrc"
+    rc.write_text("alias ll='ls -la'\n", encoding="utf-8")
+    changed = _update_shell_rc(rc, "newkey")
+    assert changed is False
+    assert rc.read_text(encoding="utf-8") == "alias ll='ls -la'\n"
+
+
+def test_shell_rc_preserves_surrounding_content(tmp_path) -> None:
+    rc = tmp_path / ".zshrc"
+    original = "# my zshrc\nalias ll='ls -la'\nexport MEM0_API_KEY='old'\nexport OTHER=keepme\n"
+    rc.write_text(original, encoding="utf-8")
+    _update_shell_rc(rc, "newkey")
+    after = rc.read_text(encoding="utf-8")
+    assert "alias ll='ls -la'\n" in after
+    assert "export OTHER=keepme\n" in after
+    assert "# my zshrc\n" in after
+    assert 'export MEM0_API_KEY="newkey"\n' in after
+
+
+def test_shell_rc_idempotent_when_already_matching(tmp_path) -> None:
+    rc = tmp_path / ".zshrc"
+    rc.write_text('export MEM0_API_KEY="same"\n', encoding="utf-8")
+    assert _update_shell_rc(rc, "same") is False
+
+
+def test_shell_rc_missing_file_is_noop(tmp_path) -> None:
+    rc = tmp_path / ".zshrc"  # does not exist
+    assert _update_shell_rc(rc, "x") is False
+
+
+# ── plugin_sync._update_claude_settings ────────────────────────────────────
+
+
+def test_claude_settings_does_not_create_env_block(tmp_path) -> None:
+    import json
+
+    settings = tmp_path / "settings.json"
+    settings.write_text(json.dumps({"otherKey": 1}), encoding="utf-8")
+    changed = _update_claude_settings(settings, "newkey")
+    assert changed is False
+    # Original content unchanged.
+    assert json.loads(settings.read_text(encoding="utf-8")) == {"otherKey": 1}
+
+
+def test_claude_settings_does_not_create_mem0_entry_in_existing_env(tmp_path) -> None:
+    import json
+
+    settings = tmp_path / "settings.json"
+    settings.write_text(json.dumps({"env": {"OTHER_KEY": "x"}}), encoding="utf-8")
+    changed = _update_claude_settings(settings, "newkey")
+    assert changed is False
+
+
+def test_claude_settings_updates_existing_entry(tmp_path) -> None:
+    import json
+
+    settings = tmp_path / "settings.json"
+    settings.write_text(
+        json.dumps({"env": {"MEM0_API_KEY": "old", "OTHER": "y"}}, indent=2),
+        encoding="utf-8",
+    )
+    changed = _update_claude_settings(settings, "fresh")
+    assert changed is True
+    data = json.loads(settings.read_text(encoding="utf-8"))
+    assert data["env"]["MEM0_API_KEY"] == "fresh"
+    assert data["env"]["OTHER"] == "y"  # other keys preserved
+
+
+def test_claude_settings_idempotent(tmp_path) -> None:
+    import json
+
+    settings = tmp_path / "settings.json"
+    settings.write_text(json.dumps({"env": {"MEM0_API_KEY": "same"}}), encoding="utf-8")
+    assert _update_claude_settings(settings, "same") is False
+
+
+def test_claude_settings_malformed_json_is_noop(tmp_path) -> None:
+    settings = tmp_path / "settings.json"
+    settings.write_text("{ this is not json", encoding="utf-8")
+    assert _update_claude_settings(settings, "x") is False
+
+
+# ── bootstrap rate-limit translation ──────────────────────────────────────
+
+
+def test_bootstrap_403_permission_surfaces_ratelimit(monkeypatch, capsys) -> None:
+    """DRF 403 'You do not have permission' must be translated to the daily limit message."""
+    from mem0_cli.commands.agent_mode_cmd import bootstrap_via_backend
+    from mem0_cli.config import Mem0Config
+
+    fake_resp = MagicMock()
+    fake_resp.status_code = 403
+    fake_resp.text = '{"detail": "You do not have permission to perform this action."}'
+    fake_resp.json = MagicMock(
+        return_value={"detail": "You do not have permission to perform this action."}
+    )
+
+    class _Client:
+        def __init__(self, *a, **kw):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def post(self, *a, **kw):
+            return fake_resp
+
+    monkeypatch.setattr(httpx, "Client", _Client)
+    cfg = Mem0Config()
+    cfg.platform.base_url = "https://api.mem0.ai"
+    import typer
+
+    with pytest.raises(typer.Exit):
+        bootstrap_via_backend(cfg)
+
+    captured = capsys.readouterr()
+    combined = captured.out + captured.err
+    assert "Daily Agent Mode signup limit reached" in combined
+    assert "permission to perform this action" not in combined

cli/python/tests/test_output.py

@@ -54,6 +54,11 @@ class TestTextFormat:
         output = buf.getvalue()
         assert "Found 0" in output
 
+    def test_format_memories_text_handles_null_fields(self):
+        console, buf = _make_console()
+        format_memories_text(console, [{"id": None, "memory": None, "created_at": None}])
+        assert "Found 1 memories" in buf.getvalue()
+
 
 class TestTableFormat:
     def test_format_memories_table(self):
@@ -70,6 +75,13 @@ class TestTableFormat:
         # Should still render (empty table)
         assert "ID" in output
 
+    def test_format_memories_table_handles_null_fields(self):
+        console, buf = _make_console()
+        format_memories_table(console, [{"id": None, "memory": None, "created_at": None}])
+        output = buf.getvalue()
+        assert "ID" in output
+        assert "Memory" in output
+
 
 class TestSingleMemory:
     def test_format_single_memory_text(self):
@@ -87,6 +99,17 @@ class TestSingleMemory:
         output = buf.getvalue()
         assert '"memory"' in output
 
+    def test_format_single_memory_handles_null_fields(self):
+        console, buf = _make_console()
+        format_single_memory(
+            console,
+            {"id": None, "memory": None, "text": "Fallback memory", "created_at": None},
+            "text",
+        )
+        output = buf.getvalue()
+        assert "Fallback memory" in output
+        assert "ID:" not in output
+
 
 class TestAddResult:
     def test_format_add_result_text(self):

cli/python/tests/test_platform_backend.py

@@ -0,0 +1,46 @@
+"""Tests for the Platform backend (mem0 Platform API client)."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from mem0_cli.backend.platform import PlatformBackend
+from mem0_cli.config import PlatformConfig
+
+
+def _make_backend() -> PlatformBackend:
+    # api_key/base_url are only used to build the httpx client; every test here
+    # patches _request, so no real network calls are made.
+    return PlatformBackend(PlatformConfig(api_key="test-key", base_url="https://api.mem0.ai"))
+
+
+class TestDeleteEntities:
+    def test_multiple_entities_returns_all_results(self):
+        backend = _make_backend()
+        responses = {
+            "/v2/entities/user/alice/": {"message": "user deleted"},
+            "/v2/entities/agent/bob/": {"message": "agent deleted"},
+        }
+        with patch.object(backend, "_request") as mock_request:
+            mock_request.side_effect = lambda method, path, **kw: responses[path]
+            result = backend.delete_entities(user_id="alice", agent_id="bob")
+
+        # Regression: previously only the last entity's response survived.
+        assert result == {
+            "user": {"message": "user deleted"},
+            "agent": {"message": "agent deleted"},
+        }
+        assert mock_request.call_count == 2
+
+    def test_single_entity_keyed_by_type(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value={"message": "user deleted"}):
+            result = backend.delete_entities(user_id="alice")
+        assert result == {"user": {"message": "user deleted"}}
+
+    def test_no_entities_raises(self):
+        backend = _make_backend()
+        import pytest
+
+        with pytest.raises(ValueError):
+            backend.delete_entities()

cli/python/tests/test_platform_backend_paths.py

@@ -0,0 +1,43 @@
+from unittest.mock import MagicMock
+
+from mem0_cli.backend.platform import PlatformBackend
+
+
+def _backend(sample_config):
+    backend = PlatformBackend(sample_config.platform)
+    backend._client = MagicMock()
+    backend._client.request.return_value = MagicMock(
+        status_code=200,
+        json=lambda: {"message": "ok"},
+        headers={},
+        raise_for_status=lambda: None,
+    )
+    return backend
+
+
+def test_memory_id_path_segments_are_encoded(sample_config):
+    backend = _backend(sample_config)
+
+    backend.get("mem/a?b#c")
+    backend.update("mem/a?b#c", content="updated")
+    backend.delete("mem/a?b#c")
+
+    paths = [call.args[1] for call in backend._client.request.call_args_list]
+    assert paths == [
+        "/v1/memories/mem%2Fa%3Fb%23c/",
+        "/v1/memories/mem%2Fa%3Fb%23c/",
+        "/v1/memories/mem%2Fa%3Fb%23c/",
+    ]
+
+
+def test_entity_and_event_path_segments_are_encoded(sample_config):
+    backend = _backend(sample_config)
+
+    backend.delete_entities(user_id="org/team?active#frag")
+    backend.get_event("evt/a?b#c")
+
+    paths = [call.args[1] for call in backend._client.request.call_args_list]
+    assert paths == [
+        "/v2/entities/user/org%2Fteam%3Factive%23frag/",
+        "/v1/event/evt%2Fa%3Fb%23c/",
+    ]

cli/python/tests/test_telemetry.py

@@ -0,0 +1,80 @@
+"""Tests for telemetry subprocess secret handling."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import sys
+
+from mem0_cli.config import Mem0Config, save_config
+from mem0_cli.telemetry import capture_event
+from mem0_cli.telemetry_sender import _load_context
+
+
+class _CaptureStdin:
+    def __init__(self):
+        self.buffer = ""
+        self.closed = False
+
+    def write(self, value: str) -> None:
+        self.buffer += value
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class _DummyProcess:
+    def __init__(self):
+        self.stdin = _CaptureStdin()
+
+
+def test_capture_event_writes_context_to_stdin_not_argv(isolate_config, monkeypatch):
+    config = Mem0Config()
+    config.platform.api_key = "m0-test-secret"
+    config.telemetry.anonymous_id = "cli-anon-test"
+    save_config(config)
+
+    captured: dict[str, object] = {}
+    proc = _DummyProcess()
+
+    def fake_popen(args, **kwargs):
+        captured["args"] = args
+        captured["kwargs"] = kwargs
+        return proc
+
+    monkeypatch.setattr("mem0_cli.telemetry.subprocess.Popen", fake_popen)
+
+    capture_event("unit_test_event", {"case": "stdin-secret"})
+
+    argv = captured["args"]
+    assert argv == [sys.executable, "-m", "mem0_cli.telemetry_sender"]
+    assert all("m0-test-secret" not in arg for arg in argv)
+
+    kwargs = captured["kwargs"]
+    assert kwargs["stdin"] == subprocess.PIPE
+    assert kwargs["text"] is True
+
+    ctx = json.loads(proc.stdin.buffer)
+    assert ctx["mem0_api_key"] == "m0-test-secret"
+    assert ctx["payload"]["event"] == "unit_test_event"
+
+    assert proc.stdin.closed
+
+
+def test_load_context_reads_from_stdin(monkeypatch):
+    monkeypatch.setattr("sys.argv", ["telemetry_sender"])
+    monkeypatch.setattr("sys.stdin", io.StringIO('{"payload": {"event": "stdin"}}'))
+
+    ctx = _load_context()
+
+    assert ctx["payload"]["event"] == "stdin"
+
+
+def test_load_context_falls_back_to_argv(monkeypatch):
+    monkeypatch.setattr("sys.argv", ["telemetry_sender", '{"payload": {"event": "argv"}}'])
+    monkeypatch.setattr("sys.stdin", io.StringIO(""))
+
+    ctx = _load_context()
+
+    assert ctx["payload"]["event"] == "argv"

docs/README.md

@@ -24,7 +24,7 @@ mintlify dev
 
 ### Publishing Changes
 
-Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard. 
+Install our GitHub App to auto-propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard. 
 
 #### Troubleshooting
 

docs/_snippets/star-on-github.mdx

@@ -0,0 +1,5 @@
+{/* Subtle, value-anchored nudge to star the repo. Drop in at peak-end "win" moments in the OSS docs (after a successful add/search, a server bootstrap, etc.). Keep it off the Platform/API pages. */}
+{/* Clicks are tracked via PostHog autocapture: the data-ph-capture-attribute-cta below tags each click with cta="star-on-github" so it's filterable as an event property. Metric = count of $autocapture where cta = star-on-github; break down by Current URL to see which win-moment converts. */}
+<Callout icon="star" iconType="solid" color="#FACC15">
+  **Using Mem0?** <a href="https://github.com/mem0ai/mem0" data-ph-capture-attribute-cta="star-on-github">Star us on GitHub</a> to help more developers discover memory for AI apps.
+</Callout>

docs/api-reference.mdx

@@ -97,7 +97,7 @@ Get your API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_so
 
 ## Next Steps
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card title="Add Your First Memory" icon="rocket" href="/api-reference/memory/add-memories">
     Start storing memories via the REST API
   </Card>
@@ -105,4 +105,8 @@ Get your API key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_so
   <Card title="Search with Filters" icon="filter" href="/api-reference/memory/search-memories">
     Learn advanced search and filtering techniques
   </Card>
+
+  <Card title="Build with cookbooks" icon="book-open" href="/cookbooks/overview">
+    See the API used end to end in real projects.
+  </Card>
 </CardGroup>

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

@@ -4,7 +4,7 @@ description: "Add facts, messages, or metadata to a user memory store with async
 openapi: post /v3/memories/add/
 ---
 
-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.
+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
 
@@ -50,6 +50,7 @@ Provide conversation messages for Mem0 to extract memories from. At least one en
 | `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. |
+| `expiration_date` | string | Optional | Date in `YYYY-MM-DD` format. The memory is visible through this date and hidden by default after it passes. |
 
 > \* At least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`) is required.
 
@@ -83,3 +84,11 @@ The request is queued for background processing. The response contains an `event
 <Info>
 Poll the event status via `GET /v1/event/{event_id}/`. Status will be `SUCCEEDED` or `FAILED` once processing completes.
 </Info>
+
+<Info>
+Memories with `expiration_date` remain stored after they expire. Search and get-all hide them by default; pass `show_expired: true` to include them.
+</Info>
+
+<Info>
+Python uses `expiration_date`; TypeScript uses `expirationDate`.
+</Info>

docs/api-reference/memory/create-memory-export.mdx

@@ -4,4 +4,4 @@ description: "Submit an export job to create a structured memory export using a
 openapi: post /v1/exports/
 ---
 
-Submit a job to create a structured export of memories using a customizable Pydantic schema. This process may take some time to complete, especially if you're exporting a large number of memories. You can tailor the export by applying various filters (e.g., `user_id`, `agent_id`, `run_id`, or `session_id`) and by modifying the Pydantic schema to ensure the final data matches your exact needs.
+Submit a job to create a structured export of memories using a customizable Pydantic schema. This process may take some time to complete, especially if you're exporting a large number of memories. You can tailor the export by applying various filters (e.g., `user_id`, `agent_id`, `app_id`, or `run_id`) and by modifying the Pydantic schema to ensure the final data matches your exact needs.

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

@@ -4,7 +4,11 @@ description: "Retrieve memories with paginated results and advanced filtering us
 openapi: post /v3/memories/
 ---
 
-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.
+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.
+
+Expired memories are hidden by default. Pass `show_expired: true` to include memories whose `expiration_date` has passed.
+
+Python uses `show_expired`; TypeScript uses `showExpired`.
 
 The `filters` object supports complex logical operations (AND, OR, NOT) and comparison operators:
 
@@ -32,6 +36,7 @@ memories = client.get_all(
             }
         ]
     },
+    show_expired=False,
     page=1,
     page_size=50
 )
@@ -46,12 +51,14 @@ memories = client.get_all(
         {
             "id": "f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c",
             "memory": "Alex is planning a trip to San Francisco from July 1st to July 10th",
+            "expiration_date": null,
             "created_at": "2024-07-01T12:00:00Z",
             "updated_at": "2024-07-01T12:00:00Z"
         },
         {
             "id": "a2b8c3d4-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
             "memory": "Alex prefers vegetarian restaurants",
+            "expiration_date": null,
             "created_at": "2024-07-05T15:30:00Z",
             "updated_at": "2024-07-05T15:30:00Z"
         }

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

@@ -4,4 +4,4 @@ description: "Retrieve the latest structured memory export after submitting an e
 openapi: post /v1/exports/get
 ---
 
-Retrieve the latest structured memory export after submitting an export job. You can filter the export by `user_id`, `run_id`, `session_id`, or `app_id` to get the most recent export matching your filters.
+Retrieve the latest structured memory export after submitting an export job. You can filter the export by `user_id`, `agent_id`, `app_id`, `run_id`, `created_at`, or `updated_at` to get the most recent export matching your filters.

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

@@ -4,9 +4,13 @@ description: "Search memories with hybrid retrieval (semantic + BM25 + entity ma
 openapi: post /v3/memories/search/
 ---
 
-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.
+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.
+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.
+
+Expired memories are hidden by default. Pass `show_expired: true` to include memories whose `expiration_date` has passed.
+
+Python uses `show_expired`; TypeScript uses `showExpired`.
 
 The `filters` object supports complex logical operations (AND, OR, NOT) and comparison operators:
 - `in`: Matches any of the values specified
@@ -20,16 +24,17 @@ The `filters` object supports complex logical operations (AND, OR, NOT) and comp
 
 ### 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) |
+| Parameter | Default |
+| --- | --- |
+| `top_k` | `10` (range 1–1000) |
+| `threshold` | `0.1` (pass `0.0` to disable) |
+| `rerank` | `false` (pass `true` to enable) |
 
 <CodeGroup>
 ```python Platform API Example
 related_memories = client.search(
     query="What are Alice's hobbies?",
+    show_expired=False,
     filters={
         "OR": [
             {
@@ -54,6 +59,7 @@ related_memories = client.search(
         "category": "hobbies"
       },
       "score": 0.82,
+      "expiration_date": null,
       "created_at": "2024-07-26T10:29:36.630547-07:00",
       "updated_at": null,
       "categories": ["hobbies"]

docs/api-reference/memory/update-memory.mdx

@@ -1,5 +1,14 @@
 ---
 title: 'Update Memory'
-description: "Update the content or metadata of a single memory by its unique ID using the PUT endpoint."
+description: "Update the content, metadata, timestamp, or expiration date of a single memory by its unique ID using the PUT endpoint."
 openapi: put /v1/memories/{memory_id}/
----
+---
+
+Use this endpoint to update mutable memory fields. To make a memory expire, set `expiration_date` to a `YYYY-MM-DD` date. To make it permanent again, send `expiration_date: null`.
+
+```python
+client.update("mem_123", expiration_date="2030-01-31")
+client.update("mem_123", expiration_date=None)
+```
+
+TypeScript uses `expirationDate`.

docs/api-reference/organization/remove-org-member.mdx

@@ -0,0 +1,5 @@
+---
+title: "Remove Organization Member"
+description: "Remove a member from an organization to revoke their access to its projects and resources."
+openapi: "delete /api/v1/orgs/organizations/{org_id}/members/"
+---

docs/api-reference/organization/update-org-member.mdx

@@ -0,0 +1,5 @@
+---
+title: "Update Organization Member"
+description: "Update an existing member's role within an organization to change their permissions and access level."
+openapi: "put /api/v1/orgs/organizations/{org_id}/members/"
+---

docs/api-reference/organizations-projects.mdx

@@ -14,7 +14,7 @@ Organizations and projects are **optional** features. You can use Mem0 without t
 
 ## Key Capabilities
 
-- **Multi-org/project Support**: Specify organization and project when initializing the Mem0 client to attribute API usage appropriately
+- **Multi-org/project Support**: Organization and project are resolved automatically from your API key via `/v1/ping/`: no org or project params are accepted by `MemoryClient.__init__`. Use a project-specific API key to target a particular project.
 - **Member Management**: Control access to data through organization and project membership
 - **Access Control**: Only members can access memories and data within their organization/project scope
 - **Team Isolation**: Maintain data separation between different teams and projects for secure collaboration
@@ -79,7 +79,7 @@ new_project = client.project.create(
 
 ### Update Project Settings
 
-Modify project configuration including custom instructions, categories, graph settings, and language preferences:
+Modify project configuration including custom instructions, categories, language preferences, retrieval criteria, and memory decay:
 
 ```python
 # Update project with custom categories
@@ -98,6 +98,17 @@ client.project.update(
 # Use the input language for memory storage and retrieval
 client.project.update(multilingual=True)
 
+# Set retrieval criteria to control which memories are surfaced in search
+client.project.update(
+    retrieval_criteria=[
+        {"name": "relevance", "description": "How directly relevant this memory is to the current topic or user query", "weight": 3},
+        {"name": "access_frequency", "description": "How often this memory has been accessed or surfaced recently", "weight": 1}
+    ]
+)
+
+# Enable Memory Decay (boosts recently-accessed memories at search time)
+client.project.update(decay=True)
+
 # Update multiple settings at once
 client.project.update(
     custom_instructions="...",
@@ -109,9 +120,37 @@ client.project.update(
 )
 ```
 
+#### Set Retrieval Criteria
+
+`retrieval_criteria` is a per-project list of dictionaries (`List[Dict]`) that shapes how memories are ranked and filtered during search. Each dictionary has three fields: `name` (identifier), `description` (interpreted by the LLM to score each memory), and `weight` (relative influence on the final score). Use this to focus retrieval on intent-aligned or signal-specific memories:
+
+```python
+client.project.update(
+    retrieval_criteria=[
+        {
+            "name": "joy",
+            "description": "Measure the intensity of positive emotions such as happiness, excitement, or amusement expressed in the memory. A higher score reflects greater joy.",
+            "weight": 3
+        },
+        {
+            "name": "curiosity",
+            "description": "Assess the extent to which the memory reflects inquisitiveness or interest in exploring new information. A higher score reflects stronger curiosity.",
+            "weight": 2
+        },
+        {
+            "name": "access_frequency",
+            "description": "How often this memory has been accessed or surfaced recently.",
+            "weight": 1
+        }
+    ]
+)
+```
+
+Pass an empty list to clear all criteria and restore default retrieval behaviour.
+
 #### Toggle Memory Decay
 
-`decay` is a per-project boolean that turns on [Memory Decay](/platform/features/memory-decay) — a search-time ranking bias that reinforces recently-accessed memories and gently dampens stale ones. The flag is `false` by default; set it via the same project-update endpoint:
+`decay` is a per-project boolean that turns on [Memory Decay](/platform/features/memory-decay): a search-time ranking bias that reinforces recently-accessed memories and gently dampens stale ones. The flag is `false` by default; set it via the same project-update endpoint:
 
 ```bash cURL
 curl -X PATCH https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/ \

docs/api-reference/project/remove-project-member.mdx

@@ -0,0 +1,5 @@
+---
+title: "Remove Project Member"
+description: "Remove a member from a project to revoke their access to its memories, configuration, and resources."
+openapi: "delete /api/v1/orgs/organizations/{org_id}/projects/{project_id}/members/"
+---

docs/api-reference/project/update-project-member.mdx

@@ -0,0 +1,5 @@
+---
+title: "Update Project Member"
+description: "Update an existing member's role within a project to change their permissions and access level."
+openapi: "put /api/v1/orgs/organizations/{org_id}/projects/{project_id}/members/"
+---

docs/api-reference/project/update-project.mdx

@@ -0,0 +1,5 @@
+---
+title: "Update Project"
+description: "Update a project's settings, including name, custom instructions, and other configuration options."
+openapi: "patch /api/v1/orgs/organizations/{org_id}/projects/{project_id}/"
+---

docs/changelog/highlights.mdx

@@ -4,16 +4,137 @@ description: "Major product launches, headline features, and milestones for Mem0
 mode: "wide"
 ---
 
+<Update label="2026-07-13" description="TypeScript provider expansion">
+
+**TypeScript OSS SDK: 26 New Providers, Reranking, and Zero-Dependency Imports**
+
+TypeScript SDK v3.1.0 is the largest provider release for the OSS SDK so far, closing most of the remaining gap with the Python SDK. Python SDK v2.0.12 ships alongside it with fixes and security patches.
+
+- **17 new vector stores:** Pinecone, Weaviate, Milvus, Chroma, MongoDB, Elasticsearch, OpenSearch, Databricks, AWS Neptune Analytics, S3 Vectors, Azure MySQL, Google Vertex AI Vector Search, Turbopuffer, Upstash Vector, Valkey, Cassandra, and Baidu Mochow.
+- **5 new LLM providers:** AWS Bedrock, xAI Grok, Together, vLLM, and Sarvam.
+- **4 new embedding providers:** Vertex AI, HuggingFace, FastEmbed, and Together.
+- **Reranking in TypeScript:** Four rerankers (Cohere, ZeroEntropy, cross-encoder, and LLM-based) with per-search rerank via a `rerank` option on `search()`.
+- **Install only what you use:** Importing `mem0ai/oss` no longer pulls in any provider SDK. Provider packages are resolved lazily on first use, so an app that configures only OpenAI and Qdrant does not need the other provider SDKs installed.
+
+See [SDK & Tools](/changelog/sdk) for version details and PR links.
+
+</Update>
+
+<Update label="2026-06-27" description="SDK memory expiration">
+
+**SDK Memory Expiration: Expiring Memories Across Python and TypeScript**
+
+The latest SDK releases add first-class expiration controls to memory writes, updates, and reads, plus new TypeScript provider coverage for production deployments.
+
+- **Python client updates:** `MemoryClient.update()` and `AsyncMemoryClient.update()` now accept `expiration_date`, including `None` to clear an existing expiration.
+- **TypeScript client updates:** `AddMemoryOptions`, `update()`, and `Memory` now support `expirationDate`; `search()` and `getAll()` can include expired memories with `showExpired`.
+- **New TypeScript LLM providers:** `MiniMaxLLM` and `LiteLLM` are now available for OpenAI-compatible MiniMax and LiteLLM proxy deployments.
+- **PGVector deployment flexibility:** TypeScript PGVector config now supports `connectionString` and `ssl`, so apps can use a managed Postgres URI instead of separate connection fields.
+
+See [SDK & Tools](/changelog/sdk) for version details and PR links.
+
+</Update>
+
+<Update label="2026-06-25" description="Mem0 Plugin v0.2.11">
+
+**Mem0 Plugin: Shared Memory for Claude Code, Cursor, Codex, and Antigravity**
+
+The shared Mem0 editor plugin is current through v0.2.11:
+
+- **Automatic context injection:** File reads, bash errors, session resume prompts, and startup timelines can retrieve relevant memories automatically.
+- **Project and global scopes:** Project-scoped memories remain the default, while `global_search` supports team-wide recall across users and app scopes.
+- **Coding categories:** A 17-category coding taxonomy installs in the background and is cached per Mem0 account.
+- **Reliable capture:** Auto-capture, compaction summaries, session summaries, and metadata defaults keep memories scoped and readable.
+- **Editor correctness:** Telemetry now reports Claude Code, Cursor, Codex, and Antigravity separately with each editor's real plugin version.
+
+</Update>
+
+<Update label="2026-06-25" description="Antigravity Plugin v0.1.3">
+
+**Antigravity Plugin: Mem0 for Google Antigravity**
+
+Antigravity support in the shared Mem0 editor plugin family is current through v0.1.3:
+
+- **Self-contained plugin:** Includes its own plugin manifest, MCP config, hooks, shared scripts, and skills.
+- **AGENTS.md convention:** Uses Antigravity's `contextFileName: "AGENTS.md"` convention.
+- **Lifecycle hooks:** Wires session start, prompt recall, file-read context, memory-tool metadata enforcement, bash-error lookup, post-tool tracking, and stop summaries.
+- **Shared memory layer:** Reuses the Mem0 Platform MCP tools and the shared 16-skill command bundle.
+- **Better automatic recall:** v0.1.3 adds reranked injected context and clean `files_touched` metadata in session summaries.
+- **Telemetry correctness:** v0.1.2 reports Antigravity as `antigravity` with the plugin's own version.
+
+</Update>
+
+<Update label="2026-06-22" description="OpenCode Plugin v0.2.0">
+
+**OpenCode Plugin: Native SDK Memory Tools for OpenCode**
+
+`@mem0/opencode-plugin` adds memory to OpenCode and is current through v0.2.0:
+
+- **Native SDK tools:** Memory tools register through `@opencode-ai/plugin` and call the `mem0ai` SDK directly, so the plugin no longer depends on `mcp.mem0.ai`.
+- **Memory scopes:** Operations support `project`, `session`, and `global` scope, with `/mem0-scope` to change the default.
+- **Automatic context:** File-context injection, structured compaction summaries, and a recent-activity timeline surface relevant memories without manual recall.
+- **Auto-dream consolidation:** Gated consolidation merges duplicates, drops stale or sensitive entries, and rewrites vague memories.
+- **Skills load in place:** The `config` hook adds bundled skills to `skills.paths` instead of copying them into user config directories.
+- **Safety controls:** Blocks `MEMORY.md` writes and redacts secrets before storing memories.
+
+</Update>
+
+<Update label="2026-06-12" description="Pi Agent Plugin v0.1.2">
+
+**Pi Agent Plugin: Persistent Memory for Pi Agent**
+
+`@mem0/pi-agent-plugin` adds semantic memory to Pi Agent and has been updated through v0.1.2:
+
+- **Agent memory tool:** Registers `mem0_memory` for scoped search, add, get, delete, and delete-all operations.
+- **Slash commands:** Adds `/mem0-remember`, `/mem0-search`, `/mem0-forget`, `/mem0-tour`, `/mem0-dream`, `/mem0-pin`, `/mem0-scope`, and `/mem0-status`.
+- **Auto-capture:** Stores user and assistant memories after agent turns.
+- **Dream consolidation:** Merges duplicates, resolves contradictions, and prunes stale memories behind session, time, and memory-count gates.
+- **Project scoping:** Uses git-root detection for stable `app_id` values across monorepos.
+- **Relevant command results:** v0.1.2 adds visible command feedback and thresholded, reranked search for search, forget, and pin commands.
+
+</Update>
+
+<Update label="2026-06-12" description="OpenClaw v1.0.13">
+
+**OpenClaw Plugin: Current Memory Backend for OpenClaw**
+
+`@mem0/openclaw-mem0` is current through v1.0.13, with the original production-ready memory backend plus newer setup, security, and runtime work:
+
+- **Skills-based memory architecture:** Triage, recall, and dream skills handle extraction, recall, consolidation, and tool guidance.
+- **Chat and CLI setup:** Supports chat-based platform setup, `openclaw mem0 init`, direct API keys, email OTP, autonomous agent setup, and OSS onboarding.
+- **Platform and OSS modes:** Works with Mem0 Platform or self-hosted OSS providers including OpenAI, Anthropic, Ollama, Qdrant, and PGVector.
+- **Agent-friendly CLI:** All 16 CLI commands support `--json` for machine-driven setup and diagnostics.
+- **Runtime integration:** Exposes OpenClaw memory capability APIs for search manager and backend config status.
+- **Security and compliance:** Added path containment checks, sensitive config metadata, dependency overrides, telemetry hashing, and metadata-only registration safety.
+
+</Update>
+
+<Update label="2026-06-10" description="Vercel AI SDK Provider v3.0.0">
+
+**Vercel AI SDK Provider: Memory-Augmented Generation for AI SDK v6**
+
+The Vercel AI SDK provider moved to the v6 provider contract and Mem0 v3 APIs:
+
+- **AI SDK v6 support:** Migrated to `LanguageModelV3` / `ProviderV3`, including v3 stream lifecycle events and content arrays.
+- **Mem0 v3 API support:** Memory writes and searches now use `/v3/memories/add/` and `/v3/memories/search/`.
+- **Mem0 sources in responses:** `generateText` and `streamText` responses include memories as sources with `providerMetadata.mem0.memories`.
+- **Safer prompt handling:** Prompts are cloned before memory injection, avoiding caller-side mutation.
+- **Async storage fix:** `addMemories` is awaited so generated memories are not silently dropped.
+- **Raw memory utilities:** Exports `searchMemories`, `retrieveMemories`, `getMemories`, and `addMemories` for apps that need direct memory control.
+- **Deployment controls:** Per-request `mem0ApiKey` and `host` support Mem0 Platform, custom API keys, and self-hosted API endpoints.
+
+</Update>
+
 <Update label="2026-05-13" description="Temporal Reasoning for Mem0 Platform v3">
 
-**Temporal Reasoning — Time-Aware Retrieval for Platform v3**
+**Temporal Reasoning: Time-Aware Retrieval for Platform v3**
 
 Mem0 Platform v3 can now interpret time-aware memories and queries so assistants retrieve the right information for questions about the past, upcoming plans, and current state.
 
-- **Time-aware search intent** — Queries like `last week`, `upcoming`, `right now`, and `as of March 2025` return contextually appropriate results automatically
-- **Enabled by default** — No per-request toggle required for v3 writes or searches
-- **Anchored relative queries** — `reference_date` anchors relative search phrases for tests, backfills, and reproducible demos
-- **Normal response shape** — Temporal reasoning affects ranking while preserving existing client response patterns
+- **Search intent parsing:** Queries like `last week`, `upcoming`, `right now`, and `as of March 2025` now resolve against memory timestamps automatically.
+- **Default v3 behavior:** No per-request toggle is needed for v3 writes or searches.
+- **Deterministic testing:** Pass `reference_date` to anchor relative phrases in tests, backfills, and demos.
+- **Stable API shape:** Temporal reasoning changes ranking, not the client response contract.
 
 See [Temporal Reasoning](/platform/features/temporal-reasoning) for usage details.
 
@@ -21,11 +142,11 @@ See [Temporal Reasoning](/platform/features/temporal-reasoning) for usage detail
 
 <Update label="2026-05-08" description="Memory Decay">
 
-**Memory Decay — Recently-Used Memories Surface Higher, Automatically**
+**Memory Decay: Recently-Used Memories Surface Higher**
 
 Per-project search-time ranking bias that boosts recently-touched memories and gently dampens stale ones. Off by default; opt in per project via the `decay` field on the project endpoint, or via `client.project.update(decay=True)` in the SDKs (Python `v2.0.2` / TypeScript `v3.0.3`).
 
-- **Soft bias, never a filter.** The scaling factor stays in `0.3×–1.5×`. Decay can reorder candidates but never zeros them out — anything that surfaced before decay can still surface after.
+- **Soft bias, never a filter.** The scaling factor stays in `0.3×–1.5×`. Decay can reorder candidates but never removes them; anything that surfaced before decay can still surface after.
 - **Reinforcement loop.** Every memory returned in a search has its access history updated, so frequently-used facts naturally float to the top over time.
 - **Public score still clamped to `[0, 1]`.** Existing API contract preserved; no client-side changes needed.
 - **v3 search only**, fully reversible. See [Memory Decay docs](/platform/features/memory-decay).
@@ -34,76 +155,48 @@ Per-project search-time ranking bias that boosts recently-touched memories and g
 
 <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**
+**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
+- **LoCoMo:** 71.4 → **91.6** (+20) for multi-turn conversation recall.
+- **LongMemEval:** 67.8 → **93.4** (+26) for long-term memory across sessions.
+- **BEAM (1M tokens):** **64.1** on production-scale memory evaluation.
+- **Agent memories:** Assistant recall moves from 46% to **100%**.
+- **Temporal reasoning:** "Where did I live before SF?" improves from 51% to **93%**.
+- **Lower token use:** Retrieval stays under 7K tokens versus 25K+ for full-context approaches.
+- **ADD-only extraction:** Memories accumulate; nothing is overwritten or deleted.
+- **Hybrid retrieval:** Semantic search, BM25 keyword search, and entity boost are scored in parallel.
+- **Graph memory (built-in)**: entities extracted, embedded, and linked across memories, with no external graph store required
 
-Breaking changes: Graph memory removed from OSS, `search()` defaults changed, deprecated params removed. See [migration guide](/migration/oss-v2-to-v3).
+Breaking changes: external graph stores removed from OSS (replaced by built-in graph memory), `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**
+**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:
+AI coding agents in Claude Code, Cursor, and Codex can now access Mem0 knowledge directly in their workflow without leaving the editor. 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
+- **mem0 Core Skill:** 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**
+**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
+- **Full command suite:** `add`, `search`, `list`, `get`, `update`, `delete`, `import`, `config`, `init`, `status`, `entity`, `event`.
+- **Interactive setup:** `mem0 init` supports email verification and direct API key entry.
+- **Runtime coverage:** Works with Mem0 Platform and self-hosted OSS modes.
+- **Automation support:** Use `--json` for CI/CD pipelines and agent workflows.
+- **Dual implementation:** Same commands and behavior across Python and Node.js.
 
 </Update>
 
@@ -113,11 +206,11 @@ Launched a unified Mem0 plugin across three major AI development environments
 
 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
+- **Apache AGE:** New graph store support, bringing the total to 4 graph store backends (Neo4j, Memgraph, Kuzu, Apache AGE). **Note:** All external graph store backends (Neo4j, Memgraph, Kuzu, Apache AGE) were subsequently removed in v2.0.0 (2026-04-14). Graph memory is now built-in entity linking with no external graph store required; see the [v2.0.0 entry above](#mem0-sdk-v2-0-0-v3-0-0).
+- **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>
 
@@ -125,6 +218,6 @@ Major expansion of the provider ecosystem:
 
 **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.
+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

@@ -1,303 +0,0 @@
----
-title: "OpenClaw"
-description: "Release notes for the OpenClaw plugin and agent harness."
-mode: "wide"
----
-
-<Update label="2026-04-29" description="v1.0.11">
-
-**New Features:**
-- **Skills-mode auto-setup:** `enableSkillsConfig()` now runs automatically after onboarding — enables triage, recall (with reranking + keyword search), and dream consolidation with `tools.profile = "full"` and disables the built-in session-memory hook to avoid conflicts
-- **Memory runtime capability:** Plugin now exposes `runtime.getMemorySearchManager()` and `resolveMemoryBackendConfig()` on the registered memory capability, enabling OpenClaw gateway to query memory status and backend config directly
-- **Dimension-aware collections:** OSS wizard detects embedder dimension changes and creates a new collection (`mem0_<dims>d`) automatically, with a warning about old memories being inaccessible under the new embedder
-- **Tool documentation in skills:** Both `memory-triage` and `memory-dream` SKILL.md files now include full tool reference sections listing all available tools with parameters
-
-**Improvements:**
-- **Auto-capture and auto-recall default to enabled:** `autoCapture` and `autoRecall` now default to `true` (was `false`). Manifest descriptions updated accordingly. Ignored in skills mode
-- **`memory_update` over delete+add:** Skills now prefer `memory_update` for in-place edits — atomic and preserves edit history. Consolidation pattern updated: update best memory, delete redundant ones
-- **Search threshold lowered:** Default `searchThreshold` reduced from `0.5` to `0.1` for broader recall. Removed hardcoded `0.6` recall-specific override — all searches now use the configured threshold
-- **Embedder dimension propagation:** Vector store config auto-resolves dimensions from embedder config when not explicitly set. Syncs `dimension` and `embeddingModelDims` fields for Qdrant/PGVector compatibility
-- **Config file write safety:** `writeFullConfig()` now re-reads and deep-merges the `plugins` section before writing, preserving `installs` and `slots` written by the OpenClaw gateway
-- **Additional embedder models:** Added `mxbai-embed-large` (1024), `all-minilm` (384), and `snowflake-arctic-embed` (1024) to known embedder dimensions
-
-**Security:**
-- Bumped `protobufjs` to `>=7.5.5` via pnpm overrides (GHSA-xq3m-2v4x-88gg) ([#5012](https://github.com/mem0ai/mem0/pull/5012))
-
-**Fixes:**
-- Moved `bootstrapTelemetryFlag()` and removed `ensureInstallRecord()` from module-level side effects — both now run inside `register()` to avoid crashes when loaded outside OpenClaw gateway
-- Fixed OSS history DB path resolution: absolute paths no longer passed through `resolvePath()`, preventing double-prefix bugs
-- Manifest `providerAuthEnvVars` replaced with spec-compliant `setup.providers` format using `id` + `envVars`
-
-**Dependencies:**
-- Bumped `mem0ai` from `3.0.1` to `3.0.2`
-- Bumped `pluginApi` and `minGatewayVersion` compat to `>=2026.4.24`
-
-</Update>
-
-<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

@@ -1,6 +1,6 @@
 ---
 title: "Platform"
-description: "Release notes for the Mem0 hosted platform — backend, dashboard, billing, and infrastructure changes."
+description: "Release notes for the Mem0 hosted platform: backend, dashboard, billing, and infrastructure changes."
 mode: "wide"
 ---
 
@@ -25,7 +25,7 @@ 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
+- **UI:** Removed the legacy external-graph-store visualization tab, page, and its references from dashboard, sidebar, project settings, playground, and billing
 
 </Update>