test: add score normalization integration tests for vector stores

Level 1 tests validate each vector store's search() returns similarity
scores (higher = better) with correct ordering using known vectors.
Level 2 tests validate the full Memory.add() + Memory.search(threshold=...)
pipeline end-to-end. Both levels are standalone scripts run via CLI args
(e.g., `python test_score_normalization.py faiss`), not collected by pytest.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "mem0-plugins",
+  "owner": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "metadata": {
+    "description": "Official Mem0 plugins for Claude"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": "./mem0-plugin",
+      "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
+      "version": "0.1.0"
+    }
+  ]
+}

.cursor-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "mem0-plugins",
+  "owner": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "metadata": {
+    "description": "Official Mem0 plugins for Cursor"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": "./mem0-plugin",
+      "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
+      "version": "0.1.0"
+    }
+  ]
+}

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,41 +1,55 @@
-name: 🐛 Bug Report
-description: Create a report to help us reproduce and fix the bug
+name: Bug Report
+description: Report a bug in mem0
+labels: ["bug"]
 
 body:
-- type: markdown
-  attributes:
-    value: >
-      #### Before submitting a bug, please make sure the issue hasn't been already addressed by searching through [the existing and past issues](https://github.com/embedchain/embedchain/issues?q=is%3Aissue+sort%3Acreated-desc+).
-- type: textarea
-  attributes:
-    label: 🐛 Describe the bug
-    description: |
-      Please provide a clear and concise description of what the bug is.
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of mem0 is affected?
+      options:
+        - Core / Python SDK
+        - TypeScript SDK
+        - Vector Store (Qdrant, PGVector, Redis, Chroma, etc.)
+        - Graph Memory (Neo4j, Memgraph, etc.)
+        - Ollama / Local Models
+        - OpenClaw
+        - REST API
+        - Other
+    validations:
+      required: true
 
-      If relevant, add a minimal example so that we can reproduce the error by running the code. It is very important for the snippet to be as succinct (minimal) as possible, so please take time to trim down any irrelevant code to help us debug efficiently. We are going to copy-paste your code and we expect to get the same result as you did: avoid any external data, and include the relevant imports, etc. For example:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      value: |
+        ### Summary
 
-      ```python
-      # All necessary imports at the beginning
-      import embedchain as ec
-      # Your code goes here
+        A clear summary of the bug.
 
+        ### Steps to Reproduce
 
-      ```
+        ```python
+        from mem0 import Memory
 
-      Please also paste or describe the results you observe instead of the expected results. If you observe an error, please paste the error message including the **full** traceback of the exception. It may be relevant to wrap error messages in ```` ```triple quotes blocks``` ````.
-    placeholder: |
-      A clear and concise description of what the bug is.
+        m = Memory()
+        # Your code here...
+        ```
 
-      ```python
-      Sample code to reproduce the problem
-      ```
+        ### Expected Behavior
 
-      ```
-      The error message you got, with the full traceback.
-      ````
-  validations:
-    required: true
-- type: markdown
-  attributes:
-    value: >
-      Thanks for contributing 🎉!
+        What you expected to happen.
+
+        ### Actual Behavior
+
+        What actually happened. Paste the full error traceback if applicable.
+
+        ### Environment
+
+        - mem0 version:
+        - Python/Node version:
+        - OS:
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
 blank_issues_enabled: true
 contact_links:
-  - name: 1-on-1 Session
-    url: https://cal.com/taranjeetio/ec
-    about: Speak directly with Taranjeet, the founder, to discuss issues, share feedback, or explore improvements for Embedchain
-  - name: Discord
+  - name: Discord Community
     url: https://discord.gg/6PzXDgEjG5
-    about: General community discussions
+    about: Ask questions and discuss with the community
+  - name: Documentation
+    url: https://docs.mem0.ai
+    about: Read the official mem0 documentation

.github/ISSUE_TEMPLATE/documentation_issue.yml

@@ -1,11 +1,23 @@
-name: Documentation
-description: Report an issue related to the Embedchain docs.
-title: "DOC: <Please write a comprehensive title after the 'DOC: ' prefix>"
+name: Documentation Issue
+description: Report an issue or suggest an improvement to the mem0 docs
+labels: ["documentation"]
 
 body:
-- type: textarea
-  attributes:
-    label: "Issue with current documentation:"
-    description: >
-      Please make sure to leave a reference to the document/code you're
-      referring to.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      value: |
+        ### Page
+
+        Link to the docs page: https://docs.mem0.ai/...
+
+        ### What's Wrong or Missing
+
+        Describe what's incorrect, unclear, or missing.
+
+        ### Suggested Fix
+
+        How should the docs be improved?
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,23 +1,41 @@
-name: 🚀 Feature request
-description: Submit a proposal/request for a new Embedchain feature
+name: Feature Request
+description: Suggest a new feature or improvement for mem0
+labels: ["enhancement"]
 
 body:
-- type: textarea
-  id: feature-request
-  attributes:
-    label: 🚀 The feature
-    description: >
-      A clear and concise description of the feature proposal
-  validations:
-    required: true
-- type: textarea
-  attributes:
-    label: Motivation, pitch
-    description: >
-      Please outline the motivation for the proposal. Is your feature request related to a specific problem? e.g., *"I'm working on X and would like Y to be possible"*. If this is related to another GitHub issue, please link here too.
-  validations:
-    required: true
-- type: markdown
-  attributes:
-    value: >
-      Thanks for contributing 🎉!
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of mem0 does this relate to?
+      options:
+        - Core / Python SDK
+        - TypeScript SDK
+        - Vector Store (Qdrant, PGVector, Redis, Chroma, etc.)
+        - Graph Memory (Neo4j, Memgraph, etc.)
+        - Ollama / Local Models
+        - OpenClaw
+        - REST API
+        - Benchmarks / Evals
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      value: |
+        ### Use Case
+
+        What problem are you trying to solve?
+
+        ### Proposed Solution
+
+        How should this work? Include API examples or pseudocode if helpful.
+
+        ### Alternatives Considered
+
+        Any workarounds you've tried or other approaches considered.
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,41 +1,38 @@
+## Linked Issue
+
+Closes #<!-- issue number -->
+
 ## Description
 
-Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+<!-- What does this PR do? Why is it needed? -->
 
-Fixes # (issue)
+## Type of Change
 
-## Type of change
-
-Please delete options that are not relevant.
-
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Refactor (does not change functionality, e.g. code style improvements, linting)
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Refactor (no functional changes)
 - [ ] Documentation update
 
-## How Has This Been Tested?
+## Breaking Changes
 
-Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+<!-- If this is a breaking change, describe what breaks and the migration path. Delete this section if not applicable. -->
 
-Please delete options that are not relevant.
+N/A
 
-- [ ] Unit Test
-- [ ] Test Script (please provide)
+## Test Coverage
 
-## Checklist:
+- [ ] I added/updated unit tests
+- [ ] I added/updated integration tests
+- [ ] I tested manually (describe below)
+- [ ] No tests needed (explain why)
 
-- [ ] My code follows the style guidelines of this project
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] Any dependent changes have been merged and published in downstream modules
-- [ ] I have checked my code and corrected any misspellings
+<!-- Describe how you tested this, or link to CI results. -->
 
-## Maintainer Checklist
+## Checklist
 
-- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
-- [ ] Made sure Checks passed
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my code
+- [ ] I have added tests that prove my fix/feature works
+- [ ] New and existing tests pass locally
+- [ ] I have updated documentation if needed

.github/advanced-issue-labeler.yml

@@ -0,0 +1,18 @@
+# Maps dropdown selections to GitHub labels
+# Used by the advanced-issue-labeler GitHub Action
+
+component:
+  - label: "sdk-python"
+    matcher: "Core / Python SDK"
+  - label: "sdk-typescript"
+    matcher: "TypeScript SDK"
+  - label: "vector-store"
+    matcher: "Vector Store"
+  - label: "graph-memory"
+    matcher: "Graph Memory"
+  - label: "ollama"
+    matcher: "Ollama"
+  - label: "openclaw"
+    matcher: "OpenClaw"
+  - label: "rest-api"
+    matcher: "REST API"

.github/workflows/ci.yml

@@ -7,6 +7,8 @@ on:
       - 'mem0/**'
       - 'tests/**'
       - 'embedchain/**'
+      - '.github/workflows/**'
+      - 'pyproject.toml'
   pull_request:
     paths:
       - 'mem0/**'
@@ -28,6 +30,8 @@ jobs:
           mem0:
             - 'mem0/**'
             - 'tests/**'
+            - '.github/workflows/**'
+            - 'pyproject.toml'
           embedchain:
             - 'embedchain/**'
 
@@ -44,6 +48,13 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Clean up disk space
+        run: |
+          df -h
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
+          sudo docker image prune --all --force
+          sudo docker builder prune -a
+          df -h
       - name: Install Hatch
         run: pip install hatch
       - name: Load cached venv

.github/workflows/issue-labeler.yml

@@ -0,0 +1,39 @@
+name: Auto-label issues
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: stefanbuck/github-issue-parser@v3
+        id: issue-parser
+        with:
+          template-path: .github/ISSUE_TEMPLATE/bug_report.yml
+
+      - uses: redhat-plumbers-in-action/advanced-issue-labeler@v3
+        with:
+          issue-form: ${{ steps.issue-parser.outputs.jsonString }}
+          section: component
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: .github/advanced-issue-labeler.yml
+
+      - uses: stefanbuck/github-issue-parser@v3
+        id: feature-parser
+        if: contains(github.event.issue.labels.*.name, 'enhancement')
+        with:
+          template-path: .github/ISSUE_TEMPLATE/feature_request.yml
+
+      - uses: redhat-plumbers-in-action/advanced-issue-labeler@v3
+        if: contains(github.event.issue.labels.*.name, 'enhancement')
+        with:
+          issue-form: ${{ steps.feature-parser.outputs.jsonString }}
+          section: component
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: .github/advanced-issue-labeler.yml

.github/workflows/openclaw-checks.yml

@@ -0,0 +1,100 @@
+name: openclaw checks
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'openclaw/**'
+      - '.github/workflows/openclaw-checks.yml'
+  pull_request:
+    paths:
+      - 'openclaw/**'
+      - '.github/workflows/openclaw-checks.yml'
+
+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: openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd openclaw && pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: cd openclaw && 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: openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd openclaw && pnpm install --frozen-lockfile
+
+      - name: Run tests with coverage
+        run: cd 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
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  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: openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd openclaw && pnpm install --frozen-lockfile
+
+      - name: Build
+        run: cd 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)

.github/workflows/stale.yml

@@ -0,0 +1,48 @@
+name: Close stale issues
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          # Issue settings
+          days-before-issue-stale: 90
+          days-before-issue-close: 14
+          stale-issue-label: 'stale'
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not
+            had any activity in 90 days. It will be closed in 14 days if no
+            further activity occurs. If this is still relevant, please leave a
+            comment or remove the `stale` label.
+          close-issue-message: >
+            This issue has been closed due to inactivity. If this is still
+            relevant, feel free to reopen it or create a new issue.
+
+          # PR settings — mark stale but never auto-close
+          days-before-pr-stale: 90
+          days-before-pr-close: -1
+          stale-pr-label: 'stale'
+          stale-pr-message: >
+            This pull request has been automatically marked as stale because it
+            has not had any activity in 90 days. Please update your branch and
+            address any review comments, or it may be closed in the future.
+
+          # Exempt these labels from stale processing
+          exempt-issue-labels: 'P0-critical,P1-high,good first issue,security'
+          exempt-pr-labels: 'P0-critical,P1-high'
+
+          # Remove stale label when there is new activity
+          remove-stale-when-updated: true
+
+          # Process up to 100 issues per run to stay within API limits
+          operations-per-run: 100

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

@@ -0,0 +1,110 @@
+name: TypeScript SDK CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'mem0-ts/**'
+      - '.github/workflows/ts-sdk-ci.yml'
+  pull_request:
+    paths:
+      - 'mem0-ts/**'
+
+jobs:
+  check_changes:
+    runs-on: ubuntu-latest
+    outputs:
+      ts_sdk_changed: ${{ steps.filter.outputs.ts_sdk }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            ts_sdk:
+              - 'mem0-ts/**'
+
+  build_ts_sdk:
+    needs: check_changes
+    if: needs.check_changes.outputs.ts_sdk_changed == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: mem0-ts/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: mem0-ts
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: mem0-ts
+        run: npx prettier --check .
+
+      - name: Build
+        working-directory: mem0-ts
+        run: pnpm run build
+
+      - name: Run unit tests
+        working-directory: mem0-ts
+        run: pnpm run test:unit
+
+      - name: Verify package exports
+        working-directory: mem0-ts
+        run: |
+          node -e "const m = require('./dist/index.js'); console.log('Client exports:', Object.keys(m).length)"
+          node -e "const m = require('./dist/oss/index.js'); console.log('OSS exports:', Object.keys(m).length)"
+
+      - name: Upload coverage
+        if: matrix.node-version == 20
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: mem0-ts/coverage/
+
+  integration_ts_sdk:
+    needs: build_ts_sdk
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 1
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: mem0-ts/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: mem0-ts
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: mem0-ts
+        run: pnpm run build
+
+      - name: Run integration tests (with cleanup)
+        working-directory: mem0-ts
+        env:
+          MEM0_API_KEY: ${{ secrets.MEM0_API_KEY }}
+        run: pnpm run test:integration

LLM.md

@@ -103,7 +103,7 @@ memory = Memory()
 # With custom configuration
 config = MemoryConfig(
     vector_store={"provider": "qdrant", "config": {"host": "localhost"}},
-    llm={"provider": "openai", "config": {"model": "gpt-4o-mini"}},
+    llm={"provider": "openai", "config": {"model": "gpt-4.1-nano-2025-04-14"}},
     embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}}
 )
 memory = Memory(config)
@@ -273,7 +273,7 @@ config = MemoryConfig(
 
 ### Supported Providers
 
-#### LLM Providers (19 supported)
+#### LLM Providers (20 supported)
 - **openai** - OpenAI GPT models (default)
 - **anthropic** - Claude models
 - **gemini** - Google Gemini
@@ -284,6 +284,7 @@ config = MemoryConfig(
 - **azure_openai** - Azure OpenAI
 - **litellm** - LiteLLM proxy
 - **deepseek** - DeepSeek models
+- **minimax** - MiniMax models
 - **xai** - xAI models
 - **sarvam** - Sarvam AI
 - **lmstudio** - LM Studio local server
@@ -339,7 +340,7 @@ config = MemoryConfig(
     llm={
         "provider": "openai",
         "config": {
-            "model": "gpt-4o-mini",
+            "model": "gpt-4.1-nano-2025-04-14",
             "temperature": 0.1,
             "max_tokens": 1000
         }
@@ -527,7 +528,7 @@ const memory = new Memory({
   },
   llm: {
     provider: 'openai',
-    config: { model: 'gpt-4o-mini' }
+    config: { model: 'gpt-4.1-nano' }
   }
 });
 

MIGRATION_GUIDE_v1.0.md

@@ -0,0 +1,221 @@
+# 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

@@ -15,8 +15,6 @@
   <a href="https://mem0.dev/DiG">Join Discord</a>
   ·
   <a href="https://mem0.dev/demo">Demo</a>
-  ·
-  <a href="https://mem0.dev/openmemory">OpenMemory</a>
 </p>
 
 <p align="center">
@@ -47,6 +45,8 @@
   <strong>⚡ +26% Accuracy vs. OpenAI Memory • 🚀 91% Faster • 💰 90% Fewer Tokens</strong>
 </p>
 
+> **🎉 mem0ai v1.0.0 is now available!** This major release includes API modernization, improved vector store support, and enhanced GCP integration. [See migration guide →](MIGRATION_GUIDE_v1.0.md)
+
 ##  🔥 Research Highlights
 - **+26% Accuracy** over OpenAI Memory on the LOCOMO benchmark
 - **91% Faster Responses** than full-context, ensuring low-latency at scale
@@ -93,9 +93,23 @@ Install sdk via npm:
 npm install mem0ai
 ```
 
+### CLI
+
+Manage memories from your terminal:
+
+```bash
+npm install -g @mem0/cli   # or: pip install mem0-cli
+
+mem0 init
+mem0 add "Prefers dark mode and vim keybindings" --user-id alice
+mem0 search "What does Alice prefer?" --user-id alice
+```
+
+See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full command reference.
+
 ### Basic Usage
 
-Mem0 requires an LLM to function, with `gpt-4o-mini` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+Mem0 requires an LLM to function, with `gpt-4.1-nano-2025-04-14 from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
 
 First step is to instantiate the memory:
 
@@ -114,7 +128,7 @@ def chat_with_memories(message: str, user_id: str = "default_user") -> str:
     # Generate Assistant response
     system_prompt = f"You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n{memories_str}"
     messages = [{"role": "system", "content": system_prompt}, {"role": "user", "content": message}]
-    response = openai_client.chat.completions.create(model="gpt-4o-mini", messages=messages)
+    response = openai_client.chat.completions.create(model="gpt-4.1-nano-2025-04-14", messages=messages)
     assistant_response = response.choices[0].message.content
 
     # Create new memories from the conversation
@@ -166,4 +180,4 @@ We now have a paper you can cite:
 
 ## ⚖️ License
 
-Apache 2.0 — see the [LICENSE](LICENSE) file for details.
+Apache 2.0 — see the [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE) file for details.

cli/README.md

@@ -0,0 +1,98 @@
+# mem0 CLI
+
+The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. Works with the Mem0 Platform API. Available in Python and Node.js.
+
+## Installation
+
+```bash
+npm install -g @mem0/cli
+```
+
+```bash
+pip install mem0-cli
+```
+
+Both packages install a `mem0` binary with identical behavior.
+
+## Quick start
+
+```bash
+# Authenticate and save config
+mem0 init
+
+# Add a memory
+mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
+
+# Search memories
+mem0 search "What are Alice's preferences?" --user-id alice
+
+# List all memories for a user
+mem0 list --user-id alice
+
+# Update a memory
+mem0 update <memory-id> "I switched to light mode"
+
+# Delete a memory
+mem0 delete <memory-id>
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `mem0 init` | Interactive setup wizard — configures API key and default user ID |
+| `mem0 add` | Add a memory from text, JSON messages, a file, or stdin |
+| `mem0 search` | Search memories using natural language |
+| `mem0 list` | List memories with optional filters and pagination |
+| `mem0 get` | Retrieve a specific memory by ID |
+| `mem0 update` | Update the text or metadata of a memory |
+| `mem0 delete` | Delete a memory, all memories for a scope, or an entity |
+| `mem0 import` | Bulk import memories from a JSON file |
+| `mem0 config` | View or modify CLI configuration |
+| `mem0 entities` | List or delete entities (users, agents, apps) |
+| `mem0 status` | Verify API connection and display current project |
+| `mem0 version` | Print the CLI version |
+
+Run `mem0 <command> --help` for detailed usage on any command.
+
+## Output formats
+
+Control how results are displayed with `--output`:
+
+| Format | Description |
+|--------|-------------|
+| `text` | Human-readable with colors and formatting (default) |
+| `json` | Structured JSON for piping to `jq` or agent consumption |
+| `table` | Tabular format (default for `list`) |
+| `quiet` | Minimal — just IDs or status codes |
+
+```bash
+mem0 search "preferences" --user-id alice --output json | jq '.data.results[].memory'
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `MEM0_API_KEY` | API key (overrides config file) |
+| `MEM0_BASE_URL` | API base URL |
+| `MEM0_USER_ID` | Default user ID |
+| `MEM0_AGENT_ID` | Default agent ID |
+| `MEM0_APP_ID` | Default app ID |
+| `MEM0_RUN_ID` | Default run ID |
+| `MEM0_ENABLE_GRAPH` | Enable graph memory (`true` / `false`) |
+
+## Implementations
+
+| Language | Directory | Package | Docs |
+|----------|-----------|---------|------|
+| TypeScript | [`node/`](./node/) | `@mem0/cli` | [README](./node/README.md) |
+| Python | [`python/`](./python/) | `mem0-cli` | [README](./python/README.md) |
+
+## Documentation
+
+Full documentation is available at [docs.mem0.ai/platform/cli](https://docs.mem0.ai/platform/cli).
+
+## License
+
+Apache-2.0

cli/cli-spec.json

@@ -0,0 +1,543 @@
+{
+  "specVersion": 1,
+  "cli": {
+    "name": "mem0",
+    "version": "0.1.0",
+    "description": "The Memory Layer for AI Agents",
+    "helpText": "\u25c6 mem0 CLI \u2014 The Memory Layer for AI Agents"
+  },
+  "branding": {
+    "logoMini": "\u25c6 mem0",
+    "tagline": "The Memory Layer for AI Agents",
+    "colors": {
+      "brand": "#8b5cf6",
+      "accent": "#a78bfa",
+      "success": "#22c55e",
+      "error": "#ef4444",
+      "warning": "#f59e0b",
+      "dim": "#6b7280"
+    },
+    "icons": {
+      "success": "\u2713",
+      "error": "\u2717",
+      "warning": "\u26a0",
+      "info": "\u25c6",
+      "pending": "\u29d7",
+      "add": "+",
+      "update": "~",
+      "delete": "-",
+      "noop": "\u00b7",
+      "connected": "\u25cf",
+      "disconnected": "\u25cf"
+    },
+    "logo": "███\u2557   ███\u2557███████\u2557███\u2557   ███\u2557 ██████\u2557      ██████\u2557██\u2557     ██\u2557\n████\u2557 ████\u2551██\u2554\u2550\u2550\u2550\u2550\u255d████\u2557 ████\u2551██\u2554\u2550████\u2557    ██\u2554\u2550\u2550\u2550\u2550\u255d██\u2551     ██\u2551\n██\u2554████\u2554██\u2551█████\u2557  ██\u2554████\u2554██\u2551██\u2551██\u2554██\u2551    ██\u2551     ██\u2551     ██\u2551\n██\u2551\u255a██\u2554\u255d██\u2551██\u2554\u2550\u2550\u255d  ██\u2551\u255a██\u2554\u255d██\u2551████\u2554\u255d██\u2551    ██\u2551     ██\u2551     ██\u2551\n██\u2551 \u255a\u2550\u255d ██\u2551███████\u2557██\u2551 \u255a\u2550\u255d ██\u2551\u255a██████\u2554\u255d    \u255a██████\u2557███████\u2557██\u2551\n\u255a\u2550\u255d     \u255a\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d     \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d      \u255a\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d"
+  },
+  "config": {
+    "configDir": "~/.mem0",
+    "configFile": "config.json",
+    "version": 1,
+    "defaultBaseUrl": "https://api.mem0.ai",
+    "sections": {
+      "platform": {
+        "fields": {
+          "api_key": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_API_KEY",
+            "redact": true
+          },
+          "base_url": {
+            "type": "string",
+            "default": "https://api.mem0.ai",
+            "envVar": "MEM0_BASE_URL"
+          }
+        }
+      },
+      "defaults": {
+        "fields": {
+          "user_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_USER_ID"
+          },
+          "agent_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_AGENT_ID"
+          },
+          "app_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_APP_ID"
+          },
+          "run_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_RUN_ID"
+          },
+          "enable_graph": {
+            "type": "boolean",
+            "default": false,
+            "envVar": "MEM0_ENABLE_GRAPH"
+          }
+        }
+      }
+    }
+  },
+  "api": {
+    "endpoints": {
+      "add": { "method": "POST", "path": "/v1/memories/" },
+      "search": { "method": "POST", "path": "/v2/memories/search/" },
+      "get": { "method": "GET", "path": "/v1/memories/{memory_id}/" },
+      "list": { "method": "POST", "path": "/v2/memories/" },
+      "update": { "method": "PUT", "path": "/v1/memories/{memory_id}/" },
+      "delete": { "method": "DELETE", "path": "/v1/memories/{memory_id}/" },
+      "deleteAll": { "method": "DELETE", "path": "/v1/memories/" },
+      "entities": { "method": "GET", "path": "/v1/entities/" },
+      "deleteEntities": { "method": "DELETE", "path": "/v1/entities/" }
+    },
+    "authHeader": "Authorization",
+    "authScheme": "Token",
+    "timeout": 30,
+    "entityTypeMap": {
+      "users": "user",
+      "agents": "agent",
+      "apps": "app",
+      "runs": "run"
+    }
+  },
+  "errors": {
+    "AuthError": {
+      "httpStatus": 401,
+      "message": "Authentication failed. Your API key may be invalid or expired."
+    },
+    "NotFoundError": {
+      "httpStatus": 404,
+      "messageTemplate": "Resource not found: {path}"
+    },
+    "APIError": {
+      "httpStatus": 400,
+      "messageTemplate": "Bad request to {path}: {detail}"
+    },
+    "noApiKey": {
+      "message": "No API key configured.",
+      "hint": "Run 'mem0 init' or set MEM0_API_KEY environment variable."
+    }
+  },
+  "optionGroups": {
+    "scope": {
+      "label": "Scope",
+      "options": ["user_id", "agent_id", "app_id", "run_id"]
+    },
+    "search": {
+      "label": "Search",
+      "options": ["top_k", "threshold", "rerank", "keyword", "filter_json", "fields", "graph", "no_graph"]
+    },
+    "pagination": {
+      "label": "Pagination",
+      "options": ["page", "page_size"]
+    },
+    "filters": {
+      "label": "Filters",
+      "options": ["category", "after", "before", "graph", "no_graph"]
+    },
+    "output": {
+      "label": "Output",
+      "options": ["output"]
+    },
+    "connection": {
+      "label": "Connection",
+      "options": ["api_key", "base_url"]
+    }
+  },
+  "globalOptions": [
+    {
+      "name": "api_key",
+      "flags": ["--api-key"],
+      "type": "string",
+      "required": false,
+      "envVar": "MEM0_API_KEY",
+      "help": "Override API key.",
+      "panel": "Connection"
+    },
+    {
+      "name": "base_url",
+      "flags": ["--base-url"],
+      "type": "string",
+      "required": false,
+      "help": "Override API base URL.",
+      "panel": "Connection"
+    },
+    {
+      "name": "version",
+      "flags": ["--version"],
+      "type": "boolean",
+      "required": false,
+      "help": "Show version and exit."
+    }
+  ],
+  "commands": [
+    {
+      "name": "add",
+      "description": "Add a memory from text, messages, file, or stdin.",
+      "usage": "mem0 add <text> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": true,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "quiet"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "text",
+          "type": "string",
+          "required": false,
+          "help": "Text content to add as a memory."
+        }
+      ],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Scope to user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Scope to agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Scope to app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Scope to run.", "panel": "Scope" },
+        { "name": "messages", "flags": ["--messages"], "type": "string", "help": "Conversation messages as JSON." },
+        { "name": "file", "flags": ["--file", "-f"], "type": "path", "help": "Read messages from JSON file." },
+        { "name": "metadata", "flags": ["--metadata", "-m"], "type": "string", "help": "Custom metadata as JSON." },
+        { "name": "immutable", "flags": ["--immutable"], "type": "boolean", "default": false, "help": "Prevent future updates." },
+        { "name": "no_infer", "flags": ["--no-infer"], "type": "boolean", "default": false, "help": "Skip inference, store raw." },
+        { "name": "expires", "flags": ["--expires"], "type": "string", "help": "Expiration date (YYYY-MM-DD)." },
+        { "name": "categories", "flags": ["--categories"], "type": "string", "help": "Categories (JSON array or comma-separated)." },
+        { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph memory extraction.", "panel": "Scope" },
+        { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph memory extraction.", "panel": "Scope" },
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output format: text, json, quiet.", "panel": "Output" }
+      ],
+      "apiEndpoint": "add"
+    },
+    {
+      "name": "search",
+      "description": "Search memories by semantic query.",
+      "usage": "mem0 search <query> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": true,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "table"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "query",
+          "type": "string",
+          "required": true,
+          "help": "Search query."
+        }
+      ],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Filter by user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Filter by agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Filter by app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Filter by run.", "panel": "Scope" },
+        { "name": "top_k", "flags": ["--top-k", "-k", "--limit"], "type": "integer", "default": 10, "help": "Number of results.", "panel": "Search" },
+        { "name": "threshold", "flags": ["--threshold"], "type": "float", "default": 0.3, "help": "Minimum similarity score.", "panel": "Search" },
+        { "name": "rerank", "flags": ["--rerank"], "type": "boolean", "default": false, "help": "Enable reranking (Platform only).", "panel": "Search" },
+        { "name": "keyword", "flags": ["--keyword"], "type": "boolean", "default": false, "help": "Use keyword search.", "panel": "Search" },
+        { "name": "filter_json", "flags": ["--filter"], "type": "string", "help": "Advanced filter expression (JSON).", "panel": "Search" },
+        { "name": "fields", "flags": ["--fields"], "type": "string", "help": "Specific fields to return (comma-separated).", "panel": "Search" },
+        { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph in search.", "panel": "Search" },
+        { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph in search.", "panel": "Search" },
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, table.", "panel": "Output" }
+      ],
+      "apiEndpoint": "search"
+    },
+    {
+      "name": "get",
+      "description": "Get a specific memory by ID.",
+      "usage": "mem0 get <memory_id> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "memory_id",
+          "type": "string",
+          "required": true,
+          "help": "Memory ID to retrieve."
+        }
+      ],
+      "options": [
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json.", "panel": "Output" }
+      ],
+      "apiEndpoint": "get"
+    },
+    {
+      "name": "list",
+      "description": "List memories with optional filters.",
+      "usage": "mem0 list [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": true,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "table"],
+      "defaultOutput": "table",
+      "arguments": [],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Filter by user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Filter by agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Filter by app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Filter by run.", "panel": "Scope" },
+        { "name": "page", "flags": ["--page"], "type": "integer", "default": 1, "help": "Page number.", "panel": "Pagination" },
+        { "name": "page_size", "flags": ["--page-size"], "type": "integer", "default": 100, "help": "Results per page.", "panel": "Pagination" },
+        { "name": "category", "flags": ["--category"], "type": "string", "help": "Filter by category.", "panel": "Filters" },
+        { "name": "after", "flags": ["--after"], "type": "string", "help": "Created after (YYYY-MM-DD).", "panel": "Filters" },
+        { "name": "before", "flags": ["--before"], "type": "string", "help": "Created before (YYYY-MM-DD).", "panel": "Filters" },
+        { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph in listing.", "panel": "Filters" },
+        { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph in listing.", "panel": "Filters" },
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "table", "help": "Output: text, json, table.", "panel": "Output" }
+      ],
+      "apiEndpoint": "list"
+    },
+    {
+      "name": "update",
+      "description": "Update a memory's text or metadata.",
+      "usage": "mem0 update <memory_id> [text] [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "quiet"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "memory_id",
+          "type": "string",
+          "required": true,
+          "help": "Memory ID to update."
+        },
+        {
+          "name": "text",
+          "type": "string",
+          "required": false,
+          "help": "New memory text."
+        }
+      ],
+      "options": [
+        { "name": "metadata", "flags": ["--metadata", "-m"], "type": "string", "help": "Update metadata (JSON)." },
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
+      ],
+      "apiEndpoint": "update"
+    },
+    {
+      "name": "delete",
+      "description": "Delete a memory, all memories matching a scope, or an entity.",
+      "usage": "mem0 delete [memory_id] [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": false,
+      "confirmDangerous": true,
+      "outputFormats": ["text", "json", "quiet"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "memory_id",
+          "type": "string",
+          "required": false,
+          "help": "Memory ID to delete (omit when using --all or --entity)."
+        }
+      ],
+      "options": [
+        { "name": "all", "flags": ["--all"], "type": "boolean", "default": false, "help": "Delete all memories matching scope filters." },
+        { "name": "entity", "flags": ["--entity"], "type": "boolean", "default": false, "help": "Delete the entity itself and all its memories (cascade)." },
+        { "name": "project", "flags": ["--project"], "type": "boolean", "default": false, "help": "With --all: delete ALL memories project-wide." },
+        { "name": "dry_run", "flags": ["--dry-run"], "type": "boolean", "default": false, "help": "Show what would be deleted without deleting." },
+        { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Skip confirmation." },
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Scope to user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Scope to agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Scope to app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Scope to run.", "panel": "Scope" },
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
+      ],
+      "apiEndpoint": "delete",
+      "notes": "Mutually exclusive modes: (1) mem0 delete <id> -- single memory, (2) mem0 delete --all [scope] -- bulk delete, (3) mem0 delete --entity [scope] -- entity cascade delete. Cannot combine <memoryId> with --all or --entity, and cannot combine --all with --entity."
+    },
+    {
+      "name": "import",
+      "description": "Import memories from a JSON file.",
+      "usage": "mem0 import <file_path> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "outputFormats": ["text"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "file_path",
+          "type": "string",
+          "required": true,
+          "help": "JSON file to import."
+        }
+      ],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Override user ID.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Override agent ID.", "panel": "Scope" }
+      ],
+      "apiEndpoint": "add"
+    },
+    {
+      "name": "config",
+      "description": "Manage mem0 configuration.",
+      "isGroup": true,
+      "subcommands": [
+        {
+          "name": "show",
+          "description": "Display current configuration (secrets redacted).",
+          "usage": "mem0 config show",
+          "needsBackend": false,
+          "needsConfig": false,
+          "arguments": [],
+          "options": []
+        },
+        {
+          "name": "get",
+          "description": "Get a configuration value.",
+          "usage": "mem0 config get <key>",
+          "needsBackend": false,
+          "needsConfig": false,
+          "arguments": [
+            {
+              "name": "key",
+              "type": "string",
+              "required": true,
+              "help": "Config key (e.g. platform.api_key)."
+            }
+          ],
+          "options": []
+        },
+        {
+          "name": "set",
+          "description": "Set a configuration value.",
+          "usage": "mem0 config set <key> <value>",
+          "needsBackend": false,
+          "needsConfig": false,
+          "arguments": [
+            {
+              "name": "key",
+              "type": "string",
+              "required": true,
+              "help": "Config key (e.g. platform.api_key)."
+            },
+            {
+              "name": "value",
+              "type": "string",
+              "required": true,
+              "help": "Value to set."
+            }
+          ],
+          "options": []
+        }
+      ]
+    },
+    {
+      "name": "entity",
+      "description": "Manage entities.",
+      "isGroup": true,
+      "subcommands": [
+        {
+          "name": "list",
+          "description": "List all entities of a given type.",
+          "usage": "mem0 entity list <entity_type>",
+          "needsBackend": true,
+          "needsConfig": false,
+          "resolveIds": false,
+          "resolveGraph": false,
+          "confirmDangerous": false,
+          "outputFormats": ["table", "json"],
+          "defaultOutput": "table",
+          "arguments": [
+            {
+              "name": "entity_type",
+              "type": "string",
+              "required": true,
+              "help": "Entity type: users, agents, apps, runs.",
+              "choices": ["users", "agents", "apps", "runs"]
+            }
+          ],
+          "options": [
+            { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "table", "help": "Output: table, json.", "panel": "Output" }
+          ],
+          "apiEndpoint": "entities"
+        },
+        {
+          "name": "delete",
+          "description": "Delete an entity and ALL its memories (cascade).",
+          "usage": "mem0 entity delete [OPTIONS]",
+          "needsBackend": true,
+          "needsConfig": false,
+          "resolveIds": false,
+          "resolveGraph": false,
+          "confirmDangerous": true,
+          "outputFormats": ["text", "json", "quiet"],
+          "defaultOutput": "text",
+          "arguments": [],
+          "options": [
+            { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "User ID.", "panel": "Scope" },
+            { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Agent ID.", "panel": "Scope" },
+            { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "App ID.", "panel": "Scope" },
+            { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Run ID.", "panel": "Scope" },
+            { "name": "dry_run", "flags": ["--dry-run"], "type": "boolean", "default": false, "help": "Show what would be deleted without deleting." },
+            { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Skip confirmation." },
+            { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
+          ],
+          "apiEndpoint": "deleteEntities"
+        }
+      ]
+    },
+    {
+      "name": "init",
+      "description": "Interactive setup wizard for mem0 CLI.",
+      "usage": "mem0 init",
+      "needsBackend": false,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "name": "status",
+      "description": "Check connectivity and authentication.",
+      "usage": "mem0 status [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "name": "help",
+      "description": "Show help. Use --json for machine-readable output (for LLM agents).",
+      "usage": "mem0 help [OPTIONS]",
+      "needsBackend": false,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "arguments": [],
+      "options": [
+        { "name": "json", "flags": ["--json"], "type": "boolean", "default": false, "help": "Output machine-readable JSON for LLM agents." }
+      ]
+    }
+  ]
+}

cli/node/README.md

@@ -0,0 +1,75 @@
+# mem0 CLI (Node.js)
+
+The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. TypeScript implementation.
+
+## Prerequisites
+
+- Node.js **18+**
+- pnpm (`npm install -g pnpm`)
+
+## Installation
+
+```bash
+npm install -g @mem0/cli
+```
+
+Or from source:
+
+```bash
+cd node
+pnpm install
+pnpm build
+pnpm link --global
+
+# Now use it like a normal CLI
+mem0 --help
+```
+
+## Running during development
+
+```bash
+cd node
+pnpm install
+
+# Development mode (runs TypeScript directly, no build needed)
+pnpm dev --help
+pnpm dev add "test memory" --user-id alice
+pnpm dev search "test" --user-id alice
+
+# Or build first, then run the compiled JS
+pnpm build
+node dist/index.js --help
+node dist/index.js add "test memory" --user-id alice
+```
+
+## Quick Start
+
+```bash
+# Set up your configuration
+mem0 init
+
+# Add a memory
+mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
+
+# Search memories
+mem0 search "What are Alice's preferences?" --user-id alice
+
+# List all memories
+mem0 list --user-id alice
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MEM0_API_KEY` | API key (overrides config file) |
+| `MEM0_BASE_URL` | API base URL |
+| `MEM0_USER_ID` | Default user ID |
+| `MEM0_AGENT_ID` | Default agent ID |
+| `MEM0_APP_ID` | Default app ID |
+| `MEM0_RUN_ID` | Default run ID |
+| `MEM0_ENABLE_GRAPH` | Enable graph memory (true/false) |
+
+## License
+
+Apache-2.0

cli/node/development.md

@@ -0,0 +1,91 @@
+# Development
+
+## Prerequisites
+
+- Node.js **18+**
+- pnpm (`npm install -g pnpm`)
+
+## Setup
+
+From the `node/` directory:
+
+```bash
+pnpm install
+```
+
+## Running the CLI
+
+There are two ways to run the CLI during development:
+
+### Option 1: Development mode (no build needed)
+
+Uses `tsx` to run TypeScript directly. Pass CLI arguments after `pnpm dev`:
+
+```bash
+pnpm dev --help
+pnpm dev version
+pnpm dev add "test memory" --user-id alice
+pnpm dev search "test" --user-id alice
+pnpm dev config show
+```
+
+> **Note:** Do NOT use `pnpm dev -- --help`. With pnpm, arguments pass through directly — adding `--` inserts a literal `--` that breaks the CLI parser.
+
+### Option 2: Build and run compiled JS
+
+```bash
+# Build first
+pnpm build
+
+# Run the compiled CLI
+node dist/index.js --help
+node dist/index.js version
+node dist/index.js add "test memory" --user-id alice
+```
+
+### Option 3: Link globally (makes `mem0` available system-wide)
+
+```bash
+pnpm build
+pnpm link --global
+
+# Now use it like a normal CLI
+mem0 --help
+mem0 version
+```
+
+> **Warning:** If you also have the Python CLI installed, both register the `mem0` command. The last one linked/installed wins. Unlink with `pnpm unlink --global`.
+
+## Build
+
+```bash
+pnpm build
+```
+
+The compiled output is in `dist/`.
+
+## Run tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+```
+
+## Lint
+
+```bash
+# Check
+pnpm lint
+
+# Auto-fix
+pnpm lint:fix
+```
+
+## Type checking
+
+```bash
+pnpm typecheck
+```

cli/node/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mem0/cli",
+  "version": "0.1.0",
+  "description": "The official CLI for mem0 — the memory layer for AI agents",
+  "type": "module",
+  "bin": {
+    "mem0": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": "mem0.ai <founders@mem0.ai>",
+  "keywords": ["mem0", "memory", "ai", "agents", "cli"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.4",
+    "ora": "^8.0.0",
+    "boxen": "^7.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "vitest": "^1.5.0",
+    "@biomejs/biome": "^1.7.0",
+    "@types/node": "^20.0.0"
+  }
+}

cli/node/src/backend/base.ts

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

cli/node/src/backend/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Backend factory re-export.
+ */
+
+export { getBackend } from "./base.js";
+export type { Backend, AddOptions, SearchOptions, ListOptions, DeleteOptions, EntityIds } from "./base.js";
+export { AuthError, NotFoundError, APIError } from "./base.js";

cli/node/src/backend/platform.ts

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

cli/node/src/branding.ts

@@ -0,0 +1,145 @@
+/**
+ * Branding and ASCII art for mem0 CLI.
+ */
+
+import chalk from "chalk";
+import ora, { type Ora } from "ora";
+import { createRequire } from "node:module";
+
+const _require = createRequire(import.meta.url);
+const PKG_VERSION: string = _require("../package.json").version;
+
+export const LOGO = `
+███╗   ███╗███████╗███╗   ███╗ ██████╗      ██████╗██╗     ██╗
+████╗ ████║██╔════╝████╗ ████║██╔═████╗    ██╔════╝██║     ██║
+██╔████╔██║█████╗  ██╔████╔██║██║██╔██║    ██║     ██║     ██║
+██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║████╔╝██║    ██║     ██║     ██║
+██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝    ╚██████╗███████╗██║
+╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝      ╚═════╝╚══════╝╚═╝
+`;
+
+export const LOGO_MINI = "◆ mem0";
+export const TAGLINE = "The Memory Layer for AI Agents";
+
+export const BRAND_COLOR = "#8b5cf6";
+export const ACCENT_COLOR = "#a78bfa";
+export const SUCCESS_COLOR = "#22c55e";
+export const ERROR_COLOR = "#ef4444";
+export const WARNING_COLOR = "#f59e0b";
+export const DIM_COLOR = "#6b7280";
+
+const brand = chalk.hex(BRAND_COLOR);
+const accent = chalk.hex(ACCENT_COLOR);
+const success = chalk.hex(SUCCESS_COLOR);
+const error = chalk.hex(ERROR_COLOR);
+const warning = chalk.hex(WARNING_COLOR);
+const dim = chalk.hex(DIM_COLOR);
+
+/**
+ * Choose a symbol based on TTY/NO_COLOR. Fancy for interactive terminals,
+ * plain-text for piped/non-TTY or NO_COLOR environments.
+ */
+export function sym(fancy: string, plain: string): string {
+  if (!process.stdout.isTTY || process.env.NO_COLOR) return plain;
+  return fancy;
+}
+
+export function printBanner(): void {
+  const pad = 3; // horizontal padding each side (matches Rich's padding=(0, 2))
+  const logoLines = LOGO.trimEnd().split("\n");
+  const tagline = `  ${TAGLINE}`;
+  const subtitle = `Node.js SDK · v${PKG_VERSION}`;
+  const contentLines = ["", ...logoLines, "", tagline, ""];
+
+  // Compute inner width from longest content line + padding both sides
+  const maxContent = Math.max(...contentLines.map((l) => l.length));
+  const innerWidth = maxContent + pad * 2;
+  const totalWidth = innerWidth + 2; // + 2 for │ borders
+
+  const topBorder = brand(`╭${"─".repeat(totalWidth - 2)}╮`);
+  const subtitleFill = totalWidth - 2 - subtitle.length - 3; // 3 = "─ " before subtitle + "─" after
+  const bottomBorder = brand(`╰${"─".repeat(subtitleFill)} ${dim(subtitle)} ${"─"}╯`);
+
+  const body = contentLines.map((line) => {
+    const rightPad = innerWidth - pad - line.length;
+    return `${brand("│")}${" ".repeat(pad)}${brand.bold(line)}${" ".repeat(Math.max(rightPad, 0))}${brand("│")}`;
+  });
+  // Re-color tagline line with accent instead of brand.bold
+  const taglineIdx = body.length - 2; // second-to-last (before trailing empty line)
+  const taglineRightPad = innerWidth - pad - tagline.length;
+  body[taglineIdx] = `${brand("│")}${" ".repeat(pad)}${accent(tagline)}${" ".repeat(Math.max(taglineRightPad, 0))}${brand("│")}`;
+
+  console.log(topBorder);
+  for (const line of body) console.log(line);
+  console.log(bottomBorder);
+}
+
+export function printSuccess(message: string): void {
+  console.log(`${success(sym("✓", "[ok]"))} ${message}`);
+}
+
+export function printError(message: string, hint?: string): void {
+  console.error(`${error(sym("✗", "[error]") + " Error:")} ${message}`);
+  if (hint) {
+    console.error(`  ${dim(hint)}`);
+  }
+}
+
+export function printWarning(message: string): void {
+  console.error(`${warning(sym("⚠", "[warn]"))} ${message}`);
+}
+
+export function printInfo(message: string): void {
+  console.log(`${brand(sym("◆", "*"))} ${message}`);
+}
+
+export function printScope(ids: Record<string, string | undefined>): void {
+  const parts: string[] = [];
+  for (const [key, val] of Object.entries(ids)) {
+    if (val) {
+      const label = key.replace(/_/g, " ").replace("id", "ID").trim();
+      parts.push(`${label}=${val}`);
+    }
+  }
+  if (parts.length > 0) {
+    console.log(`  ${dim(`Scope: ${parts.join(", ")}`)}`);
+  }
+}
+
+export interface TimedStatusContext {
+  successMsg: string;
+  errorMsg: string;
+}
+
+/**
+ * Run an async function with a spinner, timing the operation.
+ * Equivalent to Python's timed_status context manager.
+ */
+export async function timedStatus<T>(
+  message: string,
+  fn: (ctx: TimedStatusContext) => Promise<T>,
+): Promise<T> {
+  const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+  const spinner = ora({ text: dim(message), color: "magenta", stream: process.stderr }).start();
+  const start = performance.now();
+
+  try {
+    const result = await fn(ctx);
+    const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+    spinner.stop();
+    if (ctx.successMsg) {
+      console.error(`${success("✓")} ${ctx.successMsg} (${elapsed}s)`);
+    }
+    return result;
+  } catch (err) {
+    const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+    spinner.stop();
+    if (ctx.errorMsg) {
+      console.error(`${error("✗ Error:")} ${ctx.errorMsg} (${elapsed}s)`);
+    }
+    throw err;
+  }
+}
+
+/** Format helpers using brand colors for external use. */
+export const colors = { brand, accent, success, error, warning, dim };

cli/node/src/commands/config.ts

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

cli/node/src/commands/entities.ts

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

cli/node/src/commands/init.ts

@@ -0,0 +1,182 @@
+/**
+ * mem0 init — interactive setup wizard.
+ */
+
+import readline from "node:readline";
+import {
+  printBanner,
+  printError,
+  printInfo,
+  printSuccess,
+  colors,
+} from "../branding.js";
+import { type Mem0Config, createDefaultConfig, saveConfig } from "../config.js";
+import { PlatformBackend } from "../backend/platform.js";
+
+const { brand, dim } = colors;
+
+function promptSecret(label: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(label);
+
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+
+    const chars: string[] = [];
+
+    const onData = (key: string) => {
+      for (const ch of key) {
+        if (ch === "\r" || ch === "\n") {
+          cleanup();
+          process.stdout.write("\n");
+          resolve(chars.join(""));
+          return;
+        }
+        if (ch === "\x03") {
+          cleanup();
+          reject(new Error("Interrupted"));
+          return;
+        }
+        if (ch === "\x7f" || ch === "\x08") {
+          // backspace
+          if (chars.length > 0) {
+            chars.pop();
+            process.stdout.write("\b \b");
+          }
+        } else if (ch === "\x15") {
+          // Ctrl+U — clear line
+          process.stdout.write("\b \b".repeat(chars.length));
+          chars.length = 0;
+        } else if (ch >= " ") {
+          chars.push(ch);
+          process.stdout.write("*");
+        }
+      }
+    };
+
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      process.stdin.pause();
+    };
+
+    process.stdin.on("data", onData);
+  });
+}
+
+function promptLine(label: string, defaultValue?: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = defaultValue ? `${label} [${defaultValue}]: ` : `${label}: `;
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+
+async function setupPlatform(config: Mem0Config): Promise<void> {
+  console.log();
+  console.log(`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys")}`);
+  console.log();
+
+  process.stdout.write(`  ${brand("API Key")}: `);
+  const apiKey = await promptSecret("");
+  if (!apiKey) {
+    printError("API key is required.");
+    process.exit(1);
+  }
+  config.platform.apiKey = apiKey;
+}
+
+async function setupDefaults(config: Mem0Config): Promise<void> {
+  console.log();
+  printInfo("Set default entity IDs (press Enter to skip).\n");
+
+  const userId = await promptLine(`  ${brand("Default User ID")} ${dim("(recommended)")}`, "mem0-cli");
+  if (userId) config.defaults.userId = userId;
+}
+
+async function validatePlatform(config: Mem0Config): Promise<void> {
+  console.log();
+  printInfo("Validating connection...");
+  try {
+    const backend = new PlatformBackend(config.platform);
+    const status = await backend.status({
+      userId: config.defaults.userId || undefined,
+      agentId: config.defaults.agentId || undefined,
+    });
+    if (status.connected) {
+      printSuccess("Connected to mem0 Platform!");
+    } else {
+      printError(
+        `Could not connect: ${status.error ?? "Unknown error"}`,
+        "Check your API key and try again.",
+      );
+    }
+  } catch (e) {
+    printError(`Connection test failed: ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+export async function runInit(opts: { apiKey?: string; userId?: string } = {}): Promise<void> {
+  const config = createDefaultConfig();
+
+  // Non-interactive: both flags provided
+  if (opts.apiKey && opts.userId) {
+    config.platform.apiKey = opts.apiKey;
+    config.defaults.userId = opts.userId;
+    await validatePlatform(config);
+    saveConfig(config);
+    printSuccess("Configuration saved to ~/.mem0/config.json");
+    return;
+  }
+
+  // Non-TTY without full flags: error with usage hint
+  if (!process.stdin.isTTY && (!opts.apiKey || !opts.userId)) {
+    printError(
+      "Non-interactive terminal detected and missing required flags.",
+      "Usage: mem0 init --api-key <key> --user-id <id>",
+    );
+    process.exit(1);
+  }
+
+  printBanner();
+  console.log();
+  printInfo("Welcome! Let's set up your mem0 CLI.\n");
+
+  // Use provided API key or prompt
+  if (opts.apiKey) {
+    config.platform.apiKey = opts.apiKey;
+  } else {
+    await setupPlatform(config);
+  }
+
+  // Use provided user ID or prompt
+  if (opts.userId) {
+    config.defaults.userId = opts.userId;
+  } else {
+    await setupDefaults(config);
+  }
+
+  await validatePlatform(config);
+
+  saveConfig(config);
+  console.log();
+  printSuccess("Configuration saved to ~/.mem0/config.json");
+  console.log();
+  console.log(`  ${dim("Get started:")}`);
+  if (config.defaults.userId) {
+    console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+    console.log(`  ${dim('  mem0 search "preferences"')}`);
+  } else {
+    console.log(`  ${dim('  mem0 add "I prefer dark mode" --user-id alice')}`);
+    console.log(`  ${dim('  mem0 search "preferences" --user-id alice')}`);
+  }
+  console.log();
+}

cli/node/src/commands/memory.ts

@@ -0,0 +1,487 @@
+/**
+ * Memory CRUD commands: add, search, get, list, update, delete.
+ */
+
+import fs from "node:fs";
+import { printError, printInfo, printScope, printSuccess, timedStatus } from "../branding.js";
+import type { Backend } from "../backend/base.js";
+import {
+  formatAddResult,
+  formatJson,
+  formatMemoriesTable,
+  formatMemoriesText,
+  formatSingleMemory,
+  printResultSummary,
+} from "../output.js";
+
+export async function cmdAdd(
+  backend: Backend,
+  text: string | undefined,
+  opts: {
+    userId?: string;
+    agentId?: string;
+    appId?: string;
+    runId?: string;
+    messages?: string;
+    file?: string;
+    metadata?: string;
+    immutable: boolean;
+    noInfer: boolean;
+    expires?: string;
+    categories?: string;
+    enableGraph: boolean;
+    output: string;
+  },
+): Promise<void> {
+  let msgs: Record<string, unknown>[] | undefined;
+  let content = text;
+
+  // Read from file
+  if (opts.file) {
+    try {
+      const raw = fs.readFileSync(opts.file, "utf-8");
+      msgs = JSON.parse(raw);
+    } catch (e) {
+      printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
+      process.exit(1);
+    }
+  }
+  // Parse messages JSON
+  else if (opts.messages) {
+    try {
+      msgs = JSON.parse(opts.messages);
+    } catch (e) {
+      printError(`Invalid JSON in --messages: ${e instanceof Error ? e.message : e}`);
+      process.exit(1);
+    }
+  }
+  // Read from stdin if piped
+  else if (!content && !process.stdin.isTTY) {
+    content = fs.readFileSync(0, "utf-8").trim();
+  }
+
+  if (!content && !msgs) {
+    printError("No content provided. Pass text, --messages, --file, or pipe via stdin.");
+    process.exit(1);
+  }
+
+  let meta: Record<string, unknown> | undefined;
+  if (opts.metadata) {
+    try {
+      meta = JSON.parse(opts.metadata);
+    } catch {
+      printError("Invalid JSON in --metadata.");
+      process.exit(1);
+    }
+  }
+
+  let cats: string[] | undefined;
+  if (opts.categories) {
+    try {
+      cats = JSON.parse(opts.categories);
+    } catch {
+      cats = opts.categories.split(",").map((c) => c.trim());
+    }
+  }
+
+  let result: Record<string, unknown>;
+  try {
+    result = await timedStatus("Adding memory...", async () => {
+      return backend.add(content ?? undefined, msgs, {
+        userId: opts.userId,
+        agentId: opts.agentId,
+        appId: opts.appId,
+        runId: opts.runId,
+        metadata: meta,
+        immutable: opts.immutable,
+        infer: !opts.noInfer,
+        expires: opts.expires,
+        categories: cats,
+        enableGraph: opts.enableGraph,
+      });
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+
+  if (opts.output === "quiet") return;
+
+  if (opts.output === "json") {
+    formatAddResult(result, opts.output);
+    return;
+  }
+
+  console.log();
+  printScope({ user_id: opts.userId, agent_id: opts.agentId, app_id: opts.appId, run_id: opts.runId });
+  const results = Array.isArray(result) ? result : ((result.results as unknown[]) ?? [result]);
+  const count = results.length;
+  printSuccess(`Memory processed — ${count} memor${count === 1 ? "y" : "ies"} extracted`);
+  formatAddResult(result, opts.output);
+}
+
+export async function cmdSearch(
+  backend: Backend,
+  query: string | undefined,
+  opts: {
+    userId?: string;
+    agentId?: string;
+    appId?: string;
+    runId?: string;
+    topK: number;
+    threshold: number;
+    rerank: boolean;
+    keyword: boolean;
+    filterJson?: string;
+    fields?: string;
+    enableGraph: boolean;
+    output: string;
+  },
+): Promise<void> {
+  if (!query) {
+    printError("No query provided. Pass a query argument or pipe via stdin.");
+    process.exit(1);
+  }
+
+  let filters: Record<string, unknown> | undefined;
+  if (opts.filterJson) {
+    try {
+      filters = JSON.parse(opts.filterJson);
+    } catch {
+      printError("Invalid JSON in --filter.");
+      process.exit(1);
+    }
+  }
+
+  const fieldList = opts.fields ? opts.fields.split(",").map((f) => f.trim()) : undefined;
+
+  const start = performance.now();
+  let results: Record<string, unknown>[];
+  try {
+    results = await timedStatus("Searching memories...", async () => {
+      return backend.search(query!, {
+        userId: opts.userId,
+        agentId: opts.agentId,
+        appId: opts.appId,
+        runId: opts.runId,
+        topK: opts.topK,
+        threshold: opts.threshold,
+        rerank: opts.rerank,
+        keyword: opts.keyword,
+        filters,
+        fields: fieldList,
+        enableGraph: opts.enableGraph,
+      });
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const elapsed = (performance.now() - start) / 1000;
+
+  if (opts.output === "json") {
+    formatJson(results);
+  } else if (opts.output === "table") {
+    if (results.length > 0) {
+      formatMemoriesTable(results);
+      printResultSummary({ count: results.length, durationSecs: elapsed, scopeIds: { user_id: opts.userId, agent_id: opts.agentId } });
+    } else {
+      console.log();
+      printInfo("No memories found matching your query.");
+      console.log();
+    }
+  } else {
+    if (results.length > 0) {
+      formatMemoriesText(results);
+      printResultSummary({ count: results.length, durationSecs: elapsed, scopeIds: { user_id: opts.userId, agent_id: opts.agentId } });
+    } else {
+      console.log();
+      printInfo("No memories found matching your query.");
+      console.log();
+    }
+  }
+}
+
+export async function cmdGet(
+  backend: Backend,
+  memoryId: string,
+  opts: { output: string },
+): Promise<void> {
+  let result: Record<string, unknown>;
+  try {
+    result = await timedStatus("Fetching memory...", async () => {
+      return backend.get(memoryId);
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+
+  formatSingleMemory(result, opts.output);
+}
+
+export async function cmdList(
+  backend: Backend,
+  opts: {
+    userId?: string;
+    agentId?: string;
+    appId?: string;
+    runId?: string;
+    page: number;
+    pageSize: number;
+    category?: string;
+    after?: string;
+    before?: string;
+    enableGraph: boolean;
+    output: string;
+  },
+): Promise<void> {
+  const start = performance.now();
+  let results: Record<string, unknown>[];
+  try {
+    results = await timedStatus("Listing memories...", async () => {
+      return backend.listMemories({
+        userId: opts.userId,
+        agentId: opts.agentId,
+        appId: opts.appId,
+        runId: opts.runId,
+        page: opts.page,
+        pageSize: opts.pageSize,
+        category: opts.category,
+        after: opts.after,
+        before: opts.before,
+        enableGraph: opts.enableGraph,
+      });
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const elapsed = (performance.now() - start) / 1000;
+
+  if (opts.output === "json") {
+    formatJson(results);
+  } else if (opts.output === "table") {
+    if (results.length > 0) {
+      formatMemoriesTable(results);
+      printResultSummary({ count: results.length, durationSecs: elapsed, page: opts.page, scopeIds: { user_id: opts.userId, agent_id: opts.agentId } });
+    } else {
+      console.log();
+      printInfo("No memories found.");
+      console.log();
+    }
+  } else {
+    if (results.length > 0) {
+      formatMemoriesText(results, "memories");
+      printResultSummary({ count: results.length, durationSecs: elapsed, page: opts.page, scopeIds: { user_id: opts.userId, agent_id: opts.agentId } });
+    } else {
+      console.log();
+      printInfo("No memories found.");
+      console.log();
+    }
+  }
+}
+
+export async function cmdUpdate(
+  backend: Backend,
+  memoryId: string,
+  text: string | undefined,
+  opts: { metadata?: string; output: string },
+): Promise<void> {
+  let meta: Record<string, unknown> | undefined;
+  if (opts.metadata) {
+    try {
+      meta = JSON.parse(opts.metadata);
+    } catch {
+      printError("Invalid JSON in --metadata.");
+      process.exit(1);
+    }
+  }
+
+  const start = performance.now();
+  let result: Record<string, unknown>;
+  try {
+    result = await timedStatus("Updating memory...", async () => {
+      return backend.update(memoryId, text, meta);
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const elapsed = (performance.now() - start) / 1000;
+
+  if (opts.output === "json") {
+    formatJson(result);
+  } else if (opts.output !== "quiet") {
+    printSuccess(`Memory ${memoryId.slice(0, 8)} updated (${elapsed.toFixed(2)}s)`);
+  }
+}
+
+export async function cmdDelete(
+  backend: Backend,
+  memoryId: string,
+  opts: { output: string; dryRun?: boolean; force?: boolean },
+): Promise<void> {
+  if (opts.dryRun) {
+    let mem: Record<string, unknown>;
+    try {
+      mem = await backend.get(memoryId);
+    } catch (e) {
+      printError(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+    const text = (mem.memory ?? mem.text ?? "") as string;
+    printInfo(`Would delete memory ${memoryId.slice(0, 8)}: ${text}`);
+    printInfo("No changes made.");
+    return;
+  }
+
+  const start = performance.now();
+  let result: Record<string, unknown>;
+  try {
+    result = await timedStatus("Deleting...", async () => {
+      return backend.delete(memoryId);
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const elapsed = (performance.now() - start) / 1000;
+
+  if (opts.output === "json") {
+    formatJson(result);
+  } else if (opts.output !== "quiet") {
+    printSuccess(`Memory ${memoryId.slice(0, 8)} deleted (${elapsed.toFixed(2)}s)`);
+  }
+}
+
+export async function cmdDeleteAll(
+  backend: Backend,
+  opts: {
+    force: boolean;
+    dryRun?: boolean;
+    all?: boolean;
+    userId?: string;
+    agentId?: string;
+    appId?: string;
+    runId?: string;
+    output: string;
+  },
+): Promise<void> {
+  if (opts.all) {
+    // Project-wide wipe using wildcard entity IDs
+    if (opts.dryRun) {
+      printInfo("Would delete ALL memories project-wide.");
+      printInfo("No changes made.");
+      return;
+    }
+
+    if (!opts.force) {
+      const readline = await import("node:readline");
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise<string>((resolve) => {
+        rl.question(`\n  \u26a0  Delete ALL memories across the ENTIRE project? This cannot be undone. [y/N] `, resolve);
+      });
+      rl.close();
+      if (answer.toLowerCase() !== "y") {
+        printInfo("Cancelled.");
+        process.exit(0);
+      }
+    }
+
+    const start = performance.now();
+    let result: Record<string, unknown>;
+    try {
+      result = await timedStatus("Deleting all memories project-wide...", async () => {
+        return backend.delete(undefined, {
+          all: true,
+          userId: "*",
+          agentId: "*",
+          appId: "*",
+          runId: "*",
+        });
+      });
+    } catch (e) {
+      printError(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+    const elapsed = (performance.now() - start) / 1000;
+
+    if (opts.output === "json") {
+      formatJson(result);
+    } else if (opts.output !== "quiet") {
+      if (result.message) {
+        printInfo("Deletion started. Memories will be removed in the background.");
+      } else {
+        printSuccess(`All project memories deleted (${elapsed.toFixed(2)}s)`);
+      }
+    }
+    return;
+  }
+
+  if (opts.dryRun) {
+    let memories: Record<string, unknown>[];
+    try {
+      memories = await backend.listMemories({
+        userId: opts.userId,
+        agentId: opts.agentId,
+        appId: opts.appId,
+        runId: opts.runId,
+      });
+    } catch (e) {
+      printError(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+    printInfo(`Would delete ${memories.length} memories.`);
+    printInfo("No changes made.");
+    return;
+  }
+
+  if (!opts.force) {
+    const scopeParts: string[] = [];
+    if (opts.userId) scopeParts.push(`user=${opts.userId}`);
+    if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
+    if (opts.appId) scopeParts.push(`app=${opts.appId}`);
+    if (opts.runId) scopeParts.push(`run=${opts.runId}`);
+    const scope = scopeParts.length > 0 ? scopeParts.join(", ") : "ALL entities";
+
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise<string>((resolve) => {
+      rl.question(`\n  \u26a0  Delete ALL memories for ${scope}? This cannot be undone. [y/N] `, resolve);
+    });
+    rl.close();
+    if (answer.toLowerCase() !== "y") {
+      printInfo("Cancelled.");
+      process.exit(0);
+    }
+  }
+
+  const start = performance.now();
+  let result: Record<string, unknown>;
+  try {
+    result = await timedStatus("Deleting all memories...", async () => {
+      return backend.delete(undefined, {
+        all: true,
+        userId: opts.userId,
+        agentId: opts.agentId,
+        appId: opts.appId,
+        runId: opts.runId,
+      });
+    });
+  } catch (e) {
+    printError(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const elapsed = (performance.now() - start) / 1000;
+
+  if (opts.output === "json") {
+    formatJson(result);
+  } else if (opts.output !== "quiet") {
+    if (result.message) {
+      printInfo("Deletion started. Memories will be removed in the background.");
+    } else {
+      printSuccess(`All matching memories deleted (${elapsed.toFixed(2)}s)`);
+    }
+  }
+}

cli/node/src/commands/utils.ts

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

cli/node/src/config.ts

@@ -0,0 +1,159 @@
+/**
+ * Configuration management for mem0 CLI.
+ *
+ * Config precedence (highest to lowest):
+ * 1. CLI flags (--api-key, --base-url, etc.)
+ * 2. Environment variables (MEM0_API_KEY, etc.)
+ * 3. Config file (~/.mem0/config.json)
+ * 4. Defaults
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CONFIG_DIR = path.join(os.homedir(), ".mem0");
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export const DEFAULT_BASE_URL = "https://api.mem0.ai";
+export const CONFIG_VERSION = 1;
+
+export interface PlatformConfig {
+  apiKey: string;
+  baseUrl: string;
+}
+
+export interface DefaultsConfig {
+  userId: string;
+  agentId: string;
+  appId: string;
+  runId: string;
+  enableGraph: boolean;
+}
+
+export interface Mem0Config {
+  version: number;
+  defaults: DefaultsConfig;
+  platform: PlatformConfig;
+}
+
+export function createDefaultConfig(): Mem0Config {
+  return {
+    version: CONFIG_VERSION,
+    defaults: {
+      userId: "",
+      agentId: "",
+      appId: "",
+      runId: "",
+      enableGraph: false,
+    },
+    platform: {
+      apiKey: "",
+      baseUrl: DEFAULT_BASE_URL,
+    },
+  };
+}
+
+export function ensureConfigDir(): string {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  return CONFIG_DIR;
+}
+
+export function loadConfig(): Mem0Config {
+  const config = createDefaultConfig();
+
+  if (fs.existsSync(CONFIG_FILE)) {
+    const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+    const data = JSON.parse(raw);
+
+    config.version = data.version ?? CONFIG_VERSION;
+
+    const plat = data.platform ?? {};
+    config.platform.apiKey = plat.api_key ?? "";
+    config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
+
+    const defaults = data.defaults ?? {};
+    config.defaults.userId = defaults.user_id ?? "";
+    config.defaults.agentId = defaults.agent_id ?? "";
+    config.defaults.appId = defaults.app_id ?? "";
+    config.defaults.runId = defaults.run_id ?? "";
+    config.defaults.enableGraph = defaults.enable_graph ?? false;
+  }
+
+  // Environment variable overrides
+  if (process.env.MEM0_API_KEY) config.platform.apiKey = process.env.MEM0_API_KEY;
+  if (process.env.MEM0_BASE_URL) config.platform.baseUrl = process.env.MEM0_BASE_URL;
+  if (process.env.MEM0_USER_ID) config.defaults.userId = process.env.MEM0_USER_ID;
+  if (process.env.MEM0_AGENT_ID) config.defaults.agentId = process.env.MEM0_AGENT_ID;
+  if (process.env.MEM0_APP_ID) config.defaults.appId = process.env.MEM0_APP_ID;
+  if (process.env.MEM0_RUN_ID) config.defaults.runId = process.env.MEM0_RUN_ID;
+  if (process.env.MEM0_ENABLE_GRAPH) {
+    config.defaults.enableGraph = ["true", "1", "yes"].includes(
+      process.env.MEM0_ENABLE_GRAPH.toLowerCase(),
+    );
+  }
+
+  return config;
+}
+
+export function saveConfig(config: Mem0Config): void {
+  ensureConfigDir();
+
+  const data = {
+    version: config.version,
+    defaults: {
+      user_id: config.defaults.userId,
+      agent_id: config.defaults.agentId,
+      app_id: config.defaults.appId,
+      run_id: config.defaults.runId,
+      enable_graph: config.defaults.enableGraph,
+    },
+    platform: {
+      api_key: config.platform.apiKey,
+      base_url: config.platform.baseUrl,
+    },
+  };
+
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
+  fs.chmodSync(CONFIG_FILE, 0o600);
+}
+
+export function redactKey(key: string): string {
+  if (!key) return "(not set)";
+  if (key.length <= 8) return key.slice(0, 2) + "***";
+  return key.slice(0, 4) + "..." + key.slice(-4);
+}
+
+/** Key map from dotted config path to the config object fields. */
+const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
+  "platform.api_key": ["platform", "apiKey"],
+  "platform.base_url": ["platform", "baseUrl"],
+  "defaults.user_id": ["defaults", "userId"],
+  "defaults.agent_id": ["defaults", "agentId"],
+  "defaults.app_id": ["defaults", "appId"],
+  "defaults.run_id": ["defaults", "runId"],
+  "defaults.enable_graph": ["defaults", "enableGraph"],
+};
+
+export function getNestedValue(config: Mem0Config, dottedKey: string): unknown {
+  const mapping = KEY_MAP[dottedKey];
+  if (!mapping) return undefined;
+  const [section, field] = mapping;
+  return (config[section] as unknown as Record<string, unknown>)[field];
+}
+
+export function setNestedValue(config: Mem0Config, dottedKey: string, value: string): boolean {
+  const mapping = KEY_MAP[dottedKey];
+  if (!mapping) return false;
+  const [section, field] = mapping;
+  const obj = config[section] as unknown as Record<string, unknown>;
+
+  const current = obj[field];
+  if (typeof current === "boolean") {
+    obj[field] = ["true", "1", "yes"].includes(value.toLowerCase());
+  } else if (typeof current === "number") {
+    obj[field] = parseInt(value, 10);
+  } else {
+    obj[field] = value;
+  }
+  return true;
+}

cli/node/src/help.ts

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

cli/node/src/index.ts

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+
+/**
+ * Main CLI application — the entrypoint for `mem0`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import type { Mem0Config } from "./config.js";
+import { loadConfig } from "./config.js";
+import { getBackend, type Backend } from "./backend/index.js";
+import { printError, colors } from "./branding.js";
+import { richFormatHelp } from "./help.js";
+
+const _require = createRequire(import.meta.url);
+const VERSION: string = _require("../package.json").version;
+
+const program = new Command();
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function getBackendAndConfig(
+  apiKey?: string,
+  baseUrl?: string,
+): { backend: Backend; config: Mem0Config } {
+  const config = loadConfig();
+
+  if (apiKey) config.platform.apiKey = apiKey;
+  if (baseUrl) config.platform.baseUrl = baseUrl;
+
+  if (!config.platform.apiKey) {
+    printError(
+      "No API key configured.",
+      "Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+    );
+    process.exit(1);
+  }
+
+  return { backend: getBackend(config), config };
+}
+
+function getBackendOnly(apiKey?: string, baseUrl?: string): Backend {
+  return getBackendAndConfig(apiKey, baseUrl).backend;
+}
+
+/**
+ * Resolve entity IDs: CLI flag > config default > undefined.
+ *
+ * If any explicit ID is provided, only use explicit IDs (don't mix
+ * in defaults for other entity types which would over-filter).
+ * If no explicit IDs, fall back to all configured defaults.
+ */
+function resolveIds(
+  config: Mem0Config,
+  opts: {
+    userId?: string;
+    agentId?: string;
+    appId?: string;
+    runId?: string;
+  },
+): { userId?: string; agentId?: string; appId?: string; runId?: string } {
+  const hasExplicit = !!(opts.userId || opts.agentId || opts.appId || opts.runId);
+  if (hasExplicit) {
+    return {
+      userId: opts.userId || undefined,
+      agentId: opts.agentId || undefined,
+      appId: opts.appId || undefined,
+      runId: opts.runId || undefined,
+    };
+  }
+  return {
+    userId: config.defaults.userId || undefined,
+    agentId: config.defaults.agentId || undefined,
+    appId: config.defaults.appId || undefined,
+    runId: config.defaults.runId || undefined,
+  };
+}
+
+/**
+ * Resolve graph tri-state: --no-graph > --graph > config default.
+ */
+function resolveGraph(
+  config: Mem0Config,
+  opts: { graph?: boolean; noGraph?: boolean },
+): boolean {
+  if (opts.noGraph) return false;
+  if (opts.graph) return true;
+  return config.defaults.enableGraph;
+}
+
+// ── Main program ──────────────────────────────────────────────────────────
+
+program
+  .name("mem0")
+  .description(`◆ Mem0 CLI v${VERSION} · Node.js SDK\n\nThe Memory Layer for AI Agents`)
+  .option("--version", "Show version and exit.")
+  .on("option:version", () => {
+    console.log(`  ${colors.brand("◆ Mem0")} CLI v${VERSION}`);
+    process.exit(0);
+  })
+  .usage("<command> [options]")
+  .helpOption("--help", "Show this message and exit.")
+  .addHelpCommand(false)
+  .configureHelp({ formatHelp: richFormatHelp });
+
+// ── Init ──────────────────────────────────────────────────────────────────
+
+program
+  .command("init")
+  .description("Interactive setup wizard for mem0 CLI.")
+  .option("--api-key <key>", "API key (skip prompt).")
+  .option("-u, --user-id <id>", "Default user ID (skip prompt).")
+  .addHelpText("after", "\nExamples:\n  $ mem0 init\n  $ mem0 init --api-key m0-xxx --user-id alice")
+  .action(async (opts) => {
+    const { runInit } = await import("./commands/init.js");
+    await runInit({ apiKey: opts.apiKey, userId: opts.userId });
+  });
+
+// ── Memory: add ───────────────────────────────────────────────────────────
+
+program
+  .command("add [text]")
+  .description("Add a memory from text, messages, file, or stdin.")
+  .option("-u, --user-id <id>", "Scope to user.")
+  .option("--agent-id <id>", "Scope to agent.")
+  .option("--app-id <id>", "Scope to app.")
+  .option("--run-id <id>", "Scope to run.")
+  .option("--messages <json>", "Conversation messages as JSON.")
+  .option("-f, --file <path>", "Read messages from JSON file.")
+  .option("-m, --metadata <json>", "Custom metadata as JSON.")
+  .option("--immutable", "Prevent future updates.", false)
+  .option("--no-infer", "Skip inference, store raw.")
+  .option("--expires <date>", "Expiration date (YYYY-MM-DD).")
+  .option("--categories <value>", "Categories (JSON array or comma-separated).")
+  .option("--graph", "Enable graph memory extraction.", false)
+  .option("--no-graph", "Disable graph memory extraction.")
+  .option("-o, --output <format>", "Output format: text, json, quiet.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", '\nExamples:\n  $ mem0 add "I prefer dark mode" --user-id alice\n  $ echo "text" | mem0 add -u alice\n  $ mem0 add --file msgs.json -u alice -o json')
+  .action(async (text, opts) => {
+    const { cmdAdd } = await import("./commands/memory.js");
+    const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+    const ids = resolveIds(config, opts);
+    const enableGraph = resolveGraph(config, opts);
+    await cmdAdd(backend, text, { ...ids, ...opts, enableGraph });
+  });
+
+// ── Memory: search ────────────────────────────────────────────────────────
+
+program
+  .command("search [query]")
+  .description("Search memories by semantic query.")
+  .option("-u, --user-id <id>", "Filter by user.")
+  .option("--agent-id <id>", "Filter by agent.")
+  .option("--app-id <id>", "Filter by app.")
+  .option("--run-id <id>", "Filter by run.")
+  .option("-k, --top-k <n>", "Number of results.", (v) => parseInt(v), 10)
+  .option("--threshold <n>", "Minimum similarity score.", (v) => parseFloat(v), 0.3)
+  .option("--rerank", "Enable reranking (Platform only).", false)
+  .option("--keyword", "Use keyword search.", false)
+  .option("--filter <json>", "Advanced filter expression (JSON).")
+  .option("--fields <list>", "Specific fields to return (comma-separated).")
+  .option("--graph", "Enable graph in search.", false)
+  .option("--no-graph", "Disable graph in search.")
+  .option("-o, --output <format>", "Output: text, json, table.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", '\nExamples:\n  $ mem0 search "preferences" --user-id alice\n  $ mem0 search "tools" -u alice -o json -k 5\n  $ echo "preferences" | mem0 search -u alice')
+  .action(async (query, opts) => {
+    let resolvedQuery = query;
+    if (!resolvedQuery && !process.stdin.isTTY) {
+      resolvedQuery = fs.readFileSync(0, "utf-8").trim();
+    }
+    if (!resolvedQuery) {
+      printError("No query provided. Pass a query argument or pipe via stdin.");
+      process.exit(1);
+    }
+    const { cmdSearch } = await import("./commands/memory.js");
+    const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+    const ids = resolveIds(config, opts);
+    const enableGraph = resolveGraph(config, opts);
+    await cmdSearch(backend, resolvedQuery, {
+      ...ids,
+      topK: opts.topK,
+      threshold: opts.threshold,
+      rerank: opts.rerank,
+      keyword: opts.keyword,
+      filterJson: opts.filter,
+      fields: opts.fields,
+      enableGraph,
+      output: opts.output,
+    });
+  });
+
+// ── Memory: get ───────────────────────────────────────────────────────────
+
+program
+  .command("get <memoryId>")
+  .description("Get a specific memory by ID.")
+  .option("-o, --output <format>", "Output: text, json.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 get abc-123-def-456\n  $ mem0 get abc-123-def-456 -o json")
+  .action(async (memoryId, opts) => {
+    const { cmdGet } = await import("./commands/memory.js");
+    const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+    await cmdGet(backend, memoryId, { output: opts.output });
+  });
+
+// ── Memory: list ──────────────────────────────────────────────────────────
+
+program
+  .command("list")
+  .description("List memories with optional filters.")
+  .option("-u, --user-id <id>", "Filter by user.")
+  .option("--agent-id <id>", "Filter by agent.")
+  .option("--app-id <id>", "Filter by app.")
+  .option("--run-id <id>", "Filter by run.")
+  .option("--page <n>", "Page number.", (v) => parseInt(v), 1)
+  .option("--page-size <n>", "Results per page.", (v) => parseInt(v), 100)
+  .option("--category <name>", "Filter by category.")
+  .option("--after <date>", "Created after (YYYY-MM-DD).")
+  .option("--before <date>", "Created before (YYYY-MM-DD).")
+  .option("--graph", "Enable graph in listing.", false)
+  .option("--no-graph", "Disable graph in listing.")
+  .option("-o, --output <format>", "Output: text, json, table.", "table")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 list -u alice\n  $ mem0 list --category prefs --after 2024-01-01 -o json")
+  .action(async (opts) => {
+    const { cmdList } = await import("./commands/memory.js");
+    const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+    const ids = resolveIds(config, opts);
+    const enableGraph = resolveGraph(config, opts);
+    await cmdList(backend, {
+      ...ids,
+      page: opts.page,
+      pageSize: opts.pageSize,
+      category: opts.category,
+      after: opts.after,
+      before: opts.before,
+      enableGraph,
+      output: opts.output,
+    });
+  });
+
+// ── Memory: update ────────────────────────────────────────────────────────
+
+program
+  .command("update <memoryId> [text]")
+  .description("Update a memory's text or metadata.")
+  .option("-m, --metadata <json>", "Update metadata (JSON).")
+  .option("-o, --output <format>", "Output: text, json, quiet.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", `\nExamples:\n  $ mem0 update abc-123 "new text"\n  $ mem0 update abc-123 --metadata '{"key":"val"}'\n  $ echo "new text" | mem0 update abc-123`)
+  .action(async (memoryId, text, opts) => {
+    let resolvedText = text;
+    if (!resolvedText && !opts.metadata && !process.stdin.isTTY) {
+      resolvedText = fs.readFileSync(0, "utf-8").trim();
+    }
+    const { cmdUpdate } = await import("./commands/memory.js");
+    const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+    await cmdUpdate(backend, memoryId, resolvedText, { metadata: opts.metadata, output: opts.output });
+  });
+
+// ── Memory: delete (consolidated) ─────────────────────────────────────────
+
+program
+  .command("delete [memoryId]")
+  .description("Delete a memory, all memories matching a scope, or an entity.")
+  .option("--all", "Delete all memories matching scope filters.", false)
+  .option("--entity", "Delete the entity itself and all its memories (cascade).", false)
+  .option("--project", "With --all: delete ALL memories project-wide.", false)
+  .option("--dry-run", "Show what would be deleted without deleting.", false)
+  .option("--force", "Skip confirmation.", false)
+  .option("-u, --user-id <id>", "Scope to user.")
+  .option("--agent-id <id>", "Scope to agent.")
+  .option("--app-id <id>", "Scope to app.")
+  .option("--run-id <id>", "Scope to run.")
+  .option("-o, --output <format>", "Output: text, json, quiet.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", [
+    "\nExamples:",
+    "  $ mem0 delete abc-123-def-456              # single memory",
+    "  $ mem0 delete --all -u alice --force        # all memories for user",
+    "  $ mem0 delete --all --project --force       # project-wide wipe",
+    "  $ mem0 delete --entity -u alice --force     # entity + all its memories",
+  ].join("\n"))
+  .action(async (memoryId, opts) => {
+    // ── Mutual-exclusion checks ──
+    if (memoryId && opts.all) {
+      printError("Cannot combine <memoryId> with --all. Use one or the other.");
+      process.exit(1);
+    }
+    if (memoryId && opts.entity) {
+      printError("Cannot combine <memoryId> with --entity. Use one or the other.");
+      process.exit(1);
+    }
+    if (opts.all && opts.entity) {
+      printError("Cannot combine --all with --entity. Use one or the other.");
+      process.exit(1);
+    }
+    if (!memoryId && !opts.all && !opts.entity) {
+      printError(
+        "Specify a memory ID, --all, or --entity.\n" +
+        "  mem0 delete <id>              Delete a single memory\n" +
+        "  mem0 delete --all [scope]     Delete all memories matching scope\n" +
+        "  mem0 delete --entity [scope]  Delete an entity and all its memories",
+      );
+      process.exit(1);
+    }
+
+    // ── Dispatch: single memory ──
+    if (memoryId) {
+      const { cmdDelete } = await import("./commands/memory.js");
+      const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+      await cmdDelete(backend, memoryId, { output: opts.output, dryRun: opts.dryRun, force: opts.force });
+      return;
+    }
+
+    // ── Dispatch: --all ──
+    if (opts.all) {
+      const { cmdDeleteAll } = await import("./commands/memory.js");
+      const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+      const ids = opts.project
+        ? { userId: undefined, agentId: undefined, appId: undefined, runId: undefined }
+        : resolveIds(config, opts);
+      await cmdDeleteAll(backend, { force: opts.force, dryRun: opts.dryRun, all: opts.project, ...ids, output: opts.output });
+      return;
+    }
+
+    // ── Dispatch: --entity ──
+    if (opts.entity) {
+      const { cmdEntitiesDelete } = await import("./commands/entities.js");
+      const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+      await cmdEntitiesDelete(backend, opts);
+      return;
+    }
+  });
+
+// ── Config subcommands ────────────────────────────────────────────────────
+
+const configCmd = program
+  .command("config")
+  .description("Manage mem0 configuration.")
+  .addHelpCommand(false);
+
+configCmd
+  .command("show")
+  .description("Display current configuration (secrets redacted).")
+  .option("-o, --output <format>", "Output: text, json.", "text")
+  .addHelpText("after", "\nExamples:\n  $ mem0 config show\n  $ mem0 config show -o json")
+  .action(async (opts) => {
+    const { cmdConfigShow } = await import("./commands/config.js");
+    cmdConfigShow({ output: opts.output });
+  });
+
+configCmd
+  .command("get <key>")
+  .description("Get a configuration value.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 config get platform.api_key\n  $ mem0 config get defaults.user_id")
+  .action(async (key) => {
+    const { cmdConfigGet } = await import("./commands/config.js");
+    cmdConfigGet(key);
+  });
+
+configCmd
+  .command("set <key> <value>")
+  .description("Set a configuration value.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 config set defaults.user_id alice\n  $ mem0 config set platform.base_url https://api.mem0.ai")
+  .action(async (key, value) => {
+    const { cmdConfigSet } = await import("./commands/config.js");
+    cmdConfigSet(key, value);
+  });
+
+// ── Entity subcommand group ───────────────────────────────────────────────
+
+const entityCmd = program
+  .command("entity")
+  .description("Manage entities.")
+  .addHelpCommand(false)
+  .configureHelp({ formatHelp: richFormatHelp });
+
+entityCmd
+  .command("list <entityType>")
+  .description("List all entities of a given type.")
+  .option("-o, --output <format>", "Output: table, json.", "table")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 entity list users\n  $ mem0 entity list agents -o json")
+  .action(async (entityType, opts) => {
+    const { cmdEntitiesList } = await import("./commands/entities.js");
+    const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+    await cmdEntitiesList(backend, entityType, { output: opts.output });
+  });
+
+entityCmd
+  .command("delete")
+  .description("Delete an entity and ALL its memories (cascade).")
+  .option("--dry-run", "Show what would be deleted without deleting.", false)
+  .option("-u, --user-id <id>", "Scope to user.")
+  .option("--agent-id <id>", "Scope to agent.")
+  .option("--app-id <id>", "Scope to app.")
+  .option("--run-id <id>", "Scope to run.")
+  .option("--force", "Skip confirmation.", false)
+  .option("-o, --output <format>", "Output: text, json, quiet.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 entity delete --user-id alice --force\n  $ mem0 entity delete --user-id alice --dry-run")
+  .action(async (opts) => {
+    const { cmdEntitiesDelete } = await import("./commands/entities.js");
+    const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+    await cmdEntitiesDelete(backend, opts);
+  });
+
+// ── Utility commands ──────────────────────────────────────────────────────
+
+program
+  .command("status")
+  .description("Check connectivity and authentication.")
+  .option("-o, --output <format>", "Output: text, json.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 status\n  $ mem0 status -o json")
+  .action(async (opts) => {
+    const { cmdStatus } = await import("./commands/utils.js");
+    const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+    await cmdStatus(backend, {
+      userId: config.defaults.userId || undefined,
+      agentId: config.defaults.agentId || undefined,
+      output: opts.output,
+    });
+  });
+
+
+program
+  .command("import <filePath>")
+  .description("Import memories from a JSON file.")
+  .option("-u, --user-id <id>", "Override user ID.")
+  .option("--agent-id <id>", "Override agent ID.")
+  .option("-o, --output <format>", "Output: text, json.", "text")
+  .option("--api-key <key>", "Override API key.")
+  .option("--base-url <url>", "Override API base URL.")
+  .addHelpText("after", "\nExamples:\n  $ mem0 import data.json --user-id alice\n  $ mem0 import data.json -u alice -o json")
+  .action(async (filePath, opts) => {
+    const { cmdImport } = await import("./commands/utils.js");
+    const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+    const ids = resolveIds(config, opts);
+    await cmdImport(backend, filePath, { userId: ids.userId, agentId: ids.agentId, output: opts.output });
+  });
+
+// ── Help (machine-readable) ──────────────────────────────────────────────
+
+program
+  .command("help")
+  .description("Show help. Use --json for machine-readable output (for LLM agents).")
+  .option("--json", "Output machine-readable JSON for LLM agents.", false)
+  .addHelpText("after", "\nExamples:\n  $ mem0 help\n  $ mem0 help --json")
+  .action((opts) => {
+    if (opts.json) {
+      // Load spec from parent directory
+      const __dirname = path.dirname(fileURLToPath(import.meta.url));
+      const specPath = path.join(__dirname, "..", "..", "cli-spec.json");
+      if (fs.existsSync(specPath)) {
+        const spec = JSON.parse(fs.readFileSync(specPath, "utf-8"));
+        console.log(JSON.stringify(spec, null, 2));
+      } else {
+        console.log(JSON.stringify({ name: "mem0", version: VERSION, description: "The Memory Layer for AI Agents" }, null, 2));
+      }
+    } else {
+      const { brand: b } = colors;
+      console.log(`${b("◆ Mem0 CLI")} v${VERSION} · Node.js SDK\n  The Memory Layer for AI Agents\n`);
+      console.log("Usage: mem0 <command> [OPTIONS]\n");
+      console.log("Commands:");
+      console.log("  add              Add a memory from text, messages, file, or stdin");
+      console.log("  search           Search memories by semantic query");
+      console.log("  get              Get a specific memory by ID");
+      console.log("  list             List memories with optional filters");
+      console.log("  update           Update a memory's text or metadata");
+      console.log("  delete           Delete a memory, all memories, or an entity");
+      console.log("  import           Import memories from a JSON file");
+      console.log("  config           Manage configuration (show, get, set)");
+      console.log("  entity           Manage entities (list, delete)");
+      console.log("  init             Interactive setup wizard");
+      console.log("  status           Check connectivity and authentication");
+      console.log();
+      console.log("  mem0 <command> --help    Get help for a command");
+      console.log("  mem0 help --json         Machine-readable help (for LLM agents)");
+      console.log();
+    }
+  });
+
+// ── Entrypoint ────────────────────────────────────────────────────────────
+
+program.parse();

cli/node/src/output.ts

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

cli/node/tests/branding.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for branding utilities.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  BRAND_COLOR,
+  SUCCESS_COLOR,
+  ERROR_COLOR,
+  TAGLINE,
+  LOGO_MINI,
+  printSuccess,
+  printError,
+  printWarning,
+  printInfo,
+  printScope,
+} from "../src/branding.js";
+
+let output: string;
+let errOutput: string;
+const originalLog = console.log;
+const originalError = console.error;
+
+beforeEach(() => {
+  output = "";
+  errOutput = "";
+  console.log = (...args: unknown[]) => {
+    output += args.map(String).join(" ") + "\n";
+  };
+  console.error = (...args: unknown[]) => {
+    errOutput += args.map(String).join(" ") + "\n";
+  };
+});
+
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+});
+
+describe("branding constants", () => {
+  it("has correct brand color", () => {
+    expect(BRAND_COLOR).toBe("#8b5cf6");
+  });
+
+  it("has correct tagline", () => {
+    expect(TAGLINE).toBe("The Memory Layer for AI Agents");
+  });
+
+  it("has correct logo mini", () => {
+    expect(LOGO_MINI).toBe("◆ mem0");
+  });
+});
+
+describe("printSuccess", () => {
+  it("prints success message", () => {
+    printSuccess("Operation completed");
+    expect(output).toContain("Operation completed");
+  });
+});
+
+describe("printError", () => {
+  it("prints error message to stderr", () => {
+    printError("Something failed");
+    expect(errOutput).toContain("Something failed");
+  });
+
+  it("prints hint when provided to stderr", () => {
+    printError("Failed", "Try again");
+    expect(errOutput).toContain("Try again");
+  });
+});
+
+describe("printWarning", () => {
+  it("prints warning message to stderr", () => {
+    printWarning("Be careful");
+    expect(errOutput).toContain("Be careful");
+  });
+});
+
+describe("printInfo", () => {
+  it("prints info message", () => {
+    printInfo("Important note");
+    expect(output).toContain("Important note");
+  });
+});
+
+describe("printScope", () => {
+  it("prints scope when IDs present", () => {
+    printScope({ user_id: "alice", agent_id: "bot" });
+    expect(output).toContain("alice");
+    expect(output).toContain("bot");
+  });
+
+  it("prints nothing when no IDs", () => {
+    printScope({});
+    expect(output).toBe("");
+  });
+});

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

@@ -0,0 +1,156 @@
+/**
+ * Integration tests — invoke CLI as subprocess to test end-to-end.
+ */
+
+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 };
+  // Strip MEM0_ env vars
+  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,
+    };
+  }
+}
+
+describe("CLI Integration — help and version", () => {
+  it("shows help with --help", () => {
+    const result = run(["--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("mem0");
+    expect(result.stdout).toContain("add");
+    expect(result.stdout).toContain("search");
+  });
+
+  it("shows version with --version", () => {
+    const result = run(["--version"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("0.1.0");
+  });
+
+
+  it("help --json produces valid JSON", () => {
+    const result = run(["help", "--json"]);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout);
+    // spec may have cli.name or top-level name
+    const name = parsed.name ?? parsed.cli?.name;
+    expect(name).toBe("mem0");
+  });
+
+  it("shows add help", () => {
+    const result = run(["add", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("user-id");
+    expect(result.stdout).toContain("messages");
+  });
+
+  it("shows search help", () => {
+    const result = run(["search", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("top-k");
+  });
+
+  it("shows list help", () => {
+    const result = run(["list", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("page-size");
+  });
+
+  it("shows delete help with --all, --entity, --project", () => {
+    const result = run(["delete", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--all");
+    expect(result.stdout).toContain("--entity");
+    expect(result.stdout).toContain("--project");
+    expect(result.stdout).toContain("--force");
+    expect(result.stdout.toLowerCase()).toContain("memory");
+  });
+
+  it("delete with no args errors", () => {
+    const result = run(["delete"]);
+    expect(result.exitCode).not.toBe(0);
+    const combined = result.stdout + result.stderr;
+    expect(combined).toContain("--all");
+  });
+
+  it("shows entity list help", () => {
+    const result = run(["entity", "list", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.toLowerCase()).toContain("entitytype");
+  });
+
+  it("shows entity delete help", () => {
+    const result = run(["entity", "delete", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--user-id");
+    expect(result.stdout).toContain("--force");
+  });
+
+  it("shows import help", () => {
+    const result = run(["import", "--help"]);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("add help has --graph flag", () => {
+    const result = run(["add", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--graph");
+  });
+
+  it("search help has --graph flag", () => {
+    const result = run(["search", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--graph");
+  });
+
+  it("list help has --graph flag", () => {
+    const result = run(["list", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--graph");
+  });
+});
+
+describe("CLI Integration — isolated (clean home)", () => {
+  function cleanHome(): string {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+  }
+
+  it("add without API key errors", () => {
+    const home = cleanHome();
+    const result = run(["add", "test", "--user-id", "alice"], { home });
+    expect(result.exitCode).not.toBe(0);
+    const combined = result.stdout + result.stderr;
+    expect(combined.toLowerCase()).toMatch(/api.key|error/i);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  it("config show works with clean home", () => {
+    const home = cleanHome();
+    const result = run(["config", "show"], { home });
+    expect(result.exitCode).toBe(0);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+});

cli/node/tests/commands.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for CLI commands using mock backend.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createMockBackend } from "./setup.js";
+import type { Backend } from "../src/backend/base.js";
+
+let mockBackend: Backend;
+
+// Capture console.log and console.error output
+let output: string;
+let errOutput: string;
+const originalLog = console.log;
+const originalError = console.error;
+
+beforeEach(() => {
+  mockBackend = createMockBackend();
+  output = "";
+  errOutput = "";
+  console.log = (...args: unknown[]) => {
+    output += args.map(String).join(" ") + "\n";
+  };
+  console.error = (...args: unknown[]) => {
+    errOutput += args.map(String).join(" ") + "\n";
+  };
+});
+
+// Restore after each test
+import { afterEach } from "vitest";
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+});
+
+describe("cmdAdd", () => {
+  it("adds text memory", async () => {
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "I prefer dark mode", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(mockBackend.add).toHaveBeenCalledOnce();
+  });
+
+  it("adds from messages JSON", async () => {
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, undefined, {
+      userId: "alice",
+      messages: JSON.stringify([{ role: "user", content: "I love Python" }]),
+      immutable: false,
+      noInfer: false,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(mockBackend.add).toHaveBeenCalledOnce();
+  });
+
+  it("outputs json format", async () => {
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "test", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+      enableGraph: false,
+      output: "json",
+    });
+    expect(output).toContain("results");
+  });
+
+  it("quiet mode produces no memory content", async () => {
+    const { cmdAdd } = await import("../src/commands/memory.js");
+    await cmdAdd(mockBackend, "test", {
+      userId: "alice",
+      immutable: false,
+      noInfer: false,
+      enableGraph: false,
+      output: "quiet",
+    });
+    expect(output).not.toContain("dark mode");
+  });
+});
+
+describe("cmdSearch", () => {
+  it("searches and shows results in text mode", async () => {
+    const { cmdSearch } = await import("../src/commands/memory.js");
+    await cmdSearch(mockBackend, "preferences", {
+      userId: "alice",
+      topK: 10,
+      threshold: 0.3,
+      rerank: false,
+      keyword: false,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(output).toContain("Found 2");
+  });
+
+  it("outputs json format", async () => {
+    const { cmdSearch } = await import("../src/commands/memory.js");
+    await cmdSearch(mockBackend, "preferences", {
+      userId: "alice",
+      topK: 10,
+      threshold: 0.3,
+      rerank: false,
+      keyword: false,
+      enableGraph: false,
+      output: "json",
+    });
+    expect(output).toContain("memory");
+  });
+
+  it("shows no results message", async () => {
+    (mockBackend.search as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    const { cmdSearch } = await import("../src/commands/memory.js");
+    await cmdSearch(mockBackend, "nonexistent", {
+      userId: "alice",
+      topK: 10,
+      threshold: 0.3,
+      rerank: false,
+      keyword: false,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(output).toContain("No memories found");
+  });
+});
+
+describe("cmdGet", () => {
+  it("gets memory in text mode", async () => {
+    const { cmdGet } = await import("../src/commands/memory.js");
+    await cmdGet(mockBackend, "abc-123-def-456", { output: "text" });
+    expect(output).toContain("dark mode");
+  });
+
+  it("gets memory in json mode", async () => {
+    const { cmdGet } = await import("../src/commands/memory.js");
+    await cmdGet(mockBackend, "abc-123-def-456", { output: "json" });
+    expect(output).toContain("memory");
+  });
+});
+
+describe("cmdList", () => {
+  it("lists in table mode", async () => {
+    const { cmdList } = await import("../src/commands/memory.js");
+    await cmdList(mockBackend, {
+      userId: "alice",
+      page: 1,
+      pageSize: 100,
+      enableGraph: false,
+      output: "table",
+    });
+    expect(output).toContain("dark mode");
+  });
+
+  it("shows empty message", async () => {
+    (mockBackend.listMemories as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    const { cmdList } = await import("../src/commands/memory.js");
+    await cmdList(mockBackend, {
+      userId: "alice",
+      page: 1,
+      pageSize: 100,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(output).toContain("No memories found");
+  });
+});
+
+describe("cmdUpdate", () => {
+  it("updates memory", async () => {
+    const { cmdUpdate } = await import("../src/commands/memory.js");
+    await cmdUpdate(mockBackend, "abc-123", "New text", { output: "text" });
+    expect(output.toLowerCase()).toContain("updated");
+  });
+});
+
+describe("cmdDelete", () => {
+  it("deletes memory", async () => {
+    const { cmdDelete } = await import("../src/commands/memory.js");
+    await cmdDelete(mockBackend, "abc-123", { output: "text" });
+    expect(output.toLowerCase()).toContain("deleted");
+  });
+});
+
+describe("cmdDeleteAll", () => {
+  it("deletes all with force", async () => {
+    const { cmdDeleteAll } = await import("../src/commands/memory.js");
+    await cmdDeleteAll(mockBackend, {
+      force: true,
+      userId: "alice",
+      output: "text",
+    });
+    expect(output.toLowerCase()).toContain("deleted");
+  });
+});
+
+describe("cmdVersion", () => {
+  it("shows version", async () => {
+    const { cmdVersion } = await import("../src/commands/utils.js");
+    cmdVersion();
+    expect(output).toContain("0.1.0");
+  });
+});
+
+describe("cmdEntitiesList", () => {
+  it("lists users in table mode", async () => {
+    const { cmdEntitiesList } = await import("../src/commands/entities.js");
+    await cmdEntitiesList(mockBackend, "users", { output: "table" });
+    expect(output).toContain("alice");
+  });
+
+  it("lists in json mode", async () => {
+    const { cmdEntitiesList } = await import("../src/commands/entities.js");
+    await cmdEntitiesList(mockBackend, "users", { output: "json" });
+    expect(output).toContain("alice");
+  });
+});

cli/node/tests/config.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for configuration management.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  createDefaultConfig,
+  loadConfig,
+  saveConfig,
+  redactKey,
+  getNestedValue,
+  setNestedValue,
+  CONFIG_DIR,
+  CONFIG_FILE,
+} from "../src/config.js";
+
+// Use a temp directory for config during tests
+let origConfigDir: string;
+let origConfigFile: string;
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+  // Monkey-patch the module-level constants
+  // We'll use env vars and direct file manipulation instead
+  // Clear MEM0_ env vars
+  for (const key of Object.keys(process.env)) {
+    if (key.startsWith("MEM0_")) {
+      delete process.env[key];
+    }
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("redactKey", () => {
+  it("returns '(not set)' for empty key", () => {
+    expect(redactKey("")).toBe("(not set)");
+  });
+
+  it("redacts short key", () => {
+    expect(redactKey("abc")).toBe("ab***");
+  });
+
+  it("redacts normal key", () => {
+    const result = redactKey("m0-abcdefgh12345678");
+    expect(result).toBe("m0-a...5678");
+    expect(result).not.toContain("abcdefgh");
+  });
+
+  it("redacts exactly 8-char key as short", () => {
+    expect(redactKey("12345678")).toBe("12***");
+  });
+});
+
+describe("createDefaultConfig", () => {
+  it("has correct defaults", () => {
+    const config = createDefaultConfig();
+    expect(config.platform.baseUrl).toBe("https://api.mem0.ai");
+    expect(config.platform.apiKey).toBe("");
+    expect(config.defaults.userId).toBe("");
+    expect(config.defaults.enableGraph).toBe(false);
+  });
+});
+
+describe("getNestedValue", () => {
+  it("gets platform.api_key", () => {
+    const config = createDefaultConfig();
+    config.platform.apiKey = "test-key";
+    expect(getNestedValue(config, "platform.api_key")).toBe("test-key");
+  });
+
+  it("returns undefined for nonexistent key", () => {
+    const config = createDefaultConfig();
+    expect(getNestedValue(config, "nonexistent.key")).toBeUndefined();
+  });
+
+  it("gets defaults.user_id", () => {
+    const config = createDefaultConfig();
+    config.defaults.userId = "alice";
+    expect(getNestedValue(config, "defaults.user_id")).toBe("alice");
+  });
+});
+
+describe("setNestedValue", () => {
+  it("sets platform.api_key", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "platform.api_key", "new-key")).toBe(true);
+    expect(config.platform.apiKey).toBe("new-key");
+  });
+
+  it("returns false for nonexistent key", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "nonexistent.key", "val")).toBe(false);
+  });
+
+  it("sets defaults.user_id", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "defaults.user_id", "bob")).toBe(true);
+    expect(config.defaults.userId).toBe("bob");
+  });
+
+  it("coerces boolean for enable_graph", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "defaults.enable_graph", "true")).toBe(true);
+    expect(config.defaults.enableGraph).toBe(true);
+  });
+});

cli/node/tests/output.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for output formatting.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  formatMemoriesText,
+  formatMemoriesTable,
+  formatJson,
+  formatSingleMemory,
+  formatAddResult,
+  printResultSummary,
+} from "../src/output.js";
+
+let output: string;
+const originalLog = console.log;
+
+beforeEach(() => {
+  output = "";
+  console.log = (...args: unknown[]) => {
+    output += args.map(String).join(" ") + "\n";
+  };
+});
+
+afterEach(() => {
+  console.log = originalLog;
+});
+
+const sampleMemories = [
+  {
+    id: "abc-123-def-456",
+    memory: "User prefers dark mode",
+    score: 0.92,
+    created_at: "2026-02-15T10:30:00Z",
+    categories: ["preferences"],
+  },
+  {
+    id: "ghi-789-jkl-012",
+    memory: "User uses vim keybindings",
+    score: 0.78,
+    created_at: "2026-03-01T14:00:00Z",
+    categories: ["tools"],
+  },
+];
+
+describe("formatMemoriesText", () => {
+  it("shows count and memory content", () => {
+    formatMemoriesText(sampleMemories);
+    expect(output).toContain("Found 2");
+    expect(output).toContain("dark mode");
+    expect(output).toContain("vim keybindings");
+  });
+
+  it("shows scores and IDs", () => {
+    formatMemoriesText(sampleMemories);
+    expect(output).toContain("0.92");
+    expect(output).toContain("abc-123-");
+  });
+});
+
+describe("formatMemoriesTable", () => {
+  it("renders a table with memory content", () => {
+    formatMemoriesTable(sampleMemories);
+    expect(output).toContain("dark mode");
+  });
+});
+
+describe("formatJson", () => {
+  it("outputs valid JSON", () => {
+    formatJson({ key: "value" });
+    expect(JSON.parse(output)).toEqual({ key: "value" });
+  });
+});
+
+describe("formatSingleMemory", () => {
+  it("shows memory text in text mode", () => {
+    formatSingleMemory(sampleMemories[0], "text");
+    expect(output).toContain("dark mode");
+  });
+
+  it("outputs JSON in json mode", () => {
+    formatSingleMemory(sampleMemories[0], "json");
+    expect(output).toContain("memory");
+  });
+});
+
+describe("formatAddResult", () => {
+  it("shows ADD event", () => {
+    formatAddResult({
+      results: [{ id: "abc-123", memory: "Test", event: "ADD" }],
+    });
+    expect(output).toContain("Added");
+  });
+
+  it("shows PENDING event", () => {
+    formatAddResult({
+      results: [{ status: "PENDING", event_id: "evt-12345678" }],
+    });
+    expect(output).toContain("Queued");
+  });
+});
+
+describe("printResultSummary", () => {
+  it("shows count and duration", () => {
+    printResultSummary({ count: 5, durationSecs: 1.23 });
+    expect(output).toContain("5 results");
+    expect(output).toContain("1.23s");
+  });
+
+  it("handles singular", () => {
+    printResultSummary({ count: 1 });
+    expect(output).toContain("1 result");
+    expect(output).not.toContain("results");
+  });
+});

cli/node/tests/setup.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared test helpers and mock factories for mem0 CLI tests.
+ */
+
+import { vi } from "vitest";
+import type { Backend } from "../src/backend/base.js";
+
+/** Create a mock backend with all methods stubbed with sensible defaults. */
+export function createMockBackend(): Backend {
+  return {
+    add: vi.fn().mockResolvedValue({
+      results: [
+        {
+          id: "abc-123-def-456",
+          memory: "User prefers dark mode",
+          event: "ADD",
+        },
+      ],
+    }),
+
+    search: vi.fn().mockResolvedValue([
+      {
+        id: "abc-123-def-456",
+        memory: "User prefers dark mode",
+        score: 0.92,
+        created_at: "2026-02-15T10:30:00Z",
+        categories: ["preferences"],
+      },
+      {
+        id: "ghi-789-jkl-012",
+        memory: "User uses vim keybindings",
+        score: 0.78,
+        created_at: "2026-03-01T14:00:00Z",
+        categories: ["tools"],
+      },
+    ]),
+
+    get: vi.fn().mockResolvedValue({
+      id: "abc-123-def-456",
+      memory: "User prefers dark mode",
+      created_at: "2026-02-15T10:30:00Z",
+      updated_at: "2026-02-20T08:00:00Z",
+      metadata: { source: "onboarding" },
+      categories: ["preferences"],
+    }),
+
+    listMemories: vi.fn().mockResolvedValue([
+      {
+        id: "abc-123-def-456",
+        memory: "User prefers dark mode",
+        created_at: "2026-02-15T10:30:00Z",
+        categories: ["preferences"],
+      },
+      {
+        id: "ghi-789-jkl-012",
+        memory: "User uses vim keybindings",
+        created_at: "2026-03-01T14:00:00Z",
+        categories: ["tools"],
+      },
+    ]),
+
+    update: vi.fn().mockResolvedValue({ id: "abc-123-def-456", memory: "Updated memory" }),
+    delete: vi.fn().mockResolvedValue({ status: "deleted" }),
+    status: vi.fn().mockResolvedValue({
+      connected: true,
+      backend: "platform",
+      base_url: "https://api.mem0.ai",
+    }),
+    deleteEntities: vi.fn().mockResolvedValue({ message: "Entity deleted" }),
+    entities: vi.fn().mockResolvedValue([
+      { name: "alice", count: 5 },
+      { name: "bob", count: 3 },
+    ]),
+  };
+}

cli/node/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

cli/python/Makefile

@@ -0,0 +1,43 @@
+VENV := .venv
+PYTHON := $(VENV)/bin/python
+PIP := $(VENV)/bin/pip
+
+.PHONY: install dev lint format test build clean publish publish-test shell
+
+$(VENV)/bin/activate:
+	python3 -m venv $(VENV)
+	$(PIP) install -U pip
+
+install: $(VENV)/bin/activate
+	$(PIP) install -e .
+
+dev: $(VENV)/bin/activate
+	$(PIP) install -e ".[dev]"
+
+lint: dev
+	$(VENV)/bin/ruff check .
+	$(VENV)/bin/ruff format --check .
+
+format: dev
+	$(VENV)/bin/ruff check --fix .
+	$(VENV)/bin/ruff format .
+
+test: dev
+	$(VENV)/bin/pytest
+
+build: clean $(VENV)/bin/activate
+	$(PIP) install hatch
+	$(VENV)/bin/hatch build
+
+clean:
+	rm -rf dist/
+
+publish: build
+	$(VENV)/bin/hatch publish
+
+publish-test: build
+	$(VENV)/bin/hatch publish --repo test
+
+shell: $(VENV)/bin/activate
+	@echo "Spawning a new shell with the virtual environment activated..."
+	@VIRTUAL_ENV=$(CURDIR)/$(VENV) PATH=$(CURDIR)/$(VENV)/bin:$$PATH exec $(SHELL)

cli/python/README.md

@@ -0,0 +1,39 @@
+# mem0 CLI
+
+The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents.
+
+## Installation
+
+### Using pipx (recommended)
+
+```bash
+pipx install mem0-cli
+```
+
+### Using pip
+
+```bash
+pip install mem0-cli
+```
+
+> **Note:** On macOS with Homebrew Python, `pip install` outside a virtual environment will fail with an `externally-managed-environment` error ([PEP 668](https://peps.python.org/pep-0668/)). Use `pipx` instead, or install inside a virtual environment.
+
+## Quick Start
+
+```bash
+# Set up your configuration
+mem0 init
+
+# Add a memory
+mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
+
+# Search memories
+mem0 search "What are Alice's preferences?" --user-id alice
+
+# List all memories
+mem0 list --user-id alice
+```
+
+## License
+
+Apache-2.0

cli/python/development.md

@@ -0,0 +1,107 @@
+# Development
+
+## Prerequisites
+
+- Python **3.10+**
+- `make` (optional — you can use plain Python commands instead)
+
+All commands below should be run from the `python/` directory:
+
+```bash
+cd python
+```
+
+## Setup
+
+### Using Make (recommended)
+
+All `make` targets automatically create a virtual environment (`.venv/`) and install the required dependencies — no manual setup needed.
+
+```bash
+# Install the CLI in editable mode
+make install
+
+# Install with dev tools (tests + linting)
+make dev
+```
+
+### Using Python directly
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+
+# Install in editable mode
+pip install -e .
+
+# With dev tools
+pip install -e ".[dev]"
+```
+
+## Make targets
+
+| Target              | Description                                      |
+| ------------------- | ------------------------------------------------ |
+| `make install`      | Create venv and install the CLI (editable mode)  |
+| `make dev`          | Create venv and install CLI + dev dependencies   |
+| `make test`         | Run all tests (installs dev deps if needed)      |
+| `make lint`         | Run linter and format check                      |
+| `make format`       | Auto-fix lint issues and format code             |
+| `make build`        | Build distribution packages                      |
+| `make clean`        | Remove `dist/`                                   |
+| `make publish`      | Build and publish to PyPI                        |
+| `make publish-test` | Build and publish to Test PyPI                   |
+| `make shell`        | Open a new shell with the venv activated         |
+
+## Run tests
+
+```bash
+# Using Make
+make test
+
+# Using Python directly
+pytest
+
+# Run a specific test file
+pytest tests/test_cli_integration.py
+
+# Run a single test
+pytest -k test_help
+```
+
+## Run the CLI
+
+```bash
+# Using Make — drop into an activated shell
+make shell
+mem0 --help
+
+# Using Python directly (with venv activated)
+source .venv/bin/activate
+mem0 --help
+mem0 version
+
+# Or run without activating
+.venv/bin/mem0 --help
+```
+
+## Lint
+
+```bash
+# Using Make
+make lint      # check only
+make format    # auto-fix
+
+# Using Python directly (with venv activated)
+ruff check .
+ruff format .
+```
+
+## Optional extras
+
+### OSS integration
+
+```bash
+pip install -e ".[oss]"
+```

cli/python/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mem0-cli"
+version = "0.1.0"
+description = "The official CLI for mem0 — the memory layer for AI agents"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "mem0.ai", email = "founders@mem0.ai" },
+]
+keywords = ["mem0", "memory", "ai", "agents", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+oss = ["mem0ai>=0.1.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+mem0 = "mem0_cli.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mem0_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mem0_cli"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort (import sorting)
+    "W",    # pycodestyle warnings
+    "UP",   # pyupgrade (modern Python syntax)
+    "B",    # flake8-bugbear (common bugs)
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific rules
+]
+ignore = [
+    "E501",   # line too long — handled by formatter
+    "B008",   # function call in default arg — required by Typer's Option/Argument pattern
+    "SIM108", # ternary operator — sometimes less readable
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mem0_cli"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

cli/python/src/mem0_cli/__init__.py

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

cli/python/src/mem0_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running with `python -m mem0_cli`."""
+
+from mem0_cli.app import main
+
+main()

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

@@ -0,0 +1,5 @@
+"""Backend abstraction layer for mem0 CLI."""
+
+from mem0_cli.backend.base import Backend, get_backend
+
+__all__ = ["Backend", "get_backend"]

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

@@ -0,0 +1,113 @@
+"""Abstract backend interface and factory."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from mem0_cli.config import Mem0Config
+
+
+class Backend(ABC):
+    """Abstract interface for mem0 backends."""
+
+    @abstractmethod
+    def add(
+        self,
+        content: str | None = None,
+        messages: list[dict] | None = None,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        metadata: dict | None = None,
+        immutable: bool = False,
+        infer: bool = True,
+        expires: str | None = None,
+        categories: list[str] | None = None,
+        enable_graph: bool = False,
+    ) -> dict: ...
+
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        top_k: int = 10,
+        threshold: float = 0.3,
+        rerank: bool = False,
+        keyword: bool = False,
+        filters: dict | None = None,
+        fields: list[str] | None = None,
+        enable_graph: bool = False,
+    ) -> list[dict]: ...
+
+    @abstractmethod
+    def get(self, memory_id: str) -> dict: ...
+
+    @abstractmethod
+    def list_memories(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        page: int = 1,
+        page_size: int = 100,
+        category: str | None = None,
+        after: str | None = None,
+        before: str | None = None,
+        enable_graph: bool = False,
+    ) -> list[dict]: ...
+
+    @abstractmethod
+    def update(
+        self, memory_id: str, content: str | None = None, metadata: dict | None = None
+    ) -> dict: ...
+
+    @abstractmethod
+    def delete(
+        self,
+        memory_id: str | None = None,
+        *,
+        all: bool = False,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+    ) -> dict: ...
+
+    @abstractmethod
+    def delete_entities(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+    ) -> dict: ...
+
+    @abstractmethod
+    def status(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+    ) -> dict[str, Any]: ...
+
+    @abstractmethod
+    def entities(self, entity_type: str) -> list[dict]: ...
+
+
+
+def get_backend(config: Mem0Config) -> Backend:
+    """Return the Platform backend."""
+    from mem0_cli.backend.platform import PlatformBackend
+
+    return PlatformBackend(config.platform)

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

@@ -0,0 +1,325 @@
+"""Platform (SaaS) backend — communicates with api.mem0.ai."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from mem0_cli.backend.base import Backend
+from mem0_cli.config import PlatformConfig
+
+
+class PlatformBackend(Backend):
+    """Backend that talks to the mem0 Platform API."""
+
+    def __init__(self, config: PlatformConfig) -> None:
+        self.config = config
+        self.base_url = config.base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Token {config.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        resp = self._client.request(method, path, **kwargs)
+        if resp.status_code == 401:
+            raise AuthError("Authentication failed. Your API key may be invalid or expired.")
+        if resp.status_code == 404:
+            raise NotFoundError(f"Resource not found: {path}")
+        if resp.status_code == 400:
+            # Extract API error detail when available
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise APIError(f"Bad request to {path}: {detail}")
+        resp.raise_for_status()
+        if resp.status_code == 204:
+            return {}
+        return resp.json()
+
+    def add(
+        self,
+        content: str | None = None,
+        messages: list[dict] | None = None,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        metadata: dict | None = None,
+        immutable: bool = False,
+        infer: bool = True,
+        expires: str | None = None,
+        categories: list[str] | None = None,
+        enable_graph: bool = False,
+    ) -> dict:
+        payload: dict[str, Any] = {}
+
+        if messages:
+            payload["messages"] = messages
+        elif content:
+            payload["messages"] = [{"role": "user", "content": content}]
+
+        if user_id:
+            payload["user_id"] = user_id
+        if agent_id:
+            payload["agent_id"] = agent_id
+        if app_id:
+            payload["app_id"] = app_id
+        if run_id:
+            payload["run_id"] = run_id
+        if metadata:
+            payload["metadata"] = metadata
+        if immutable:
+            payload["immutable"] = True
+        if not infer:
+            payload["infer"] = False
+        if expires:
+            payload["expiration_date"] = expires
+        if categories:
+            payload["categories"] = categories
+        if enable_graph:
+            payload["enable_graph"] = True
+
+        return self._request("POST", "/v1/memories/", json=payload)
+
+    def _build_filters(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        extra_filters: dict | None = None,
+    ) -> dict | None:
+        """Build a filters dict for v2 API endpoints.
+
+        Entity IDs are ANDed (all provided IDs must match).
+        Extra filters (date ranges, categories) are also ANDed.
+        """
+        # If caller passed a pre-built filter structure (e.g. --filter from CLI), use it directly
+        if extra_filters and ("AND" in extra_filters or "OR" in extra_filters):
+            return extra_filters
+
+        # Build AND conditions for entity IDs
+        and_conditions: list[dict[str, Any]] = []
+        if user_id:
+            and_conditions.append({"user_id": user_id})
+        if agent_id:
+            and_conditions.append({"agent_id": agent_id})
+        if app_id:
+            and_conditions.append({"app_id": app_id})
+        if run_id:
+            and_conditions.append({"run_id": run_id})
+
+        # Append any extra filters (dates, categories)
+        if extra_filters:
+            for k, v in extra_filters.items():
+                and_conditions.append({k: v})
+
+        if len(and_conditions) == 1:
+            return and_conditions[0]
+        elif and_conditions:
+            return {"AND": and_conditions}
+        else:
+            return None
+
+    def search(
+        self,
+        query: str,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        top_k: int = 10,
+        threshold: float = 0.3,
+        rerank: bool = False,
+        keyword: bool = False,
+        filters: dict | None = None,
+        fields: list[str] | None = None,
+        enable_graph: bool = False,
+    ) -> list[dict]:
+        payload: dict[str, Any] = {"query": query, "top_k": top_k, "threshold": threshold}
+
+        api_filters = self._build_filters(
+            user_id=user_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            run_id=run_id,
+            extra_filters=filters,
+        )
+        if api_filters:
+            payload["filters"] = api_filters
+        if rerank:
+            payload["rerank"] = True
+        if keyword:
+            payload["keyword_search"] = True
+        if fields:
+            payload["fields"] = fields
+        if enable_graph:
+            payload["enable_graph"] = True
+
+        result = self._request("POST", "/v2/memories/search/", json=payload)
+        return (
+            result
+            if isinstance(result, list)
+            else result.get("results", result.get("memories", []))
+        )
+
+    def get(self, memory_id: str) -> dict:
+        return self._request("GET", f"/v1/memories/{memory_id}/")
+
+    def list_memories(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+        page: int = 1,
+        page_size: int = 100,
+        category: str | None = None,
+        after: str | None = None,
+        before: str | None = None,
+        enable_graph: bool = False,
+    ) -> list[dict]:
+        payload: dict[str, Any] = {}
+        params = {"page": str(page), "page_size": str(page_size)}
+
+        # Build filters for v2 API — entity IDs and date filters go inside "filters"
+        extra: dict[str, Any] = {}
+        if category:
+            extra["categories"] = {"contains": category}
+        if after:
+            extra["created_at"] = {**(extra.get("created_at", {})), "gte": after}
+        if before:
+            extra["created_at"] = {**(extra.get("created_at", {})), "lte": before}
+
+        api_filters = self._build_filters(
+            user_id=user_id,
+            agent_id=agent_id,
+            app_id=app_id,
+            run_id=run_id,
+            extra_filters=extra if extra else None,
+        )
+        if api_filters:
+            payload["filters"] = api_filters
+        if enable_graph:
+            payload["enable_graph"] = True
+
+        result = self._request("POST", "/v2/memories/", json=payload, params=params)
+        return (
+            result
+            if isinstance(result, list)
+            else result.get("results", result.get("memories", []))
+        )
+
+    def update(
+        self, memory_id: str, content: str | None = None, metadata: dict | None = None
+    ) -> dict:
+        payload: dict[str, Any] = {}
+        if content:
+            payload["text"] = content
+        if metadata:
+            payload["metadata"] = metadata
+        return self._request("PUT", f"/v1/memories/{memory_id}/", json=payload)
+
+    def delete(
+        self,
+        memory_id: str | None = None,
+        *,
+        all: bool = False,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+    ) -> dict:
+        if all:
+            params: dict[str, str] = {}
+            if user_id:
+                params["user_id"] = user_id
+            if agent_id:
+                params["agent_id"] = agent_id
+            if app_id:
+                params["app_id"] = app_id
+            if run_id:
+                params["run_id"] = run_id
+            return self._request("DELETE", "/v1/memories/", params=params)
+        elif memory_id:
+            return self._request("DELETE", f"/v1/memories/{memory_id}/")
+        else:
+            raise ValueError("Either memory_id or --all is required")
+
+    def delete_entities(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+        app_id: str | None = None,
+        run_id: str | None = None,
+    ) -> dict:
+        params: dict[str, str] = {}
+        if user_id:
+            params["user_id"] = user_id
+        if agent_id:
+            params["agent_id"] = agent_id
+        if app_id:
+            params["app_id"] = app_id
+        if run_id:
+            params["run_id"] = run_id
+        if not params:
+            raise ValueError("At least one entity ID is required for delete_entities.")
+        return self._request("DELETE", "/v1/entities/", params=params)
+
+    def status(
+        self,
+        *,
+        user_id: str | None = None,
+        agent_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Check connectivity by making a lightweight API call."""
+        try:
+            # If entity IDs are available, validate with a minimal memories list
+            if user_id or agent_id:
+                payload: dict[str, Any] = {}
+                params = {"page": "1", "page_size": "1"}
+                api_filters = self._build_filters(user_id=user_id, agent_id=agent_id)
+                if api_filters:
+                    payload["filters"] = api_filters
+                self._request("POST", "/v2/memories/", json=payload, params=params)
+            else:
+                # No entity IDs — use entities endpoint to validate API key
+                self._request("GET", "/v1/entities/")
+            return {"connected": True, "backend": "platform", "base_url": self.base_url}
+        except Exception as e:
+            return {"connected": False, "backend": "platform", "error": str(e)}
+
+    def entities(self, entity_type: str) -> list[dict]:
+        result = self._request("GET", "/v1/entities/")
+        items = result if isinstance(result, list) else result.get("results", [])
+        # Filter by entity type client-side (API returns all types)
+        type_map = {"users": "user", "agents": "agent", "apps": "app", "runs": "run"}
+        target_type = type_map.get(entity_type)
+        if target_type:
+            items = [e for e in items if e.get("type", "").lower() == target_type]
+        return items
+
+
+
+class AuthError(Exception):
+    pass
+
+
+class NotFoundError(Exception):
+    pass
+
+
+class APIError(Exception):
+    pass

cli/python/src/mem0_cli/branding.py

@@ -0,0 +1,130 @@
+"""Branding and ASCII art for mem0 CLI."""
+
+import os
+import sys
+import time
+from contextlib import contextmanager
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.status import Status
+from rich.text import Text
+
+# stderr console for spinners, errors, and timing messages
+_err = Console(stderr=True)
+
+LOGO = r"""
+███╗   ███╗███████╗███╗   ███╗ ██████╗      ██████╗██╗     ██╗
+████╗ ████║██╔════╝████╗ ████║██╔═████╗    ██╔════╝██║     ██║
+██╔████╔██║█████╗  ██╔████╔██║██║██╔██║    ██║     ██║     ██║
+██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║████╔╝██║    ██║     ██║     ██║
+██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝    ╚██████╗███████╗██║
+╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝      ╚═════╝╚══════╝╚═╝
+"""
+
+LOGO_MINI = "◆ mem0"
+
+TAGLINE = "The Memory Layer for AI Agents"
+
+BRAND_COLOR = "#8b5cf6"  # Purple
+ACCENT_COLOR = "#a78bfa"
+SUCCESS_COLOR = "#22c55e"
+ERROR_COLOR = "#ef4444"
+WARNING_COLOR = "#f59e0b"
+DIM_COLOR = "#6b7280"
+
+
+def _sym(fancy: str, plain: str) -> str:
+    """Return *fancy* when stdout is a TTY with colour, else *plain*."""
+    if not sys.stdout.isatty() or os.environ.get("NO_COLOR") is not None:
+        return plain
+    return fancy
+
+
+def print_banner(console: Console) -> None:
+    """Print the mem0 welcome banner."""
+    logo_text = Text(LOGO, style=f"bold {BRAND_COLOR}")
+    tagline = Text(f"  {TAGLINE}\n", style=f"{ACCENT_COLOR}")
+
+    content = Text()
+    content.append_text(logo_text)
+    content.append_text(tagline)
+
+    panel = Panel(
+        content,
+        border_style=BRAND_COLOR,
+        padding=(0, 2),
+        subtitle=f"[{DIM_COLOR}]Python SDK · v{_get_version()}[/]",
+        subtitle_align="right",
+    )
+    console.print(panel)
+
+
+def print_success(console: Console, message: str) -> None:
+    sym = _sym("✓", "[ok]")
+    console.print(f"[{SUCCESS_COLOR}]{sym}[/] {message}")
+
+
+def print_error(console: Console, message: str, hint: str | None = None) -> None:
+    sym = _sym("✗", "[error]")
+    console.print(f"[{ERROR_COLOR}]{sym} Error:[/] {message}")
+    if hint:
+        console.print(f"  [{DIM_COLOR}]{hint}[/]")
+
+
+def print_warning(console: Console, message: str) -> None:
+    sym = _sym("⚠", "[warn]")
+    console.print(f"[{WARNING_COLOR}]{sym}[/] {message}")
+
+
+def print_info(console: Console, message: str) -> None:
+    sym = _sym("◆", "*")
+    console.print(f"[{BRAND_COLOR}]{sym}[/] {message}")
+
+
+@contextmanager
+def timed_status(console: Console, message: str):
+    """Spinner with automatic timing. Yields a context object for setting the final message.
+
+    The spinner and timing output are sent to stderr (via ``_err``) so they
+    never contaminate machine-readable stdout.  The *console* parameter is
+    kept for backward compatibility but is not used for spinner output.
+    """
+
+    class _Ctx:
+        def __init__(self):
+            self.success_msg = ""
+            self.error_msg = ""
+
+    ctx = _Ctx()
+    start = time.perf_counter()
+    try:
+        with Status(f"[{DIM_COLOR}]{message}[/]", console=_err):
+            yield ctx
+    except Exception:
+        elapsed = time.perf_counter() - start
+        if ctx.error_msg:
+            print_error(_err, f"{ctx.error_msg} ({elapsed:.2f}s)")
+        raise
+    else:
+        elapsed = time.perf_counter() - start
+        if ctx.success_msg:
+            print_success(_err, f"{ctx.success_msg} ({elapsed:.2f}s)")
+
+
+def print_scope(console: Console, **ids: str | None) -> None:
+    """Show active entity scope if any IDs are set."""
+    parts = []
+    for key, val in ids.items():
+        if val:
+            label = key.replace("_", " ").replace("id", "ID").strip()
+            parts.append(f"{label}={val}")
+    if parts:
+        scope_str = ", ".join(parts)
+        console.print(f"  [{DIM_COLOR}]Scope: {scope_str}[/]")
+
+
+def _get_version() -> str:
+    from mem0_cli import __version__
+
+    return __version__

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

@@ -0,0 +1 @@
+"""CLI command modules."""

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

@@ -0,0 +1,108 @@
+"""Config management commands: show, set, get."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+from mem0_cli.branding import ACCENT_COLOR, BRAND_COLOR, DIM_COLOR, print_error, print_success
+from mem0_cli.config import (
+    get_nested_value,
+    load_config,
+    redact_key,
+    save_config,
+    set_nested_value,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def cmd_config_show(*, output: str = "text") -> None:
+    """Display current configuration (secrets redacted)."""
+    from mem0_cli.output import format_json_envelope
+
+    config = load_config()
+
+    if output == "json":
+        format_json_envelope(
+            console,
+            command="config show",
+            data={
+                "defaults": {
+                    "user_id": config.defaults.user_id or None,
+                    "agent_id": config.defaults.agent_id or None,
+                    "app_id": config.defaults.app_id or None,
+                    "run_id": config.defaults.run_id or None,
+                    "enable_graph": config.defaults.enable_graph,
+                },
+                "platform": {
+                    "api_key": redact_key(config.platform.api_key),
+                    "base_url": config.platform.base_url,
+                },
+            },
+        )
+        return
+
+    console.print()
+    console.print(f"  [{BRAND_COLOR}]◆ mem0 Configuration[/]\n")
+
+    table = Table(border_style=BRAND_COLOR, header_style=f"bold {ACCENT_COLOR}", padding=(0, 2))
+    table.add_column("Key", style="bold")
+    table.add_column("Value")
+
+    # Defaults
+    table.add_row(
+        "defaults.user_id",
+        config.defaults.user_id or f"[{DIM_COLOR}](not set)[/]",
+    )
+    table.add_row(
+        "defaults.agent_id",
+        config.defaults.agent_id or f"[{DIM_COLOR}](not set)[/]",
+    )
+    table.add_row(
+        "defaults.app_id",
+        config.defaults.app_id or f"[{DIM_COLOR}](not set)[/]",
+    )
+    table.add_row(
+        "defaults.run_id",
+        config.defaults.run_id or f"[{DIM_COLOR}](not set)[/]",
+    )
+    table.add_row(
+        "defaults.enable_graph",
+        str(config.defaults.enable_graph).lower(),
+    )
+    table.add_row("", "")
+
+    # Platform
+    table.add_row("[bold]platform.api_key[/]", redact_key(config.platform.api_key))
+    table.add_row("platform.base_url", config.platform.base_url)
+
+    console.print(table)
+    console.print()
+
+
+def cmd_config_get(key: str) -> None:
+    """Get a config value."""
+    config = load_config()
+    value = get_nested_value(config, key)
+
+    if value is None:
+        print_error(err_console, f"Unknown config key: {key}")
+    else:
+        # Redact secrets
+        if "api_key" in key or "key" in key.split(".")[-1:]:
+            console.print(redact_key(str(value)))
+        else:
+            console.print(str(value))
+
+
+def cmd_config_set(key: str, value: str) -> None:
+    """Set a config value."""
+    config = load_config()
+    if set_nested_value(config, key, value):
+        save_config(config)
+        display = redact_key(value) if "key" in key else value
+        print_success(console, f"{key} = {display}")
+    else:
+        print_error(err_console, f"Unknown config key: {key}")

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

@@ -0,0 +1,133 @@
+"""Entity management commands."""
+
+from __future__ import annotations
+
+import time as _time
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from mem0_cli.backend.base import Backend
+from mem0_cli.branding import (
+    ACCENT_COLOR,
+    BRAND_COLOR,
+    DIM_COLOR,
+    print_error,
+    print_info,
+    print_success,
+    timed_status,
+)
+from mem0_cli.output import format_json
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def cmd_entities_list(backend: Backend, entity_type: str, *, output: str) -> None:
+    """List entities of a given type."""
+    valid_types = {"users", "agents", "apps", "runs"}
+    if entity_type not in valid_types:
+        print_error(err_console, f"Invalid entity type: {entity_type}. Use: {', '.join(valid_types)}")
+        raise typer.Exit(1)
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, f"Fetching {entity_type}...") as _ts:
+        try:
+            results = backend.entities(entity_type)
+        except Exception as e:
+            print_error(err_console, str(e), hint="This feature may require the mem0 Platform.")
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, results)
+        return
+
+    if not results:
+        print_info(console, f"No {entity_type} found.")
+        return
+
+    table = Table(border_style=BRAND_COLOR, header_style=f"bold {ACCENT_COLOR}", padding=(0, 1))
+    table.add_column("Name / ID", style="bold")
+    table.add_column("Created", max_width=12)
+
+    for entity in results:
+        name = entity.get("name", entity.get("id", "—"))
+        created = str(entity.get("created_at", "—"))[:10]
+        table.add_row(str(name), created)
+
+    console.print()
+    console.print(table)
+    console.print(f"  [{DIM_COLOR}]{len(results)} {entity_type} ({_elapsed:.2f}s)[/]")
+    console.print()
+
+
+def cmd_entities_delete(
+    backend: Backend,
+    *,
+    user_id: str | None,
+    agent_id: str | None,
+    app_id: str | None,
+    run_id: str | None,
+    force: bool,
+    dry_run: bool = False,
+    output: str,
+) -> None:
+    """Delete an entity and all its memories (cascade delete)."""
+    if not any([user_id, agent_id, app_id, run_id]):
+        print_error(err_console, "Provide at least one of --user-id, --agent-id, --app-id, --run-id.")
+        raise typer.Exit(1)
+
+    if dry_run:
+        scope_parts = []
+        if user_id:
+            scope_parts.append(f"user={user_id}")
+        if agent_id:
+            scope_parts.append(f"agent={agent_id}")
+        if app_id:
+            scope_parts.append(f"app={app_id}")
+        if run_id:
+            scope_parts.append(f"run={run_id}")
+        scope = ", ".join(scope_parts)
+        print_info(console, f"Would delete entity {scope} and all its memories.")
+        print_info(console, "No changes made (dry run).")
+        return
+
+    if not force:
+        scope_parts = []
+        if user_id:
+            scope_parts.append(f"user={user_id}")
+        if agent_id:
+            scope_parts.append(f"agent={agent_id}")
+        if app_id:
+            scope_parts.append(f"app={app_id}")
+        if run_id:
+            scope_parts.append(f"run={run_id}")
+        scope = ", ".join(scope_parts)
+
+        confirm = typer.confirm(
+            f"\n  \u26a0  Delete entity {scope} AND all its memories? This cannot be undone."
+        )
+        if not confirm:
+            print_info(console, "Cancelled.")
+            raise typer.Exit(0)
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Deleting entity...") as _ts:
+        try:
+            result = backend.delete_entities(
+                user_id=user_id,
+                agent_id=agent_id,
+                app_id=app_id,
+                run_id=run_id,
+            )
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, result)
+    elif output != "quiet":
+        print_success(console, f"Entity deleted with all memories ({_elapsed:.2f}s)")

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

@@ -0,0 +1,194 @@
+"""mem0 init — interactive setup wizard."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from mem0_cli.branding import (
+    BRAND_COLOR,
+    DIM_COLOR,
+    print_banner,
+    print_error,
+    print_info,
+    print_success,
+)
+from mem0_cli.config import Mem0Config, save_config
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _prompt_secret(label: str) -> str:
+    """Prompt for a secret value, echoing '*' for each character typed."""
+    sys.stdout.write(label)
+    sys.stdout.flush()
+
+    chars: list[str] = []
+
+    if sys.platform == "win32":
+        import msvcrt
+
+        while True:
+            ch = msvcrt.getwch()
+            if ch in ("\r", "\n"):
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+                break
+            if ch == "\x03":
+                raise KeyboardInterrupt
+            if ch in ("\x08", "\x7f"):  # backspace
+                if chars:
+                    chars.pop()
+                    sys.stdout.write("\b \b")
+                    sys.stdout.flush()
+            else:
+                chars.append(ch)
+                sys.stdout.write("*")
+                sys.stdout.flush()
+    else:
+        import termios
+        import tty
+
+        fd = sys.stdin.fileno()
+        old_settings = termios.tcgetattr(fd)
+        try:
+            tty.setraw(fd)
+            while True:
+                ch = sys.stdin.read(1)
+                if ch in ("\r", "\n"):
+                    sys.stdout.write("\r\n")
+                    sys.stdout.flush()
+                    break
+                if ch == "\x03":
+                    raise KeyboardInterrupt
+                if ch in ("\x7f", "\x08"):  # backspace/delete
+                    if chars:
+                        chars.pop()
+                        sys.stdout.write("\b \b")
+                        sys.stdout.flush()
+                elif ch == "\x15":  # Ctrl+U — clear line
+                    sys.stdout.write("\b \b" * len(chars))
+                    sys.stdout.flush()
+                    chars = []
+                elif ch >= " ":  # ignore other control characters
+                    chars.append(ch)
+                    sys.stdout.write("*")
+                    sys.stdout.flush()
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+    return "".join(chars)
+
+
+def run_init(*, api_key: str | None = None, user_id: 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.
+    """
+    config = Mem0Config()
+
+    # Fully non-interactive when both flags provided
+    if api_key and user_id:
+        config.platform.api_key = api_key
+        config.defaults.user_id = user_id
+        _validate_platform(config)
+        save_config(config)
+        print_success(console, "Configuration saved to ~/.mem0/config.json")
+        return
+
+    # Non-TTY without full flags -> error
+    if not sys.stdin.isatty() and (not api_key or not user_id):
+        print_error(
+            err_console,
+            "Non-interactive terminal detected and required flags missing.",
+            hint="Run: mem0 init --api-key <key> --user-id <id>",
+        )
+        raise typer.Exit(1)
+
+    print_banner(console)
+    console.print()
+    print_info(console, "Welcome! Let's set up your mem0 CLI.\n")
+
+    # Use provided flags or prompt
+    if api_key:
+        config.platform.api_key = api_key
+    else:
+        _setup_platform(config)
+
+    if user_id:
+        config.defaults.user_id = user_id
+    else:
+        _setup_defaults(config)
+
+    _validate_platform(config)
+
+    save_config(config)
+    console.print()
+    print_success(console, "Configuration saved to ~/.mem0/config.json")
+    console.print()
+    console.print(f"  [{DIM_COLOR}]Get started:[/]")
+    if config.defaults.user_id:
+        console.print(f'  [{DIM_COLOR}]  mem0 add "I prefer dark mode"[/]')
+        console.print(f'  [{DIM_COLOR}]  mem0 search "preferences"[/]')
+    else:
+        console.print(f'  [{DIM_COLOR}]  mem0 add "I prefer dark mode" --user-id alice[/]')
+        console.print(f'  [{DIM_COLOR}]  mem0 search "preferences" --user-id alice[/]')
+    console.print()
+
+
+def _setup_platform(config: Mem0Config) -> None:
+    """Platform setup flow."""
+    console.print()
+    console.print(f"  [{DIM_COLOR}]Get your API key at https://app.mem0.ai/dashboard/api-keys[/]")
+    console.print()
+
+    console.print(f"  [{BRAND_COLOR}]API Key[/]: ", end="")
+    api_key = _prompt_secret("")
+    if not api_key:
+        print_error(err_console, "API key is required.")
+        raise typer.Exit(1)
+
+    config.platform.api_key = api_key
+
+
+def _setup_defaults(config: Mem0Config) -> None:
+    """Collect default entity IDs."""
+    console.print()
+    print_info(console, "Set default entity IDs (press Enter to skip).\n")
+
+    user_id = Prompt.ask(
+        f"  [{BRAND_COLOR}]Default User ID[/] [{DIM_COLOR}](recommended)[/]",
+        default="mem0-cli",
+    )
+    if user_id:
+        config.defaults.user_id = user_id
+
+
+def _validate_platform(config: Mem0Config) -> None:
+    """Validate platform connection after all inputs are collected."""
+    console.print()
+    print_info(console, "Validating connection...")
+    try:
+        from mem0_cli.backend.platform import PlatformBackend
+
+        backend = PlatformBackend(config.platform)
+        status = backend.status(
+            user_id=config.defaults.user_id or None,
+            agent_id=config.defaults.agent_id or None,
+        )
+        if status.get("connected"):
+            print_success(console, "Connected to mem0 Platform!")
+        else:
+            print_error(
+                err_console,
+                f"Could not connect: {status.get('error', 'Unknown error')}",
+                hint="Check your API key and try again.",
+            )
+    except Exception as e:
+        print_error(err_console, f"Connection test failed: {e}")

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

@@ -0,0 +1,469 @@
+"""Memory CRUD commands: add, search, get, list, update, delete."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time as _time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from mem0_cli.backend.base import Backend
+from mem0_cli.branding import (
+    print_error,
+    print_info,
+    print_scope,
+    print_success,
+    timed_status,
+)
+from mem0_cli.output import (
+    format_add_result,
+    format_json,
+    format_memories_table,
+    format_memories_text,
+    format_single_memory,
+    print_result_summary,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def cmd_add(
+    backend: Backend,
+    text: str | None,
+    *,
+    user_id: str | None,
+    agent_id: str | None,
+    app_id: str | None,
+    run_id: str | None,
+    messages: str | None,
+    file: Path | None,
+    metadata: str | None,
+    immutable: bool,
+    no_infer: bool,
+    expires: str | None,
+    categories: str | None,
+    enable_graph: bool = False,
+    output: str = "text",
+) -> None:
+    """Add a memory."""
+    msgs = None
+    content = text
+
+    # Read from file
+    if file:
+        try:
+            raw = Path(file).read_text()
+            msgs = json.loads(raw)
+        except (FileNotFoundError, json.JSONDecodeError) as e:
+            print_error(err_console, f"Failed to read file: {e}")
+            raise typer.Exit(1) from None
+
+    # Parse messages JSON
+    elif messages:
+        try:
+            msgs = json.loads(messages)
+        except json.JSONDecodeError as e:
+            print_error(err_console, f"Invalid JSON in --messages: {e}")
+            raise typer.Exit(1) from None
+
+    # Read from stdin if no text and stdin is piped
+    elif not content and not sys.stdin.isatty():
+        content = sys.stdin.read().strip()
+
+    if not content and not msgs:
+        print_error(
+            err_console, "No content provided. Pass text, --messages, --file, or pipe via stdin."
+        )
+        raise typer.Exit(1)
+
+    meta = None
+    if metadata:
+        try:
+            meta = json.loads(metadata)
+        except json.JSONDecodeError:
+            print_error(err_console, "Invalid JSON in --metadata.")
+            raise typer.Exit(1) from None
+
+    cats = None
+    if categories:
+        try:
+            cats = json.loads(categories)
+        except json.JSONDecodeError:
+            cats = [c.strip() for c in categories.split(",")]
+
+    with timed_status(err_console, "Adding memory...") as ts:
+        try:
+            result = backend.add(
+                content=content,
+                messages=msgs,
+                user_id=user_id,
+                agent_id=agent_id,
+                app_id=app_id,
+                run_id=run_id,
+                metadata=meta,
+                immutable=immutable,
+                infer=not no_infer,
+                expires=expires,
+                categories=cats,
+                enable_graph=enable_graph,
+            )
+        except Exception as e:
+            ts.error_msg = str(e)
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+
+    if output == "quiet":
+        return
+
+    if output == "json":
+        format_add_result(console, result, output)
+        return
+
+    console.print()
+    print_scope(console, user_id=user_id, agent_id=agent_id, app_id=app_id, run_id=run_id)
+    # Count results
+    results = result if isinstance(result, list) else result.get("results", [result])
+    count = len(results) if results else 0
+    print_success(
+        console, f"Memory processed — {count} memor{'y' if count == 1 else 'ies'} extracted"
+    )
+    format_add_result(console, result, output)
+
+
+def cmd_search(
+    backend: Backend,
+    query: str,
+    *,
+    user_id: str | None,
+    agent_id: str | None,
+    app_id: str | None,
+    run_id: str | None,
+    top_k: int,
+    threshold: float,
+    rerank: bool,
+    keyword: bool,
+    filter_json: str | None,
+    fields: str | None,
+    enable_graph: bool = False,
+    output: str = "text",
+) -> None:
+    """Search memories."""
+    filters = None
+    if filter_json:
+        try:
+            filters = json.loads(filter_json)
+        except json.JSONDecodeError:
+            print_error(err_console, "Invalid JSON in --filter.")
+            raise typer.Exit(1) from None
+
+    field_list = None
+    if fields:
+        field_list = [f.strip() for f in fields.split(",")]
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Searching memories...") as _ts:
+        try:
+            results = backend.search(
+                query,
+                user_id=user_id,
+                agent_id=agent_id,
+                app_id=app_id,
+                run_id=run_id,
+                top_k=top_k,
+                threshold=threshold,
+                rerank=rerank,
+                keyword=keyword,
+                filters=filters,
+                fields=field_list,
+                enable_graph=enable_graph,
+            )
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, results)
+    elif output == "table":
+        if results:
+            format_memories_table(console, results)
+            print_result_summary(
+                console, len(results), duration_secs=_elapsed, user_id=user_id, agent_id=agent_id
+            )
+        else:
+            console.print()
+            print_info(console, "No memories found matching your query.")
+            console.print()
+    else:
+        if results:
+            format_memories_text(console, results)
+            print_result_summary(
+                console, len(results), duration_secs=_elapsed, user_id=user_id, agent_id=agent_id
+            )
+        else:
+            console.print()
+            print_info(console, "No memories found matching your query.")
+            console.print()
+
+
+def cmd_get(backend: Backend, memory_id: str, *, output: str) -> None:
+    """Get a specific memory by ID."""
+    with timed_status(err_console, "Fetching memory...") as _ts:
+        try:
+            result = backend.get(memory_id)
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+
+    format_single_memory(console, result, output)
+
+
+def cmd_list(
+    backend: Backend,
+    *,
+    user_id: str | None,
+    agent_id: str | None,
+    app_id: str | None,
+    run_id: str | None,
+    page: int,
+    page_size: int,
+    category: str | None,
+    after: str | None,
+    before: str | None,
+    enable_graph: bool = False,
+    output: str = "table",
+) -> None:
+    """List memories."""
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Listing memories...") as _ts:
+        try:
+            results = backend.list_memories(
+                user_id=user_id,
+                agent_id=agent_id,
+                app_id=app_id,
+                run_id=run_id,
+                page=page,
+                page_size=page_size,
+                category=category,
+                after=after,
+                before=before,
+                enable_graph=enable_graph,
+            )
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, results)
+    elif output == "table":
+        if results:
+            format_memories_table(console, results)
+            print_result_summary(
+                console,
+                len(results),
+                duration_secs=_elapsed,
+                page=page,
+                user_id=user_id,
+                agent_id=agent_id,
+            )
+        else:
+            console.print()
+            print_info(console, "No memories found.")
+            console.print()
+    else:
+        if results:
+            format_memories_text(console, results, title="memories")
+            print_result_summary(
+                console,
+                len(results),
+                duration_secs=_elapsed,
+                page=page,
+                user_id=user_id,
+                agent_id=agent_id,
+            )
+        else:
+            console.print()
+            print_info(console, "No memories found.")
+            console.print()
+
+
+def cmd_update(
+    backend: Backend,
+    memory_id: str,
+    text: str | None,
+    *,
+    metadata: str | None,
+    output: str,
+) -> None:
+    """Update a memory."""
+    meta = None
+    if metadata:
+        try:
+            meta = json.loads(metadata)
+        except json.JSONDecodeError:
+            print_error(err_console, "Invalid JSON in --metadata.")
+            raise typer.Exit(1) from None
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Updating memory...") as _ts:
+        try:
+            result = backend.update(memory_id, content=text, metadata=meta)
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, result)
+    elif output != "quiet":
+        print_success(console, f"Memory {memory_id[:8]} updated ({_elapsed:.2f}s)")
+
+
+def cmd_delete(
+    backend: Backend,
+    memory_id: str,
+    *,
+    dry_run: bool = False,
+    force: bool = False,
+    output: str,
+) -> None:
+    """Delete a single memory by ID."""
+    if dry_run:
+        # Fetch and display what would be deleted
+        try:
+            mem = backend.get(memory_id)
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+        format_single_memory(console, mem, output)
+        print_info(console, "No changes made (dry run).")
+        return
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Deleting...") as _ts:
+        try:
+            result = backend.delete(memory_id=memory_id)
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, result)
+    elif output != "quiet":
+        print_success(console, f"Memory {memory_id[:8]} deleted ({_elapsed:.2f}s)")
+
+
+def cmd_delete_all(
+    backend: Backend,
+    *,
+    force: bool,
+    dry_run: bool = False,
+    all_: bool = False,
+    user_id: str | None,
+    agent_id: str | None,
+    app_id: str | None,
+    run_id: str | None,
+    output: str,
+) -> None:
+    """Delete all memories matching a scope."""
+    if all_:
+        # Project-wide wipe using wildcard entity IDs
+        if dry_run:
+            print_info(console, "Would delete ALL memories project-wide.")
+            print_info(console, "No changes made (dry run).")
+            return
+
+        if not force:
+            confirm = typer.confirm(
+                "\n  ⚠  Delete ALL memories across the ENTIRE project? This cannot be undone."
+            )
+            if not confirm:
+                print_info(console, "Cancelled.")
+                raise typer.Exit(0)
+
+        _start = _time.perf_counter()
+        with timed_status(err_console, "Deleting all memories project-wide...") as _ts:
+            try:
+                result = backend.delete(
+                    all=True,
+                    user_id="*",
+                    agent_id="*",
+                    app_id="*",
+                    run_id="*",
+                )
+            except Exception as e:
+                print_error(err_console, str(e))
+                raise typer.Exit(1) from None
+        _elapsed = _time.perf_counter() - _start
+
+        if output == "json":
+            format_json(console, result)
+        elif output != "quiet":
+            if isinstance(result, dict) and "message" in result:
+                print_info(console, "Deletion started. Memories will be removed in the background.")
+            else:
+                print_success(console, f"All project memories deleted ({_elapsed:.2f}s)")
+        return
+
+    if dry_run:
+        # List matching memories and show count
+        try:
+            results = backend.list_memories(
+                user_id=user_id,
+                agent_id=agent_id,
+                app_id=app_id,
+                run_id=run_id,
+            )
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+        count = len(results)
+        print_info(console, f"Would delete {count} memor{'y' if count == 1 else 'ies'}.")
+        print_info(console, "No changes made (dry run).")
+        return
+
+    if not force:
+        scope_parts = []
+        if user_id:
+            scope_parts.append(f"user={user_id}")
+        if agent_id:
+            scope_parts.append(f"agent={agent_id}")
+        if app_id:
+            scope_parts.append(f"app={app_id}")
+        if run_id:
+            scope_parts.append(f"run={run_id}")
+        scope = ", ".join(scope_parts) if scope_parts else "ALL entities"
+
+        confirm = typer.confirm(f"\n  ⚠  Delete ALL memories for {scope}? This cannot be undone.")
+        if not confirm:
+            print_info(console, "Cancelled.")
+            raise typer.Exit(0)
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Deleting all memories...") as _ts:
+        try:
+            result = backend.delete(
+                all=True,
+                user_id=user_id,
+                agent_id=agent_id,
+                app_id=app_id,
+                run_id=run_id,
+            )
+        except Exception as e:
+            print_error(err_console, str(e))
+            raise typer.Exit(1) from None
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json(console, result)
+    elif output != "quiet":
+        if isinstance(result, dict) and "message" in result:
+            print_info(console, "Deletion started. Memories will be removed in the background.")
+        else:
+            print_success(console, f"All matching memories deleted ({_elapsed:.2f}s)")

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

@@ -0,0 +1,141 @@
+"""Utility commands: status, version, import."""
+
+from __future__ import annotations
+
+import json
+import time as _time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import track
+
+from mem0_cli import __version__
+from mem0_cli.backend.base import Backend
+from mem0_cli.branding import (
+    BRAND_COLOR,
+    DIM_COLOR,
+    ERROR_COLOR,
+    SUCCESS_COLOR,
+    print_error,
+    print_success,
+    timed_status,
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def cmd_status(
+    backend: Backend,
+    *,
+    user_id: str | None = None,
+    agent_id: str | None = None,
+    output: str = "text",
+) -> None:
+    """Check connectivity and auth."""
+    from mem0_cli.output import format_json_envelope
+
+    _start = _time.perf_counter()
+    with timed_status(err_console, "Checking connection...") as _ts:
+        result = backend.status(user_id=user_id, agent_id=agent_id)
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json_envelope(
+            console,
+            command="status",
+            data={
+                "connected": result.get("connected", False),
+                "backend": result.get("backend", "?"),
+                "base_url": result.get("base_url", ""),
+                "latency_ms": int(_elapsed * 1000),
+            },
+            duration_ms=int(_elapsed * 1000),
+        )
+        return
+
+    lines = []
+    if result.get("connected"):
+        lines.append(f"  [{SUCCESS_COLOR}]●[/] Connected")
+    else:
+        lines.append(f"  [{ERROR_COLOR}]●[/] Disconnected")
+
+    lines.append(f"  [{DIM_COLOR}]Backend:[/]  {result.get('backend', '?')}")
+    if result.get("base_url"):
+        lines.append(f"  [{DIM_COLOR}]API URL:[/]  {result['base_url']}")
+    if result.get("error"):
+        lines.append(f"  [{ERROR_COLOR}]Error:[/]    {result['error']}")
+    lines.append(f"  [{DIM_COLOR}]Latency:[/]  {_elapsed:.2f}s")
+
+    content = "\n".join(lines)
+    panel = Panel(
+        content,
+        title=f"[{BRAND_COLOR}]Connection Status[/]",
+        title_align="left",
+        border_style=BRAND_COLOR,
+        padding=(1, 1),
+    )
+    console.print()
+    console.print(panel)
+    console.print()
+
+
+def cmd_version() -> None:
+    """Show version."""
+    console.print(f"  [{BRAND_COLOR}]◆ Mem0[/] CLI v{__version__}")
+
+
+def cmd_import(
+    backend: Backend,
+    file_path: str,
+    *,
+    user_id: str | None,
+    agent_id: str | None,
+    output: str = "text",
+) -> None:
+    """Import memories from a JSON file."""
+    from mem0_cli.output import format_json_envelope
+
+    try:
+        data = json.loads(Path(file_path).read_text())
+    except (FileNotFoundError, json.JSONDecodeError) as e:
+        print_error(err_console, f"Failed to read file: {e}")
+        raise typer.Exit(1) from None
+
+    if not isinstance(data, list):
+        data = [data]
+
+    added = 0
+    failed = 0
+    _start = _time.perf_counter()
+    for item in track(data, description=f"[{DIM_COLOR}]Importing memories...[/]", console=err_console):
+        content = item.get("memory", item.get("text", item.get("content", "")))
+        if not content:
+            failed += 1
+            continue
+        try:
+            backend.add(
+                content=content,
+                user_id=user_id or item.get("user_id"),
+                agent_id=agent_id or item.get("agent_id"),
+                metadata=item.get("metadata"),
+            )
+            added += 1
+        except Exception:
+            failed += 1
+    _elapsed = _time.perf_counter() - _start
+
+    if output == "json":
+        format_json_envelope(
+            console,
+            command="import",
+            data={"added": added, "failed": failed, "duration_s": round(_elapsed, 2)},
+            duration_ms=int(_elapsed * 1000),
+        )
+        return
+
+    print_success(err_console, f"Imported {added} memories ({_elapsed:.2f}s)")
+    if failed:
+        print_error(err_console, f"{failed} memories failed to import.")

cli/python/src/mem0_cli/config.py

@@ -0,0 +1,176 @@
+"""Configuration management for mem0 CLI.
+
+Config precedence (highest to lowest):
+1. CLI flags (--api-key, --base-url, etc.)
+2. Environment variables (MEM0_API_KEY, etc.)
+3. Config file (~/.mem0/config.json)
+4. Defaults
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path.home() / ".mem0"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+DEFAULT_BASE_URL = "https://api.mem0.ai"
+CONFIG_VERSION = 1
+
+
+@dataclass
+class PlatformConfig:
+    api_key: str = ""
+    base_url: str = DEFAULT_BASE_URL
+
+
+@dataclass
+class DefaultsConfig:
+    user_id: str = ""
+    agent_id: str = ""
+    app_id: str = ""
+    run_id: str = ""
+    enable_graph: bool = False
+
+
+@dataclass
+class Mem0Config:
+    version: int = CONFIG_VERSION
+    defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
+    platform: PlatformConfig = field(default_factory=PlatformConfig)
+
+
+def ensure_config_dir() -> Path:
+    """Create ~/.mem0 directory with secure permissions if it doesn't exist."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    os.chmod(CONFIG_DIR, stat.S_IRWXU)  # 0700
+    return CONFIG_DIR
+
+
+def load_config() -> Mem0Config:
+    """Load config from file, applying env var overrides."""
+    config = Mem0Config()
+
+    if CONFIG_FILE.exists():
+        with open(CONFIG_FILE) as f:
+            data = json.load(f)
+
+        config.version = data.get("version", CONFIG_VERSION)
+
+        plat = data.get("platform", {})
+        config.platform.api_key = plat.get("api_key", "")
+        config.platform.base_url = plat.get("base_url", DEFAULT_BASE_URL)
+
+        defaults = data.get("defaults", {})
+        config.defaults.user_id = defaults.get("user_id", "")
+        config.defaults.agent_id = defaults.get("agent_id", "")
+        config.defaults.app_id = defaults.get("app_id", "")
+        config.defaults.run_id = defaults.get("run_id", "")
+        config.defaults.enable_graph = defaults.get("enable_graph", False)
+
+    # Environment variable overrides
+    env_key = os.environ.get("MEM0_API_KEY")
+    if env_key:
+        config.platform.api_key = env_key
+
+    env_base = os.environ.get("MEM0_BASE_URL")
+    if env_base:
+        config.platform.base_url = env_base
+
+    env_user_id = os.environ.get("MEM0_USER_ID")
+    if env_user_id:
+        config.defaults.user_id = env_user_id
+
+    env_agent_id = os.environ.get("MEM0_AGENT_ID")
+    if env_agent_id:
+        config.defaults.agent_id = env_agent_id
+
+    env_app_id = os.environ.get("MEM0_APP_ID")
+    if env_app_id:
+        config.defaults.app_id = env_app_id
+
+    env_run_id = os.environ.get("MEM0_RUN_ID")
+    if env_run_id:
+        config.defaults.run_id = env_run_id
+
+    env_graph = os.environ.get("MEM0_ENABLE_GRAPH")
+    if env_graph:
+        config.defaults.enable_graph = env_graph.lower() in ("true", "1", "yes")
+
+    return config
+
+
+def save_config(config: Mem0Config) -> None:
+    """Write config to disk with secure permissions."""
+    ensure_config_dir()
+
+    data: dict[str, Any] = {
+        "version": config.version,
+        "defaults": {
+            "user_id": config.defaults.user_id,
+            "agent_id": config.defaults.agent_id,
+            "app_id": config.defaults.app_id,
+            "run_id": config.defaults.run_id,
+            "enable_graph": config.defaults.enable_graph,
+        },
+        "platform": {
+            "api_key": config.platform.api_key,
+            "base_url": config.platform.base_url,
+        },
+    }
+
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+
+    os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+
+
+def redact_key(key: str) -> str:
+    """Redact an API key for display: m0-xxx...xxx"""
+    if not key:
+        return "(not set)"
+    if len(key) <= 8:
+        return key[:2] + "***"
+    return key[:4] + "..." + key[-4:]
+
+
+def get_nested_value(config: Mem0Config, dotted_key: str) -> Any:
+    """Get a config value by dotted path, e.g. 'platform.api_key'."""
+    parts = dotted_key.split(".")
+    obj: Any = config
+    for part in parts:
+        if hasattr(obj, part):
+            obj = getattr(obj, part)
+        else:
+            return None
+    return obj
+
+
+def set_nested_value(config: Mem0Config, dotted_key: str, value: str) -> bool:
+    """Set a config value by dotted path. Returns True on success."""
+    parts = dotted_key.split(".")
+    obj: Any = config
+    for part in parts[:-1]:
+        if hasattr(obj, part):
+            obj = getattr(obj, part)
+        else:
+            return False
+
+    final_key = parts[-1]
+    if not hasattr(obj, final_key):
+        return False
+
+    current = getattr(obj, final_key)
+    # Type coercion
+    if isinstance(current, bool):
+        value = value.lower() in ("true", "1", "yes")  # type: ignore[assignment]
+    elif isinstance(current, int):
+        value = int(value)  # type: ignore[assignment]
+
+    setattr(obj, final_key, value)
+    return True

cli/python/src/mem0_cli/output.py

@@ -0,0 +1,242 @@
+"""Output formatting for mem0 CLI — text, JSON, table, quiet modes."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from mem0_cli.branding import ACCENT_COLOR, BRAND_COLOR, DIM_COLOR, SUCCESS_COLOR, _sym
+
+
+def format_memories_text(console: Console, memories: list[dict], title: str = "memories") -> None:
+    """Render memories in human-friendly text mode."""
+    count = len(memories)
+    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]
+        score = mem.get("score")
+        created = _format_date(mem.get("created_at"))
+        category = mem.get("categories", [None])
+        if isinstance(category, list):
+            category = category[0] if category else None
+
+        line = Text()
+        line.append(f"  {i}. ", style="bold")
+        line.append(memory_text, style="white")
+        console.print(line)
+
+        details = []
+        if score is not None:
+            details.append(f"Score: {score:.2f}")
+        if mem_id:
+            details.append(f"ID: {mem_id}")
+        if created:
+            details.append(f"Created: {created}")
+        if category:
+            details.append(f"Category: {category}")
+
+        if details:
+            detail_str = " · ".join(details)
+            console.print(f"     [{DIM_COLOR}]{detail_str}[/]")
+        console.print()
+
+
+def format_memories_table(console: Console, memories: list[dict]) -> None:
+    """Render memories in a rich table."""
+    table = Table(
+        border_style=BRAND_COLOR,
+        header_style=f"bold {ACCENT_COLOR}",
+        row_styles=["", "dim"],
+        padding=(0, 1),
+    )
+    table.add_column("ID", style="dim", max_width=10)
+    table.add_column("Memory", max_width=50, no_wrap=False)
+    table.add_column("Category", max_width=14)
+    table.add_column("Created", max_width=12)
+
+    for mem in memories:
+        mem_id = mem.get("id", "")[:8]
+        memory_text = mem.get("memory", mem.get("text", ""))
+        if len(memory_text) > 60:
+            memory_text = memory_text[:57] + "..."
+        categories = mem.get("categories", [])
+        cat = categories[0] if isinstance(categories, list) and categories else "—"
+        created = _format_date(mem.get("created_at")) or "—"
+        table.add_row(mem_id, memory_text, cat, created)
+
+    console.print()
+    console.print(table)
+    console.print()
+
+
+def format_json(console: Console, data: Any) -> None:
+    """Output data as pretty-printed JSON."""
+    console.print_json(json.dumps(data, default=str))
+
+
+def format_single_memory(console: Console, mem: dict, output: str = "text") -> None:
+    """Format a single memory for display."""
+    if output == "json":
+        format_json(console, mem)
+        return
+
+    memory_text = mem.get("memory", mem.get("text", ""))
+    mem_id = mem.get("id", "")
+
+    lines = []
+    lines.append(f"  [white bold]{memory_text}[/]")
+    lines.append("")
+
+    if mem_id:
+        lines.append(f"  [{DIM_COLOR}]ID:[/]         {mem_id}")
+    created = _format_date(mem.get("created_at"))
+    if created:
+        lines.append(f"  [{DIM_COLOR}]Created:[/]    {created}")
+    updated = _format_date(mem.get("updated_at"))
+    if updated:
+        lines.append(f"  [{DIM_COLOR}]Updated:[/]    {updated}")
+    meta = mem.get("metadata")
+    if meta:
+        lines.append(f"  [{DIM_COLOR}]Metadata:[/]   {json.dumps(meta)}")
+    categories = mem.get("categories")
+    if categories:
+        cat_str = ", ".join(categories) if isinstance(categories, list) else categories
+        lines.append(f"  [{DIM_COLOR}]Categories:[/] {cat_str}")
+
+    content = "\n".join(lines)
+    panel = Panel(
+        content,
+        title=f"[{BRAND_COLOR}]Memory[/]",
+        title_align="left",
+        border_style=BRAND_COLOR,
+        padding=(1, 1),
+    )
+    console.print()
+    console.print(panel)
+    console.print()
+
+
+def format_add_result(console: Console, result: dict | list, output: str = "text") -> None:
+    """Format the result of an add operation."""
+    if output == "json":
+        format_json(console, result)
+        return
+    if output == "quiet":
+        return
+
+    # result from API is typically {"results": [...]}
+    results = result if isinstance(result, list) else result.get("results", [result])
+    if not results:
+        console.print(f"  [{DIM_COLOR}]No memories extracted.[/]")
+        return
+
+    console.print()
+    for r in results:
+        # Detect async PENDING response from Platform API
+        if r.get("status") == "PENDING":
+            event_id = r.get("event_id", "")[:8]
+            icon = f"[{ACCENT_COLOR}]{_sym('⧗', '...')}[/]"
+            parts = [f"  {icon} [{DIM_COLOR}]{'Queued':<10}[/]"]
+            parts.append("[white]Processing in background[/]")
+            if event_id:
+                parts.append(f"[{DIM_COLOR}](event {event_id})[/]")
+            console.print("  ".join(parts))
+            continue
+
+        event = r.get("event", "ADD")
+        memory = r.get("memory") or r.get("text") or r.get("content") or r.get("data") or ""
+        mem_id = (r.get("id") or r.get("memory_id") or "")[:8]
+
+        if event == "ADD":
+            icon = f"[{SUCCESS_COLOR}]+[/]"
+            label = "Added"
+        elif event == "UPDATE":
+            icon = f"[{ACCENT_COLOR}]~[/]"
+            label = "Updated"
+        elif event == "DELETE":
+            icon = "[red]-[/]"
+            label = "Deleted"
+        elif event == "NOOP":
+            icon = f"[{DIM_COLOR}]·[/]"
+            label = "No change"
+        else:
+            icon = f"[{DIM_COLOR}]?[/]"
+            label = event
+
+        # Build the display line
+        parts = [f"  {icon} [{DIM_COLOR}]{label:<10}[/]"]
+        if memory:
+            parts.append(f"[white]{memory}[/]")
+        if mem_id:
+            parts.append(f"[{DIM_COLOR}]({mem_id})[/]")
+        console.print("  ".join(parts))
+    console.print()
+
+
+def format_json_envelope(
+    console: Console,
+    *,
+    command: str,
+    data: Any,
+    duration_ms: int | None = None,
+    scope: dict | None = None,
+    count: int | None = None,
+    status: str = "success",
+    error: str | None = None,
+) -> None:
+    """Output structured JSON envelope for AI agent consumption."""
+    envelope: dict[str, Any] = {
+        "status": status,
+        "command": command,
+    }
+    if duration_ms is not None:
+        envelope["duration_ms"] = duration_ms
+    if scope is not None:
+        envelope["scope"] = scope
+    if count is not None:
+        envelope["count"] = count
+    if error:
+        envelope["error"] = error
+    envelope["data"] = data
+    console.print_json(json.dumps(envelope, default=str))
+
+
+def print_result_summary(
+    console: Console,
+    count: int,
+    *,
+    duration_secs: float | None = None,
+    page: int | None = None,
+    **scope_ids: str | None,
+) -> None:
+    """Print a summary footer after result lists."""
+    parts = [f"{count} result{'s' if count != 1 else ''}"]
+    if page is not None:
+        parts.append(f"page {page}")
+    scope_parts = [f"{k.replace('_', ' ')}={v}" for k, v in scope_ids.items() if v]
+    if scope_parts:
+        parts.append(", ".join(scope_parts))
+    if duration_secs is not None:
+        parts.append(f"{duration_secs:.2f}s")
+
+    summary = " · ".join(parts)
+    console.print(f"  [{DIM_COLOR}]{summary}[/]")
+    console.print()
+
+
+def _format_date(dt_str: str | None) -> str | None:
+    if not dt_str:
+        return None
+    try:
+        dt = datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
+        return dt.strftime("%Y-%m-%d")
+    except (ValueError, AttributeError):
+        return str(dt_str)[:10] if dt_str else None

cli/python/tests/conftest.py

@@ -0,0 +1,109 @@
+"""Shared fixtures for mem0 CLI tests."""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import MagicMock
+
+import pytest
+
+from mem0_cli.backend.base import Backend
+from mem0_cli.config import Mem0Config
+
+
+@pytest.fixture(autouse=True)
+def isolate_config(tmp_path, monkeypatch):
+    """Redirect config to a temp directory so tests don't touch real config."""
+    fake_config_dir = tmp_path / ".mem0"
+    fake_config_file = fake_config_dir / "config.json"
+    monkeypatch.setattr("mem0_cli.config.CONFIG_DIR", fake_config_dir)
+    monkeypatch.setattr("mem0_cli.config.CONFIG_FILE", fake_config_file)
+    # Also patch the commands that import config
+    monkeypatch.setattr("mem0_cli.commands.config_cmd.CONFIG_DIR", fake_config_dir, raising=False)
+    # Clear any MEM0 env vars
+    for key in list(os.environ.keys()):
+        if key.startswith("MEM0_"):
+            monkeypatch.delenv(key, raising=False)
+    return fake_config_dir
+
+
+@pytest.fixture
+def mock_backend():
+    """Return a mock backend with all methods stubbed."""
+    backend = MagicMock(spec=Backend)
+
+    # Default return values
+    backend.add.return_value = {
+        "results": [
+            {
+                "id": "abc-123-def-456",
+                "memory": "User prefers dark mode",
+                "event": "ADD",
+            }
+        ]
+    }
+
+    backend.search.return_value = [
+        {
+            "id": "abc-123-def-456",
+            "memory": "User prefers dark mode",
+            "score": 0.92,
+            "created_at": "2026-02-15T10:30:00Z",
+            "categories": ["preferences"],
+        },
+        {
+            "id": "ghi-789-jkl-012",
+            "memory": "User uses vim keybindings",
+            "score": 0.78,
+            "created_at": "2026-03-01T14:00:00Z",
+            "categories": ["tools"],
+        },
+    ]
+
+    backend.get.return_value = {
+        "id": "abc-123-def-456",
+        "memory": "User prefers dark mode",
+        "created_at": "2026-02-15T10:30:00Z",
+        "updated_at": "2026-02-20T08:00:00Z",
+        "metadata": {"source": "onboarding"},
+        "categories": ["preferences"],
+    }
+
+    backend.list_memories.return_value = [
+        {
+            "id": "abc-123-def-456",
+            "memory": "User prefers dark mode",
+            "created_at": "2026-02-15T10:30:00Z",
+            "categories": ["preferences"],
+        },
+        {
+            "id": "ghi-789-jkl-012",
+            "memory": "User uses vim keybindings",
+            "created_at": "2026-03-01T14:00:00Z",
+            "categories": ["tools"],
+        },
+    ]
+
+    backend.update.return_value = {"id": "abc-123-def-456", "memory": "Updated memory"}
+    backend.delete.return_value = {"status": "deleted"}
+    backend.status.return_value = {
+        "connected": True,
+        "backend": "platform",
+        "base_url": "https://api.mem0.ai",
+    }
+    backend.delete_entities.return_value = {"message": "Entity deleted"}
+    backend.entities.return_value = [
+        {"name": "alice", "count": 5},
+        {"name": "bob", "count": 3},
+    ]
+
+    return backend
+
+
+@pytest.fixture
+def sample_config():
+    """Return a sample config object."""
+    config = Mem0Config()
+    config.platform.api_key = "m0-test-key-12345678"
+    config.platform.base_url = "https://api.mem0.ai"
+    return config

cli/python/tests/test_branding.py

@@ -0,0 +1,54 @@
+"""Tests for branding and output helpers."""
+
+from __future__ import annotations
+
+from io import StringIO
+
+from rich.console import Console
+
+from mem0_cli.branding import print_banner, print_error, print_info, print_success, print_warning
+
+
+def _make_console() -> tuple[Console, StringIO]:
+    buf = StringIO()
+    return Console(file=buf, force_terminal=False, no_color=True, width=80), buf
+
+
+class TestBranding:
+    def test_print_banner(self):
+        console, buf = _make_console()
+        print_banner(console)
+        output = buf.getvalue()
+        # Banner contains the mem0 ASCII art and tagline
+        assert "Memory Layer" in output or "mem" in output.lower()
+
+    def test_print_success(self):
+        console, buf = _make_console()
+        print_success(console, "It worked!")
+        output = buf.getvalue()
+        assert "It worked!" in output
+
+    def test_print_error(self):
+        console, buf = _make_console()
+        print_error(console, "Something failed", hint="Try this fix")
+        output = buf.getvalue()
+        assert "Something failed" in output
+        assert "Try this fix" in output
+
+    def test_print_error_no_hint(self):
+        console, buf = _make_console()
+        print_error(console, "Failed")
+        output = buf.getvalue()
+        assert "Failed" in output
+
+    def test_print_warning(self):
+        console, buf = _make_console()
+        print_warning(console, "Watch out")
+        output = buf.getvalue()
+        assert "Watch out" in output
+
+    def test_print_info(self):
+        console, buf = _make_console()
+        print_info(console, "FYI")
+        output = buf.getvalue()
+        assert "FYI" in output

cli/python/tests/test_cli_integration.py

@@ -0,0 +1,238 @@
+"""Integration tests — invoke CLI as subprocess to test end-to-end.
+
+These tests launch the CLI as a real subprocess, so they must manage
+environment isolation themselves (monkeypatch doesn't cross process
+boundaries).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import pytest
+
+
+def _run(
+    args: list[str],
+    env_override: dict | None = None,
+    home_dir: str | None = None,
+) -> subprocess.CompletedProcess:
+    """Run mem0 CLI command and capture output.
+
+    Args:
+        args: CLI arguments.
+        env_override: Extra env vars to set.
+        home_dir: If provided, set HOME to this path so the subprocess
+            reads config from ``<home_dir>/.mem0/config.json`` instead
+            of the user's real config.  This is critical for tests that
+            depend on a clean (no API key) or custom config state.
+    """
+    env = os.environ.copy()
+    # Strip all MEM0_ env vars so tests start clean
+    for key in list(env.keys()):
+        if key.startswith("MEM0_"):
+            del env[key]
+    if home_dir:
+        env["HOME"] = home_dir
+    if env_override:
+        env.update(env_override)
+    return subprocess.run(
+        [sys.executable, "-m", "mem0_cli", *args],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+@pytest.fixture
+def clean_home(tmp_path):
+    """Return a temp directory to use as HOME, ensuring no ~/.mem0 exists."""
+    return str(tmp_path)
+
+
+class TestCLIIntegration:
+    """Tests that only inspect help text / version — no config needed."""
+
+    def test_help(self):
+        result = _run(["--help"])
+        assert result.returncode == 0
+        assert "mem0" in result.stdout
+        assert "add" in result.stdout
+        assert "search" in result.stdout
+
+    def test_version_flag(self):
+        result = _run(["--version"])
+        assert result.returncode == 0
+        assert "0.1.0" in result.stdout
+
+
+    def test_add_help(self):
+        result = _run(["add", "--help"])
+        assert result.returncode == 0
+        assert "user-id" in result.stdout
+        assert "messages" in result.stdout
+
+    def test_add_help_has_scope_panel(self):
+        """Verify rich_help_panel grouping shows in help output."""
+        result = _run(["add", "--help"])
+        assert result.returncode == 0
+        assert "Scope" in result.stdout
+
+    def test_search_help(self):
+        result = _run(["search", "--help"])
+        assert result.returncode == 0
+        assert "top-k" in result.stdout
+
+    def test_list_help(self):
+        result = _run(["list", "--help"])
+        assert result.returncode == 0
+        assert "page-size" in result.stdout
+
+    def test_delete_help(self):
+        result = _run(["delete", "--help"])
+        assert result.returncode == 0
+        assert "--all" in result.stdout
+        assert "--entity" in result.stdout
+        assert "--project" in result.stdout
+        assert "--force" in result.stdout
+        assert "--dry-run" in result.stdout
+
+    def test_entity_list_help(self):
+        result = _run(["entity", "list", "--help"])
+        assert result.returncode == 0
+        assert "entity-type" in result.stdout.lower() or "entity_type" in result.stdout.lower()
+
+    def test_entity_delete_help(self):
+        result = _run(["entity", "delete", "--help"])
+        assert result.returncode == 0
+        assert "--user-id" in result.stdout
+        assert "--force" in result.stdout
+
+    def test_import_help(self):
+        result = _run(["import", "--help"])
+        assert result.returncode == 0
+
+    def test_no_args_shows_help(self):
+        """no_args_is_help=True makes Typer print help and exit with code 2."""
+        result = _run([])
+        # Typer returns exit code 2 for "no command given" — this is standard
+        # Click/Typer behaviour and not an error.
+        assert result.returncode in (0, 2)
+        assert "Usage" in result.stdout
+
+
+class TestCLIIsolated:
+    """Tests that need a clean HOME to avoid reading the user's real config."""
+
+    def test_add_no_key_errors(self, clean_home):
+        """Without an API key, `mem0 add` must fail with a helpful message."""
+        result = _run(
+            ["add", "test", "--user-id", "alice"],
+            home_dir=clean_home,
+        )
+        assert result.returncode != 0
+        combined = result.stderr + result.stdout
+        assert "API key" in combined or "api" in combined.lower() or "Error" in combined
+
+    def test_search_no_key_errors(self, clean_home):
+        """Without an API key, `mem0 search` must fail."""
+        result = _run(
+            ["search", "preferences", "--user-id", "alice"],
+            home_dir=clean_home,
+        )
+        assert result.returncode != 0
+        combined = result.stderr + result.stdout
+        assert "API key" in combined or "Error" in combined
+
+    def test_list_no_key_errors(self, clean_home):
+        """Without an API key, `mem0 list` must fail."""
+        result = _run(["list"], home_dir=clean_home)
+        assert result.returncode != 0
+        combined = result.stderr + result.stdout
+        assert "API key" in combined or "Error" in combined
+
+    def test_delete_no_id_no_all_errors(self, clean_home):
+        """Delete without memory_id, --all, or --entity must fail."""
+        result = _run(
+            ["delete", "--api-key", "m0-fake-key"],
+            home_dir=clean_home,
+        )
+        assert result.returncode != 0
+        combined = result.stderr + result.stdout
+        assert "memory ID" in combined.lower() or "--all" in combined or "--entity" in combined or "Error" in combined
+
+    def test_config_show_clean(self, clean_home):
+        """config show with no config should still work."""
+        result = _run(["config", "show"], home_dir=clean_home)
+        assert result.returncode == 0
+        assert "backend" in result.stdout.lower() or "platform" in result.stdout.lower()
+
+    def test_config_set_and_get_roundtrip(self, clean_home):
+        """config set then config get should return the set value."""
+        _run(
+            ["config", "set", "defaults.user_id", "integration-test-user"],
+            home_dir=clean_home,
+        )
+        result = _run(
+            ["config", "get", "defaults.user_id"],
+            home_dir=clean_home,
+        )
+        assert result.returncode == 0
+        assert "integration-test-user" in result.stdout
+
+    def test_import_nonexistent_file(self, clean_home):
+        """Importing a nonexistent file should fail gracefully."""
+        result = _run(
+            ["import", "/nonexistent/file.json", "--api-key", "m0-fake"],
+            home_dir=clean_home,
+        )
+        assert result.returncode != 0
+        combined = result.stderr + result.stdout
+        assert "Failed" in combined or "Error" in combined or "error" in combined
+
+    def test_add_no_content_errors(self, clean_home):
+        """add with no text/messages/file should fail."""
+        result = _run(
+            ["add", "--user-id", "alice", "--api-key", "m0-fake"],
+            home_dir=clean_home,
+        )
+        assert result.returncode != 0
+        combined = result.stderr + result.stdout
+        assert "No content" in combined or "Error" in combined
+
+
+class TestCLINewFeatures:
+    """Tests for MCP parity features: --graph, --limit, entities delete."""
+
+    def test_add_help_has_graph(self):
+        result = _run(["add", "--help"])
+        assert result.returncode == 0
+        assert "--graph" in result.stdout
+
+    def test_search_help_has_graph_and_limit(self):
+        result = _run(["search", "--help"])
+        assert result.returncode == 0
+        assert "--graph" in result.stdout
+        assert "--limit" in result.stdout
+
+    def test_list_help_has_graph(self):
+        result = _run(["list", "--help"])
+        assert result.returncode == 0
+        assert "--graph" in result.stdout
+
+    def test_delete_entity_via_delete_flag(self):
+        """delete --entity should appear in help output."""
+        result = _run(["delete", "--help"])
+        assert result.returncode == 0
+        assert "--entity" in result.stdout
+
+    def test_entity_delete_has_scope_options(self):
+        """entity delete should expose scope options."""
+        result = _run(["entity", "delete", "--help"])
+        assert result.returncode == 0
+        assert "--user-id" in result.stdout
+        assert "--force" in result.stdout
+        assert "--app-id" in result.stdout
+        assert "--run-id" in result.stdout

cli/python/tests/test_config.py

@@ -0,0 +1,240 @@
+"""Tests for configuration management."""
+
+from __future__ import annotations
+
+import os
+
+from mem0_cli.config import (
+    Mem0Config,
+    get_nested_value,
+    load_config,
+    redact_key,
+    save_config,
+    set_nested_value,
+)
+
+
+class TestRedactKey:
+    def test_empty_key(self):
+        assert redact_key("") == "(not set)"
+
+    def test_short_key(self):
+        assert redact_key("abc") == "ab***"
+
+    def test_normal_key(self):
+        result = redact_key("m0-abcdefgh12345678")
+        assert result == "m0-a...5678"
+        assert "abcdefgh" not in result
+
+    def test_exact_8_chars(self):
+        # 8 chars is <= 8, so it gets the short redaction
+        assert redact_key("12345678") == "12***"
+
+
+class TestConfig:
+    def test_default_config(self):
+        config = Mem0Config()
+        assert config.platform.base_url == "https://api.mem0.ai"
+        assert config.platform.api_key == ""
+
+    def test_save_and_load(self, isolate_config):
+        config = Mem0Config()
+        config.platform.api_key = "m0-test-key"
+
+        save_config(config)
+
+        loaded = load_config()
+        assert loaded.platform.api_key == "m0-test-key"
+
+    def test_env_var_override(self, isolate_config, monkeypatch):
+        config = Mem0Config()
+        config.platform.api_key = "file-key"
+        save_config(config)
+
+        monkeypatch.setenv("MEM0_API_KEY", "env-key")
+        loaded = load_config()
+        assert loaded.platform.api_key == "env-key"
+
+    def test_load_nonexistent_config(self, isolate_config):
+        config = load_config()
+        assert config.platform.api_key == ""
+
+    def test_config_file_permissions(self, isolate_config):
+        config = Mem0Config()
+        config.platform.api_key = "secret"
+        save_config(config)
+
+        from mem0_cli.config import CONFIG_FILE
+
+        mode = os.stat(CONFIG_FILE).st_mode & 0o777
+        assert mode == 0o600
+
+    def test_defaults_save_and_load(self, isolate_config):
+        config = Mem0Config()
+        config.defaults.user_id = "alice"
+        config.defaults.agent_id = "support-bot"
+        config.defaults.app_id = "my-app"
+        config.defaults.run_id = "run-001"
+
+        save_config(config)
+        loaded = load_config()
+
+        assert loaded.defaults.user_id == "alice"
+        assert loaded.defaults.agent_id == "support-bot"
+        assert loaded.defaults.app_id == "my-app"
+        assert loaded.defaults.run_id == "run-001"
+
+    def test_defaults_env_var_override(self, isolate_config, monkeypatch):
+        config = Mem0Config()
+        config.defaults.user_id = "file-user"
+        save_config(config)
+
+        monkeypatch.setenv("MEM0_USER_ID", "env-user")
+        monkeypatch.setenv("MEM0_AGENT_ID", "env-agent")
+        loaded = load_config()
+        assert loaded.defaults.user_id == "env-user"
+        assert loaded.defaults.agent_id == "env-agent"
+
+    def test_backward_compat_no_defaults_key(self, isolate_config):
+        """Old config files without 'defaults' key should load fine."""
+        import json
+
+        from mem0_cli.config import CONFIG_FILE, ensure_config_dir
+
+        ensure_config_dir()
+        # Write a config without the "defaults" key
+        data = {
+            "version": 1,
+            "platform": {"api_key": "m0-test", "base_url": "https://api.mem0.ai"},
+        }
+        with open(CONFIG_FILE, "w") as f:
+            json.dump(data, f)
+
+        loaded = load_config()
+        assert loaded.platform.api_key == "m0-test"
+        assert loaded.defaults.user_id == ""
+        assert loaded.defaults.agent_id == ""
+
+    def test_default_config_has_empty_defaults(self):
+        config = Mem0Config()
+        assert config.defaults.user_id == ""
+        assert config.defaults.agent_id == ""
+        assert config.defaults.app_id == ""
+        assert config.defaults.run_id == ""
+        assert config.defaults.enable_graph is False
+
+    def test_enable_graph_save_and_load(self, isolate_config):
+        config = Mem0Config()
+        config.defaults.enable_graph = True
+        save_config(config)
+        loaded = load_config()
+        assert loaded.defaults.enable_graph is True
+
+    def test_enable_graph_env_var_true(self, isolate_config, monkeypatch):
+        monkeypatch.setenv("MEM0_ENABLE_GRAPH", "true")
+        loaded = load_config()
+        assert loaded.defaults.enable_graph is True
+
+    def test_enable_graph_env_var_false(self, isolate_config, monkeypatch):
+        config = Mem0Config()
+        config.defaults.enable_graph = True
+        save_config(config)
+        monkeypatch.setenv("MEM0_ENABLE_GRAPH", "false")
+        loaded = load_config()
+        assert loaded.defaults.enable_graph is False
+
+    def test_backward_compat_no_enable_graph_key(self, isolate_config):
+        """Old config files without 'enable_graph' key should default to False."""
+        import json
+
+        from mem0_cli.config import CONFIG_FILE, ensure_config_dir
+
+        ensure_config_dir()
+        data = {
+            "version": 1,
+            "defaults": {"user_id": "alice"},
+            "platform": {"api_key": "m0-test", "base_url": "https://api.mem0.ai"},
+        }
+        with open(CONFIG_FILE, "w") as f:
+            json.dump(data, f)
+
+        loaded = load_config()
+        assert loaded.defaults.enable_graph is False
+        assert loaded.defaults.user_id == "alice"
+
+
+class TestNestedAccess:
+    def test_get_nested_value(self):
+        config = Mem0Config()
+        config.platform.api_key = "test-key"
+        assert get_nested_value(config, "platform.api_key") == "test-key"
+
+    def test_get_nonexistent_key(self):
+        config = Mem0Config()
+        assert get_nested_value(config, "nonexistent.key") is None
+
+    def test_set_nested_value(self):
+        config = Mem0Config()
+        assert set_nested_value(config, "platform.api_key", "new-key")
+        assert config.platform.api_key == "new-key"
+
+    def test_set_nonexistent_key(self):
+        config = Mem0Config()
+        assert set_nested_value(config, "nonexistent.key", "val") is False
+
+    def test_get_defaults_user_id(self):
+        config = Mem0Config()
+        config.defaults.user_id = "alice"
+        assert get_nested_value(config, "defaults.user_id") == "alice"
+
+    def test_set_defaults_user_id(self):
+        config = Mem0Config()
+        assert set_nested_value(config, "defaults.user_id", "bob")
+        assert config.defaults.user_id == "bob"
+
+    def test_set_defaults_enable_graph(self):
+        config = Mem0Config()
+        assert set_nested_value(config, "defaults.enable_graph", "true")
+        assert config.defaults.enable_graph is True
+
+
+class TestResolveIds:
+    def test_cli_flag_overrides_default(self):
+        from mem0_cli.app import _resolve_ids
+
+        config = Mem0Config()
+        config.defaults.user_id = "default-user"
+        ids = _resolve_ids(
+            config,
+            user_id="cli-user",
+            agent_id=None,
+        )
+        assert ids["user_id"] == "cli-user"
+
+    def test_default_used_when_flag_is_none(self):
+        from mem0_cli.app import _resolve_ids
+
+        config = Mem0Config()
+        config.defaults.user_id = "default-user"
+        config.defaults.agent_id = "default-agent"
+        ids = _resolve_ids(config, user_id=None, agent_id=None)
+        assert ids["user_id"] == "default-user"
+        assert ids["agent_id"] == "default-agent"
+
+    def test_none_when_neither_set(self):
+        from mem0_cli.app import _resolve_ids
+
+        config = Mem0Config()
+        ids = _resolve_ids(config, user_id=None, agent_id=None)
+        assert ids["user_id"] is None
+        assert ids["agent_id"] is None
+        assert ids["app_id"] is None
+        assert ids["run_id"] is None
+
+    def test_empty_string_treated_as_unset(self):
+        from mem0_cli.app import _resolve_ids
+
+        config = Mem0Config()
+        config.defaults.user_id = ""
+        ids = _resolve_ids(config, user_id=None)
+        assert ids["user_id"] is None

cli/python/tests/test_output.py

@@ -0,0 +1,136 @@
+"""Tests for output formatting."""
+
+from __future__ import annotations
+
+from io import StringIO
+
+from rich.console import Console
+
+from mem0_cli.output import (
+    format_add_result,
+    format_memories_table,
+    format_memories_text,
+    format_single_memory,
+)
+
+
+def _make_console() -> tuple[Console, StringIO]:
+    buf = StringIO()
+    return Console(file=buf, force_terminal=False, no_color=True, width=120, highlight=False), buf
+
+
+SAMPLE_MEMORIES = [
+    {
+        "id": "abc-123-def-456",
+        "memory": "User prefers dark mode",
+        "score": 0.92,
+        "created_at": "2026-02-15T10:30:00Z",
+        "categories": ["preferences"],
+    },
+    {
+        "id": "ghi-789-jkl-012",
+        "memory": "User uses vim keybindings",
+        "score": 0.78,
+        "created_at": "2026-03-01T14:00:00Z",
+        "categories": ["tools"],
+    },
+]
+
+
+class TestTextFormat:
+    def test_format_memories_text(self):
+        console, buf = _make_console()
+        format_memories_text(console, SAMPLE_MEMORIES)
+        output = buf.getvalue()
+        assert "Found 2 memories" in output
+        assert "dark mode" in output
+        assert "vim keybindings" in output
+        assert "0.92" in output
+
+    def test_format_memories_text_empty(self):
+        console, buf = _make_console()
+        format_memories_text(console, [])
+        output = buf.getvalue()
+        assert "Found 0" in output
+
+
+class TestTableFormat:
+    def test_format_memories_table(self):
+        console, buf = _make_console()
+        format_memories_table(console, SAMPLE_MEMORIES)
+        output = buf.getvalue()
+        assert "dark mode" in output
+        assert "abc-123-" in output
+
+    def test_format_memories_table_empty(self):
+        console, buf = _make_console()
+        format_memories_table(console, [])
+        output = buf.getvalue()
+        # Should still render (empty table)
+        assert "ID" in output
+
+
+class TestSingleMemory:
+    def test_format_single_memory_text(self):
+        console, buf = _make_console()
+        mem = SAMPLE_MEMORIES[0]
+        format_single_memory(console, mem, "text")
+        output = buf.getvalue()
+        assert "dark mode" in output
+        assert "abc-123-def-456" in output
+
+    def test_format_single_memory_json(self):
+        console, buf = _make_console()
+        mem = SAMPLE_MEMORIES[0]
+        format_single_memory(console, mem, "json")
+        output = buf.getvalue()
+        assert '"memory"' in output
+
+
+class TestAddResult:
+    def test_format_add_result_text(self):
+        console, buf = _make_console()
+        result = {
+            "results": [
+                {"id": "abc-123-def-456", "memory": "User prefers dark mode", "event": "ADD"},
+            ]
+        }
+        format_add_result(console, result, "text")
+        output = buf.getvalue()
+        assert "dark mode" in output
+        assert "Added" in output
+
+    def test_format_add_result_update_event(self):
+        console, buf = _make_console()
+        result = {
+            "results": [
+                {"id": "abc-123", "memory": "Updated pref", "event": "UPDATE"},
+            ]
+        }
+        format_add_result(console, result, "text")
+        output = buf.getvalue()
+        assert "Updated" in output
+
+    def test_format_add_result_noop(self):
+        console, buf = _make_console()
+        result = {
+            "results": [
+                {"id": "abc-123", "memory": "Same thing", "event": "NOOP"},
+            ]
+        }
+        format_add_result(console, result, "text")
+        output = buf.getvalue()
+        assert "No change" in output
+
+    def test_format_add_result_quiet(self):
+        console, buf = _make_console()
+        result = {"results": [{"id": "abc-123", "memory": "Quiet", "event": "ADD"}]}
+        format_add_result(console, result, "quiet")
+        output = buf.getvalue()
+        assert output.strip() == ""
+
+    def test_format_add_result_empty(self):
+        console, buf = _make_console()
+        format_add_result(console, {"results": []}, "text")
+        output = buf.getvalue()
+        assert "No memories extracted" in output

docs/_snippets/paper-release.mdx

@@ -1,3 +1,3 @@
 <Note type="info">
-  📢 Announcing our research paper: Mem0 achieves <strong>26%</strong> higher accuracy than OpenAI Memory, <strong>91%</strong> lower latency, and <strong>90%</strong> token savings! [Read the paper](https://mem0.ai/research) to learn how we're revolutionizing AI agent memory.
+  <strong>🎉 Mem0 1.0.0 is here!</strong> Enhanced filtering, reranking, and smarter memory management.
 </Note>

docs/api-reference.mdx

@@ -1,191 +1,108 @@
 ---
-title: Overview
-icon: "info"
+title: "Overview"
+icon: "terminal"
 iconType: "solid"
+description: "REST APIs for memory management, search, and entity operations"
 ---
 
-Mem0 provides a powerful set of APIs that allow you to integrate advanced memory management capabilities into your applications. Our APIs are designed to be intuitive, efficient, and scalable, enabling you to create, retrieve, update, and delete memories across various entities such as users, agents, apps, and runs.
+## Mem0 REST API
 
-## Key Features
+Mem0 provides a comprehensive REST API for integrating advanced memory capabilities into your applications. Create, search, update, and manage memories across users, agents, and custom entities with simple HTTP requests.
 
-- **Memory Management**: Add, retrieve, update, and delete memories with ease.
-- **Entity-based Operations**: Perform operations on memories associated with specific users, agents, apps, or runs.
-- **Advanced Search**: Utilize our search API to find relevant memories based on various criteria.
-- **History Tracking**: Access the history of memory interactions for comprehensive analysis.
-- **User Management**: Manage user entities and their associated memories.
+<Info>
+**Quick start:** Get your API key from the [Mem0 Dashboard](https://app.mem0.ai/dashboard/api-keys) and make your first memory operation in minutes.
+</Info>
 
-## API Structure
+---
 
-Our API is organized into several main categories:
+## Quick Start Guide
 
-1. **Memory APIs**: Core operations for managing individual memories and collections.
-2. **Entities APIs**: Manage different entity types (users, agents, etc.) and their associated memories.
-3. **Search API**: Advanced search functionality to retrieve relevant memories.
-4. **History API**: Track and retrieve the history of memory interactions.
+Get started with Mem0 API in three simple steps:
+
+1. **[Add Memories](/api-reference/memory/add-memories)** - Store information and context from user conversations
+2. **[Search Memories](/api-reference/memory/search-memories)** - Retrieve relevant memories using semantic search
+3. **[Get Memories](/api-reference/memory/get-memories)** - Fetch all memories for a specific entity
+
+---
+
+## Core Operations
+
+<CardGroup cols={2}>
+  <Card title="Add Memories" icon="plus" href="/api-reference/memory/add-memories">
+    Store new memories from conversations and interactions
+  </Card>
+
+  <Card title="Search Memories" icon="magnifying-glass" href="/api-reference/memory/search-memories">
+    Find relevant memories using semantic search with filters
+  </Card>
+
+  <Card title="Update Memory" icon="pen" href="/api-reference/memory/update-memory">
+    Modify existing memory content and metadata
+  </Card>
+
+  <Card title="Delete Memory" icon="trash" href="/api-reference/memory/delete-memory">
+    Remove specific memories or batch delete operations
+  </Card>
+</CardGroup>
+
+---
+
+## API Categories
+
+Explore the full API organized by functionality:
+
+<CardGroup cols={2}>
+  <Card title="Memory APIs" icon="microchip" href="/api-reference/memory/add-memories">
+    Core and advanced operations: CRUD, search, batch updates, history, and exports
+  </Card>
+
+  <Card title="Events APIs" icon="clock" href="/api-reference/events/get-events">
+    Track and monitor the status of asynchronous memory operations
+  </Card>
+
+  <Card title="Entities APIs" icon="users" href="/api-reference/entities/get-users">
+    Manage users, agents, and their associated memory data
+  </Card>
+
+  <Card title="Organizations & Projects" icon="building" href="/api-reference/organizations-projects">
+    Multi-tenant support, access control, and team collaboration
+  </Card>
+
+  <Card title="Webhooks" icon="webhook" href="/api-reference/webhook/create-webhook">
+    Real-time notifications for memory events and updates
+  </Card>
+</CardGroup>
+
+<Note>
+**Building multi-tenant apps?** Learn about [Organizations & Projects](/api-reference/organizations-projects) for team isolation and access control.
+</Note>
+
+---
 
 ## Authentication
 
-All API requests require authentication using HTTP Basic Auth. Ensure you include your API key in the Authorization header of each request.
+All API requests require authentication using Token-based authentication. Include your API key in the Authorization header:
 
-## Organizations and projects (optional)
-
-Organizations and projects provide the following capabilities:
-
-- **Multi-org/project Support**: Specify organization and project when initializing the Mem0 client to attribute API usage appropriately
-- **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
-
-Example with the mem0 Python package:
-
-<Tabs>
-  <Tab title="Python">
-
-```python
-from mem0 import MemoryClient
-client = MemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
+```bash
+Authorization: Token <your-api-key>
 ```
 
-  </Tab>
+Get your API key from the [Mem0 Dashboard](https://app.mem0.ai/dashboard/api-keys).
 
-  <Tab title="Node.js">
+<Warning>
+**Keep your API key secure.** Never expose it in client-side code or public repositories. Use environment variables and server-side requests only.
+</Warning>
 
-```javascript
-import { MemoryClient } from "mem0ai";
-const client = new MemoryClient({organizationId: "YOUR_ORG_ID", projectId: "YOUR_PROJECT_ID"});
-```
+---
 
-  </Tab>
-</Tabs>
+## Next Steps
 
-### Project Management Methods
+<CardGroup cols={2}>
+  <Card title="Add Your First Memory" icon="rocket" href="/api-reference/memory/add-memories">
+    Start storing memories via the REST API
+  </Card>
 
-The Mem0 client provides comprehensive project management capabilities through the `client.project` interface:
-
-#### Get Project Details
-
-Retrieve information about the current project:
-
-```python
-# Get all project details
-project_info = client.project.get()
-
-# Get specific fields only
-project_info = client.project.get(fields=["name", "description", "custom_categories"])
-```
-
-#### Create a New Project
-
-Create a new project within your organization:
-
-```python
-# Create a project with name and description
-new_project = client.project.create(
-    name="My New Project",
-    description="A project for managing customer support memories"
-)
-```
-
-#### Update Project Settings
-
-Modify project configuration including custom instructions, categories, and graph settings:
-
-```python
-# Update project with custom categories
-client.project.update(
-    custom_categories=[
-        {"customer_preferences": "Customer likes, dislikes, and preferences"},
-        {"support_history": "Previous support interactions and resolutions"}
-    ]
-)
-
-# Update project with custom instructions
-client.project.update(
-    custom_instructions="..."
-)
-
-# Enable graph memory for the project
-client.project.update(enable_graph=True)
-
-# Update multiple settings at once
-client.project.update(
-    custom_instructions="...",
-    custom_categories=[
-        {"personal_info": "User personal information and preferences"},
-        {"work_context": "Professional context and work-related information"}
-    ],
-    enable_graph=True
-)
-```
-
-#### Delete Project
-
-<Note>
-This action will remove all memories, messages, and other related data in the project. This operation is irreversible.
-</Note>
-
-Remove a project and all its associated data:
-
-```python
-# Delete the current project (irreversible)
-result = client.project.delete()
-```
-
-#### Member Management
-
-Manage project members and their access levels:
-
-```python
-# Get all project members
-members = client.project.get_members()
-
-# Add a new member as a reader
-client.project.add_member(
-    email="colleague@company.com",
-    role="READER"  # or "OWNER"
-)
-
-# Update a member's role
-client.project.update_member(
-    email="colleague@company.com",
-    role="OWNER"
-)
-
-# Remove a member from the project
-client.project.remove_member(email="colleague@company.com")
-```
-
-#### Member Roles
-
-- **READER**: Can view and search memories, but cannot modify project settings or manage members
-- **OWNER**: Full access including project modification, member management, and all reader permissions
-
-#### Async Support
-
-All project methods are also available in async mode:
-
-```python
-from mem0 import AsyncMemoryClient
-
-async def manage_project():
-    client = AsyncMemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
-
-    # All methods support async/await
-    project_info = await client.project.get()
-    await client.project.update(enable_graph=True)
-    members = await client.project.get_members()
-
-# To call the async function properly
-import asyncio
-asyncio.run(manage_project())
-```
-
-## Getting Started
-
-To begin using the Mem0 API, you'll need to:
-
-1. Sign up for a [Mem0 account](https://app.mem0.ai) and obtain your API key.
-2. Familiarize yourself with the API endpoints and their functionalities.
-3. Make your first API call to add or retrieve a memory.
-
-Explore the detailed documentation for each API endpoint to learn more about request/response formats, parameters, and example usage.
+  <Card title="Search with Filters" icon="filter" href="/api-reference/memory/search-memories">
+    Learn advanced search and filtering techniques
+  </Card>
+</CardGroup>

docs/api-reference/entities/delete-user.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Delete User'
-openapi: delete /v1/entities/{entity_type}/{entity_id}/
+description: "Remove a user entity from the Mem0 platform by entity type and ID using the DELETE endpoint."
+openapi: delete /v2/entities/{entity_type}/{entity_id}/
 ---

docs/api-reference/entities/get-users.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Get Users'
+description: "Retrieve a list of all user entities stored in the Mem0 platform using the GET endpoint."
 openapi: get /v1/entities/
 ---

docs/api-reference/events/get-event.mdx

@@ -0,0 +1,7 @@
+---
+title: 'Get Event'
+description: "Retrieve details of a specific event by ID, including status and payload for async memory operations."
+openapi: get /v1/event/{event_id}/
+---
+
+Retrieve details about a specific event by passing its `event_id`. This endpoint is particularly helpful for tracking the status, payload, and completion details of asynchronous memory operations.

docs/api-reference/events/get-events.mdx

@@ -0,0 +1,13 @@
+---
+title: 'Get Events'
+description: "List recent events for your organization and project, useful for dashboards, alerting, and audit logging."
+openapi: get /v1/events/
+---
+
+List recent events for your organization and project.
+
+## Use Cases
+
+- **Dashboards**: Summarize adds/searches over time by paging through events.
+- **Alerting**: Poll for `FAILED` events and trigger follow-up workflows.
+- **Audit**: Store the returned payload/metadata for compliance logs.

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

@@ -1,4 +1,102 @@
 ---
 title: 'Add Memories'
+description: "Add facts, messages, or metadata to a user memory store with support for async processing and event tracking."
 openapi: post /v1/memories/
----
+---
+
+Add new facts, messages, or metadata to a user’s memory store. The Add Memories endpoint accepts either raw text or conversational turns and commits them asynchronously so the memory is ready for later search, retrieval, and graph queries.
+
+## Endpoint
+
+- **Method**: `POST`
+- **URL**: `/v1/memories/`
+- **Content-Type**: `application/json`
+
+Memories are processed asynchronously by default. The response contains queued events you can track while the platform finalizes enrichment.
+
+## Required headers
+
+| Header | Required | Description |
+| --- | --- | --- |
+| `Authorization: Token <MEM0_API_KEY>` | Yes | API key scoped to your workspace. |
+| `Accept: application/json` | Yes | Ensures a JSON response. |
+
+## Request body
+
+Provide at least one message or direct memory string. Most callers supply `messages` so Mem0 can infer structured memories as part of ingestion.
+
+<CodeGroup>
+```json Basic request
+{
+  "user_id": "alice",
+  "messages": [
+    { "role": "user", "content": "I moved to Austin last month." }
+  ],
+  "metadata": {
+    "source": "onboarding_form"
+  }
+}
+```
+</CodeGroup>
+
+### Common fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `user_id` | string | No* | Associates the memory with a user. Provide when you want the memory scoped to a specific identity. |
+| `messages` | array | No* | Conversation turns for Mem0 to infer memories from. Each object should include `role` and `content`. |
+| `metadata` | object | Optional | Custom key/value metadata (e.g., `{"topic": "preferences"}`). |
+| `infer` | boolean (default `true`) | Optional | Set to `false` to skip inference and store the provided text as-is. |
+| `async_mode` | boolean (default `true`) | Optional | Controls asynchronous processing. Most clients leave this enabled. |
+| `output_format` | string (default `v1.1`) | Optional | Response format. `v1.1` wraps results in a `results` array. |
+
+> \* Provide at least one `messages` entry to describe what you are storing. For scoped memories, include `user_id`. You can also attach `agent_id`, `app_id`, `run_id`, `project_id`, or `org_id` to refine ownership.
+
+<Tip>
+  Need more details? See [all request parameters](#body-messages) below for complete field descriptions, types, and constraints.
+</Tip>
+
+## Response
+
+Successful requests return an array of events queued for processing. Each event includes the generated memory text and an identifier you can persist for auditing.
+
+<CodeGroup>
+```json 200 response
+[
+  {
+    "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
+    "event": "ADD",
+    "data": {
+      "memory": "The user moved to Austin in 2025."
+    }
+  }
+]
+```
+
+```json 400 response
+{
+  "error": "400 Bad Request",
+  "details": {
+    "message": "Invalid input data. Please refer to the memory creation documentation at https://docs.mem0.ai/platform/quickstart#4-1-create-memories for correct formatting and required fields."
+  }
+}
+```
+</CodeGroup>
+
+## Graph relationships
+
+Add Memories can enrich the knowledge graph on write. Set `enable_graph: true` to create entity nodes and relationships for the stored memory. Use this when you want downstream `get_all` or search calls to traverse connected entities.
+
+<CodeGroup>
+```json Graph-aware request
+{
+  "user_id": "alice",
+  "messages": [
+    { "role": "user", "content": "I met with Dr. Lee at General Hospital." }
+  ],
+  "enable_graph": true
+}
+```
+</CodeGroup>
+
+The response follows the same format, and related entities become available in [Graph Memory](/platform/features/graph-memory) queries.

docs/api-reference/memory/batch-delete.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Batch Delete Memories'
+description: "Delete multiple memories in a single batch request using the Mem0 API DELETE endpoint."
 openapi: delete /v1/batch/
 ---

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

@@ -1,4 +1,5 @@
 ---
 title: 'Batch Update Memories'
+description: "Update multiple memories in a single batch request using the Mem0 API PUT endpoint."
 openapi: put /v1/batch/
 ---

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

@@ -1,6 +1,7 @@
 ---
 title: 'Create Memory Export'
+description: "Submit an export job to create a structured memory export using a customizable Pydantic schema and filters."
 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`, `run_id`, or `session_id`) and by modifying the Pydantic schema to ensure the final data matches your exact needs.

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

@@ -1,4 +1,5 @@
 ---
 title: 'Delete Memories'
+description: "Delete all memories matching specified filters from the Mem0 memory store using the DELETE endpoint."
 openapi: delete /v1/memories/
 ---

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

@@ -1,4 +1,5 @@
 ---
 title: 'Delete Memory'
+description: "Delete a single memory by its unique memory ID from the Mem0 platform using the DELETE endpoint."
 openapi: delete /v1/memories/{memory_id}/
 ---

docs/api-reference/memory/feedback.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Feedback'
+description: "Submit positive or negative feedback on memory results to help improve memory accuracy and relevance."
 openapi: post /v1/feedback/
 ---

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

@@ -0,0 +1,100 @@
+---
+title: "Get Memories"
+description: "Retrieve memories with advanced filtering using logical operators like AND, OR, NOT, and comparison queries."
+openapi: post /v2/memories/
+---
+
+The v2 get memories API is powerful and flexible, allowing for more precise memory listing without the need for a search query. It supports complex logical operations (AND, OR, NOT) and comparison operators for advanced filtering capabilities. The comparison operators include:
+
+- `in`: Matches any of the values specified
+- `gte`: Greater than or equal to
+- `lte`: Less than or equal to
+- `gt`: Greater than
+- `lt`: Less than
+- `ne`: Not equal to
+- `icontains`: Case-insensitive containment check
+- `*`: Wildcard character that matches everything
+
+<CodeGroup>
+```python Code
+memories = client.get_all(
+    filters={
+        "AND": [
+            {
+                "user_id": "alex"
+            },
+            {
+                "created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}
+            }
+        ]
+    }
+)
+```
+
+```python Output
+{
+    "results": [
+        {
+            "id": "f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c",
+            "memory": "Alex is planning a trip to San Francisco from July 1st to July 10th",
+            "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",
+            "created_at": "2024-07-05T15:30:00Z",
+            "updated_at": "2024-07-05T15:30:00Z"
+        }
+    ],
+    "total": 2
+}
+```
+
+</CodeGroup>
+
+## Graph Memory
+
+To retrieve graph memory relationships between entities, pass `output_format="v1.1"` in your request. This will return memories with entity and relationship information from the knowledge graph.
+
+<CodeGroup>
+```python Code
+memories = client.get_all(
+    filters={
+        "user_id": "alex"
+    },
+    output_format="v1.1"
+)
+```
+
+```python Output
+{
+    "results": [
+        {
+            "id": "f4cbdb08-7062-4f3e-8eb2-9f5c80dfe64c",
+            "memory": "Alex is planning a trip to San Francisco",
+            "entities": [
+                {
+                    "id": "entity-1",
+                    "name": "Alex",
+                    "type": "person"
+                },
+                {
+                    "id": "entity-2",
+                    "name": "San Francisco",
+                    "type": "location"
+                }
+            ],
+            "relations": [
+                {
+                    "source": "entity-1",
+                    "target": "entity-2",
+                    "relationship": "traveling_to"
+                }
+            ]
+        }
+    ]
+}
+```
+
+</CodeGroup>

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

@@ -1,5 +1,6 @@
 ---
 title: 'Get Memory Export'
+description: "Retrieve the latest structured memory export after submitting an export job, with optional entity filters."
 openapi: post /v1/exports/get
 ---
 

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

@@ -1,4 +1,5 @@
 ---
 title: 'Get Memory'
+description: "Retrieve a single memory by its unique memory ID from the Mem0 platform using the GET endpoint."
 openapi: get /v1/memories/{memory_id}/
 ---

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

@@ -1,4 +1,5 @@
 ---
 title: 'Memory History'
+description: "Retrieve the full change history of a specific memory to track how it has evolved over time."
 openapi: get /v1/memories/{memory_id}/history/
 ---

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

@@ -0,0 +1,105 @@
+---
+title: 'Search Memories'
+description: "Search memories with semantic queries and advanced filtering using logical and comparison operators."
+openapi: post /v2/memories/search/
+---
+
+The v2 search API is powerful and flexible, allowing for more precise memory retrieval. It supports complex logical operations (AND, OR, NOT) and comparison operators for advanced filtering capabilities. The comparison operators include:
+- `in`: Matches any of the values specified
+- `gte`: Greater than or equal to
+- `lte`: Less than or equal to
+- `gt`: Greater than
+- `lt`: Less than
+- `ne`: Not equal to
+- `icontains`: Case-insensitive containment check
+- `*`: Wildcard character that matches everything
+
+<CodeGroup>
+```python Platform API Example
+related_memories = client.search(
+    query="What are Alice's hobbies?",
+    filters={
+        "OR": [
+            {
+              "user_id": "alice"
+            },
+            {
+              "agent_id": {"in": ["travel-agent", "sports-agent"]}
+            }
+        ]
+    },
+)
+```
+
+```json Output
+{
+  "memories": [
+    {
+      "id": "ea925981-272f-40dd-b576-be64e4871429",
+      "memory": "Likes to play cricket and plays cricket on weekends.",
+      "metadata": {
+        "category": "hobbies"
+      },
+      "score": 0.32116443111457704,
+      "created_at": "2024-07-26T10:29:36.630547-07:00",
+      "updated_at": null,
+      "user_id": "alice",
+      "agent_id": "sports-agent"
+    }
+  ],
+}
+```
+</CodeGroup>
+
+<CodeGroup>
+```python Wildcard Example
+# Using wildcard to match all run_ids for a specific user
+all_memories = client.search(
+    query="What are Alice's hobbies?",
+    filters={
+        "AND": [
+            {
+                "user_id": "alice"
+            },
+            {
+                "run_id": "*"
+            }
+        ]
+    },
+)
+```
+</CodeGroup>
+
+<CodeGroup>
+```python Categories Filter Examples
+# Example 1: Using 'contains' for partial matching
+finance_memories = client.search(
+    query="What are my financial goals?",
+    filters={
+        "AND": [
+            { "user_id": "alice" },
+            {
+                "categories": {
+                    "contains": "finance"
+                }
+            }
+        ]
+    },
+)
+
+# Example 2: Using 'in' for exact matching
+personal_memories = client.search(
+    query="What personal information do you have?",
+    filters={
+        "AND": [
+            { "user_id": "alice" },
+            {
+                "categories": {
+                    "in": ["personal_information"]
+                }
+            }
+        ]
+    },
+)
+```
+</CodeGroup>

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

@@ -1,4 +1,5 @@
 ---
 title: 'Update Memory'
+description: "Update the content or metadata of a single memory by its unique ID using the PUT endpoint."
 openapi: put /v1/memories/{memory_id}/
 ---

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

@@ -1,4 +0,0 @@
----
-title: 'Get Memories (v1 - Deprecated)'
-openapi: get /v1/memories/
----

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

@@ -1,4 +0,0 @@
----
-title: 'Search Memories (v1 - Deprecated)'
-openapi: post /v1/memories/search/
----

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

@@ -1,65 +0,0 @@
----
-title: 'Get Memories (v2)'
-openapi: post /v2/memories/
----
-
-The v2 get memories API is powerful and flexible, allowing for more precise memory listing without the need for a search query. It supports complex logical operations (AND, OR, NOT) and comparison operators for advanced filtering capabilities. The comparison operators include:
-- `in`: Matches any of the values specified
-- `gte`: Greater than or equal to
-- `lte`: Less than or equal to
-- `gt`: Greater than
-- `lt`: Less than
-- `ne`: Not equal to
-- `icontains`: Case-insensitive containment check
-- `*`: Wildcard character that matches everything
-
-<CodeGroup>
-```python Code
-memories = m.get_all(
-    filters={
-        "AND": [
-            {
-                "user_id": "alex"
-            },
-            {
-                "created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}
-            }
-        ]
-    },
-    version="v2"
-)
-```
-
-```json Output
-[
-{
-    "id":"f38b689d-6b24-45b7-bced-17fbb4d8bac7",
-    "memory":"Name: Alex. Vegetarian. Allergic to nuts.",
-    "user_id":"alex",
-    "hash":"62bc074f56d1f909f1b4c2b639f56f6a",
-    "metadata":null,
-    "created_at":"2024-07-25T23:57:00.108347-07:00",
-    "updated_at":"2024-07-25T23:57:00.108367-07:00"
-}
-]
-```
-</CodeGroup>
-
-<CodeGroup>
-```python Wildcard Example
-# Using wildcard to get all memories for a specific user across all run_ids
-memories = m.get_all(
-    filters={
-        "AND": [
-            {
-                "user_id": "alex"
-            },
-            {
-                "run_id": "*"
-            }
-        ]
-    },
-    version="v2"
-)
-```
-</CodeGroup>

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

@@ -1,108 +0,0 @@
----
-title: 'Search Memories (v2)'
-openapi: post /v2/memories/search/
----
-
-The v2 search API is powerful and flexible, allowing for more precise memory retrieval. It supports complex logical operations (AND, OR, NOT) and comparison operators for advanced filtering capabilities. The comparison operators include:
-- `in`: Matches any of the values specified
-- `gte`: Greater than or equal to
-- `lte`: Less than or equal to
-- `gt`: Greater than
-- `lt`: Less than
-- `ne`: Not equal to
-- `icontains`: Case-insensitive containment check
-- `*`: Wildcard character that matches everything
-
-  <CodeGroup>
-  ```python Code
-  related_memories = m.search(
-      query="What are Alice's hobbies?",
-      version="v2",
-      filters={
-          "OR": [
-              {
-                "user_id": "alice"
-              },
-              {
-                "agent_id": {"in": ["travel-agent", "sports-agent"]}
-              }
-          ]
-      },
-  )
-  ```
-
-  ```json Output
-  {
-    "memories": [
-      {
-        "id": "ea925981-272f-40dd-b576-be64e4871429",
-        "memory": "Likes to play cricket and plays cricket on weekends.",
-        "metadata": {
-          "category": "hobbies"
-        },
-        "score": 0.32116443111457704,
-        "created_at": "2024-07-26T10:29:36.630547-07:00",
-        "updated_at": null,
-        "user_id": "alice",
-        "agent_id": "sports-agent"
-      }
-    ],
-  }
-  ```
-  </CodeGroup>
-
-  <CodeGroup>
-  ```python Wildcard Example
-  # Using wildcard to match all run_ids for a specific user
-  all_memories = m.search(
-      query="What are Alice's hobbies?",
-      version="v2",
-      filters={
-          "AND": [
-              {
-                  "user_id": "alice"
-              },
-              {
-                  "run_id": "*"
-              }
-          ]
-      },
-  )
-  ```
-  </CodeGroup>
-
-  <CodeGroup>
-  ```python Categories Filter Examples
-  # Example 1: Using 'contains' for partial matching
-  finance_memories = m.search(
-      query="What are my financial goals?",
-      version="v2",
-      filters={
-          "AND": [
-              { "user_id": "alice" },
-              {
-                  "categories": {
-                      "contains": "finance"
-                  }
-              }
-          ]
-      },
-  )
-
-  # Example 2: Using 'in' for exact matching
-  personal_memories = m.search(
-      query="What personal information do you have?",
-      version="v2",
-      filters={
-          "AND": [
-              { "user_id": "alice" },
-              {
-                  "categories": {
-                      "in": ["personal_information"]
-                  }
-              }
-          ]
-      },
-  )
-  ```
-  </CodeGroup>

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

@@ -1,5 +1,6 @@
 ---
 title: 'Add Member'
+description: "Add a new member to an organization with a specified role such as READER or OWNER access level."
 openapi: post /api/v1/orgs/organizations/{org_id}/members/
 ---
 

docs/api-reference/organization/create-org.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Create Organization'
+description: "Create a new organization on the Mem0 platform to manage projects, members, and memory resources."
 openapi: post /api/v1/orgs/organizations/
 ---

docs/api-reference/organization/delete-org.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Delete Organization'
+description: "Permanently delete an organization and its associated resources from the Mem0 platform."
 openapi: delete /api/v1/orgs/organizations/{org_id}/
 ---

docs/api-reference/organization/get-org-members.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Get Members'
+description: "Retrieve a list of all members belonging to a specific organization on the Mem0 platform."
 openapi: get /api/v1/orgs/organizations/{org_id}/members/
 ---

docs/api-reference/organization/get-org.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Get Organization'
+description: "Retrieve details of a specific organization by its ID from the Mem0 platform using the GET endpoint."
 openapi: get /api/v1/orgs/organizations/{org_id}/
 ---

docs/api-reference/organization/get-orgs.mdx

@@ -1,4 +1,5 @@
 ---
 title: 'Get Organizations'
+description: "Retrieve a list of all organizations associated with your Mem0 account using the GET endpoint."
 openapi: get /api/v1/orgs/organizations/
 ---

docs/api-reference/organizations-projects.mdx

@@ -0,0 +1,197 @@
+---
+title: Organizations & Projects
+icon: "building"
+description: "Manage multi-tenant applications with organization and project APIs"
+---
+
+## Overview
+
+Organizations and projects provide multi-tenant support, access control, and team collaboration capabilities for Mem0 Platform. Use these APIs to build applications that support multiple teams, customers, or isolated environments.
+
+<Info>
+Organizations and projects are **optional** features. You can use Mem0 without them for single-user or simple multi-user applications.
+</Info>
+
+## Key Capabilities
+
+- **Multi-org/project Support**: Specify organization and project when initializing the Mem0 client to attribute API usage appropriately
+- **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
+
+---
+
+## Using Organizations & Projects
+
+### Initialize with Org/Project Context
+
+Example with the mem0 Python package:
+
+<Tabs>
+  <Tab title="Python">
+
+```python
+from mem0 import MemoryClient
+client = MemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
+```
+
+  </Tab>
+
+  <Tab title="Node.js">
+
+```javascript
+import { MemoryClient } from "mem0ai";
+const client = new MemoryClient({
+  organizationId: "YOUR_ORG_ID",
+  projectId: "YOUR_PROJECT_ID"
+});
+```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Project Management
+
+The Mem0 client provides comprehensive project management through the `client.project` interface:
+
+### Get Project Details
+
+Retrieve information about the current project:
+
+```python
+# Get all project details
+project_info = client.project.get()
+
+# Get specific fields only
+project_info = client.project.get(fields=["name", "description", "custom_categories"])
+```
+
+### Create a New Project
+
+Create a new project within your organization:
+
+```python
+# Create a project with name and description
+new_project = client.project.create(
+    name="My New Project",
+    description="A project for managing customer support memories"
+)
+```
+
+### Update Project Settings
+
+Modify project configuration including custom instructions, categories, and graph settings:
+
+```python
+# Update project with custom categories
+client.project.update(
+    custom_categories=[
+        {"customer_preferences": "Customer likes, dislikes, and preferences"},
+        {"support_history": "Previous support interactions and resolutions"}
+    ]
+)
+
+# Update project with custom instructions
+client.project.update(
+    custom_instructions="..."
+)
+
+# Enable graph memory for the project
+client.project.update(enable_graph=True)
+
+# Update multiple settings at once
+client.project.update(
+    custom_instructions="...",
+    custom_categories=[
+        {"personal_info": "User personal information and preferences"},
+        {"work_context": "Professional context and work-related information"}
+    ],
+    enable_graph=True
+)
+```
+
+### Delete Project
+
+<Warning>
+This action will remove all memories, messages, and other related data in the project. **This operation is irreversible.**
+</Warning>
+
+Remove a project and all its associated data:
+
+```python
+# Delete the current project (irreversible)
+result = client.project.delete()
+```
+
+---
+
+## Member Management
+
+Manage project members and their access levels:
+
+```python
+# Get all project members
+members = client.project.get_members()
+
+# Add a new member as a reader
+client.project.add_member(
+    email="colleague@company.com",
+    role="READER"  # or "OWNER"
+)
+
+# Update a member's role
+client.project.update_member(
+    email="colleague@company.com",
+    role="OWNER"
+)
+
+# Remove a member from the project
+client.project.remove_member(email="colleague@company.com")
+```
+
+### Member Roles
+
+| Role | Permissions |
+|------|-------------|
+| **READER** | Can view and search memories, but cannot modify project settings or manage members |
+| **OWNER** | Full access including project modification, member management, and all reader permissions |
+
+---
+
+## Async Support
+
+All project methods are available in async mode:
+
+```python
+from mem0 import AsyncMemoryClient
+
+async def manage_project():
+    client = AsyncMemoryClient(org_id='YOUR_ORG_ID', project_id='YOUR_PROJECT_ID')
+
+    # All methods support async/await
+    project_info = await client.project.get()
+    await client.project.update(enable_graph=True)
+    members = await client.project.get_members()
+
+# To call the async function properly
+import asyncio
+asyncio.run(manage_project())
+```
+
+---
+
+## API Reference
+
+For complete API specifications and additional endpoints, see:
+
+<CardGroup cols={2}>
+  <Card title="Organizations APIs" icon="building" href="/api-reference/organization/create-org">
+    Create, get, and manage organizations
+  </Card>
+
+  <Card title="Project APIs" icon="folder" href="/api-reference/project/create-project">
+    Full project CRUD and member management endpoints
+  </Card>
+</CardGroup>

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

@@ -1,5 +1,6 @@
 ---
 title: 'Add Member'
+description: "Add a new member to a project with a specified role such as READER or OWNER access level."
 openapi: post /api/v1/orgs/organizations/{org_id}/projects/{project_id}/members/
 ---