chore: changing the page links

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

.agents/plugins/marketplace.json

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

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

@@ -30,9 +30,6 @@ jobs:
           cache: 'pnpm'
           cache-dependency-path: cli/node/pnpm-lock.yaml
 
-      - name: Upgrade npm for OIDC trusted publishing
-        run: npm install -g npm@latest
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -40,4 +37,10 @@ jobs:
         run: pnpm run build
 
       - name: Publish to npm
-        run: npm publish --provenance --access public
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/openclaw-cd.yml

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

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

@@ -30,9 +30,6 @@ jobs:
           cache: 'pnpm'
           cache-dependency-path: mem0-ts/pnpm-lock.yaml
 
-      - name: Upgrade npm for OIDC trusted publishing
-        run: npm install -g npm@latest
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -40,4 +37,10 @@ jobs:
         run: pnpm run build
 
       - name: Publish to npm
-        run: npm publish --provenance --access public
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

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

@@ -30,9 +30,6 @@ jobs:
           cache: 'pnpm'
           cache-dependency-path: vercel-ai-sdk/pnpm-lock.yaml
 
-      - name: Upgrade npm for OIDC trusted publishing
-        run: npm install -g npm@latest
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -40,4 +37,10 @@ jobs:
         run: pnpm run build
 
       - name: Publish to npm
-        run: npm publish --provenance --access public
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

AGENTS.md

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

CLAUDE.md

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

CONTRIBUTING.md

@@ -75,6 +75,7 @@ All packages are published automatically via GitHub Actions when a GitHub Releas
 | `mem0ai` (TypeScript SDK) | npm | `ts-v*` | `ts-v2.4.6` |
 | `@mem0/cli` (Node CLI) | npm | `cli-node-v*` | `cli-node-v0.1.2` |
 | `@mem0/vercel-ai-provider` | npm | `vercel-ai-v*` | `vercel-ai-v2.0.6` |
+| `@mem0/openclaw-mem0` | npm | `openclaw-v*` | `openclaw-v1.0.1` |
 
 #### How to Release
 

LLM.md

@@ -266,7 +266,7 @@ config = MemoryConfig(
     graph_store=GraphStoreConfig(provider="neo4j", config={...}),  # optional
     history_db_path="~/.mem0/history.db",
     version="v1.1",
-    custom_fact_extraction_prompt="Custom prompt...",
+    custom_instructions="Custom prompt...",
     custom_update_memory_prompt="Custom prompt..."
 )
 ```
@@ -684,7 +684,7 @@ Conversation: {messages}
 """
 
 config = MemoryConfig(
-    custom_fact_extraction_prompt=custom_extraction_prompt
+    custom_instructions=custom_extraction_prompt
 )
 memory = Memory(config)
 ```

README.md

@@ -39,19 +39,33 @@
 </p>
 
 <p align="center">
-  <a href="https://mem0.ai/research"><strong>📄 Building Production-Ready AI Agents with Scalable Long-Term Memory →</strong></a>
-</p>
-<p align="center">
-  <strong>⚡ +26% Accuracy vs. OpenAI Memory • 🚀 91% Faster • 💰 90% Fewer Tokens</strong>
+  <a href="https://mem0.ai/blog/mem0-the-token-efficient-memory-algorithm"><strong>📄 Building Production-Ready AI Agents with Scalable Long-Term Memory →</strong></a>
 </p>
 
-> **🎉 mem0ai v1.0.0 is now available!** This major release includes API modernization, improved vector store support, and enhanced GCP integration. [See migration guide →](MIGRATION_GUIDE_v1.0.md)
+## New Memory Algorithm (April 2026)
 
-##  🔥 Research Highlights
-- **+26% Accuracy** over OpenAI Memory on the LOCOMO benchmark
-- **91% Faster Responses** than full-context, ensuring low-latency at scale
-- **90% Lower Token Usage** than full-context, cutting costs without compromise
-- [Read the full paper](https://mem0.ai/research)
+| Benchmark | Old | New  | Tokens  | Latency p50  |
+| --- | --- | --- | --- | --- |
+| **LoCoMo** | 71.4 | **91.6** | 7.0K  | 0.88s  |
+| **LongMemEval** | 67.8 | **93.4** | 6.8K  | 1.09s  |
+| **BEAM (1M)** | — | **64.1** | 6.7K  | 1.00s  |
+| **BEAM (10M)** | — | **48.6** | 6.9K  | 1.05s  |
+
+All benchmarks run on the same production-representative model stack. Single-pass retrieval (one call, no agentic loops).
+
+**What changed:**
+- **Single-pass ADD-only extraction** -- one LLM call, no UPDATE/DELETE. Memories accumulate; nothing is overwritten.
+- **Agent-generated facts are first-class** -- when an agent confirms an action, that information is now stored with equal weight.
+- **Entity linking** -- entities are extracted, embedded, and linked across memories for retrieval boosting.
+- **Multi-signal retrieval** -- semantic, BM25 keyword, and entity matching scored in parallel and fused.
+
+See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for upgrade instructions. The [evaluation framework](https://github.com/mem0ai/memory-benchmarks) is open-sourced so anyone can reproduce the numbers.
+
+## Research Highlights
+- **91.6 on LoCoMo** -- +20 points over the previous algorithm
+- **93.4 on LongMemEval** -- +26 points, with +53.6 on assistant memory recall
+- **64.1 on BEAM (1M)** -- production-scale memory evaluation at 1M tokens
+- [Read the full paper](https://mem0.ai/blog/mem0-the-token-efficient-memory-algorithm)
 
 # Introduction
 
@@ -88,6 +102,13 @@ Install the sdk via pip:
 pip install mem0ai
 ```
 
+For enhanced hybrid search with BM25 keyword matching and entity extraction, install with NLP support:
+
+```bash
+pip install mem0ai[nlp]
+python -m spacy download en_core_web_sm
+```
+
 Install sdk via npm:
 ```bash
 npm install mem0ai
@@ -109,7 +130,9 @@ See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full comm
 
 ### Basic Usage
 
-Mem0 requires an LLM to function, with `gpt-4.1-nano-2025-04-14 from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+Mem0 requires an LLM to function, with `gpt-5-mini` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+
+Mem0 uses `text-embedding-3-small` from OpenAI as the default embedding model. For best results with hybrid search (semantic + keyword + entity boosting), we recommend using at least [Qwen 600M](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct) or a comparable embedding model. See [Supported Embeddings](https://docs.mem0.ai/components/embedders/overview) for configuration details.
 
 First step is to instantiate the memory:
 
@@ -122,13 +145,13 @@ memory = Memory()
 
 def chat_with_memories(message: str, user_id: str = "default_user") -> str:
     # Retrieve relevant memories
-    relevant_memories = memory.search(query=message, user_id=user_id, limit=3)
+    relevant_memories = memory.search(query=message, filters={"user_id": user_id}, top_k=3)
     memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories["results"])
 
     # Generate Assistant response
     system_prompt = f"You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n{memories_str}"
     messages = [{"role": "system", "content": system_prompt}, {"role": "user", "content": message}]
-    response = openai_client.chat.completions.create(model="gpt-4.1-nano-2025-04-14", messages=messages)
+    response = openai_client.chat.completions.create(model="gpt-5-mini", messages=messages)
     assistant_response = response.choices[0].message.content
 
     # Create new memories from the conversation

cli/cli-spec.json

@@ -10,8 +10,8 @@
     "logoMini": "\u25c6 mem0",
     "tagline": "The Memory Layer for AI Agents",
     "colors": {
-      "brand": "#F1C96C",
-      "accent": "#F5D78E",
+      "brand": "#8b5cf6",
+      "accent": "#a78bfa",
       "success": "#22c55e",
       "error": "#ef4444",
       "warning": "#f59e0b",

cli/node/README.md

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

cli/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/cli",
-  "version": "0.1.2",
+  "version": "0.2.3",
   "description": "The official CLI for mem0 — the memory layer for AI agents",
   "type": "module",
   "bin": {

cli/node/src/backend/base.ts

@@ -89,6 +89,8 @@ export interface Backend {
 
 	deleteEntities(opts: EntityIds): Promise<Record<string, unknown>>;
 
+	ping(): Promise<Record<string, unknown>>;
+
 	status(opts?: { userId?: string; agentId?: string }): Promise<
 		Record<string, unknown>
 	>;

cli/node/src/backend/platform.ts

@@ -3,6 +3,8 @@
  */
 
 import type { PlatformConfig } from "../config.js";
+import { isAgentMode } from "../state.js";
+import { CLI_VERSION } from "../version.js";
 import {
 	APIError,
 	type AddOptions,
@@ -24,6 +26,9 @@ export class PlatformBackend implements Backend {
 		this.headers = {
 			Authorization: `Token ${config.apiKey}`,
 			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
 		};
 	}
 
@@ -38,9 +43,14 @@ export class PlatformBackend implements Backend {
 			url += `?${qs}`;
 		}
 
+		const headers = {
+			...this.headers,
+			"X-Mem0-Caller-Type": isAgentMode() ? "agent" : "user",
+		};
+
 		const fetchOpts: RequestInit = {
 			method,
-			headers: this.headers,
+			headers,
 			signal: AbortSignal.timeout(30_000),
 		};
 		if (opts?.json) {
@@ -106,6 +116,7 @@ export class PlatformBackend implements Backend {
 		if (opts.expires) payload.expiration_date = opts.expires;
 		if (opts.categories) payload.categories = opts.categories;
 		if (opts.enableGraph) payload.enable_graph = true;
+		payload.source = "CLI";
 
 		return (await this._request("POST", "/v1/memories/", {
 			json: payload,
@@ -166,6 +177,7 @@ export class PlatformBackend implements Backend {
 		if (opts.keyword) payload.keyword_search = true;
 		if (opts.fields) payload.fields = opts.fields;
 		if (opts.enableGraph) payload.enable_graph = true;
+		payload.source = "CLI";
 
 		const result = (await this._request("POST", "/v2/memories/search/", {
 			json: payload,
@@ -176,10 +188,9 @@ export class PlatformBackend implements Backend {
 	}
 
 	async get(memoryId: string): Promise<Record<string, unknown>> {
-		return (await this._request("GET", `/v1/memories/${memoryId}/`)) as Record<
-			string,
-			unknown
-		>;
+		return (await this._request("GET", `/v1/memories/${memoryId}/`, {
+			params: { source: "CLI" },
+		})) as Record<string, unknown>;
 	}
 
 	async listMemories(
@@ -217,6 +228,7 @@ export class PlatformBackend implements Backend {
 		});
 		if (apiFilters) payload.filters = apiFilters;
 		if (opts.enableGraph) payload.enable_graph = true;
+		payload.source = "CLI";
 
 		const result = (await this._request("POST", "/v2/memories/", {
 			json: payload,
@@ -235,6 +247,7 @@ export class PlatformBackend implements Backend {
 		const payload: Record<string, unknown> = {};
 		if (content) payload.text = content;
 		if (metadata) payload.metadata = metadata;
+		payload.source = "CLI";
 		return (await this._request("PUT", `/v1/memories/${memoryId}/`, {
 			json: payload,
 		})) as Record<string, unknown>;
@@ -245,7 +258,7 @@ export class PlatformBackend implements Backend {
 		opts: DeleteOptions = {},
 	): Promise<Record<string, unknown>> {
 		if (opts.all) {
-			const params: Record<string, string> = {};
+			const params: Record<string, string> = { source: "CLI" };
 			if (opts.userId) params.user_id = opts.userId;
 			if (opts.agentId) params.agent_id = opts.agentId;
 			if (opts.appId) params.app_id = opts.appId;
@@ -255,10 +268,9 @@ export class PlatformBackend implements Backend {
 			})) as Record<string, unknown>;
 		}
 		if (memoryId) {
-			return (await this._request(
-				"DELETE",
-				`/v1/memories/${memoryId}/`,
-			)) as Record<string, unknown>;
+			return (await this._request("DELETE", `/v1/memories/${memoryId}/`, {
+				params: { source: "CLI" },
+			})) as Record<string, unknown>;
 		}
 		throw new Error("Either memoryId or --all is required");
 	}
@@ -281,16 +293,21 @@ export class PlatformBackend implements Backend {
 			result = (await this._request(
 				"DELETE",
 				`/v2/entities/${entityType}/${entityId}/`,
+				{ params: { source: "CLI" } },
 			)) as Record<string, unknown>;
 		}
 		return result;
 	}
 
+	async ping(): Promise<Record<string, unknown>> {
+		return (await this._request("GET", "/v1/ping/")) as Record<string, unknown>;
+	}
+
 	async status(
 		opts: { userId?: string; agentId?: string } = {},
 	): Promise<Record<string, unknown>> {
 		try {
-			await this._request("GET", "/v1/ping/");
+			await this.ping();
 			return { connected: true, backend: "platform", base_url: this.baseUrl };
 		} catch (e) {
 			return {

cli/node/src/branding.ts

@@ -19,8 +19,8 @@ export const LOGO = `
 export const LOGO_MINI = "◆ mem0";
 export const TAGLINE = "The Memory Layer for AI Agents";
 
-export const BRAND_COLOR = "#F1C96C";
-export const ACCENT_COLOR = "#F5D78E";
+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";

cli/node/src/commands/init.ts

@@ -41,10 +41,16 @@ async function emailLogin(
 	const url = baseUrl.replace(/\/+$/, "");
 	let codeValue = code;
 
+	const sourceHeaders = {
+		"Content-Type": "application/json",
+		"X-Mem0-Source": "cli",
+		"X-Mem0-Client-Language": "node",
+	};
+
 	if (!codeValue) {
 		const resp = await fetch(`${url}/api/v1/auth/email_code/`, {
 			method: "POST",
-			headers: { "Content-Type": "application/json" },
+			headers: sourceHeaders,
 			body: JSON.stringify({ email }),
 			signal: AbortSignal.timeout(30_000),
 		});
@@ -85,7 +91,7 @@ async function emailLogin(
 
 	const verifyResp = await fetch(`${url}/api/v1/auth/email_code/verify/`, {
 		method: "POST",
-		headers: { "Content-Type": "application/json" },
+		headers: sourceHeaders,
 		body: JSON.stringify({ email, code: codeValue.trim() }),
 		signal: AbortSignal.timeout(30_000),
 	});
@@ -215,6 +221,16 @@ async function validatePlatform(config: Mem0Config): Promise<void> {
 		});
 		if (status.connected) {
 			printSuccess("Connected to mem0 Platform!");
+			// Cache user_email from ping response for telemetry distinct_id
+			try {
+				const pingData = (await backend.ping()) as Record<string, unknown>;
+				const userEmail = pingData?.user_email as string | undefined;
+				if (userEmail) {
+					config.platform.userEmail = userEmail;
+				}
+			} catch {
+				/* ignore — telemetry ID will fall back to API key hash */
+			}
 		} else {
 			printError(
 				`Could not connect: ${status.error ?? "Unknown error"}`,
@@ -307,6 +323,7 @@ export async function runInit(
 
 		config.platform.apiKey = apiKeyVal;
 		config.platform.baseUrl = baseUrl;
+		config.platform.userEmail = email;
 		config.defaults.userId =
 			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
 
@@ -385,6 +402,7 @@ export async function runInit(
 
 			config.platform.apiKey = apiKeyVal;
 			config.platform.baseUrl = baseUrl;
+			config.platform.userEmail = email;
 			config.defaults.userId =
 				opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
 

cli/node/src/config.ts

@@ -20,6 +20,7 @@ export const CONFIG_VERSION = 1;
 export interface PlatformConfig {
 	apiKey: string;
 	baseUrl: string;
+	userEmail: string;
 }
 
 export interface DefaultsConfig {
@@ -30,10 +31,15 @@ export interface DefaultsConfig {
 	enableGraph: boolean;
 }
 
+export interface TelemetryConfig {
+	anonymousId: string;
+}
+
 export interface Mem0Config {
 	version: number;
 	defaults: DefaultsConfig;
 	platform: PlatformConfig;
+	telemetry: TelemetryConfig;
 }
 
 export function createDefaultConfig(): Mem0Config {
@@ -49,6 +55,10 @@ export function createDefaultConfig(): Mem0Config {
 		platform: {
 			apiKey: "",
 			baseUrl: DEFAULT_BASE_URL,
+			userEmail: "",
+		},
+		telemetry: {
+			anonymousId: "",
 		},
 	};
 }
@@ -70,6 +80,7 @@ export function loadConfig(): Mem0Config {
 		const plat = data.platform ?? {};
 		config.platform.apiKey = plat.api_key ?? "";
 		config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
+		config.platform.userEmail = plat.user_email ?? "";
 
 		const defaults = data.defaults ?? {};
 		config.defaults.userId = defaults.user_id ?? "";
@@ -77,6 +88,9 @@ export function loadConfig(): Mem0Config {
 		config.defaults.appId = defaults.app_id ?? "";
 		config.defaults.runId = defaults.run_id ?? "";
 		config.defaults.enableGraph = defaults.enable_graph ?? false;
+
+		const telemetry = data.telemetry ?? {};
+		config.telemetry.anonymousId = telemetry.anonymous_id ?? "";
 	}
 
 	// Environment variable overrides
@@ -114,6 +128,10 @@ export function saveConfig(config: Mem0Config): void {
 		platform: {
 			api_key: config.platform.apiKey,
 			base_url: config.platform.baseUrl,
+			user_email: config.platform.userEmail,
+		},
+		telemetry: {
+			anonymous_id: config.telemetry.anonymousId,
 		},
 	};
 
@@ -131,6 +149,7 @@ export function redactKey(key: string): string {
 const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
 	"platform.api_key": ["platform", "apiKey"],
 	"platform.base_url": ["platform", "baseUrl"],
+	"platform.user_email": ["platform", "userEmail"],
 	"defaults.user_id": ["defaults", "userId"],
 	"defaults.agent_id": ["defaults", "agentId"],
 	"defaults.app_id": ["defaults", "appId"],
@@ -139,6 +158,7 @@ const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
 	// Short-form aliases
 	api_key: ["platform", "apiKey"],
 	base_url: ["platform", "baseUrl"],
+	user_email: ["platform", "userEmail"],
 	user_id: ["defaults", "userId"],
 	agent_id: ["defaults", "agentId"],
 	app_id: ["defaults", "appId"],

cli/node/src/index.ts

@@ -8,22 +8,27 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { type Backend, getBackend } from "./backend/index.js";
-import { colors, printError } from "./branding.js";
+import { AuthError, type Backend, getBackend } from "./backend/index.js";
+import { colors, printError, printWarning } from "./branding.js";
 import type { Mem0Config } from "./config.js";
-import { loadConfig } from "./config.js";
+import { loadConfig, saveConfig } from "./config.js";
 import { richFormatHelp } from "./help.js";
 import { setAgentMode } from "./state.js";
+import { captureEvent } from "./telemetry.js";
 import { CLI_VERSION } from "./version.js";
 
 const program = new Command();
 
+// ── Validated user identity (set by getBackendAndConfig) ─────────────────
+
+let _validatedUserEmail: string | undefined;
+
 // ── Helpers ──────────────────────────────────────────────────────────────
 
-function getBackendAndConfig(
+async function getBackendAndConfig(
 	apiKey?: string,
 	baseUrl?: string,
-): { backend: Backend; config: Mem0Config } {
+): Promise<{ backend: Backend; config: Mem0Config }> {
 	const config = loadConfig();
 
 	if (apiKey) config.platform.apiKey = apiKey;
@@ -37,11 +42,51 @@ function getBackendAndConfig(
 		process.exit(1);
 	}
 
-	return { backend: getBackend(config), config };
+	const backend = getBackend(config);
+
+	// Validate the API key upfront with a fast timeout
+	try {
+		const pingData = (await Promise.race([
+			backend.ping(),
+			new Promise<never>((_, reject) =>
+				setTimeout(() => reject(new Error("timeout")), 5000),
+			),
+		])) as Record<string, unknown>;
+
+		const email = pingData?.user_email as string | undefined;
+		if (email) {
+			_validatedUserEmail = email;
+			if (config.platform.userEmail !== email) {
+				config.platform.userEmail = email;
+				try {
+					saveConfig(config);
+				} catch {
+					/* ignore */
+				}
+			}
+		}
+	} catch (e) {
+		if (e instanceof AuthError) {
+			printError(
+				"Invalid or expired API key.",
+				"Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+			);
+			process.exit(1);
+		}
+		// Network error / timeout — warn but proceed
+		printWarning(
+			"Could not validate API key (network issue). Proceeding anyway.",
+		);
+	}
+
+	return { backend, config };
 }
 
-function getBackendOnly(apiKey?: string, baseUrl?: string): Backend {
-	return getBackendAndConfig(apiKey, baseUrl).backend;
+async function getBackendOnly(
+	apiKey?: string,
+	baseUrl?: string,
+): Promise<Backend> {
+	return (await getBackendAndConfig(apiKey, baseUrl)).backend;
 }
 
 function checkAgentMode(): boolean {
@@ -123,6 +168,30 @@ program
 	.addHelpCommand(false)
 	.configureHelp({ formatHelp: richFormatHelp });
 
+// ── Telemetry hook ───────────────────────────────────────────────────────
+
+program.hook("preAction", (_thisCommand, actionCommand) => {
+	try {
+		const commandName = actionCommand.name();
+		const parentName = actionCommand.parent?.name();
+		const fullCommand =
+			parentName && parentName !== "mem0"
+				? `${parentName}.${commandName}`
+				: commandName;
+		const isAgent = !!(program.opts().json || program.opts().agent);
+		captureEvent(
+			`cli.${fullCommand}`,
+			{
+				command: fullCommand,
+				is_agent: isAgent,
+			},
+			_validatedUserEmail,
+		);
+	} catch {
+		/* silently swallow */
+	}
+});
+
 // ── Init ──────────────────────────────────────────────────────────────────
 
 program
@@ -179,7 +248,10 @@ program
 	.action(async (text, opts) => {
 		const { cmdAdd } = await import("./commands/memory.js");
 		const isAgent = checkAgentMode();
-		const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
 		const ids = resolveIds(config, opts);
 		const enableGraph = resolveGraph(config, opts);
 		const output = isAgent ? "agent" : opts.output;
@@ -233,7 +305,10 @@ program
 		}
 		const { cmdSearch } = await import("./commands/memory.js");
 		const isAgent = checkAgentMode();
-		const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
 		const ids = resolveIds(config, opts);
 		const enableGraph = resolveGraph(config, opts);
 		const output = isAgent ? "agent" : opts.output;
@@ -265,7 +340,7 @@ program
 	.action(async (memoryId, opts) => {
 		const { cmdGet } = await import("./commands/memory.js");
 		const isAgent = checkAgentMode();
-		const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdGet(backend, memoryId, { output });
 	});
@@ -301,7 +376,10 @@ program
 	.action(async (opts) => {
 		const { cmdList } = await import("./commands/memory.js");
 		const isAgent = checkAgentMode();
-		const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
 		const ids = resolveIds(config, opts);
 		const enableGraph = resolveGraph(config, opts);
 		const output = isAgent ? "agent" : opts.output;
@@ -337,7 +415,7 @@ program
 		}
 		const { cmdUpdate } = await import("./commands/memory.js");
 		const isAgent = checkAgentMode();
-		const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdUpdate(backend, memoryId, resolvedText, {
 			metadata: opts.metadata,
@@ -407,7 +485,7 @@ program
 		// ── Dispatch: single memory ──
 		if (memoryId) {
 			const { cmdDelete } = await import("./commands/memory.js");
-			const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+			const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 			await cmdDelete(backend, memoryId, {
 				output,
 				dryRun: opts.dryRun,
@@ -419,7 +497,7 @@ program
 		// ── Dispatch: --all ──
 		if (opts.all) {
 			const { cmdDeleteAll } = await import("./commands/memory.js");
-			const { backend, config } = getBackendAndConfig(
+			const { backend, config } = await getBackendAndConfig(
 				opts.apiKey,
 				opts.baseUrl,
 			);
@@ -444,7 +522,7 @@ program
 		// ── Dispatch: --entity ──
 		if (opts.entity) {
 			const { cmdEntitiesDelete } = await import("./commands/entities.js");
-			const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+			const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 			await cmdEntitiesDelete(backend, { ...opts, output });
 			return;
 		}
@@ -519,7 +597,7 @@ entityCmd
 	.action(async (entityType, opts) => {
 		const { cmdEntitiesList } = await import("./commands/entities.js");
 		const isAgent = checkAgentMode();
-		const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdEntitiesList(backend, entityType, { output });
 	});
@@ -543,7 +621,7 @@ entityCmd
 	.action(async (opts) => {
 		const { cmdEntitiesDelete } = await import("./commands/entities.js");
 		const isAgent = checkAgentMode();
-		const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdEntitiesDelete(backend, { ...opts, output });
 	});
@@ -569,7 +647,7 @@ eventCmd
 	.action(async (opts) => {
 		const { cmdEventList } = await import("./commands/events.js");
 		const isAgent = checkAgentMode();
-		const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdEventList(backend, { output });
 	});
@@ -587,7 +665,7 @@ eventCmd
 	.action(async (eventId, opts) => {
 		const { cmdEventStatus } = await import("./commands/events.js");
 		const isAgent = checkAgentMode();
-		const backend = getBackendOnly(opts.apiKey, opts.baseUrl);
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdEventStatus(backend, eventId, { output });
 	});
@@ -604,7 +682,10 @@ program
 	.action(async (opts) => {
 		const { cmdStatus } = await import("./commands/utils.js");
 		const isAgent = checkAgentMode();
-		const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdStatus(backend, {
 			userId: config.defaults.userId || undefined,
@@ -628,7 +709,10 @@ program
 	.action(async (filePath, opts) => {
 		const { cmdImport } = await import("./commands/utils.js");
 		const isAgent = checkAgentMode();
-		const { backend, config } = getBackendAndConfig(opts.apiKey, opts.baseUrl);
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
 		const ids = resolveIds(config, opts);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdImport(backend, filePath, {

cli/node/src/telemetry.ts

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

cli/node/telemetry-sender.cjs

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

cli/node/tests/branding.test.ts

@@ -39,7 +39,7 @@ afterEach(() => {
 
 describe("branding constants", () => {
   it("has correct brand color", () => {
-    expect(BRAND_COLOR).toBe("#F1C96C");
+    expect(BRAND_COLOR).toBe("#8b5cf6");
   });
 
   it("has correct tagline", () => {

cli/python/README.md

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

cli/python/pyproject.toml

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

cli/python/src/mem0_cli/__init__.py

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

cli/python/src/mem0_cli/app.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import json as _json
 import os
 import stat as _stat_mod
@@ -12,7 +13,7 @@ import typer
 from rich.console import Console
 
 from mem0_cli import __version__
-from mem0_cli.branding import BRAND_COLOR, print_error
+from mem0_cli.branding import BRAND_COLOR, print_error, print_warning
 
 console = Console()
 err_console = Console(stderr=True)
@@ -55,6 +56,44 @@ event_app = typer.Typer(
 # entity_app and event_app registered after Memory commands to control panel ordering
 
 
+# ── Validated user identity (set by _get_backend_and_config) ──────────────
+
+_validated_user_email: str | None = None
+
+# ── Telemetry helper ─────────────────────────────────────────────────────
+
+
+def _fire_telemetry(command_name: str, extra: dict | None = None) -> None:
+    """Fire a PostHog telemetry event (non-blocking, never fails)."""
+    try:
+        from mem0_cli.telemetry import capture_event
+
+        props = {"command": command_name}
+        if extra:
+            props.update(extra)
+        capture_event(f"cli.{command_name}", props, pre_resolved_email=_validated_user_email)
+    except Exception:
+        pass
+
+
+@config_app.callback(invoke_without_command=True)
+def _config_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"config.{ctx.invoked_subcommand}")
+
+
+@entity_app.callback(invoke_without_command=True)
+def _entity_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"entity.{ctx.invoked_subcommand}")
+
+
+@event_app.callback(invoke_without_command=True)
+def _event_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand:
+        _fire_telemetry(f"event.{ctx.invoked_subcommand}")
+
+
 # ── Helpers ───────────────────────────────────────────────────────────────
 
 
@@ -62,9 +101,16 @@ def _get_backend_and_config(
     api_key: str | None = None,
     base_url: str | None = None,
 ):
-    """Build and return the Platform backend plus the loaded config."""
+    """Build and return the Platform backend plus the loaded config.
+
+    Validates the API key upfront via ``/v1/ping/`` and caches the
+    resolved user email for telemetry.
+    """
+    global _validated_user_email
+
     from mem0_cli.backend import get_backend
-    from mem0_cli.config import load_config
+    from mem0_cli.backend.platform import AuthError
+    from mem0_cli.config import load_config, save_config
 
     config = load_config()
 
@@ -81,7 +127,29 @@ def _get_backend_and_config(
         )
         raise typer.Exit(1)
 
-    return get_backend(config), config
+    backend = get_backend(config)
+
+    # Validate the API key upfront with a fast timeout
+    try:
+        ping_data = backend.ping(timeout=5.0)
+        email = ping_data.get("user_email") if isinstance(ping_data, dict) else None
+        if email:
+            _validated_user_email = email
+            if config.platform.user_email != email:
+                config.platform.user_email = email
+                with contextlib.suppress(Exception):
+                    save_config(config)
+    except AuthError:
+        print_error(
+            err_console,
+            "Invalid or expired API key.",
+            hint="Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+        )
+        raise typer.Exit(1) from None
+    except Exception:
+        print_warning(err_console, "Could not validate API key (network issue). Proceeding anyway.")
+
+    return backend, config
 
 
 def _get_backend(
@@ -165,8 +233,11 @@ def main_callback(
     if version:
         from mem0_cli.commands.utils import cmd_version
 
+        _fire_telemetry("version")
         cmd_version()
         raise typer.Exit()
+    if ctx.invoked_subcommand:
+        _fire_telemetry(ctx.invoked_subcommand)
 
 
 # ── Memory: add ───────────────────────────────────────────────────────────
@@ -571,12 +642,14 @@ def delete(
 
     # ── Dispatch ─────────────────────────────────────────────────────
     if memory_id is not None:
+        _fire_telemetry("delete", {"delete_mode": "single"})
         from mem0_cli.commands.memory import cmd_delete
 
         backend = _get_backend(api_key, base_url)
         cmd_delete(backend, memory_id, dry_run=dry_run, force=force, output=output)
 
     elif all_:
+        _fire_telemetry("delete", {"delete_mode": "all"})
         from mem0_cli.commands.memory import cmd_delete_all
 
         backend, config = _get_backend_and_config(api_key, base_url)
@@ -584,6 +657,7 @@ def delete(
         cmd_delete_all(backend, force=force, dry_run=dry_run, all_=project, **ids, output=output)
 
     else:  # --entity
+        _fire_telemetry("delete", {"delete_mode": "entity"})
         from mem0_cli.commands.entities import cmd_entities_delete
 
         backend = _get_backend(api_key, base_url)

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

@@ -6,6 +6,7 @@ from typing import Any
 
 import httpx
 
+from mem0_cli import __version__
 from mem0_cli.backend.base import Backend
 from mem0_cli.config import PlatformConfig
 
@@ -21,11 +22,17 @@ class PlatformBackend(Backend):
             headers={
                 "Authorization": f"Token {config.api_key}",
                 "Content-Type": "application/json",
+                "X-Mem0-Source": "cli",
+                "X-Mem0-Client-Language": "python",
+                "X-Mem0-Client-Version": __version__,
             },
             timeout=30.0,
         )
 
     def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        from mem0_cli.state import is_agent_mode
+
+        self._client.headers["X-Mem0-Caller-Type"] = "agent" if is_agent_mode() else "user"
         resp = self._client.request(method, path, **kwargs)
         if resp.status_code == 401:
             raise AuthError("Authentication failed. Your API key may be invalid or expired.")
@@ -86,6 +93,7 @@ class PlatformBackend(Backend):
             payload["categories"] = categories
         if enable_graph:
             payload["enable_graph"] = True
+        payload["source"] = "CLI"
 
         return self._request("POST", "/v1/memories/", json=payload)
 
@@ -165,6 +173,7 @@ class PlatformBackend(Backend):
             payload["fields"] = fields
         if enable_graph:
             payload["enable_graph"] = True
+        payload["source"] = "CLI"
 
         result = self._request("POST", "/v2/memories/search/", json=payload)
         return (
@@ -174,7 +183,7 @@ class PlatformBackend(Backend):
         )
 
     def get(self, memory_id: str) -> dict:
-        return self._request("GET", f"/v1/memories/{memory_id}/")
+        return self._request("GET", f"/v1/memories/{memory_id}/", params={"source": "CLI"})
 
     def list_memories(
         self,
@@ -213,6 +222,7 @@ class PlatformBackend(Backend):
             payload["filters"] = api_filters
         if enable_graph:
             payload["enable_graph"] = True
+        payload["source"] = "CLI"
 
         result = self._request("POST", "/v2/memories/", json=payload, params=params)
         return (
@@ -229,6 +239,7 @@ class PlatformBackend(Backend):
             payload["text"] = content
         if metadata:
             payload["metadata"] = metadata
+        payload["source"] = "CLI"
         return self._request("PUT", f"/v1/memories/{memory_id}/", json=payload)
 
     def delete(
@@ -242,7 +253,7 @@ class PlatformBackend(Backend):
         run_id: str | None = None,
     ) -> dict:
         if all:
-            params: dict[str, str] = {}
+            params: dict[str, str] = {"source": "CLI"}
             if user_id:
                 params["user_id"] = user_id
             if agent_id:
@@ -253,7 +264,7 @@ class PlatformBackend(Backend):
                 params["run_id"] = run_id
             return self._request("DELETE", "/v1/memories/", params=params)
         elif memory_id:
-            return self._request("DELETE", f"/v1/memories/{memory_id}/")
+            return self._request("DELETE", f"/v1/memories/{memory_id}/", params={"source": "CLI"})
         else:
             raise ValueError("Either memory_id or --all is required")
 
@@ -278,9 +289,25 @@ class PlatformBackend(Backend):
         # Delete each provided entity via the v2 path-based endpoint
         result: dict = {}
         for entity_type, entity_id in entities.items():
-            result = self._request("DELETE", f"/v2/entities/{entity_type}/{entity_id}/")
+            result = self._request(
+                "DELETE", f"/v2/entities/{entity_type}/{entity_id}/", params={"source": "CLI"}
+            )
         return result
 
+    def ping(self, timeout: float | None = None) -> dict:
+        """Call the ping endpoint and return the raw response.
+
+        When *timeout* is given it overrides the client-level timeout so that
+        validation pings can fail fast without blocking the user.
+        """
+        if timeout is not None:
+            resp = self._client.get("/v1/ping/", timeout=timeout)
+            if resp.status_code == 401:
+                raise AuthError("Authentication failed. Your API key may be invalid or expired.")
+            resp.raise_for_status()
+            return resp.json()
+        return self._request("GET", "/v1/ping/")
+
     def status(
         self,
         *,
@@ -289,7 +316,7 @@ class PlatformBackend(Backend):
     ) -> dict[str, Any]:
         """Check connectivity using the ping endpoint."""
         try:
-            self._request("GET", "/v1/ping/")
+            self.ping()
             return {"connected": True, "backend": "platform", "base_url": self.base_url}
         except Exception as e:
             return {"connected": False, "backend": "platform", "error": str(e)}

cli/python/src/mem0_cli/branding.py

@@ -26,8 +26,8 @@ LOGO_MINI = "◆ mem0"
 
 TAGLINE = "The Memory Layer for AI Agents"
 
-BRAND_COLOR = "#F1C96C"  # Golden
-ACCENT_COLOR = "#F5D78E"
+BRAND_COLOR = "#8b5cf6"  # Purple
+ACCENT_COLOR = "#a78bfa"
 SUCCESS_COLOR = "#22c55e"
 ERROR_COLOR = "#ef4444"
 WARNING_COLOR = "#f59e0b"

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

@@ -108,6 +108,10 @@ def _email_login(
     The caller expects at minimum an ``api_key`` field.
     """
     url = base_url.rstrip("/")
+    _source_headers = {
+        "X-Mem0-Source": "cli",
+        "X-Mem0-Client-Language": "python",
+    }
 
     with httpx.Client(timeout=30.0) as client:
         # If code is already provided, skip sending — user already has a code
@@ -116,6 +120,7 @@ def _email_login(
             resp = client.post(
                 f"{url}/api/v1/auth/email_code/",
                 json={"email": email},
+                headers=_source_headers,
             )
             if resp.status_code == 429:
                 print_error(err_console, "Too many attempts. Try again in a few minutes.")
@@ -148,6 +153,7 @@ def _email_login(
         resp = client.post(
             f"{url}/api/v1/auth/email_code/verify/",
             json={"email": email, "code": code.strip()},
+            headers=_source_headers,
         )
         if resp.status_code == 429:
             print_error(err_console, "Too many attempts. Try again in a few minutes.")
@@ -229,6 +235,7 @@ def run_init(
             raise typer.Exit(1)
         config.platform.api_key = api_key_val
         config.platform.base_url = base_url
+        config.platform.user_email = email
         config.defaults.user_id = (
             user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
         )
@@ -299,6 +306,7 @@ def run_init(
                 raise typer.Exit(1)
             config.platform.api_key = api_key_val
             config.platform.base_url = base_url
+            config.platform.user_email = email_addr
             config.defaults.user_id = (
                 user_id or os.environ.get("USER") or os.environ.get("USERNAME") or "mem0-cli"
             )
@@ -384,6 +392,14 @@ def _validate_platform(config: Mem0Config) -> None:
         )
         if status.get("connected"):
             print_success(console, "Connected to mem0 Platform!")
+            # Cache user_email from ping response for telemetry distinct_id
+            try:
+                ping_data = backend.ping()
+                user_email = ping_data.get("user_email") if isinstance(ping_data, dict) else None
+                if user_email:
+                    config.platform.user_email = user_email
+            except Exception:
+                pass
         else:
             print_error(
                 err_console,

cli/python/src/mem0_cli/config.py

@@ -27,6 +27,7 @@ CONFIG_VERSION = 1
 class PlatformConfig:
     api_key: str = ""
     base_url: str = DEFAULT_BASE_URL
+    user_email: str = ""
 
 
 @dataclass
@@ -38,16 +39,23 @@ class DefaultsConfig:
     enable_graph: bool = False
 
 
+@dataclass
+class TelemetryConfig:
+    anonymous_id: str = ""
+
+
 @dataclass
 class Mem0Config:
     version: int = CONFIG_VERSION
     defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
     platform: PlatformConfig = field(default_factory=PlatformConfig)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
 
 
 SHORT_KEY_ALIASES: dict[str, str] = {
     "api_key": "platform.api_key",
     "base_url": "platform.base_url",
+    "user_email": "platform.user_email",
     "user_id": "defaults.user_id",
     "agent_id": "defaults.agent_id",
     "app_id": "defaults.app_id",
@@ -76,6 +84,7 @@ def load_config() -> Mem0Config:
         plat = data.get("platform", {})
         config.platform.api_key = plat.get("api_key", "")
         config.platform.base_url = plat.get("base_url", DEFAULT_BASE_URL)
+        config.platform.user_email = plat.get("user_email", "")
 
         defaults = data.get("defaults", {})
         config.defaults.user_id = defaults.get("user_id", "")
@@ -84,6 +93,9 @@ def load_config() -> Mem0Config:
         config.defaults.run_id = defaults.get("run_id", "")
         config.defaults.enable_graph = defaults.get("enable_graph", False)
 
+        telemetry = data.get("telemetry", {})
+        config.telemetry.anonymous_id = telemetry.get("anonymous_id", "")
+
     # Environment variable overrides
     env_key = os.environ.get("MEM0_API_KEY")
     if env_key:
@@ -132,6 +144,10 @@ def save_config(config: Mem0Config) -> None:
         "platform": {
             "api_key": config.platform.api_key,
             "base_url": config.platform.base_url,
+            "user_email": config.platform.user_email,
+        },
+        "telemetry": {
+            "anonymous_id": config.telemetry.anonymous_id,
         },
     }
 

cli/python/src/mem0_cli/telemetry.py

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

cli/python/src/mem0_cli/telemetry_sender.py

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

cli/python/tests/test_cli_integration.py

@@ -83,11 +83,6 @@ class TestCLIIntegration:
         assert "add" in result.stdout
         assert "search" in result.stdout
 
-    def test_version_flag(self):
-        result = _run(["--version"])
-        assert result.returncode == 0
-        assert "0.1.0" in result.stdout
-
     def test_add_help(self):
         result = _run(["add", "--help"])
         assert result.returncode == 0

cli/python/tests/test_commands.py

@@ -30,7 +30,6 @@ from mem0_cli.commands.memory import (
 from mem0_cli.commands.utils import (
     cmd_import,
     cmd_status,
-    cmd_version,
 )
 
 
@@ -742,15 +741,6 @@ class TestStatusCommand:
         assert '"status"' in output
 
 
-class TestVersionCommand:
-    def test_version(self):
-        console, buf = _make_console()
-        with patch("mem0_cli.commands.utils.console", console):
-            cmd_version()
-        output = buf.getvalue()
-        assert "0.1.0" in output
-
-
 class TestImportCommand:
     def test_import_json(self, mock_backend, tmp_path):
         file_path = tmp_path / "import.json"

cookbooks/helper/mem0_teachability.py

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

docs/api-reference.mdx

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

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

@@ -47,8 +47,6 @@ Provide at least one message or direct memory string. Most callers supply `messa
 | `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.
 
@@ -83,20 +81,3 @@ Successful requests return an array of events queued for processing. Each event
 ```
 </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/get-memories.mdx

@@ -62,8 +62,7 @@ To retrieve graph memory relationships between entities, pass `output_format="v1
 memories = client.get_all(
     filters={
         "user_id": "alex"
-    },
-    output_format="v1.1"
+    }
 )
 ```
 

docs/api-reference/organizations-projects.mdx

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

docs/changelog/highlights.mdx

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

docs/changelog/openclaw.mdx

@@ -0,0 +1,199 @@
+---
+title: "OpenClaw"
+description: "Release notes for the OpenClaw plugin and agent harness."
+mode: "wide"
+---
+
+<Update label="2026-04-11" description="v1.0.6">
+
+**Bug Fixes:**
+- **Telemetry:** Replaced shared `"anonymous-openclaw"` fallback with a persistent per-machine random hash (`openclaw-anon-<uuid>`), so anonymous plugin users are counted individually in PostHog ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Added PostHog `$identify` event on first authenticated run to stitch anonymous history onto the authenticated profile ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Fixed event loss on short-lived CLI invocations — added `beforeExit` handler to flush queued events before the process exits ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Added lazy `/v1/ping/` email resolution so users who configure API key outside `mem0 init` show as their email in PostHog, not an md5 hash ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+- **Telemetry:** Unified CLI event prefix from `openclaw.<cmd>` to `openclaw.cli.<cmd>` on the needsSetup branch to match the authenticated branch ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+
+**Improvements:**
+- **API:** Added `source: "OPENCLAW"` to all provider calls (`add`, `search`, `getAll`) across tools, CLI commands, recall, and the OSS backend adapter ([#4790](https://github.com/mem0ai/mem0/pull/4790))
+
+</Update>
+
+<Update label="2026-04-07" description="v1.0.5">
+
+**Bug Fixes:**
+- **Init interactive choice bug**: Fixed number selection in `openclaw mem0 init` — entering 1/2/3 now correctly selects the corresponding option (was broken by readline prefill concatenating with user input)
+- **OSS pgvector crash** ([#4727](https://github.com/mem0ai/mem0/issues/4727)): Fixed "Client has already been connected" cascade when using pgvector in OSS mode. The warmup call swallowed errors leaving a half-initialized pg client; concurrent recall/capture then all hit `client.connect()` on the same client. Fix: let warmup errors propagate (so `initPromise` resets and retries with a fresh Memory + fresh pg client) and build fresh config objects per attempt instead of mutating shared state.
+
+**Removed:**
+- **`orgId` / `projectId` config parameters**: Removed from config schema, CLI (`config show/get/set`), init display, and providers. The API key is project-scoped, so separate org/project IDs are unnecessary and could cause access errors if mismatched.
+- **`enableGraph` config parameter**: Removed from all config surfaces, providers, backend, and tools. Graph memory is being deprecated — removing the flag avoids unnecessary exposure.
+
+</Update>
+
+<Update label="2026-04-04" description="v1.0.4">
+
+**New Features:**
+- **Interactive init flow**: `openclaw mem0 init` with interactive menu (email verification or direct API key). Non-interactive modes: `--api-key`, `--email`, `--email --code`
+- **`memory_add` tool**: Replaces `memory_store` — name now matches `mem0` CLI and platform API
+- **`memory_delete` tool**: Unified delete — single ID, search-then-delete, bulk, entity cascade. Replaces `memory_forget` and `memory_delete_all`
+- **CLI subcommands**: `openclaw mem0 init`, `openclaw mem0 status`, `openclaw mem0 config show`, `openclaw mem0 config set`
+- **`import` CLI command**: Bulk-import memories from a JSON file with `--user-id` and `--agent-id` overrides
+- **`event list` / `event status` CLI commands**: Monitor background processing events
+- **`fs-safe.ts` module**: Isolated filesystem wrappers in a separate entry point
+- **`backend/` module**: `PlatformBackend` with direct HTTP API access for CLI commands
+- **Plugin manifest**: Added `contracts.tools`, `configSchema`, and `uiHints` to `openclaw.plugin.json`
+- **Test suite**: 329 tests across 10 test files
+
+**Changes:**
+- **Modular architecture**: Extracted tools into `tools/` directory (6 files) and CLI into `cli/commands.ts`
+- **Code splitting**: tsup builds with `splitting: true` and two entry points
+- **Skills updated**: All SKILL.md files reference new tool names (`memory_add`, `memory_delete`)
+- **Auto-recall timeout**: Recall wrapped in 8-second `Promise.race`
+- **Auto-capture fire-and-forget**: `provider.add()` runs in background via `.then()/.catch()`
+- **Auto-capture minimum content gate**: Skips extraction when total user content is fewer than 50 chars
+
+**Removed:**
+- `memory_store` tool — replaced by `memory_add`
+- `memory_forget` tool — replaced by `memory_delete`
+- `memory_delete_all` tool — merged into `memory_delete`
+- `memory_history` tool and `history` CLI command — deprecated
+
+</Update>
+
+<Update label="2026-04-03" description="v1.0.3">
+
+**Bug Fixes:**
+- **Security**: Added `safePath()` containment helper to `readSkillFile` and `readDomainOverlay` in `skill-loader.ts` — prevents directory traversal
+- **Noise filter**: Reverted incorrect `After-Compaction` regex rename back to `Post-Compaction`
+
+**Changes:**
+- **Supply-chain hardening**: Pinned `mem0ai` dependency to exact `2.3.0` (was `^2.3.0`)
+
+**Tests:**
+- 12 new tests covering `safePath`, `readSkillFile`, `readDomainOverlay`, and `loadSkill` with traversal inputs
+
+</Update>
+
+<Update label="2026-04-02" description="v1.0.2">
+
+**Bug Fixes:**
+- **Security**: Removed `resolveEnvVars()` and `resolveEnvVarsDeep()` from `config.ts` — plugin-side env resolution was redundant and triggered static analysis warnings ([#4676](https://github.com/mem0ai/mem0/pull/4676))
+
+</Update>
+
+<Update label="2026-04-02" description="v1.0.1">
+
+**New Features:**
+- **CD workflow**: Added continuous deployment workflow with OIDC trusted publishing ([#4672](https://github.com/mem0ai/mem0/pull/4672))
+- **Plugin configuration manifest**: Added `compat` and `build` metadata to `package.json` ([#4667](https://github.com/mem0ai/mem0/pull/4667))
+- **LICENSE**: Added Apache-2.0 license file ([#4667](https://github.com/mem0ai/mem0/pull/4667))
+
+**Bug Fixes:**
+- **Dream gate**: Fixed cheap-first ordering, session isolation, and verified completion ([#4666](https://github.com/mem0ai/mem0/pull/4666))
+- **Graceful startup**: Plugin now starts gracefully when no API key is configured ([#4669](https://github.com/mem0ai/mem0/pull/4669))
+
+</Update>
+
+<Update label="2026-04-01" description="v1.0.0">
+
+**New Features:**
+- **Skills-based memory architecture**: New skill-loader and skill-based extraction pipeline with batched extraction ([#4624](https://github.com/mem0ai/mem0/pull/4624))
+- **Dream gate**: Memory consolidation and dream-cycle processing during idle periods
+- **Enhanced recall**: New `recall.ts` module with improved recall logic and skill-aware retrieval
+- **Memory triage skill**: Domain-aware memory triage with companion domain support and recall protocol
+- **Memory dream skill**: Skill for memory consolidation during idle periods
+- **Plugin configuration**: Added `openclaw.plugin.json` manifest and `scripts/configure.py` setup helper
+
+**Changes:**
+- Extraction pipeline refactored to use skills-based architecture for more contextual and higher quality memory capture
+
+</Update>
+
+<Update label="2026-03-26" description="v0.4.1">
+
+**New Features:**
+- **Improved extraction quality**: Enhanced noise filtering, deduplication, and better extraction instructions
+
+**Bug Fixes:**
+- **Credential detection**: Improved detection of credentials, API keys, and secrets in extraction instructions (#4552)
+- **Standalone timestamps**: Prevented extraction of standalone timestamps as memories (#4550)
+
+</Update>
+
+<Update label="2026-03-16" description="v0.4.0">
+
+**New Features:**
+- **Non-interactive trigger filtering**: Skips recall and capture for `cron`, `heartbeat`, `automation`, and `schedule` triggers
+- **Subagent hallucination prevention**: Detects ephemeral subagent sessions and routes recall to parent namespace
+- **Dynamic recall thresholding**: Memories scoring less than 50% of top result are dropped
+- **SQLite resilience**: Init error recovery with automatic retry for OSS mode
+- **`disableHistory` config option**: New `oss.disableHistory` flag
+- 78 unit tests covering filtering, isolation, trigger filtering, subagent detection, and SQLite resilience
+
+**Changes:**
+- Auto-recall threshold raised from 0.5 to 0.6 for stricter precision
+- Recall candidate pool increased to `topK * 2` for better filtering headroom
+- Relaxed extraction instructions: related facts kept together to preserve context
+
+**Bug Fixes:**
+- **Concurrent session race condition**: Lifecycle hooks now use `ctx.sessionKey` directly instead of a shared mutable variable
+
+</Update>
+
+<Update label="2026-03-12" description="v0.3.1">
+
+**New Features:**
+- **Message filtering pipeline**: Multi-stage noise removal before extraction
+- **Broad recall for new sessions**: Short or new-session prompts trigger secondary broad search
+- **Client-side threshold filtering**: Safety net that drops low-relevance results
+- **Temporal anchoring**: Extraction instructions now include current date
+- 55 unit tests covering filtering and isolation helpers
+
+**Changes:**
+- Extraction window expanded from last 10 to last 20 messages
+- Rewritten custom extraction instructions for conciseness and deduplication
+- Refactored monolithic `index.ts` (1772 lines) into 6 focused modules
+
+</Update>
+
+<Update label="2026-03-10" description="v0.3.0">
+
+**Bug Fixes:**
+- Updated `mem0ai` dependency with sqlite3 to better-sqlite3 migration (#4270)
+
+</Update>
+
+<Update label="2026-03-09" description="v0.2.0">
+
+**New Features:**
+- Per-agent memory isolation for multi-agent setups via `agentId`
+- "Understanding userId" section in docs
+
+**Changes:**
+- Updated config examples to use concrete `userId` values instead of placeholders
+
+**Bug Fixes:**
+- Migrated platform search to Mem0 v2 API
+
+</Update>
+
+<Update label="2026-02-19" description="v0.1.2">
+
+**New Features:**
+- Source field for openclaw memory entries
+
+**Bug Fixes:**
+- Auto-recall injection and auto-capture message drop
+
+</Update>
+
+<Update label="2026-02-02" description="v0.1.0">
+
+**New Features:**
+- Initial release of the OpenClaw Mem0 plugin
+- Platform mode (Mem0 Cloud) and open-source mode support
+- Auto-recall: inject relevant memories before each turn
+- Auto-capture: store facts after each turn
+- Configurable `topK`, `threshold`, and `apiVersion` options
+
+</Update>

docs/changelog/platform.mdx

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

docs/changelog/sdk.mdx

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

docs/components/llms/models/google_AI.mdx

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

docs/components/llms/models/langchain.mdx

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

docs/components/llms/models/litellm.mdx

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

docs/components/llms/models/openai.mdx

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

docs/components/rerankers/config.mdx

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

docs/components/rerankers/custom-prompts.mdx

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

docs/components/rerankers/models/cohere.mdx

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

docs/components/rerankers/models/huggingface.mdx

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

docs/components/rerankers/models/llm.mdx

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

docs/components/rerankers/models/llm_reranker.mdx

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

docs/components/rerankers/models/sentence_transformer.mdx

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

docs/components/rerankers/models/zero_entropy.mdx

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

docs/components/rerankers/optimization.mdx

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

docs/components/vectordbs/dbs/langchain.mdx

@@ -15,7 +15,7 @@ Mem0 supports LangChain as a provider for vector store integration. LangChain pr
 ```python Python
 import os
 from mem0 import Memory
-from langchain_community.vectorstores import Chroma
+from langchain_chroma import Chroma
 from langchain_openai import OpenAIEmbeddings
 
 # Initialize a LangChain vector store

docs/components/vectordbs/dbs/opensearch.mdx

@@ -72,7 +72,7 @@ m.add(messages, user_id="alice", metadata={"category": "movies"})
 ### Search Memories
 
 ```python
-results = m.search("What kind of movies does Alice like?", user_id="alice")
+results = m.search("What kind of movies does Alice like?", filters={"user_id": "alice"})
 ```
 
 ### Features

docs/components/vectordbs/dbs/turbopuffer.mdx

@@ -36,7 +36,7 @@ messages = [
 m.add(messages, user_id="alice", metadata={"category": "movies"})
 
 # Search memories
-results = m.search(query="sci-fi recommendations", user_id="alice")
+results = m.search(query="sci-fi recommendations", filters={"user_id": "alice"})
 ```
 
 ### Config

docs/components/vectordbs/dbs/valkey.mdx

@@ -50,4 +50,25 @@ Here are the parameters available for configuring Valkey:
 | `hnsw_m` | Number of bi-directional links for HNSW | `16` |
 | `hnsw_ef_construction` | Size of dynamic candidate list for HNSW | `200` |
 | `hnsw_ef_runtime` | Size of dynamic candidate list for search | `10` |
+| `cluster_mode` | Enable cluster mode for Valkey cluster (CME) deployments | `false` |
 | `distance_metric` | Distance metric for vector similarity | `cosine` |
+
+## Cluster Mode
+
+To use Valkey with cluster mode enabled (CME), set `cluster_mode` to `true`:
+
+```python
+config = {
+    "vector_store": {
+        "provider": "valkey",
+        "config": {
+            "collection_name": "memories",
+            "valkey_url": "valkey://cluster-endpoint:6379",
+            "embedding_model_dims": 1536,
+            "cluster_mode": True
+        }
+    }
+}
+```
+
+When cluster mode is enabled, the connector uses `ValkeyCluster` instead of the standalone client, which handles `MOVED`/`ASK` redirections automatically. Search queries are coordinated across all shards by the valkey-search module's built-in coordinator. See the [valkey-search documentation](https://github.com/valkey-io/valkey-search) for details on cluster mode behavior.

docs/cookbooks/companions/ai-tutor.mdx

@@ -60,7 +60,7 @@ class PersonalAITutor:
         """
         # Start a streaming response request to the AI
         response = self.client.responses.create(
-            model="gpt-4.1-nano-2025-04-14",
+            model="gpt-5-mini",
             instructions="You are a personal AI Tutor.",
             input=question,
             stream=True
@@ -81,7 +81,7 @@ class PersonalAITutor:
         :param user_id: Optional user ID to filter memories.
         :return: List of memories.
         """
-        return self.memory.get_all(user_id=user_id)
+        return self.memory.get_all(filters={"user_id": user_id})
 
 # Instantiate the PersonalAITutor
 ai_tutor = PersonalAITutor()

docs/cookbooks/companions/local-companion-ollama.mdx

@@ -57,7 +57,7 @@ m = Memory.from_config(config)
 m.add("I'm visiting Paris", user_id="john")
 
 # Retrieve memories
-memories = m.get_all(user_id="john")
+memories = m.get_all(filters={"user_id": "john"})
 ```
 
 ## Key Points

docs/cookbooks/companions/nodejs-companion.mdx

@@ -47,7 +47,7 @@ ${memoriesStr}`;
   ];
   
   const response = await openaiClient.chat.completions.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
     messages: messages
   });
   

docs/cookbooks/companions/quickstart-demo.mdx

@@ -45,7 +45,7 @@ Before you begin, follow these steps to set up the demo application:
    OPENAI_API_KEY=your_openai_api_key
    MEM0_API_KEY=your_mem0_api_key
    ```
-   You can obtain your `MEM0_API_KEY` by signing up at [Mem0 API Dashboard](https://app.mem0.ai/dashboard/api-keys).
+   You can obtain your `MEM0_API_KEY` by signing up at <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">Mem0 API Dashboard</a>.
 
 5. Start the development server:
    ```bash

docs/cookbooks/companions/travel-assistant.mdx

@@ -36,7 +36,7 @@ config = {
     "llm": {
         "provider": "openai",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
             "temperature": 0.1,
             "max_tokens": 2000,
         }
@@ -77,7 +77,7 @@ class PersonalTravelAssistant:
 
         # Generate response using Responses API
         response = self.client.responses.create(
-            model="gpt-4.1-nano-2025-04-14",
+            model="gpt-5-mini",
             input=prompt
         )
 
@@ -89,11 +89,11 @@ class PersonalTravelAssistant:
         return answer
 
     def get_memories(self, user_id):
-        memories = self.memory.get_all(user_id=user_id)
+        memories = self.memory.get_all(filters={"user_id": user_id})
         return [m['memory'] for m in memories['results']]
 
     def search_memories(self, query, user_id):
-        memories = self.memory.search(query, user_id=user_id)
+        memories = self.memory.search(query, filters={"user_id": user_id})
         return [m['memory'] for m in memories['results']]
 
 # Usage example
@@ -143,7 +143,7 @@ class PersonalTravelAssistant:
 
         # Generate response using gpt-4.1-nano
         response = self.client.chat.completions.create(
-            model="gpt-4.1-nano-2025-04-14"2025-04-14",
+            model="gpt-5-mini",
             messages=self.messages
         )
         answer = response.choices[0].message.content
@@ -158,7 +158,7 @@ class PersonalTravelAssistant:
         return [m['memory'] for m in memories.get('results', [])]
 
     def search_memories(self, query, user_id):
-        memories = self.memory.search(query, user_id=user_id)
+        memories = self.memory.search(query, filters={"user_id": user_id})
         return [m['memory'] for m in memories.get('results', [])]
 
 # Usage example

docs/cookbooks/companions/voice-companion-openai.mdx

@@ -126,16 +126,15 @@ async def search_memories(
     print(f"Finding memories related to: {query}")
     results = await mem0_client.search(
         query,
-        user_id=USER_ID,
-        limit=5,
+        filters={"user_id": USER_ID},
+        top_k=5,
         threshold=0.7,  # Higher threshold for more relevant results
-        
     )
-    
+
     # Format and return the results
     if not results.get('results', []):
         return "I don't have any relevant memories about this topic."
-    
+
     memories = [f"• {result['memory']}" for result in results.get('results', [])]
     return "Here's what I remember that might be relevant:\n" + "\n".join(memories)
 ```
@@ -161,7 +160,7 @@ def create_memory_voice_agent():
             Use the search_memories tool when you need context from past conversations or user asks you to recall something.
             """,
         ),
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         tools=[save_memories, search_memories],
     )
     
@@ -342,16 +341,15 @@ async def search_memories(
     print(f"Finding memories related to: {query}")
     results = await mem0_client.search(
         query,
-        user_id=USER_ID,
-        limit=5,
+        filters={"user_id": USER_ID},
+        top_k=5,
         threshold=0.7,  # Higher threshold for more relevant results
-        
     )
-    
+
     # Format and return the results
     if not results.get('results', []):
         return "I don't have any relevant memories about this topic."
-    
+
     memories = [f"• {result['memory']}" for result in results.get('results', [])]
     return "Here's what I remember that might be relevant:\n" + "\n".join(memories)
 
@@ -368,7 +366,7 @@ def create_memory_voice_agent():
             Use the search_memories tool when you need context from past conversations or user asks you to recall something.
             """,
         ),
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         tools=[save_memories, search_memories],
     )
     

docs/cookbooks/essentials/building-ai-companion.mdx

@@ -62,7 +62,7 @@ mem0_client = MemoryClient(api_key="your-mem0-key")
 
 def chat(user_input, user_id):
     # Retrieve relevant memories
-    memories = mem0_client.search(user_input, user_id=user_id, limit=5)
+    memories = mem0_client.search(user_input, filters={"user_id": user_id}, top_k=5)
     context = "\\n".join(m["memory"] for m in memories["results"])
 
     # Call LLM with memory context
@@ -123,7 +123,7 @@ ollama_chat = OpenAI(base_url=f"{OLLAMA_URL}/v1", api_key="ollama")
 
 def chat(user_input, user_id):
     # Retrieve relevant memories
-    memories = memory.search(user_input, user_id=user_id, limit=5)
+    memories = memory.search(user_input, filters={"user_id": user_id}, top_k=5)
     context = "\n".join(m["memory"] for m in memories["results"])
 
     # Call LLM with memory context (Ollama via OpenAI-compatible API)
@@ -319,7 +319,7 @@ print([m["memory"] for m in memories["results"]])
   </Tab>
   <Tab title="Open Source">
 ```python
-memories = memory.get_all(user_id="max")
+memories = memory.get_all(filters={"user_id": "max"})
 print([m["memory"] for m in memories["results"]])
 # Output: ["Max wants to run marathon under 4 hours", "hey", "lol ok", "cool thanks", "gtg bye"]
 ```
@@ -354,10 +354,10 @@ Exclude:
 ```
   </Tab>
   <Tab title="Open Source">
-Tell Mem0 what matters by including `custom_fact_extraction_prompt` in the config dict:
+Tell Mem0 what matters by including `custom_instructions` in the config dict:
 
 ```python
-MEMORY_CONFIG["custom_fact_extraction_prompt"] = """
+MEMORY_CONFIG["custom_instructions"] = """
 Extract from running coach conversations:
 - Training goals and race targets
 - Physical constraints or injuries
@@ -375,7 +375,7 @@ Return JSON with key "facts" as a list of strings (use [] if nothing to store).
 memory = Memory.from_config(MEMORY_CONFIG)
 ```
 
-<Note>`custom_fact_extraction_prompt` is a top-level key in the config dictionary passed to `Memory.from_config()`. Make sure it's set before creating the Memory instance — not after.</Note>
+<Note>`custom_instructions` is a top-level key in the config dictionary passed to `Memory.from_config()`. Make sure it's set before creating the Memory instance — not after.</Note>
   </Tab>
 </Tabs>
 
@@ -397,7 +397,7 @@ print([m["memory"] for m in memories["results"]])
 chat("hey how's it going", user_id="max")
 chat("I prefer trail running over roads", user_id="max")
 
-memories = memory.get_all(user_id="max")
+memories = memory.get_all(filters={"user_id": "max"})
 print([m["memory"] for m in memories["results"]])
 # Output: ["Max wants to run marathon under 4 hours", "Max prefers trail running over roads"]
 ```
@@ -446,7 +446,7 @@ Retrieve agent style alongside user memories:
   <Tab title="Platform">
 ```python
 # Get coach personality
-agent_memories = mem0_client.search("coaching style", agent_id="ray_coach")
+agent_memories = mem0_client.search("coaching style", filters={"agent_id": "ray_coach"})
 # Output: ["Max wants direct, data-driven feedback. Skip motivational language."]
 
 # Store conversations with agent_id
@@ -459,7 +459,7 @@ mem0_client.add([
   <Tab title="Open Source">
 ```python
 # Get coach personality
-agent_memories = memory.search("coaching style", agent_id="ray_coach")
+agent_memories = memory.search("coaching style", filters={"agent_id": "ray_coach"})
 # Output: ["Max wants direct, data-driven feedback. Skip motivational language."]
 
 # Store conversations with agent_id
@@ -520,7 +520,7 @@ memory.add(
 # "hey" → don't store
 # "cool thanks" → don't store
 
-# Or rely on custom_fact_extraction_prompt to filter automatically
+# Or rely on custom_instructions to filter automatically
 ```
   </Tab>
 </Tabs>
@@ -545,11 +545,11 @@ expiration = (datetime.now() + timedelta(days=14)).strftime("%Y-%m-%d")
 mem0_client.add(
     [{"role": "user", "content": "Rolled my left ankle, needs rest"}],
     user_id="max",
-    expiration_date=expiration
+    metadata={"memory_bucket": "constraints", "expires_on": expiration}
 )
 ```
 
-In 14 days, this memory disappears automatically. Ray stops asking about the ankle.
+Store `expires_on` in metadata and periodically clean up expired memories. Ray stops asking about the ankle once it's removed.
   </Tab>
   <Tab title="Open Source">
 ```python
@@ -627,7 +627,7 @@ MEMORY_CONFIG = {
             "ollama_base_url": "http://localhost:11434",
         },
     },
-    "custom_fact_extraction_prompt": """
+    "custom_instructions": """
     Extract: goals, constraints, preferences, progress
     Exclude: greetings, filler, casual chat
     Return JSON with key "facts" as a list of strings.
@@ -684,8 +684,7 @@ expiration = (datetime.now() + timedelta(days=14)).strftime("%Y-%m-%d")
 mem0_client.add(
     [{"role": "user", "content": "Rolled ankle, need light workouts"}],
     user_id="max",
-    categories=["constraints"],
-    expiration_date=expiration
+    metadata={"memory_bucket": "constraints", "expires_on": expiration}
 )
 ```
   </Tab>
@@ -706,13 +705,13 @@ memory.add(
 <Tabs>
   <Tab title="Platform">
 ```python
-memories = mem0_client.search("training plan", user_id="max", limit=5)
+memories = mem0_client.search("training plan", filters={"user_id": "max"}, top_k=5)
 # Gets: marathon goal, trail preference, ankle injury (if still valid)
 ```
   </Tab>
   <Tab title="Open Source">
 ```python
-memories = memory.search("training plan", user_id="max", limit=5)
+memories = memory.search("training plan", filters={"user_id": "max"}, top_k=5)
 # Gets: marathon goal, trail preference, ankle injury (if still valid / not pruned)
 ```
   </Tab>
@@ -806,7 +805,7 @@ mem0_client.update(goal_memory["id"], "Max wants to run sub-3:45 marathon")
   <Tab title="Open Source">
 ```python
 # Find the old memory
-memories = memory.get_all(user_id="max")
+memories = memory.get_all(filters={"user_id": "max"})
 goal_memory = [m for m in memories["results"] if "sub-4" in m["memory"]][0]
 
 # Update it

docs/cookbooks/essentials/choosing-memory-architecture-vector-vs-graph.mdx

@@ -112,19 +112,17 @@ Let's add the same information with graph memory enabled:
 ```python
 client.add(
     "Emma works with David on the mobile app redesign",
-    user_id="company_kb",
-    enable_graph=True
+    user_id="company_kb"
 )
 
 client.add(
     "David reports to Rachel, who manages the design team",
-    user_id="company_kb",
-    enable_graph=True
+    user_id="company_kb"
 )
 
 ```
 
-When you set `enable_graph=True`, Mem0 extracts entities and relationships:
+When graph memory is enabled, Mem0 extracts entities and relationships:
 
 - `emma --[works_with]--> david`
 - `david --[reports_to]--> rachel`
@@ -135,8 +133,7 @@ Now the same query works differently:
 ```python
 results = client.search(
     "Who is Emma's teammate's manager?",
-    filters={"user_id": "company_kb"},
-    enable_graph=True
+    filters={"user_id": "company_kb"}
 )
 
 print(results['results'][0]['memory'])
@@ -209,30 +206,27 @@ For our company knowledge base, we'll use both:
 
 ## Putting It Together
 
-Let's build a small company knowledge base with both approaches:
+Let's build a small company knowledge base:
 
 ```python
-# Facts about individuals - vector store is fine
+# Facts about individuals
 client.add("Emma specializes in React and TypeScript", user_id="company_kb")
 client.add("David has 5 years of product management experience", user_id="company_kb")
 
-# Relationships - use graph memory
+# Relationships
 client.add(
     "Emma and David work together on the mobile app",
-    user_id="company_kb",
-    enable_graph=True
+    user_id="company_kb"
 )
 
 client.add(
     "David reports to Rachel",
-    user_id="company_kb",
-    enable_graph=True
+    user_id="company_kb"
 )
 
 client.add(
     "Rachel runs weekly team syncs every Tuesday",
-    user_id="company_kb",
-    enable_graph=True
+    user_id="company_kb"
 )
 
 ```
@@ -257,8 +251,7 @@ Emma specializes in React and TypeScript
 # Multi-hop relationship - graph search
 results = client.search(
     "What meetings does Emma's project manager's boss run?",
-    filters={"user_id": "company_kb"},
-    enable_graph=True
+    filters={"user_id": "company_kb"}
 )
 print(results['results'][0]['memory'])
 
@@ -281,23 +274,22 @@ Enable graph memory when your queries need multi-hop traversal: org charts (who
 
 ## The Tradeoff
 
-Graph memory adds processing time and cost. When you call `client.add()` with `enable_graph=True`, Mem0 makes extra LLM calls to extract entities and relationships.
+Graph memory adds processing time and cost. Mem0 makes extra LLM calls to extract entities and relationships from each memory.
 
 <Note>
-**Cost consideration:** Graph memory extraction adds ~2-3 extra LLM calls per `add()` operation to identify entities and relationships. Use it selectively—enable graph for organizational structure and long-term relationships, skip it for temporary notes and simple facts.
+**Cost consideration:** Graph memory extraction adds ~2-3 extra LLM calls per `add()` operation to identify entities and relationships. Use it when your use case benefits from relationship traversal—organizational structures, team hierarchies, and long-term connections.
 </Note>
 
 Use graph memory when the relationship traversal adds real value. For most use cases, vector search is sufficient and faster.
 
 ```python
-# Long-term organizational structure - worth using graph
+# Long-term organizational structure - benefits from graph
 client.add(
     "Emma mentors two junior engineers on the frontend team",
-    user_id="company_kb",
-    enable_graph=True
+    user_id="company_kb"
 )
 
-# Temporary notes - skip graph, not worth the cost
+# Temporary notes stored with a run_id for session isolation
 client.add(
     "Emma is out sick today",
     user_id="company_kb",
@@ -308,38 +300,13 @@ client.add(
 
 ---
 
-## Enabling Graph Memory
-
-You can enable graph memory in two ways:
-
-**Per-call** (recommended to start):
-
-```python
-client.add("Emma works with David", user_id="company_kb", enable_graph=True)
-client.search("team structure", filters={"user_id": "company_kb"}, enable_graph=True)
-
-```
-
-**Project-wide** (if most of your data has relationships):
-
-```python
-client.project.update(enable_graph=True)
-
-# Now every add uses graph automatically
-client.add("Emma mentors Jordan", user_id="company_kb")
-
-```
-
----
-
 ## What You Built
 
 A hybrid company knowledge base that combines both architectures:
 
 - **Vector search** - Fast semantic lookups for individual facts (Emma's skills, David's experience)
 - **Graph memory** - Multi-hop relationship traversal (Emma's teammate's manager, project hierarchies)
-- **Selective enablement** - Graph only for long-term organizational structure, vector for everything else
-- **Cost optimization** - Skip graph extraction for temporary notes and simple facts
+- **Cost optimization** - Use graph for long-term organizational structure, vector for temporary notes and simple facts
 
 This pattern scales from 10-person startups to enterprise org charts with thousands of employees.
 

docs/cookbooks/essentials/controlling-memory-ingestion.mdx

@@ -38,7 +38,7 @@ client = MemoryClient(api_key="your-api-key")
 ```
 
 <Note>
-Replace `your-api-key` with your actual Mem0 API key from the [dashboard](https://app.mem0.ai). Without proper API authentication, memory operations will fail.
+Replace `your-api-key` with your actual Mem0 API key from the <a href="https://app.mem0.ai" rel="nofollow">dashboard</a>. Without proper API authentication, memory operations will fail.
 </Note>
 
 ---
@@ -514,8 +514,8 @@ These controls prevent retrieval failures and ensure your AI assistant works wit
 Start with conservative filters (only store confirmed facts) and iterate based on your application's needs. Combine custom instructions with confidence thresholds for the most reliable memory ingestion pipeline.
 
 <CardGroup cols={2}>
-  <Card title="Expire Short-Term Data" icon="timer" href="/cookbooks/essentials/memory-expiration-short-and-long-term">
-    Automatically clean up session context before it clutters retrieval.
+  <Card title="Build a Mem0 Companion" icon="users" href="/cookbooks/essentials/building-ai-companion">
+    Learn core memory patterns including temporary vs permanent data handling.
   </Card>
   <Card title="Choose Your Memory Architecture" icon="sitemap" href="/cookbooks/essentials/choosing-memory-architecture-vector-vs-graph">
     Learn when to layer graph memory alongside vectors for multi-hop queries.

docs/cookbooks/essentials/entity-partitioning-playbook.mdx

@@ -17,7 +17,7 @@ from mem0 import MemoryClient
 client = MemoryClient(api_key="m0-...")
 ```
 
-Grab an API key from the <Link href="https://app.mem0.ai/">Mem0 dashboard</Link> to get started.
+Grab an API key from the <a href="https://app.mem0.ai/" rel="nofollow">Mem0 dashboard</a> to get started.
 
 ## Store and Retrieve Scoped Memories
 

docs/cookbooks/essentials/exporting-memories.mdx

@@ -20,7 +20,7 @@ client = MemoryClient(api_key="your-api-key")
 ```
 
 <Note>
-Your API key needs export permissions to download memory data. Check your project settings on the [dashboard](https://app.mem0.ai) if export operations fail with authentication errors.
+Your API key needs export permissions to download memory data. Check your project settings on the <a href="https://app.mem0.ai" rel="nofollow">dashboard</a> if export operations fail with authentication errors.
 </Note>
 
 Let's add some sample memories to work with:
@@ -280,8 +280,8 @@ This covers data portability, GDPR compliance, system migrations, and manual rev
 Use **`get_all()`** for bulk retrieval, **`search()`** for specific questions, and **`create_memory_export()`** for structured data exports with custom schemas. Remember exports expire after 7 days—download them locally for long-term archives.
 
 <CardGroup cols={2}>
-  <Card title="Expire Short-Term Data" icon="timer" href="/cookbooks/essentials/memory-expiration-short-and-long-term">
-    Keep exports lean by clearing session context before you archive it.
+  <Card title="Build a Mem0 Companion" icon="users" href="/cookbooks/essentials/building-ai-companion">
+    Learn core memory patterns including temporary vs permanent data handling.
   </Card>
   <Card title="Control Memory Ingestion" icon="filter" href="/cookbooks/essentials/controlling-memory-ingestion">
     Ensure only verified insights make it into your export pipeline.

docs/cookbooks/essentials/memory-expiration-short-and-long-term.mdx

@@ -1,277 +0,0 @@
----
-title: Set Memory Expiration
-description: "Define short-term versus long-term retention so the store stays fresh."
----
-
-
-While building memory systems, we realized their size grows fast. Session notes, temporary context, chat history - everything starts accumulating and bogging down the system. This pollutes search results and increase storage costs. Not every memory needs to persist forever.
-
-In this cookbook, we'll go through how to use short-term vs long-term memories and see where it's best to use them.
-
----
-
-## Overview
-
-By default, Mem0 memories persist forever. This works for user preferences and core facts, but temporary data should expire automatically.
-
-In this tutorial, we will:
-
-- Understand default (permanent) memory behavior
-- Add expiration dates for temporary memories
-- Decide what should be temporary vs permanent
-
----
-
-## Setup
-
-```python
-from mem0 import MemoryClient
-from datetime import datetime, timedelta
-
-client = MemoryClient(api_key="your-api-key")
-```
-
-<Note>
-Import `datetime` and `timedelta` to calculate expiration dates. Without these imports, you'll need to manually format ISO timestamps—error-prone and harder to read.
-</Note>
-
----
-
-## Default Behavior: Everything Persists
-
-By default, all memories persist forever:
-
-```python
-# Store user preference
-client.add("User prefers dark mode", user_id="sarah")
-
-# Store session context
-client.add("Currently browsing electronics category", user_id="sarah")
-
-# 6 months later - both still exist
-results = client.get_all(filters={"user_id": "sarah"})
-print(f"Total memories: {len(results['results'])}")
-
-```
-
-**Output:**
-
-```
-Total memories: 2
-
-```
-
-Both the preference and session context persist. The preference is useful, but the 6-month-old session context is not.
-
----
-
-## The Problem: Memory Bloat
-
-Without expiration, memories accumulate forever. Session notes from weeks ago mix with current preferences. Storage grows, search results get polluted with irrelevant old context, and retrieval quality degrades.
-
-<Warning>
-Memory bloat degrades search quality. When "User prefers dark mode" competes with "Currently browsing electronics" from 6 months ago, semantic search returns stale session data instead of actual preferences. Old memories pollute retrieval.
-</Warning>
-
----
-
-## Short-Term Memories: Adding Expiration
-
-Set `expiration_date` to make memories temporary:
-
-```python
-from datetime import datetime, timedelta
-
-# Session context - expires in 7 days
-expires_at = (datetime.now() + timedelta(days=7)).isoformat()
-
-client.add(
-    "Currently browsing electronics category",
-    user_id="sarah",
-    expiration_date=expires_at
-)
-
-# User preference - no expiration, persists forever
-client.add(
-    "User prefers dark mode",
-    user_id="sarah"
-)
-
-```
-
-<Info icon="check">
-**Expected behavior:** After 7 days, the session context automatically disappears—no cron jobs, no manual cleanup. The preference persists forever. Mem0 handles expiration transparently.
-</Info>
-
-Memories with `expiration_date` are automatically removed after expiring. No cleanup job needed - Mem0 handles it.
-
-<Tip>
-Start conservative with short expiration windows (7 days), then extend them based on usage patterns. It's easier to increase retention than to clean up over-retained stale data. Monitor search quality to find the right balance.
-</Tip>
-
----
-
-## When to Use Each
-
-### Permanent Memories (no expiration_date):
-
-**Use for:**
-
-- User preferences and settings
-- Account information
-- Important facts and milestones
-- Historical data that matters long-term
-
-```python
-client.add("User prefers email notifications", user_id="sarah")
-client.add("User's birthday is March 15th", user_id="sarah")
-client.add("User completed onboarding on Jan 5th", user_id="sarah")
-
-```
-
-### Temporary Memories (with expiration_date):
-
-**Use for:**
-
-- Session context (current page, browsing history)
-- Temporary reminders
-- Recent chat history
-- Cached data
-
-```python
-expires_7d = (datetime.now() + timedelta(days=7)).isoformat()
-
-client.add(
-    "Currently viewing product ABC123",
-    user_id="sarah",
-    expiration_date=expires_7d
-)
-
-client.add(
-    "Asked about return policy",
-    user_id="sarah",
-    expiration_date=expires_7d
-)
-
-```
-
----
-
-## Setting Different Expiration Periods
-
-Different data needs different lifetimes:
-
-```python
-# Session context - 7 days
-expires_7d = (datetime.now() + timedelta(days=7)).isoformat()
-client.add("Browsing electronics", user_id="sarah", expiration_date=expires_7d)
-
-# Recent chat - 30 days
-expires_30d = (datetime.now() + timedelta(days=30)).isoformat()
-client.add("User asked about warranty", user_id="sarah", expiration_date=expires_30d)
-
-# Important preference - no expiration
-client.add("User prefers dark mode", user_id="sarah")
-
-```
-
----
-
-## Using Metadata to Track Memory Types
-
-Tag memories to make filtering easier:
-
-```python
-expires_7d = (datetime.now() + timedelta(days=7)).isoformat()
-
-# Tag session context
-client.add(
-    "Browsing electronics",
-    user_id="sarah",
-    expiration_date=expires_7d,
-    metadata={"type": "session"}
-)
-
-# Tag preference
-client.add(
-    "User prefers dark mode",
-    user_id="sarah",
-    metadata={"type": "preference"}
-)
-
-# Query only preferences
-preferences = client.get_all(
-    filters={
-        "AND": [
-            {"user_id": "sarah"},
-            {"metadata": {"type": "preference"}}
-        ]
-    }
-)
-
-```
-
----
-
-## Checking Expiration Status
-
-See which memories will expire and when:
-
-```python
-results = client.get_all(filters={"user_id": "sarah"})
-
-for memory in results['results']:
-    exp_date = memory.get('expiration_date')
-
-    if exp_date:
-        print(f"Temporary: {memory['memory']}")
-        print(f"  Expires: {exp_date}\\n")
-    else:
-        print(f"Permanent: {memory['memory']}\\n")
-
-```
-
-**Output:**
-
-```
-Temporary: Browsing electronics
-  Expires: 2025-11-01T10:30:00Z
-
-Temporary: Viewed MacBook Pro and Dell XPS
-  Expires: 2025-11-01T10:30:00Z
-
-Permanent: User prefers dark mode
-
-Permanent: User prefers email notifications
-
-```
-
----
-
-## What You Built
-
-A self-cleaning memory system with automatic retention policies:
-
-- **Automatic expiration** - Memories self-destruct after defined periods, no cron jobs needed
-- **Tiered retention** - 7-day session context, 30-day chat history, permanent preferences
-- **Metadata tagging** - Classify memories by type (session, preference, chat) for filtered retrieval
-- **Expiration tracking** - Check which memories will expire and when using `get_all()`
-
-This pattern keeps storage costs low and search quality high as your memory store scales.
-
----
-
-## Summary
-
-Memory expiration keeps storage clean and search results relevant. Use **`expiration_date`** for temporary data (session context, recent chats), skip it for permanent facts (preferences, account info). Mem0 handles cleanup automatically—no background jobs required.
-
-Start by identifying what's temporary versus permanent, then set conservative expiration windows and adjust based on retrieval quality.
-
-<CardGroup cols={2}>
-  <Card title="Control Memory Ingestion" icon="filter" href="/cookbooks/essentials/controlling-memory-ingestion">
-    Pair expirations with ingestion rules so only trusted context persists.
-  </Card>
-  <Card title="Export Memories Safely" icon="download" href="/cookbooks/essentials/exporting-memories">
-    Build compliant archives once your retention windows are dialed in.
-  </Card>
-</CardGroup>

docs/cookbooks/frameworks/chrome-extension.mdx

@@ -1,70 +0,0 @@
----
-title: Browser Extension Memory
-description: "Add Mem0's universal memory layer to Chrome chat surfaces."
----
-
-
-Enhance your AI interactions with Mem0, a Chrome extension that introduces a universal memory layer across platforms like ChatGPT, Claude, and Perplexity. Mem0 ensures seamless context sharing, making your AI experiences more personalized and efficient.
-
-<Note>
-  We now support Grok! The Mem0 Chrome Extension has been updated to work with Grok, bringing the same powerful memory capabilities to your Grok conversations.
-</Note>
-
-
-## Features
-
-- **Universal Memory Layer**: Share context seamlessly across ChatGPT, Claude, Perplexity, and Grok.
-- **Smart Context Detection**: Automatically captures relevant information from your conversations.
-- **Intelligent Memory Retrieval**: Surfaces pertinent memories at the right time.
-- **One-Click Sync**: Easily synchronize with existing ChatGPT memories.
-- **Memory Dashboard**: Manage all your memories in one centralized location.
-
-## Installation
-
-You can install the Mem0 Chrome Extension using one of the following methods:
-
-### Method 1: Chrome Web Store Installation
-
-1. **Download the Extension**: Open Google Chrome and navigate to the [Mem0 Chrome Extension page](https://chromewebstore.google.com/detail/mem0/onihkkbipkfeijkadecaafbgagkhglop?hl=en).
-2. **Add to Chrome**: Click on the "Add to Chrome" button.
-3. **Confirm Installation**: In the pop-up dialog, click "Add extension" to confirm. The Mem0 icon should now appear in your Chrome toolbar.
-
-### Method 2: Manual Installation
-
-1. **Download the Extension**: Clone or download the extension files from the [Mem0 Chrome Extension GitHub repository](https://github.com/mem0ai/mem0-chrome-extension).
-2. **Access Chrome Extensions**: Open Google Chrome and navigate to `chrome://extensions`.
-3. **Enable Developer Mode**: Toggle the "Developer mode" switch in the top right corner.
-4. **Load Unpacked Extension**: Click "Load unpacked" and select the directory containing the extension files.
-5. **Confirm Installation**: The Mem0 Chrome Extension should now appear in your Chrome toolbar.
-
-## Usage
-
-1. **Locate the Mem0 Icon**: After installation, find the Mem0 icon in your Chrome toolbar.
-2. **Sign In**: Click the icon and sign in with your Google account.
-3. **Interact with AI Assistants**:
-   - **ChatGPT and Perplexity**: Continue your conversations as usual; Mem0 operates seamlessly in the background.
-   - **Claude**: Click the Mem0 button or use the shortcut `Ctrl + M` to activate memory functions.
-
-## Configuration
-
-- **API Key**: Obtain your API key from the Mem0 Dashboard to connect the extension to the Mem0 API.
-- **User ID**: This is your unique identifier in the Mem0 system. If not provided, it defaults to `chrome-extension-user`.
-
-## Demo Video
-
-<iframe width="700" height="400" src="https://www.youtube.com/embed/dqenCMMlfwQ?si=zhGVrkq6IS_0Jwyj" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
-
-## Privacy and Data Security
-
-Your messages are sent to the Mem0 API for extracting and retrieving memories. Mem0 is committed to ensuring your data's privacy and security.
-
----
-
-<CardGroup cols={2}>
-  <Card title="Build a Mem0 Companion" icon="users" href="/cookbooks/essentials/building-ai-companion">
-    Learn the foundations of memory-powered assistants that work across platforms.
-  </Card>
-  <Card title="Multimodal Support" icon="image" href="/platform/features/multimodal-support">
-    Extend your browser interactions with vision and audio memory.
-  </Card>
-</CardGroup>

docs/cookbooks/frameworks/gemini-3-with-mem0-mcp.mdx

@@ -55,7 +55,7 @@ GEMINI_API_KEY=your-gemini-api-key-here
 ```
 
 <Note>
-Ensure you have your Mem0 API key from the [Mem0 Dashboard](https://app.mem0.ai) and your Gemini API key from the [Google AI Studio](https://ai.studio/app/api-keys).
+Ensure you have your Mem0 API key from the <a href="https://app.mem0.ai" rel="nofollow">Mem0 Dashboard</a> and your Gemini API key from the [Google AI Studio](https://ai.studio/app/api-keys).
 </Note>
 
 ## Gemini Memory Agent

docs/cookbooks/frameworks/llamaindex-multiagent.mdx

@@ -41,7 +41,7 @@ Set up your environment variables:
 - `MEM0_API_KEY`: Your Mem0 Platform API key
 - `OPENAI_API_KEY`: Your OpenAI API key
 
-You can obtain your Mem0 Platform API key from the [Mem0 Platform](https://app.mem0.ai).
+You can obtain your Mem0 Platform API key from the <a href="https://app.mem0.ai" rel="nofollow">Mem0 Platform</a>.
 
 ## Complete Implementation
 
@@ -83,7 +83,7 @@ class MultiAgentLearningSystem:
 
     def __init__(self, student_id: str):
         self.student_id = student_id
-        self.llm = OpenAI(model="gpt-4.1-nano-2025-04-14", temperature=0.2)
+        self.llm = OpenAI(model="gpt-5-mini", temperature=0.2)
 
         # Memory context for this student
         self.memory_context = {"user_id": student_id, "app": "learning_assistant"}
@@ -357,7 +357,7 @@ Based on our previous session, I remember we covered Vision Language Models and
 ## Help & Resources
 
 - [LlamaIndex Agent Workflows](https://docs.llamaindex.ai/en/stable/use_cases/agents/)
-- [Mem0 Platform](https://app.mem0.ai/)
+- <a href="https://app.mem0.ai/" rel="nofollow">Mem0 Platform</a>
 
 ---
 

docs/cookbooks/frameworks/llamaindex-react.mdx

@@ -22,10 +22,10 @@ import os
 from llama_index.llms.openai import OpenAI
 
 os.environ["OPENAI_API_KEY"] = "<your-openai-api-key>"
-llm = OpenAI(model="gpt-4.1-nano-2025-04-14")
+llm = OpenAI(model="gpt-5-mini")
 ```
 
-Initialize the Mem0 client. You can find your API key [here](https://app.mem0.ai/dashboard/api-keys). Read about Mem0 [Open Source](https://docs.mem0.ai/open-source/overview).
+Initialize the Mem0 client. You can find your API key <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">here</a>. Read about Mem0 [Open Source](https://docs.mem0.ai/open-source/overview).
 ```python
 os.environ["MEM0_API_KEY"] = "<your-mem0-api-key>"
 

docs/cookbooks/frameworks/mirofish-swarm-memory.mdx

@@ -1,766 +0,0 @@
----
-title: MiroFish Swarm Memory
-description: "Build a multi-agent swarm simulation with graph-powered memory using Mem0 and MiroFish patterns."
----
-
-<Snippet file="blank-notif.mdx" />
-
-Build a multi-agent swarm simulation with graph-powered memory using Mem0 OSS and [MiroFish](https://github.com/666ghj/MiroFish) patterns. MiroFish is a graph-centric system — it extracts entities and relationships from documents, builds a knowledge graph, and queries it throughout its pipeline. Mem0's Graph Memory is a natural replacement for its Zep Cloud integration.
-
-<Note>
-  This cookbook demonstrates the **core memory patterns** using a simplified simulation. MiroFish's actual architecture uses a factory pattern (`memory_factory.py`) with abstract providers, batch buffering with retries in `ZepGraphMemoryUpdater`, and IPC-based agent interviews. This cookbook focuses on the Mem0 API integration points — wrap these calls in your own retry/batch logic for production use.
-</Note>
-
-## Overview
-
-This cookbook implements a **Housing Policy Prediction Simulation** following MiroFish's five-stage workflow:
-
-1. **Graph Building** — Ingest seed documents, extract entities and relationships
-2. **Environment Setup** — Query the knowledge graph to enrich agent profiles
-3. **Simulation** — Track agent interactions with per-agent memory isolation
-4. **Report Generation** — Semantic search + graph traversal for analysis
-5. **Deep Interaction** — Query post-simulation memory and relationships (MiroFish also supports live agent interviews via IPC — not covered here)
-
-Three agents debate a housing policy reform:
-- **Mayor Chen** — Policy advocate pushing for zoning reform
-- **Wang (Homeowner)** — Opposition leader organizing resistance
-- **Professor Li** — Academic providing data-driven analysis
-
-## Prerequisites
-
-```bash
-pip install "mem0ai[graph]"
-```
-
-You need a graph backend. Choose one:
-
-| Backend | Setup | Best for |
-|---|---|---|
-| **Neo4j Aura** (free tier) | [Sign up](https://neo4j.com/product/auradb/), get Bolt URI | Production, closest to Zep |
-| **Neo4j Docker** | `docker run -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:5` | Local development |
-| **Kuzu** (embedded) | No setup needed — runs in-process | Quick testing, zero dependencies |
-
-```bash
-export OPENAI_API_KEY="sk-..."
-
-# Option A: Neo4j Docker (local development)
-docker run -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:5
-export NEO4J_URL="neo4j://localhost:7687"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="password"
-
-# Option B: Neo4j Aura (production — free tier available)
-export NEO4J_URL="neo4j+s://<your-instance>.databases.neo4j.io"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="your-aura-password"
-
-# Option C: Kuzu (zero setup — auto-detected when NEO4J_URL is not set)
-# No exports needed
-```
-
-## Complete Implementation
-
-```python
-"""
-MiroFish Swarm Prediction Simulation with Mem0 Graph Memory
-
-MiroFish uses Zep Cloud as its knowledge graph backend. This implementation
-replaces Zep with Mem0 OSS Graph Memory, which provides:
-- Automatic entity extraction from text
-- Relationship mining (source → relationship → destination triples)
-- Combined vector + graph search returning memories AND relations
-- Per-agent isolation via run_id
-- Self-hosted with no node caps
-
-Follows MiroFish's 5-stage pipeline:
-1. Graph Building    - Ingest seed documents, extract entities
-2. Environment Setup - Query graph to enrich agent profiles
-3. Simulation        - Track agent actions with per-agent isolation
-4. Report Generation - Semantic + graph search for analysis
-5. Deep Interaction  - Query post-simulation knowledge graph
-
-Run:
-    export OPENAI_API_KEY="sk-..."
-    export NEO4J_URL="neo4j://localhost:7687"
-    export NEO4J_USERNAME="neo4j"
-    export NEO4J_PASSWORD="password"
-    python mirofish_swarm_memory.py
-"""
-
-import os
-import time
-from mem0 import Memory
-
-
-# ======================================================================
-# MiroFish Agent Action Types (matches OASIS simulation output)
-# ======================================================================
-
-# Twitter actions
-TWITTER_ACTIONS = [
-    "CREATE_POST", "LIKE_POST", "REPOST", "FOLLOW",
-    "DO_NOTHING", "QUOTE_POST",
-]
-
-# Reddit actions (superset — includes moderation + discovery)
-REDDIT_ACTIONS = [
-    "LIKE_POST", "DISLIKE_POST", "CREATE_POST", "CREATE_COMMENT",
-    "LIKE_COMMENT", "DISLIKE_COMMENT", "SEARCH_POSTS", "SEARCH_USER",
-    "TREND", "REFRESH", "DO_NOTHING", "FOLLOW", "MUTE",
-]
-
-# Combined (DO_NOTHING is skipped during memory storage)
-MIROFISH_ACTIONS = list(set(TWITTER_ACTIONS + REDDIT_ACTIONS) - {"DO_NOTHING"})
-
-
-# ======================================================================
-# Graph Memory Configuration
-# ======================================================================
-
-def build_config():
-    """Build Mem0 config with Graph Memory.
-
-    Uses Neo4j if credentials are set, otherwise falls back to Kuzu (embedded).
-    """
-    neo4j_url = os.environ.get("NEO4J_URL")
-
-    # Shared config for LLM, embedder, and vector store
-    base = {
-        "llm": {
-            "provider": "openai",
-            "config": {"model": "gpt-4o-mini", "temperature": 0.1}
-        },
-        "embedder": {
-            "provider": "openai",
-            "config": {"model": "text-embedding-3-small", "embedding_dims": 1536}
-        },
-        "vector_store": {
-            "provider": "qdrant",
-            "config": {
-                "collection_name": "mirofish",
-                "embedding_model_dims": 1536,
-            }
-        },
-    }
-
-    custom_prompt = (
-        "Extract all people, organizations, policies, locations, "
-        "and their relationships. Capture support/opposition stances, "
-        "affiliations, and quantitative claims."
-    )
-
-    if neo4j_url:
-        base["graph_store"] = {
-            "provider": "neo4j",
-            "config": {
-                "url": neo4j_url,
-                "username": os.environ.get("NEO4J_USERNAME", "neo4j"),
-                "password": os.environ.get("NEO4J_PASSWORD", "password"),
-            },
-            "custom_prompt": custom_prompt,
-        }
-    else:
-        # Fallback: Kuzu embedded (no external services needed)
-        print("  NEO4J_URL not set — using Kuzu (embedded) graph store")
-        base["graph_store"] = {
-            "provider": "kuzu",
-            "config": {"db": "/tmp/mirofish_graph.kuzu"},
-            "custom_prompt": custom_prompt,
-        }
-
-    return base
-
-
-# ======================================================================
-# Simulation Engine
-# ======================================================================
-
-class MiroFishSimulation:
-    """
-    Multi-agent simulation with graph-powered memory.
-
-    Uses Mem0 Graph Memory to replace MiroFish's Zep Cloud integration:
-    - Entities and relationships are extracted automatically from text
-    - search() returns both semantic memories AND graph relations
-    - Per-agent isolation via run_id
-    - Project isolation via user_id
-    """
-
-    def __init__(self, project_id: str, config: dict):
-        self.project_id = project_id
-        self.memory = Memory.from_config(config)
-        self.stats = {
-            "documents_ingested": 0,
-            "activities_recorded": 0,
-            "rounds_completed": 0,
-        }
-
-    # ------------------------------------------------------------------
-    # Stage 1: Graph Building — Seed Document Ingestion
-    # ------------------------------------------------------------------
-
-    def ingest_documents(self, documents: list[str]):
-        """Ingest seed documents and extract entities + relationships.
-
-        MiroFish equivalent: GraphBuilderService.build_graph()
-        Zep equivalent: graph.add_batch() with episode polling
-
-        With Mem0 Graph Memory, each document is processed by the LLM
-        to extract entities (people, orgs, policies) and relationships
-        (supports, opposes, filed). These become nodes and edges in the
-        graph store, alongside vector embeddings for semantic search.
-        """
-        print("  Ingesting documents and building knowledge graph...")
-        for i, doc in enumerate(documents):
-            result = self.memory.add(
-                [{"role": "user", "content": doc}],
-                user_id=self.project_id,
-                metadata={"stage": "graph_building", "source": "seed_document", "chunk_index": i}
-            )
-            # Graph Memory returns extracted relations
-            relations = result.get("relations", {})
-            added = relations.get("added_entities", [])
-            if added:
-                print(f"    Doc {i}: extracted {len(added)} entities/relations")
-
-        self.stats["documents_ingested"] = len(documents)
-        print(f"  Ingested {len(documents)} documents")
-
-    # ------------------------------------------------------------------
-    # Stage 2: Environment Setup — Agent Profile Enrichment
-    # ------------------------------------------------------------------
-
-    def enrich_agent_profile(self, agent_name: str, persona_query: str) -> dict:
-        """Search memory + graph for context relevant to an agent's persona.
-
-        MiroFish equivalent: OasisProfileGenerator using graph.search()
-
-        Returns both semantic memories and graph relations that can be
-        injected into the agent's system prompt.
-        """
-        results = self.memory.search(
-            persona_query,
-            user_id=self.project_id,
-            limit=10
-        )
-        facts = [r["memory"] for r in results.get("results", [])]
-        relations = results.get("relations", [])
-
-        print(f"  {agent_name}: {len(facts)} facts, {len(relations)} relations")
-        return {"facts": facts, "relations": relations}
-
-    # ------------------------------------------------------------------
-    # Stage 3: Simulation — Agent Activity Tracking
-    # ------------------------------------------------------------------
-
-    def record_action(self, agent_id: str, agent_name: str,
-                      action_type: str, content: str,
-                      platform: str, round_num: int):
-        """Record a single agent action as a memory with graph extraction.
-
-        MiroFish equivalent: ZepGraphMemoryUpdater.add_activity()
-        Zep equivalent: graph.add(type="text", data=episode_text)
-
-        Agent memories use run_id to group by agent (no assistant
-        memories involved). Graph Memory extracts entities/relationships
-        from the action content automatically.
-        """
-        formatted = f"{agent_name} [{action_type}]: {content}"
-
-        self.memory.add(
-            [{"role": "user", "content": formatted}],
-            run_id=agent_id,
-            metadata={
-                "action_type": action_type,
-                "platform": platform,
-                "round": round_num,
-                "agent_name": agent_name,
-            }
-        )
-        self.stats["activities_recorded"] += 1
-
-    def run_round(self, round_num: int, activities: list[tuple]):
-        """Execute one simulation round."""
-        print(f"  Round {round_num}: {len(activities)} actions")
-        for agent_id, agent_name, action_type, content, platform in activities:
-            self.record_action(agent_id, agent_name, action_type, content, platform, round_num)
-        self.stats["rounds_completed"] = max(self.stats["rounds_completed"], round_num)
-
-    def recall_agent_memory(self, agent_id: str, query: str) -> dict:
-        """Agent recalls its own memories mid-simulation.
-
-        Searches by run_id to match the scope used during add().
-        """
-        results = self.memory.search(
-            query,
-            run_id=agent_id,
-            limit=5
-        )
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    # ------------------------------------------------------------------
-    # Stage 4: Report Generation — Semantic + Graph Retrieval
-    # ------------------------------------------------------------------
-
-    def quick_search(self, query: str, limit: int = 10) -> dict:
-        """Semantic search + graph relations across all agents.
-
-        MiroFish equivalent: ZepToolsService.quick_search()
-        Returns both vector-matched memories and related graph triples.
-        """
-        results = self.memory.search(
-            query,
-            user_id=self.project_id,
-            limit=limit
-        )
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    def panorama_search(self) -> dict:
-        """Retrieve all memories + all graph relations.
-
-        MiroFish equivalent: ZepToolsService.panorama_search()
-        Returns the complete knowledge state for report generation.
-        """
-        results = self.memory.get_all(user_id=self.project_id)
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    def agent_search(self, agent_id: str, query: str, limit: int = 10) -> dict:
-        """Search within a single agent's memory space."""
-        results = self.memory.search(
-            query,
-            run_id=agent_id,
-            limit=limit
-        )
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    # ------------------------------------------------------------------
-    # Cleanup
-    # ------------------------------------------------------------------
-
-    def cleanup(self):
-        """Delete all memories and graph data for this simulation."""
-        self.memory.delete_all(user_id=self.project_id)
-        print(f"  Cleaned up all memories for {self.project_id}")
-
-
-# ======================================================================
-# Run the full 5-stage pipeline
-# ======================================================================
-
-def main():
-    project_id = f"mirofish_housing_{int(time.time())}"
-    config = build_config()
-    sim = MiroFishSimulation(project_id=project_id, config=config)
-
-    # ==================================================================
-    # STAGE 1: Graph Building — Ingest seed documents
-    # ==================================================================
-    print("=" * 60)
-    print("STAGE 1: Graph Building")
-    print("=" * 60)
-
-    sim.ingest_documents([
-        "The city council proposed a new zoning reform allowing higher "
-        "density housing in suburban areas. Mayor Chen expressed strong "
-        "support, citing a 40% housing shortage affecting young professionals. "
-        "The reform would allow buildings up to 8 stories in previously "
-        "restricted 3-story zones.",
-
-        "Local homeowners association president Wang opposes the reform, "
-        "arguing it will decrease property values by 15-20%. The association "
-        "represents 5,000 homeowners in the affected districts. Wang has "
-        "organized three community meetings and collected 2,000 signatures.",
-
-        "Professor Li from Beijing University published research showing "
-        "similar reforms in Shenzhen led to 15% price drops in existing "
-        "homes but created 30% more affordable housing units within 3 years. "
-        "The study covered 12 districts and 50,000 housing units.",
-    ])
-
-    # ==================================================================
-    # STAGE 2: Environment Setup — Enrich agent profiles
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 2: Environment Setup")
-    print("=" * 60)
-
-    mayor_context = sim.enrich_agent_profile(
-        "Mayor Chen",
-        "Mayor Chen housing reform zoning policy"
-    )
-    wang_context = sim.enrich_agent_profile(
-        "Wang",
-        "Wang homeowner opposition property values petition"
-    )
-    li_context = sim.enrich_agent_profile(
-        "Professor Li",
-        "Professor Li research housing data Shenzhen"
-    )
-
-    print("\n  Example profile context for Mayor Chen:")
-    for fact in mayor_context["facts"][:3]:
-        print(f"    Fact: {fact}")
-    for rel in mayor_context["relations"][:3]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # STAGE 3: Simulation — Run agent interactions
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 3: Simulation")
-    print("=" * 60)
-
-    # Round 1: Opening statements
-    sim.run_round(1, [
-        ("mayor_chen", "Mayor Chen", "CREATE_POST",
-         "This reform will create 10,000 new housing units by 2028. "
-         "Young families deserve affordable homes. #HousingForAll",
-         "twitter"),
-
-        ("wang_homeowner", "Wang", "CREATE_POST",
-         "Our property values will plummet! The council ignores the "
-         "voices of 5,000 homeowners. #StopTheReform",
-         "twitter"),
-
-        ("prof_li", "Professor Li", "CREATE_POST",
-         "New analysis: Shenzhen zoning data shows net positive outcomes "
-         "after 3 years. Short-term pain, long-term gain for housing equity.",
-         "twitter"),
-    ])
-
-    # Round 2: Debate and interaction
-    sim.run_round(2, [
-        ("wang_homeowner", "Wang", "CREATE_COMMENT",
-         "Replied to Professor Li: 'Shenzhen is a tier-1 city with "
-         "completely different dynamics. Your comparison is misleading.'",
-         "twitter"),
-
-        ("mayor_chen", "Mayor Chen", "LIKE_POST",
-         "Liked Professor Li's post about Shenzhen housing data.",
-         "twitter"),
-
-        ("prof_li", "Professor Li", "CREATE_COMMENT",
-         "Replied to Wang: 'The methodology controls for city tier "
-         "and population density. I invite you to review the full dataset.'",
-         "twitter"),
-
-        ("mayor_chen", "Mayor Chen", "CREATE_POST",
-         "Data from @ProfLi confirms what we've been saying: zoning "
-         "reform works. Let's move forward with evidence, not fear.",
-         "twitter"),
-    ])
-
-    # Round 3: Escalation and platform expansion
-    sim.run_round(3, [
-        ("wang_homeowner", "Wang", "CREATE_POST",
-         "Filing formal petition with 3,000 signatures against the "
-         "zoning reform. Council meeting next Tuesday. All homeowners "
-         "must attend!",
-         "reddit"),
-
-        ("mayor_chen", "Mayor Chen", "CREATE_POST",
-         "Announcing public town hall on zoning reform this Saturday. "
-         "All voices welcome. Data-driven decisions benefit everyone.",
-         "twitter"),
-
-        ("prof_li", "Professor Li", "CREATE_POST",
-         "Published full dataset and methodology on my university page. "
-         "Transparency is essential for informed public debate.",
-         "twitter"),
-
-        ("wang_homeowner", "Wang", "FOLLOW",
-         "Followed @MayorChen to monitor policy updates.",
-         "twitter"),
-    ])
-
-    # Mid-simulation: agent recalls own memory + graph
-    print("\n  Mid-simulation recall for Mayor Chen:")
-    mayor_recall = sim.recall_agent_memory(
-        "mayor_chen",
-        "What positions have I taken on housing reform?"
-    )
-    for mem in mayor_recall["memories"]:
-        print(f"    Memory: {mem}")
-    for rel in mayor_recall["relations"][:3]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # STAGE 4: Report Generation — Retrieve memories + graph for analysis
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 4: Report Generation")
-    print("=" * 60)
-
-    # Quick search: targeted query
-    print("\n  Quick Search: 'opposition to housing reform'")
-    opposition = sim.quick_search("opposition to housing reform", limit=5)
-    for mem in opposition["memories"]:
-        print(f"    Memory: {mem}")
-    for rel in opposition["relations"][:3]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # Agent-specific search
-    print("\n  Agent Search: Wang's activities")
-    wang_activities = sim.agent_search("wang_homeowner", "all actions and statements")
-    for mem in wang_activities["memories"]:
-        print(f"    Memory: {mem}")
-
-    # Panorama: full overview
-    print("\n  Panorama Search: all memories + relations")
-    panorama = sim.panorama_search()
-    print(f"    Total memories: {len(panorama['memories'])}")
-    print(f"    Total relations: {len(panorama['relations'])}")
-    for mem in panorama["memories"][:5]:
-        print(f"    Memory: {mem}")
-    if len(panorama["memories"]) > 5:
-        print(f"    ... and {len(panorama['memories']) - 5} more")
-    for rel in panorama["relations"][:5]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # STAGE 5: Deep Interaction — Post-simulation queries
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 5: Deep Interaction")
-    print("=" * 60)
-
-    queries = [
-        "How did the debate evolve across the three rounds?",
-        "What evidence was cited by each side?",
-        "Who supports and who opposes the reform?",
-    ]
-
-    for query in queries:
-        print(f"\n  Query: '{query}'")
-        results = sim.quick_search(query, limit=3)
-        for mem in results["memories"][:2]:
-            print(f"    Memory: {mem}")
-        for rel in results["relations"][:2]:
-            src = rel.get("source", rel.get("source_node", "?"))
-            edge = rel.get("relationship", rel.get("relation", "?"))
-            dst = rel.get("destination", rel.get("destination_node", "?"))
-            print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # Summary
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("SIMULATION COMPLETE")
-    print("=" * 60)
-    print(f"  Project ID:        {project_id}")
-    print(f"  Documents ingested: {sim.stats['documents_ingested']}")
-    print(f"  Activities tracked: {sim.stats['activities_recorded']}")
-    print(f"  Rounds completed:  {sim.stats['rounds_completed']}")
-    print(f"  Total memories:    {len(panorama['memories'])}")
-    print(f"  Total relations:   {len(panorama['relations'])}")
-
-    # Cleanup (uncomment to delete all memories + graph data)
-    # sim.cleanup()
-
-
-if __name__ == "__main__":
-    print("MiroFish Swarm Prediction Simulation powered by Mem0 Graph Memory\n")
-    main()
-```
-
-## How It Works
-
-### Graph Memory: The Right Fit for MiroFish
-
-MiroFish's entire pipeline revolves around a **knowledge graph** — it extracts entities from documents, builds relationships, and queries the graph throughout simulation and reporting. Mem0's Graph Memory provides the same capabilities:
-
-| MiroFish needs | Zep Cloud | Mem0 Graph Memory |
-|---|---|---|
-| **Entity extraction** | Built-in via Zep API | Automatic via LLM extraction |
-| **Relationship mining** | Graph edges | `(source) --[relationship]--> (destination)` triples |
-| **Semantic + keyword search** | Semantic + BM25 | Vector similarity + graph relation retrieval |
-| **Graph traversal** | Node/edge queries | `relations` array in search results |
-| **Per-agent isolation** | Single shared graph in MiroFish | Native `run_id` scoping |
-| **Self-hosting** | No (cloud only) | Yes — Neo4j, Memgraph, Kuzu, Neptune |
-| **Node/memory limits** | Capped on free tier | Unlimited (self-hosted) |
-
-### How search() Returns Both Memories and Relations
-
-When Graph Memory is enabled, every `search()` call returns two arrays:
-
-```python
-results = memory.search("housing reform", user_id="my_sim")
-
-# Vector-matched memories (ordered by similarity)
-results["results"]   # [{"memory": "...", "score": 0.85, ...}, ...]
-
-# Graph relations connected to query entities
-results["relations"] # [{"source": "mayor_chen", "relationship": "supports", "destination": "zoning_reform"}, ...]
-```
-
-This is what makes Mem0 Graph Memory a natural replacement for Zep — you get semantic search AND structured graph data in a single call.
-
-### Per-Agent Memory Isolation
-
-`user_id` scopes the simulation project. `run_id` tags individual agent actions at storage time (we use `run_id` instead of `agent_id` since no assistant memories are involved). Searches use `user_id` for project-wide retrieval:
-
-```python
-# Store project-level memories (seed documents)
-memory.add(
-    [{"role": "user", "content": "Mayor Chen supports the zoning reform."}],
-    user_id="my_sim"
-)
-
-# Store agent-specific memories (simulation actions)
-memory.add(
-    [{"role": "user", "content": "Mayor Chen [CREATE_POST]: Reform works!"}],
-    run_id="mayor_chen"
-)
-
-# Search project-level memories (seed docs)
-memory.search("housing reform", user_id="my_sim")
-
-# Search agent-specific memories (actions stored with run_id)
-memory.search("housing reform", run_id="mayor_chen")
-
-# Get all project-level memories + graph relations
-memory.get_all(user_id="my_sim")
-```
-
-<Note>
-  Use `user_id` for project-level data (seed documents) and `run_id` for agent actions — both for `add()` and `search()`. Always match the scope: if you `add()` with `run_id`, `search()` with `run_id`. Use the message list format `[{"role": "user", "content": "..."}]` for all `add()` calls — it works on both OSS and Cloud.
-</Note>
-
-### Stage Mapping
-
-| MiroFish Stage | What Happens | Mem0 Graph Memory Call |
-|---|---|---|
-| **1. Graph Building** | Ingest docs, extract entities | `memory.add(doc, user_id=project)` — entities/relations extracted automatically |
-| **2. Environment Setup** | Enrich agent personas from graph | `memory.search(query, user_id=project)` — returns facts + relations |
-| **3. Simulation** | Track per-agent actions | `memory.add(messages, run_id=agent)` |
-| **3. Simulation** | Mid-round recall | `memory.search(query, run_id=agent)` |
-| **4. Report Generation** | Targeted analysis | `memory.search(query, user_id=project)` — memories + graph |
-| **4. Report Generation** | Full overview | `memory.get_all(user_id=project)` — all memories + all relations |
-| **5. Deep Interaction** | Follow-up queries | `memory.search(query, user_id=project)` |
-
-### Zep-to-Mem0 Migration Reference
-
-For developers replacing MiroFish's Zep integration. Note that Mem0 Graph Memory covers the core graph operations but some Zep features have no direct equivalent — see caveats below.
-
-| MiroFish Service | Zep Call | Mem0 Graph Memory Equivalent | Caveat |
-|---|---|---|---|
-| GraphBuilderService | `client.graph.create()` | Implicit on first `memory.add()` | |
-| GraphBuilderService | `client.graph.set_ontology()` | `custom_prompt` in graph_store config | Freeform text, not a typed schema like Zep's `EntityModel`/`EdgeModel` |
-| GraphBuilderService | `client.graph.add_batch(episodes)` | `memory.add()` per chunk | No batch API — call per chunk |
-| GraphBuilderService | `client.graph.episode.get(uuid)` | Not needed (add is synchronous in OSS) | |
-| GraphBuilderService | `client.graph.delete(id)` | `memory.delete_all(user_id=...)` | |
-| ZepEntityReader | `client.graph.node.get_by_graph_id()` | `memory.get_all(user_id=...)` → `relations` | |
-| ZepEntityReader | `client.graph.node.get(uuid)` | `memory.search(entity_name, user_id=...)` | Semantic search, not exact ID lookup |
-| ZepEntityReader | `client.graph.node.get_entity_edges()` | `memory.search(entity_name, user_id=...)` → `relations` | Returns all matching relations, not edges for a specific node |
-| ZepGraphMemoryUpdater | `client.graph.add(type="text")` | `memory.add(messages, run_id=...)` | No batch buffering or retry — implement in your wrapper |
-| ZepToolsService | `search_graph(query, scope)` | `memory.search(query, user_id=...)` → memories + relations | |
-| ZepToolsService | `get_entities()` | `memory.get_all(user_id=...)` → `relations` | |
-| ZepToolsService | Panorama (all nodes + edges) | `memory.get_all(user_id=...)` | No temporal fact separation (active vs historical) |
-| ZepToolsService | InsightForge (multi-query decomposition) | Not available | Implement LLM-driven sub-query decomposition in your own ReportAgent |
-| OasisProfileGenerator | `client.graph.search()` | `memory.search(query, user_id=...)` | |
-
-<Note>
-  **What Mem0 Graph Memory does not cover**: Zep's typed ontology schemas (`EntityModel`, `EdgeModel`), temporal fact lifecycle (`valid_at`/`invalid_at`/`expired_at`), single-node-by-ID lookup, and InsightForge's multi-query decomposition. For InsightForge-like functionality, implement sub-query logic in your own ReportAgent using `memory.search()` as the retrieval primitive.
-</Note>
-
-### Custom Extraction Prompts
-
-Guide what entities and relationships Mem0 extracts — analogous to (but less structured than) Zep's `set_ontology()`:
-
-```python
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {"url": "...", "username": "...", "password": "..."},
-        "custom_prompt": (
-            "Extract all people, organizations, policies, locations, "
-            "and their relationships. Capture support/opposition stances, "
-            "affiliations, and quantitative claims."
-        ),
-    }
-}
-```
-
-### Action Types
-
-MiroFish's OASIS engine produces these agent action types. Format them as natural language when storing. Skip `DO_NOTHING` actions (no memory value). `TREND` and `REFRESH` are Reddit-only discovery actions — store if you want to track browsing behavior.
-
-| Action Type | Platform | Example Memory Content |
-|---|---|---|
-| `CREATE_POST` | Both | `"Mayor Chen [CREATE_POST]: This reform will create 10,000 units"` |
-| `CREATE_COMMENT` | Reddit | `"Wang [CREATE_COMMENT]: Replied to Prof Li: 'Your data is misleading'"` |
-| `LIKE_POST` | Both | `"Mayor Chen [LIKE_POST]: Liked Prof Li's post about Shenzhen data"` |
-| `REPOST` | Twitter | `"Prof Li [REPOST]: Reposted Mayor Chen's town hall announcement"` |
-| `FOLLOW` | Both | `"Wang [FOLLOW]: Followed @MayorChen"` |
-| `QUOTE_POST` | Twitter | `"Mayor Chen [QUOTE_POST]: 'Data confirms reform works' quoting Prof Li"` |
-| `DISLIKE_POST` | Reddit | `"Wang [DISLIKE_POST]: Downvoted Mayor Chen's reform post"` |
-| `TREND` | Reddit | `"Prof Li [TREND]: Browsed trending topics"` |
-| `DO_NOTHING` | Both | Skip — no memory value |
-
-## Running the Example
-
-```bash
-# Option A: Neo4j (production)
-export OPENAI_API_KEY="sk-..."
-export NEO4J_URL="neo4j://localhost:7687"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="password"
-python mirofish_swarm_memory.py
-
-# Option B: Kuzu (zero dependencies, just need OpenAI key)
-export OPENAI_API_KEY="sk-..."
-python mirofish_swarm_memory.py  # auto-detects missing NEO4J_URL, uses Kuzu
-```
-
-<Note>
-Exact output varies as Mem0 automatically extracts and deduplicates entities. The specific relations and memory counts depend on LLM extraction quality.
-</Note>
-
-## Best Practices
-
-1. **Unique `user_id` per simulation** — Use timestamps or UUIDs (e.g., `mirofish_housing_1742198400`) to prevent memory collisions between runs
-2. **Always set `run_id` for agent actions** — Per-agent isolation prevents memory cross-contamination between agents
-3. **Use `custom_prompt`** — Guide entity extraction to capture domain-specific relationships (people, policies, stances)
-4. **Format actions as natural language** — `"Mayor Chen [CREATE_POST]: content"` extracts better entities than raw JSON
-5. **Query relations for reports** — The `relations` array in search results gives structured `(source, relationship, destination)` triples for building analytical reports
-6. **Cleanup old simulations** — Call `delete_all(user_id=...)` when a simulation run is no longer needed
-
-## Resources
-
-- [MiroFish GitHub](https://github.com/666ghj/MiroFish) — Source code and setup guide
-- [MiroFish Documentation](https://deepwiki.com/666ghj/MiroFish) — Full framework docs
-- [Mem0 Graph Memory](/open-source/features/graph-memory) — Graph Memory documentation
-- [Mem0 Documentation](https://docs.mem0.ai/) — Full API reference
-
-<CardGroup cols={2}>
-  <Card title="Graph Memory" icon="network-wired" href="/open-source/features/graph-memory">
-    Full Graph Memory documentation with provider setup.
-  </Card>
-  <Card title="MiroFish GitHub" icon="fish" href="https://github.com/666ghj/MiroFish">
-    MiroFish source code and setup guide.
-  </Card>
-</CardGroup>

docs/cookbooks/integrations/agents-sdk-tool.mdx

@@ -112,7 +112,7 @@ async def search_memory(
         query: The search query.
     """
     user_id = context.context.user_id or "default_user"
-    memories = await client.search(query, user_id=user_id)
+    memories = await client.search(query, filters={"user_id": user_id})
     results = '\n'.join([result["memory"] for result in memories["results"]])
     return str(results)
 ```
@@ -222,8 +222,8 @@ context = Mem0Context(user_id="user123")
 
 ## Resources
 
-- [Mem0 Documentation](https://docs.mem0.ai)
-- [Mem0 Dashboard](https://app.mem0.ai/dashboard)
+- [Mem0 Documentation](https://docs.mem0.ai/introduction)
+- <a href="https://app.mem0.ai/dashboard" rel="nofollow">Mem0 Dashboard</a>
 - [API Reference](https://docs.mem0.ai/api-reference)
 
 ---

docs/cookbooks/integrations/aws-bedrock.mdx

@@ -1,17 +1,17 @@
 ---
 title: Bedrock with Persistent Memory
-description: "Pair Mem0 with AWS Bedrock, OpenSearch, and Neptune for a managed stack."
+description: "Pair Mem0 with AWS Bedrock and OpenSearch for a managed stack."
 ---
 
 
-This example demonstrates how to configure and use the `mem0ai` SDK with **AWS Bedrock**, **OpenSearch Service (AOSS)**, and **AWS Neptune Analytics** for persistent memory capabilities in Python.
+This example demonstrates how to configure and use the `mem0ai` SDK with **AWS Bedrock** and **OpenSearch Service (AOSS)** for persistent memory capabilities in Python.
 
 ## Installation
 
 Install the required dependencies to include the Amazon data stack, including **boto3**, **opensearch-py**, and **langchain-aws**:
 
 ```bash
-pip install "mem0ai[graph,extras]"
+pip install "mem0ai[extras]"
 ```
 
 ## Environment Setup
@@ -38,7 +38,6 @@ This sets up Mem0 with:
 - [AWS Bedrock for LLM](https://docs.mem0.ai/components/llms/models/aws_bedrock)
 - [AWS Bedrock for embeddings](https://docs.mem0.ai/components/embedders/models/aws_bedrock#aws-bedrock)
 - [OpenSearch as the vector store](https://docs.mem0.ai/components/vectordbs/dbs/opensearch)
-- [Graph Memory guide](https://docs.mem0.ai/open-source/features/graph-memory)
 
 ```python
 import boto3
@@ -79,12 +78,6 @@ config = {
             "embedding_model_dims": 1024,
         }
     },
-    "graph_store": {
-        "provider": "neptune",
-        "config": {
-            "endpoint": f"neptune-graph://my-graph-identifier",
-        },
-    },
 }
 
 # Initialize the memory system
@@ -93,8 +86,6 @@ m = Memory.from_config(config)
 
 ## Usage
 
-Reference [Notebook example](https://github.com/mem0ai/mem0/blob/main/examples/graph-db-demo/neptune-example.ipynb)
-
 ### Add a memory
 
 ```python
@@ -112,13 +103,13 @@ result = m.add(messages, user_id="alice", metadata={"category": "movie_recommend
 ### Search a memory
 
 ```python
-relevant_memories = m.search(query, user_id="alice")
+relevant_memories = m.search(query, filters={"user_id": "alice"})
 ```
 
 ### Get all memories
 
 ```python
-all_memories = m.get_all(user_id="alice")
+all_memories = m.get_all(filters={"user_id": "alice"})
 ```
 
 ### Get a specific memory
@@ -129,15 +120,12 @@ memory = m.get(memory_id)
 
 ## Conclusion
 
-With Mem0 and AWS services like Bedrock, OpenSearch, and Neptune Analytics, you can build intelligent AI companions that remember, adapt, and personalize their responses over time. This makes them ideal for long-term assistants, tutors, or support bots with persistent memory and natural conversation abilities.
+With Mem0 and AWS services like Bedrock and OpenSearch, you can build intelligent AI companions that remember, adapt, and personalize their responses over time. This makes them ideal for long-term assistants, tutors, or support bots with persistent memory and natural conversation abilities.
 
 ---
 
 <CardGroup cols={2}>
-  <Card title="Neptune Analytics with Mem0" icon="database" href="/cookbooks/integrations/neptune-analytics">
-    Explore graph-based memory storage with AWS Neptune Analytics.
-  </Card>
-  <Card title="Graph Memory Features" icon="sitemap" href="/platform/features/graph-memory">
-    Learn how to leverage knowledge graphs for entity relationships.
+  <Card title="Memory Evaluation" icon="chart-line" href="/core-concepts/memory-evaluation">
+    Understand how Mem0's memory system is benchmarked and evaluated.
   </Card>
 </CardGroup>

docs/cookbooks/integrations/healthcare-google-adk.mdx

@@ -77,7 +77,7 @@ def retrieve_patient_info(query: str) -> dict:
     results = mem0_client.search(
         query,
         user_id=USER_ID,
-        limit=5,
+        top_k=5,
         threshold=0.7  # Higher threshold for more relevant results
     )
 

docs/cookbooks/integrations/neptune-analytics.mdx

@@ -1,133 +0,0 @@
----
-title: Graph Memory on Neptune
-description: "Combine Mem0 graph memory with AWS Neptune Analytics and Bedrock."
----
-
-
-This example demonstrates how to configure and use the `mem0ai` SDK with **AWS Bedrock** and **AWS Neptune Analytics** for persistent memory capabilities in Python.
-
-## Installation
-
-Install the required dependencies to include the Amazon data stack, including **boto3** and **langchain-aws**:
-
-```bash
-pip install "mem0ai[graph,extras]"
-```
-
-## Environment Setup
-
-Set your AWS environment variables:
-
-```python
-import os
-
-# Set these in your environment or notebook
-os.environ['AWS_REGION'] = 'us-west-2'
-os.environ['AWS_ACCESS_KEY_ID'] = 'AK00000000000000000'
-os.environ['AWS_SECRET_ACCESS_KEY'] = 'AS00000000000000000'
-
-# Confirm they are set
-print(os.environ['AWS_REGION'])
-print(os.environ['AWS_ACCESS_KEY_ID'])
-print(os.environ['AWS_SECRET_ACCESS_KEY'])
-```
-
-## Configuration and Usage
-
-This sets up Mem0 with:
-- [AWS Bedrock for LLM](https://docs.mem0.ai/components/llms/models/aws_bedrock)
-- [AWS Bedrock for embeddings](https://docs.mem0.ai/components/embedders/models/aws_bedrock#aws-bedrock)
-- [Neptune Analytics as the vector store](https://docs.mem0.ai/components/vectordbs/dbs/neptune_analytics)
-- [Graph Memory guide](https://docs.mem0.ai/open-source/features/graph-memory).
-
-```python
-import boto3
-from mem0.memory.main import Memory
-
-region = 'us-west-2'
-neptune_analytics_endpoint = 'neptune-graph://my-graph-identifier'
-
-config = {
-    "embedder": {
-        "provider": "aws_bedrock",
-        "config": {
-            "model": "amazon.titan-embed-text-v2:0"
-        }
-    },
-    "llm": {
-        "provider": "aws_bedrock",
-        "config": {
-            "model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
-            "temperature": 0.1,
-            "max_tokens": 2000
-        }
-    },
-    "vector_store": {
-        "provider": "neptune",
-        "config": {
-            "collection_name": "mem0",
-            "endpoint": neptune_analytics_endpoint,
-        },
-    },
-    "graph_store": {
-        "provider": "neptune",
-        "config": {
-            "endpoint": neptune_analytics_endpoint,
-        },
-    },
-}
-
-# Initialize the memory system
-m = Memory.from_config(config)
-```
-
-## Usage
-
-Reference [Notebook example](https://github.com/mem0ai/mem0/blob/main/examples/graph-db-demo/neptune-example.ipynb)
-
-#### Add a memory:
-
-```python
-messages = [
-    {"role": "user", "content": "I'm planning to watch a movie tonight. Any recommendations?"},
-    {"role": "assistant", "content": "How about a thriller movies? They can be quite engaging."},
-    {"role": "user", "content": "I'm not a big fan of thriller movies but I love sci-fi movies."},
-    {"role": "assistant", "content": "Got it! I'll avoid thriller recommendations and suggest sci-fi movies in the future."}
-]
-
-# Store inferred memories (default behavior)
-result = m.add(messages, user_id="alice", metadata={"category": "movie_recommendations"})
-```
-
-#### Search a memory:
-```python
-relevant_memories = m.search(query, user_id="alice")
-```
-
-#### Get all memories:
-```python
-all_memories = m.get_all(user_id="alice")
-```
-
-#### Get a specific memory:
-```python
-memory = m.get(memory_id)
-```
-
-
----
-
-## Conclusion
-
-With Mem0 and AWS services like Bedrock and Neptune Analytics, you can build intelligent AI companions that remember, adapt, and personalize their responses over time. This makes them ideal for long-term assistants, tutors, or support bots with persistent memory and natural conversation abilities.
-
----
-
-<CardGroup cols={2}>
-  <Card title="AWS Bedrock with Mem0" icon="aws" href="/cookbooks/integrations/aws-bedrock">
-    Combine Neptune Analytics with AWS Bedrock for complete AWS stack.
-  </Card>
-  <Card title="Graph Memory Architecture" icon="sitemap" href="/cookbooks/essentials/choosing-memory-architecture-vector-vs-graph">
-    Understand when to use graph vs vector memory for your use case.
-  </Card>
-</CardGroup>

docs/cookbooks/integrations/openai-tool-calls.mdx

@@ -23,18 +23,15 @@ MEM0_API_KEY=your_mem0_api_key
 OPENAI_API_KEY=your_openai_api_key
 ```
 
-Get your Mem0 API key from the [Mem0 Dashboard](https://app.mem0.ai/dashboard/api-keys).
+Get your Mem0 API key from the <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">Mem0 Dashboard</a>.
 
 ### Configuration
 
 ```javascript
-const mem0Config = {
-    apiKey: process.env.MEM0_API_KEY,
-    user_id: "sample-user",
-};
+const USER_ID = "sample-user";
 
 const openAIClient = new OpenAI();
-const mem0Client = new MemoryClient(mem0Config);
+const mem0Client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
 ```
 
 ## Adding Memories
@@ -43,14 +40,14 @@ Store user preferences, past interactions, or any relevant information:
 <CodeGroup>
 ```javascript JavaScript
 async function addUserPreferences() {
-    const mem0Client = new MemoryClient(mem0Config);
+    const mem0Client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
     
     const userPreferences = "I Love BMW, Audi and Porsche. I Hate Mercedes. I love Red cars and Maroon cars. I have a budget of 120K to 150K USD. I like Audi the most.";
     
     await mem0Client.add([{
         role: "user",
         content: userPreferences,
-    }], mem0Config);
+    }], { userId: "sample-user" });
 }
 
 await addUserPreferences();
@@ -91,7 +88,7 @@ await addUserPreferences();
 Search for relevant memories based on the current user input:
 
 ```javascript
-const relevantMemories = await mem0Client.search(userInput, mem0Config);
+const relevantMemories = await mem0Client.search(userInput, { userId: USER_ID });
 ```
 
 ## Structured Responses with Zod
@@ -121,7 +118,7 @@ const carRecommendationTool = zodResponsesFunction({
 
 // Use the tool in your OpenAI request
 const response = await openAIClient.responses.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
     tools: [{ type: "web_search_preview" }, carRecommendationTool],
     input: `${getMemoryString(relevantMemories)}\n${userInput}`,
 });
@@ -133,7 +130,7 @@ Combine memory with web search for up-to-date recommendations:
 
 ```javascript
 const response = await openAIClient.responses.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
     tools: [{ type: "web_search_preview" }, carRecommendationTool],
     input: `${getMemoryString(relevantMemories)}\n${userInput}`,
 });
@@ -152,10 +149,7 @@ import dotenv from 'dotenv';
 
 dotenv.config();
 
-const mem0Config = {
-    apiKey: process.env.MEM0_API_KEY,
-    user_id: "sample-user",
-};
+const USER_ID = "sample-user";
 
 async function run() {
     // Responses without memories
@@ -185,7 +179,7 @@ const Cars = z.object({
 
 async function main(memory = false) {
   const openAIClient = new OpenAI();
-  const mem0Client = new MemoryClient(mem0Config);
+  const mem0Client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
 
   const input = "Suggest me some cars that I can buy today.";
 
@@ -195,16 +189,16 @@ async function main(memory = false) {
   await mem0Client.add([{
     role: "user",
     content: input,
-  }], mem0Config);
+  }], { userId: USER_ID });
 
   // Search for relevant memories
   let relevantMemories = []
   if (memory) {
-    relevantMemories = await mem0Client.search(input, mem0Config);
+    relevantMemories = await mem0Client.search(input, { userId: USER_ID });
   }
 
   const response = await openAIClient.responses.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
     tools: [{ type: "web_search_preview" }, tool],
     input: `${getMemoryString(relevantMemories)}\n${input}`,
   });
@@ -213,14 +207,14 @@ async function main(memory = false) {
 }
 
 async function addSampleMemories() {
-  const mem0Client = new MemoryClient(mem0Config);
+  const mem0Client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
 
   const myInterests = "I Love BMW, Audi and Porsche. I Hate Mercedes. I love Red cars and Maroon cars. I have a budget of 120K to 150K USD. I like Audi the most.";
   
   await mem0Client.add([{
     role: "user",
     content: myInterests,
-  }], mem0Config);
+  }], { userId: USER_ID });
 }
 
 const getMemoryString = (memories) => {
@@ -308,8 +302,8 @@ run().catch(console.error);
 
 ## Resources
 
-- [Mem0 Documentation](https://docs.mem0.ai)
-- [Mem0 Dashboard](https://app.mem0.ai/dashboard)
+- [Mem0 Documentation](https://docs.mem0.ai/introduction)
+- <a href="https://app.mem0.ai/dashboard" rel="nofollow">Mem0 Dashboard</a>
 - [API Reference](https://docs.mem0.ai/api-reference)
 - [OpenAI Documentation](https://platform.openai.com/docs)
 

docs/cookbooks/operations/content-writing.mdx

@@ -202,7 +202,7 @@ Preferences:
     ]
 
     response = openai.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         messages=messages
     )
     clean_response = response.choices[0].message.content.strip()

docs/cookbooks/operations/support-inbox.mdx

@@ -79,7 +79,7 @@ class CustomerSupportAIAgent:
         :param user_id: Optional user ID to filter memories.
         :return: List of memories.
         """
-        return self.memory.get_all(user_id=user_id)
+        return self.memory.get_all(filters={"user_id": user_id})
 
 # Instantiate the CustomerSupportAIAgent
 support_agent = CustomerSupportAIAgent()

docs/cookbooks/operations/team-task-agent.mdx

@@ -45,7 +45,7 @@ class CollaborativeAgent:
 
     def brainstorm(self, prompt):
         # Get recent messages for context
-        memories = self.mem.search(prompt, run_id=self.run_id, limit=5)["results"]
+        memories = self.mem.search(prompt, filters={"run_id": self.run_id}, top_k=5)["results"]
         context = "\n".join(f"- {m['memory']} (by {m.get('actor_id', 'Unknown')})" for m in memories)
         client = OpenAI()
         messages = [
@@ -53,14 +53,14 @@ class CollaborativeAgent:
             {"role": "user", "content": f"Prompt: {prompt}\nContext:\n{context}"}
         ]
         reply = client.chat.completions.create(
-            model="gpt-4.1-nano-2025-04-14",
+            model="gpt-5-mini",
             messages=messages
         ).choices[0].message.content.strip()
         self.add_message("assistant", "assistant", reply)
         return reply
 
     def get_all_messages(self):
-        return self.mem.get_all(run_id=self.run_id)["results"]
+        return self.mem.get_all(filters={"run_id": self.run_id})["results"]
 
     def print_sorted_by_time(self):
         messages = self.get_all_messages()

docs/cookbooks/overview.mdx

@@ -37,13 +37,6 @@ Here are some examples of how Mem0 can be integrated into various applications:
   >
     Filter speculation and low-confidence data.
   </Card>
-  <Card
-    title="Set Memory Expiration"
-    icon="timer"
-    href="/cookbooks/essentials/memory-expiration-short-and-long-term"
-  >
-    Short-term vs long-term retention strategies.
-  </Card>
 </CardGroup>
 
 ## Companion Playbooks
@@ -201,10 +194,7 @@ Here are some examples of how Mem0 can be integrated into various applications:
   >
     Persistent personality for Eliza agents.
   </Card>
-  <Card title="Browser Extension Memory" icon="globe" href="/cookbooks/frameworks/chrome-extension">
-    Universal memory layer for Chrome.
-  </Card>
-</CardGroup>
+  </CardGroup>
 
 ---
 

docs/core-concepts/memory-evaluation.mdx

@@ -0,0 +1,354 @@
+---
+title: "Memory Evaluation"
+description: "Understand how Mem0's memory system is evaluated, benchmark results, and how to run evaluations on your own data."
+icon: "chart-bar"
+iconType: "solid"
+---
+
+## Why Memory Evaluation Matters
+
+Most AI agent memory systems retrieve information by maximizing context window size. That works on benchmarks but not in production, where every token adds cost. **Token efficiency** — achieving high accuracy with less context per query — is what separates benchmark performance from production viability.
+
+The new Mem0 algorithm achieves competitive accuracy on LoCoMo, LongMemEval, and BEAM while averaging **under 7,000 tokens per retrieval call**. Full-context approaches on the same benchmarks routinely consume 25,000+ tokens per query.
+
+Evaluating a memory system at scale comes down to three parameters: **accuracy** (what the benchmarks measure), **cost** (context tokens per query), and **performance** (latency). Optimizing one is easy. Balancing all three at scale is the actual problem.
+
+Some benchmarks today — particularly smaller ones like LoCoMo and LongMemEval — can be materially improved by aggressive retrieval strategies, larger context windows, or frontier models. That does not necessarily mean the underlying memory system has gotten better. We evaluate under constraints that reflect how memory systems actually run in production: limited context windows and practical token budgets.
+
+## Architecture Overview
+
+Mem0's memory system operates across two phases — **extraction** (writing) and **retrieval** (reading) — with an entity linking layer connecting them.
+
+### Memory Extraction (Distillation)
+
+When new conversations arrive, the extraction pipeline processes them through five stages:
+
+1. **Store New Memories** — Conversation enters the pipeline asynchronously (after the agent responds)
+2. **Context Lookup** — Find related existing memories to avoid duplicates
+3. **Distill Memories** — Single-pass LLM extraction produces ADD-only facts from input + context
+4. **Deduplicate + Embed** — Hash-based deduplication, then vectorize new memories
+5. **Entity Linking** — Identify entities (proper nouns, quoted text, compound noun phrases) and link them across memories
+
+Memories are distributed across three storage layers, each tuned for a specific retrieval pattern:
+
+| Store | Contents | Purpose |
+|---|---|---|
+| **Vector Database** | Memory text, embeddings, metadata (timestamps, hash, categories, attributed_to) | Primary fact storage + semantic retrieval |
+| **Entity Store** | Entities + embeddings + linked memory IDs | Entity-based retrieval boost |
+| **SQL Database** | History log (ADD events) + rolling message window | Audit trail + extraction dedup context |
+
+<Info>
+The key architectural decision is **ADD-only extraction**. New facts are stored alongside old ones — nothing is overwritten or deleted. When information changes, both the old and new facts survive. This preserves temporal context and eliminates information loss from premature consolidation.
+</Info>
+
+### Multi-Signal Retrieval
+
+When a query arrives, the retrieval pipeline scores candidates across three signals in parallel:
+
+1. **Semantic Search** — Vector similarity scoring against memory embeddings
+2. **Keyword Search** — Normalized term matching via BM25 with verb-form lemmatization
+3. **Entity Search** — Entity graph matching boosts memories linked to query entities
+
+Results are fused via rank scoring into a final top-K set. Different query types lean on different signals:
+
+| Query Type | Primary Signal | Example |
+|---|---|---|
+| Conceptual | Semantic | "What does the user think about remote work?" |
+| Factual/exact | BM25 keyword | "What meetings did I attend last week?" |
+| Entity-centric | Entity matching | "What do we know about Alice?" |
+| Temporal | Semantic + keyword | "When did the user first mention the project?" |
+
+The combined score outperformed every individual signal across every category tested.
+
+## Benchmarks
+
+### LoCoMo
+
+[LoCoMo](https://github.com/snap-stanford/locomo) tests single-hop, multi-hop, open-domain, and temporal memory recall across conversational sessions.
+
+| Category | Old Algorithm | New Algorithm | Delta |
+|---|---|---|---|
+| **Overall** | **71.4** | **91.6** | **+20.2** |
+| Single-hop | 76.6 | 92.3 | +15.7 |
+| Multi-hop | 70.2 | 93.3 | +23.1 |
+| Open-domain | 57.3 | 76.0 | +18.7 |
+| Temporal | 63.2 | 92.8 | +29.6 |
+
+*Mean tokens: 6,956*
+
+The two largest gains are **temporal queries (+29.6)** and **multi-hop reasoning (+23.1)**. Both categories directly test the ADD-only architecture (preserving temporal context) and entity linking (connecting facts across memories).
+
+### LongMemEval
+
+[LongMemEval](https://github.com/xiaowu0162/LongMemEval) evaluates memory across single-session and multi-session contexts, including knowledge updates and temporal reasoning.
+
+| Category | Old Algorithm | New Algorithm | Delta |
+|---|---|---|---|
+| **Overall** | **67.8** | **93.4** | **+25.6** |
+| Single-session (user) | 94.3 | 97.1 | +2.8 |
+| Single-session (assistant) | 46.4 | 100.0 | +53.6 |
+| Single-session (preference) | 76.7 | 96.7 | +20.0 |
+| Knowledge update | 79.5 | 96.2 | +16.7 |
+| Temporal reasoning | 51.1 | 93.2 | +42.1 |
+| Multi-session | 70.7 | 86.5 | +15.8 |
+
+*Mean tokens: 6,787*
+
+The biggest gain is **single-session assistant (+53.6)** — the previous algorithm had a blind spot for agent-generated facts. The new algorithm treats them as first-class memories.
+
+The **+42.1 on temporal reasoning** reflects the ADD-only architecture preserving chronological context that the previous UPDATE/DELETE model would destroy.
+
+### BEAM
+
+[BEAM](https://github.com/mem0ai/memory-benchmarks) evaluates memory systems at 1M and 10M token scales across ten task categories. It is the only public benchmark that operates at context volumes production AI agents actually encounter.
+
+| Category | 1M | 10M |
+|---|---|---|
+| **Overall** | **64.1** | **48.6** |
+| preference_following | 88.3 | 90.4 |
+| instruction_following | 85.2 | 82.5 |
+| information_extraction | 70.0 | 56.3 |
+| knowledge_update | 65.0 | 75.0 |
+| multi_session_reasoning | 65.2 | 26.1 |
+| summarization | 63.5 | 46.9 |
+| temporal_reasoning | 61.8 | 16.3 |
+| event_ordering | 53.6 | 20.2 |
+| abstention | 52.5 | 40.0 |
+| contradiction_resolution | 35.7 | 32.5 |
+
+*Mean tokens (1M): 6,719. Mean tokens (10M): 6,914.*
+
+<Info>
+**BEAM is the most relevant benchmark here.** It operates at 1M and 10M token scales and cannot be solved by simply expanding the context window. The results at 10M reflect where memory systems actually stand at production context volumes. The system holds up well on preference following, instruction following, and knowledge updates at both scales. Weaker categories at 10M (temporal reasoning, event ordering, multi-session reasoning) are open problems across the field — they require higher-order representations of how events relate to each other across time, which is a primary focus of our ongoing research.
+</Info>
+
+### Performance Summary
+
+All results use a single-pass retrieval setup: one retrieval call, one answer, no agentic loops.
+
+| Benchmark | Old Algorithm | New Algorithm | Average tokens / query |
+|---|---|---|---|
+| **LoCoMo** | 71.4 | **91.6** | 6,956 |
+| **LongMemEval** | 67.8 | **93.4** | 6,787 |
+| **BEAM (1M)** | — | **64.1** | 6,719 |
+| **BEAM (10M)** | — | **48.6** | 6,914 |
+
+<Info>
+Scores reflect Mem0's managed platform, which includes proprietary optimizations not available in the open-source SDK. Open-source users should expect directionally similar gains but not identical numbers.
+</Info>
+
+All benchmarks run on the same production-representative model stack. Scores carry a ±1 point confidence interval due to judge inconsistency.
+
+## Running Evaluations
+
+The full evaluation framework is [open-sourced](https://github.com/mem0ai/memory-benchmarks) so anyone can reproduce the numbers independently. It supports both Mem0 Cloud and self-hosted OSS backends.
+
+### Setup
+
+<Tabs>
+  <Tab title="Mem0 Cloud">
+    ```bash
+    git clone https://github.com/mem0ai/memory-benchmarks.git
+    cd memory-benchmarks
+    pip install -r requirements.txt
+
+    # Set your API keys
+    export MEM0_API_KEY=m0-your-key
+    export OPENAI_API_KEY=sk-your-key
+    ```
+  </Tab>
+  <Tab title="Mem0 OSS (Docker)">
+    ```bash
+    git clone https://github.com/mem0ai/memory-benchmarks.git
+    cd memory-benchmarks
+    pip install -r requirements.txt
+
+    # Copy and configure environment
+    cp .env.example .env
+    # Edit .env to add OPENAI_API_KEY
+
+    # Start local Mem0 server + Qdrant
+    docker compose up -d
+    # Mem0 server: http://localhost:8888
+    # Qdrant:      http://localhost:6333
+    ```
+  </Tab>
+</Tabs>
+
+### Running a Benchmark
+
+Each benchmark is a Python module with its own runner ([source code](https://github.com/mem0ai/memory-benchmarks/tree/main/benchmarks)). All share common CLI options:
+
+| Option | Default | Description |
+|---|---|---|
+| `--project-name` | (required) | Run identifier for tracking results |
+| `--backend` | `oss` | `oss` (self-hosted) or `cloud` (Mem0 Platform) |
+| `--mem0-api-key` | — | Mem0 API key (required for `cloud` backend) |
+| `--mem0-host` | `http://localhost:8888` | Mem0 server URL (for `oss` backend) |
+| `--top-k` | `200` | Number of memories to retrieve per query |
+| `--top-k-cutoffs` | `10,20,50,200` | Evaluate accuracy at multiple retrieval depths (BEAM default: `100`) |
+| `--answerer-model` | *(varies)* | LLM for generating answers from retrieved memories |
+| `--judge-model` | *(varies)* | LLM for judging answer correctness |
+| `--provider` | `openai` | LLM provider: `openai`, `anthropic`, `azure` |
+| `--judge-provider` | (same as `--provider`) | Override provider for the judge model |
+| `--max-workers` | `10` | Parallel workers for evaluation |
+| `--predict-only` | — | Stop after search, skip answer + judge phases |
+| `--evaluate-only` | — | Skip ingest + search, evaluate existing results |
+| `--resume` | — | Resume from checkpoint (BEAM and LongMemEval; on by default for LongMemEval) |
+
+<CodeGroup>
+```bash LoCoMo
+# ~300 questions across 10 conversations (fastest benchmark)
+python -m benchmarks.locomo.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --top-k 200
+
+# Self-hosted
+python -m benchmarks.locomo.run \
+  --project-name my-eval \
+  --top-k 200
+```
+
+```bash LongMemEval
+# 500 questions across 6 categories
+python -m benchmarks.longmemeval.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --all-questions \
+  --top-k 200
+
+# Self-hosted
+python -m benchmarks.longmemeval.run \
+  --project-name my-eval \
+  --all-questions \
+  --top-k 200
+```
+
+```bash BEAM
+# 1M token scale (100 conversations)
+python -m benchmarks.beam.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --chat-sizes 1M \
+  --conversations 0-99 \
+  --top-k 200
+
+# 10M token scale
+python -m benchmarks.beam.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --chat-sizes 10M \
+  --conversations 0-99 \
+  --top-k 200
+```
+</CodeGroup>
+
+### Custom Model Configuration
+
+To run evaluations with custom models (Azure OpenAI, Ollama, etc.), copy one of the provided configs:
+
+```bash
+# Available configs: openai.yaml, azure-openai.yaml, ollama.yaml
+cp configs/azure-openai.yaml mem0-config.yaml
+# Edit mem0-config.yaml with your model details
+
+# Uncomment the volume mount in docker-compose.yml, then restart:
+docker compose down && docker compose up -d
+```
+
+### Viewing Results
+
+Results are saved to `results/[benchmark]/` and can be explored through the built-in web UI:
+
+```bash
+npm install
+npm run dev -- -p 3001
+# Open http://localhost:3001
+```
+
+The UI lets you browse per-question results, inspect retrieval details, and compare multiple runs.
+
+### Result Format
+
+Each evaluated question produces a structured result:
+
+```json
+{
+  "id": "locomo_q_001",
+  "group": "temporal",
+  "question": "When did the user first mention moving?",
+  "ground_truth": "During the March 3rd conversation",
+  "retrieval": {
+    "search_query": "when did user mention moving",
+    "search_results": ["..."],
+    "search_latency_ms": 123.4,
+    "total_results": 42
+  },
+  "generation": {
+    "generated_answer": "The user first mentioned moving on March 3rd",
+    "model": "<answerer-model>",
+    "prompt_tokens": 500,
+    "completion_tokens": 100
+  },
+  "judgment": {
+    "judgment": "CORRECT",
+    "score": 0.85,
+    "reason": "Answer correctly identifies the date",
+    "model": "<judge-model>"
+  },
+  "cutoff_results": {
+    "top_10": { "score": 0.75, "judgment": "CORRECT" },
+    "top_50": { "score": 0.85, "judgment": "CORRECT" },
+    "top_200": { "score": 0.90, "judgment": "CORRECT" }
+  }
+}
+```
+
+## Interpreting Results
+
+When evaluating memory systems, keep these considerations in mind:
+
+- **Saturating a small benchmark is not the same as building a memory system that works at scale.** Small benchmarks can be brute-forced with aggressive retrieval and frontier models.
+- **Token efficiency matters as much as accuracy.** A system that scores 95% using 25K tokens per query isn't comparable to one scoring 90% using 7K tokens. Report mean tokens per query alongside scores.
+- **Compare at equal constraints.** Always compare systems using the same retrieval budget, the same model, and the same latency budget. A frontier model at maximum recall is not comparable to a smaller production-grade model at production-realistic retrieval depth.
+- **Watch for score ceiling effects.** Categories like "single-session user" are already near-saturated (97%+). Improvements in these categories are less meaningful than gains in harder categories like temporal reasoning or multi-session.
+- **BEAM at 10M is the real test.** Any system can look good at small scale. The 10M-token BEAM benchmark reveals whether the retrieval system actually scales.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="What judge model is used for evaluation?">
+    The judge model is configurable via `--judge-model` and `--judge-provider` flags. See the [evaluation repository](https://github.com/mem0ai/memory-benchmarks) for the current defaults. Scores carry a ±1 point confidence interval due to judge inconsistency.
+  </Accordion>
+  <Accordion title="Can I evaluate with a different extraction model?">
+    Yes. For self-hosted, configure the extraction model in your `mem0-config.yaml` (see the `configs/` directory of the evaluation repo for provider-specific examples). For Mem0 Cloud, extraction uses the platform's default. Using a frontier model will likely produce higher scores but at higher cost and latency.
+  </Accordion>
+  <Accordion title="Why are BEAM scores lower than LoCoMo/LongMemEval?">
+    BEAM operates at 1M and 10M token scales — orders of magnitude larger than LoCoMo or LongMemEval. At these scales, similar content appears multiple times across the window, and the memory system must surface the exact correct memory over many close matches. The scores reflect the genuine difficulty of the task, not a regression in the algorithm.
+  </Accordion>
+  <Accordion title="How do I contribute a new benchmark?">
+    Open a pull request to the [memory-benchmarks repository](https://github.com/mem0ai/memory-benchmarks) with your benchmark implementation. See the repository README for the expected interface and format.
+  </Accordion>
+</AccordionGroup>
+
+## Resources
+
+<CardGroup cols={2}>
+  <Card title="Evaluation Repository" icon="github" href="https://github.com/mem0ai/memory-benchmarks">
+    Open-source evaluation framework for reproducing all benchmark results
+  </Card>
+  <Card title="Research" icon="flask" href="https://mem0.ai/research">
+    Published research papers and technical reports
+  </Card>
+  <Card title="Blog Post" icon="newspaper" href="https://mem0.ai/blog/new-algorithm">
+    Detailed writeup of the new algorithm design and results
+  </Card>
+  <Card title="Platform Migration" icon="arrow-right" href="/migration/platform-v2-to-v3">
+    Guide for migrating your Platform integration
+  </Card>
+</CardGroup>

docs/core-concepts/memory-operations/add.mdx

@@ -21,7 +21,7 @@ Adding memory is how Mem0 captures useful details from a conversation so your ag
 - **Messages** – The ordered list of user/assistant turns you send to `add`.
 - **Infer** – Controls whether Mem0 extracts structured memories (`infer=True`, default) or stores raw messages.
 - **Metadata** – Optional filters (e.g., `{"category": "movie_recommendations"}`) that improve retrieval later.
-- **User / Session identifiers** – `user_id`, `session_id`, or `run_id` that scope the memory for future searches.
+- **User / Session identifiers** – `user_id`, `agent_id`, or `run_id` that scope the memory for future searches.
 
 ## How does it work?
 
@@ -85,7 +85,6 @@ const messages = [
 
 await client.add(messages, {
   user_id: "alice",
-  version: "v2",
 });
 ```
 </CodeGroup>
@@ -173,7 +172,6 @@ For full list of supported fields, required formats, and advanced options, see t
 | Capability | Mem0 Platform | Mem0 OSS |
 | --- | --- | --- |
 | Conflict resolution | Automatic with dashboard visibility | SDK handles merges locally; you control storage |
-| Graph writes | Toggle per request (`enable_graph=True`) | Requires configuring a graph provider |
 | Rate limits | Managed quotas per workspace | Limited by your hardware and provider APIs |
 | Dashboard visibility | Yes — inspect memories visually | Inspect via CLI, logs, or custom UI |
 

docs/core-concepts/memory-operations/delete.mdx

@@ -120,7 +120,7 @@ import MemoryClient from 'mem0ai';
 
 const client = new MemoryClient({ apiKey: "your-api-key" });
 
-client.deleteAll({ user_id: "alice" })
+client.deleteAll({ userId: "alice" })
   .then(result => console.log(result))
   .catch(error => console.error(error));
 ```
@@ -162,12 +162,12 @@ import MemoryClient from 'mem0ai';
 const client = new MemoryClient({ apiKey: "your-api-key" });
 
 // Delete all memories across every user in the project
-client.deleteAll({ user_id: "*" })
+client.deleteAll({ userId: "*" })
   .then(result => console.log(result))
   .catch(error => console.error(error));
 
 // Full project wipe — all four filters must be explicitly set to "*"
-client.deleteAll({ user_id: "*", agent_id: "*", app_id: "*", run_id: "*" })
+client.deleteAll({ userId: "*", agentId: "*", appId: "*", runId: "*" })
   .then(result => console.log(result))
   .catch(error => console.error(error));
 ```

docs/core-concepts/memory-operations/search.mdx

@@ -56,7 +56,7 @@ Search converts your natural language question into a vector embedding, then fin
 client.search("What are Alice's hobbies?", filters={"user_id": "alice"})
 
 # OSS
-m.search("What are Alice's hobbies?", user_id="alice")
+m.search("What are Alice's hobbies?", filters={"user_id": "alice"})
 ```
 
 <Tip>
@@ -74,7 +74,7 @@ m.search("What are Alice's hobbies?", user_id="alice")
 
 | Capability | Mem0 Platform | Mem0 OSS |
 | --- | --- | --- |
-| **user_id usage** | In `filters={"user_id": "alice"}` for search/get_all | As parameter `user_id="alice"` for all operations |
+| **Entity IDs on search / get_all** | Inside `filters={"user_id": "alice"}` | Inside `filters={"user_id": "alice"}` (aligned with Platform in v3 — top-level kwargs raise `ValueError`) |
 | **Filter syntax** | Logical operators (`AND`, `OR`, comparisons) with field-level access | Basic field filters, extend via Python hooks |
 | **Reranking** | Toggle `rerank=True` with managed reranker catalog | Requires configuring local or third-party rerankers |
 | **Thresholds** | Request-level configuration (`threshold`, `top_k`) | Controlled via SDK parameters |
@@ -125,14 +125,13 @@ from mem0 import Memory
 
 m = Memory()
 
-# Simple search
-related_memories = m.search("Should I drink coffee or tea?", user_id="alice")
+# Simple search — entity IDs go in `filters`
+related_memories = m.search("Should I drink coffee or tea?", filters={"user_id": "alice"})
 
-# Search with filters
+# Search with additional metadata filters (combine entity + metadata in the same dict)
 memories = m.search(
     "food preferences",
-    user_id="alice",
-    filters={"categories": {"contains": "diet"}}
+    filters={"user_id": "alice", "categories": {"contains": "diet"}},
 )
 ```
 
@@ -141,13 +140,14 @@ import { Memory } from 'mem0ai/oss';
 
 const memory = new Memory();
 
-// Simple search
-const relatedMemories = memory.search("Should I drink coffee or tea?", { userId: "alice" });
+// Simple search — entity IDs go inside `filters`
+const relatedMemories = memory.search("Should I drink coffee or tea?", {
+    filters: { userId: "alice" },
+});
 
-// Search with filters (if supported)
+// Combine entity + metadata filters in the same filters object
 const memories = memory.search("food preferences", {
-    userId: "alice",
-    filters: { categories: { contains: "diet" } }
+    filters: { userId: "alice", categories: { contains: "diet" } },
 });
 ```
 </CodeGroup>
@@ -176,8 +176,12 @@ client.search("query", filters={
 
 *OSS:*
 ```python
-# Get memories from a specific agent session
-m.search("query", user_id="alice", agent_id="chatbot", run_id="session-123")
+# Get memories from a specific agent session — entity IDs combined in filters
+m.search("query", filters={
+    "user_id": "alice",
+    "agent_id": "chatbot",
+    "run_id": "session-123",
+})
 ```
 
 **Filter by Date Range:**

docs/core-concepts/memory-types.mdx

@@ -52,7 +52,7 @@ Mem0 maps these classic categories onto its layered storage so you can decide wh
 Mem0 stores each layer separately and merges them when you query:
 
 1. **Capture** – Messages enter the conversation layer while the turn is active.
-2. **Promote** – Relevant details persist to session or user memory based on your `user_id`, `session_id`, and metadata.
+2. **Promote** – Relevant details persist to session or user memory based on your `user_id`, `run_id`, and metadata.
 3. **Retrieve** – The search pipeline pulls from all layers, ranking user memories first, then session notes, then raw history.
 
 ```python
@@ -66,19 +66,19 @@ memory = Memory(api_key=os.environ["MEM0_API_KEY"])
 memory.add(
     ["I'm Alex and I prefer boutique hotels."],
     user_id="alex",
-    session_id="trip-planning-2025",
+    run_id="trip-planning-2025",
 )
 
 # Later in the session, pull long-term + session context
 results = memory.search(
     "Any hotel preferences?",
     user_id="alex",
-    session_id="trip-planning-2025",
+    run_id="trip-planning-2025",
 )
 ```
 
 <Tip>
-  Use `session_id` when you want short-term context to expire automatically; rely on `user_id` for lasting personalization.
+  Use `run_id` when you want short-term context to expire automatically; rely on `user_id` for lasting personalization.
 </Tip>
 
 ## When should you use each layer?

docs/docs.json

@@ -12,7 +12,7 @@
   "logo": {
     "light": "/logo/light.svg",
     "dark": "/logo/dark.svg",
-    "href": "https://app.mem0.ai/"
+    "href": "https://mem0.ai"
   },
   "navigation": {
     "anchors": [
@@ -55,7 +55,8 @@
                       "core-concepts/memory-operations/add",
                       "core-concepts/memory-operations/search",
                       "core-concepts/memory-operations/update",
-                      "core-concepts/memory-operations/delete"
+                      "core-concepts/memory-operations/delete",
+                      "core-concepts/memory-evaluation"
                     ]
                   },
                   {
@@ -70,7 +71,6 @@
                           "platform/features/v2-memory-filters",
                           "platform/features/entity-scoped-memory",
                           "platform/features/async-client",
-                          "platform/features/async-mode-default-change",
                           "platform/features/multimodal-support",
                           "platform/features/custom-categories"
                         ]
@@ -79,8 +79,6 @@
                         "group": "Advanced Features",
                         "icon": "bolt",
                         "pages": [
-                          "platform/features/graph-memory",
-                          "platform/features/graph-threshold",
                           "platform/features/advanced-retrieval",
                           "platform/advanced-memory-operations",
                           "platform/features/criteria-retrieval",
@@ -94,8 +92,7 @@
                         "pages": [
                           "platform/features/direct-import",
                           "platform/features/memory-export",
-                          "platform/features/timestamp",
-                          "platform/features/expiration-date"
+                          "platform/features/timestamp"
                         ]
                       },
                       {
@@ -121,9 +118,8 @@
                     "group": "Migration Guide",
                     "icon": "arrow-right",
                     "pages": [
+                      "migration/platform-v2-to-v3",
                       "migration/oss-to-platform",
-                      "migration/v0-to-v1",
-                      "migration/breaking-changes",
                       "migration/api-changes"
                     ]
                   },
@@ -136,6 +132,19 @@
                   }
                 ]
               },
+              {
+                "tab": "OpenClaw",
+                "groups": [
+                  {
+                    "group": "Agent Harness",
+                    "icon": "robot",
+                    "pages": [
+                      "integrations/openclaw",
+                      "integrations/hermes"
+                    ]
+                  }
+                ]
+              },
               {
                 "tab": "Open Source",
                 "groups": [
@@ -154,13 +163,11 @@
                     "icon": "server",
                     "pages": [
                       "open-source/features/overview",
-                      "open-source/features/graph-memory",
                       "open-source/features/metadata-filtering",
                       "open-source/features/reranker-search",
                       "open-source/features/async-memory",
                       "open-source/features/multimodal-support",
-                      "open-source/features/custom-fact-extraction-prompt",
-                      "open-source/features/custom-update-memory-prompt",
+                      "open-source/features/custom-instructions",
                       "open-source/features/rest-api",
                       "open-source/features/openai_compatibility"
                     ]
@@ -287,6 +294,13 @@
                       }
                     ]
                   },
+                  {
+                    "group": "Migration",
+                    "icon": "arrow-right",
+                    "pages": [
+                      "migration/oss-v2-to-v3"
+                    ]
+                  },
                   {
                     "group": "Community & Support",
                     "icon": "users",
@@ -314,7 +328,6 @@
                       "cookbooks/essentials/building-ai-companion",
                       "cookbooks/essentials/entity-partitioning-playbook",
                       "cookbooks/essentials/controlling-memory-ingestion",
-                      "cookbooks/essentials/memory-expiration-short-and-long-term",
                       "cookbooks/essentials/tagging-and-organizing-memories",
                       "cookbooks/essentials/exporting-memories",
                       "cookbooks/essentials/choosing-memory-architecture-vector-vs-graph"
@@ -353,7 +366,6 @@
                       "cookbooks/integrations/mastra-agent",
                       "cookbooks/integrations/healthcare-google-adk",
                       "cookbooks/integrations/aws-bedrock",
-                      "cookbooks/integrations/neptune-analytics",
                       "cookbooks/integrations/tavily-search"
                     ]
                   },
@@ -365,9 +377,7 @@
                       "cookbooks/frameworks/llamaindex-multiagent",
                       "cookbooks/frameworks/multimodal-retrieval",
                       "cookbooks/frameworks/eliza-os-character",
-                      "cookbooks/frameworks/chrome-extension",
-                      "cookbooks/frameworks/gemini-3-with-mem0-mcp",
-                      "cookbooks/frameworks/mirofish-swarm-memory"
+                      "cookbooks/frameworks/gemini-3-with-mem0-mcp"
                     ]
                   }
                 ]
@@ -393,11 +403,11 @@
                       "integrations/autogen",
                       "integrations/agno",
                       "integrations/camel-ai",
-                      "integrations/openclaw",
                       "integrations/openai-agents-sdk",
                       "integrations/google-ai-adk",
                       "integrations/mastra",
-                      "integrations/vercel-ai-sdk"
+                      "integrations/vercel-ai-sdk",
+                      "integrations/chatdev"
                     ]
                   },
                   {
@@ -430,6 +440,28 @@
                   }
                 ]
               },
+              {
+                "tab": "Agent Plugins",
+                "groups": [
+                  {
+                    "group": "Coding Agents",
+                    "icon": "terminal",
+                    "pages": [
+                      "integrations/claude-code",
+                      "integrations/cursor",
+                      "integrations/codex"
+                    ]
+                  },
+                  {
+                    "group": "Agent Harness",
+                    "icon": "robot",
+                    "pages": [
+                      "integrations/openclaw",
+                      "integrations/hermes"
+                    ]
+                  }
+                ]
+              },
               {
                 "tab": "API Reference",
                 "groups": [
@@ -522,10 +554,13 @@
                 "tab": "Release Notes",
                 "groups": [
                   {
-                    "group": "Changelog",
+                    "group": "Release Notes",
                     "icon": "rocket",
                     "pages": [
-                      "changelog"
+                      "changelog/highlights",
+                      "changelog/sdk",
+                      "changelog/platform",
+                      "changelog/openclaw"
                     ]
                   }
                 ]
@@ -579,6 +614,38 @@
     ]
   },
   "redirects": [
+    {
+      "source": "/migration/breaking-changes",
+      "destination": "/"
+    },
+    {
+      "source": "/migration/v0-to-v1",
+      "destination": "/"
+    },
+    {
+      "source": "/platform/features/expiration-date",
+      "destination": "/"
+    },
+    {
+      "source": "/cookbooks/essentials/memory-expiration-short-and-long-term",
+      "destination": "/cookbooks/essentials/building-ai-companion"
+    },
+    {
+      "source": "/platform/features/async-mode-default-change",
+      "destination": "/"
+    },
+    {
+      "source": "/open-source/features/custom-fact-extraction-prompt",
+      "destination": "/open-source/features/custom-instructions"
+    },
+    {
+      "source": "/platform/features/graph-memory",
+      "destination": "/migration/oss-v2-to-v3"
+    },
+    {
+      "source": "/changelog",
+      "destination": "/changelog/highlights"
+    },
     {
       "source": "/api-reference/memory/v2-search-memories",
       "destination": "/api-reference/memory/search-memories"
@@ -673,11 +740,23 @@
     },
     {
       "source": "/examples/aws_neptune_analytics_hybrid_store",
-      "destination": "/cookbooks/integrations/neptune-analytics"
+      "destination": "/migration/oss-v2-to-v3"
     },
     {
       "source": "/examples/aws_neptune_analytics_hybrid_st",
-      "destination": "/cookbooks/integrations/neptune-analytics"
+      "destination": "/migration/oss-v2-to-v3"
+    },
+    {
+      "source": "/cookbooks/integrations/neptune-analytics",
+      "destination": "/migration/oss-v2-to-v3"
+    },
+    {
+      "source": "/platform/features/graph-threshold",
+      "destination": "/migration/platform-v2-to-v3"
+    },
+    {
+      "source": "/open-source/features/custom-update-memory-prompt",
+      "destination": "/open-source/features/custom-instructions"
     },
     {
       "source": "/examples/personalized-search-tavily-mem0",
@@ -737,7 +816,11 @@
     },
     {
       "source": "/examples/chrome-extension",
-      "destination": "/cookbooks/frameworks/chrome-extension"
+      "destination": "/cookbooks/overview"
+    },
+    {
+      "source": "/cookbooks/frameworks/chrome-extension",
+      "destination": "/cookbooks/overview"
     },
     {
       "source": "/examples",
@@ -745,11 +828,11 @@
     },
     {
       "source": "/open-source/graph_memory/overview",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
     },
     {
       "source": "/open-source/graph_memory/features",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
     },
     {
       "source": "/v0x/examples/ai_companion_js",
@@ -777,7 +860,7 @@
     },
     {
       "source": "/v0x/examples/chrome-extension",
-      "destination": "/cookbooks/frameworks/chrome-extension"
+      "destination": "/cookbooks/overview"
     },
     {
       "source": "/v0x/examples/youtube-assistant",
@@ -845,7 +928,7 @@
     },
     {
       "source": "/v0x/examples/aws_neptune_analytics_hybrid_store",
-      "destination": "/cookbooks/integrations/neptune-analytics"
+      "destination": "/migration/oss-v2-to-v3"
     },
     {
       "source": "/features/memory-export",
@@ -929,7 +1012,7 @@
     },
     {
       "source": "/features/graph-memory",
-      "destination": "/platform/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
     },
     {
       "source": "/features/:slug",
@@ -1037,7 +1120,7 @@
     },
     {
       "source": "/open-source/graph-memory",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
     },
     {
       "source": "/cookbooks/customer-support-agent",

docs/integrations.mdx

@@ -381,4 +381,39 @@ Here are the available integrations for Mem0:
   >
     Build AI agents with persistent memory using Mastra's framework and tools.
   </Card>
+  <Card
+    title="OpenAI Agents SDK"
+    icon="robot"
+    href="/integrations/openai-agents-sdk"
+  >
+    Integrate Mem0 with the OpenAI Agents SDK for persistent memory across multi-agent workflows.
+  </Card>
+  <Card
+    title="Google ADK"
+    icon="google"
+    href="/integrations/google-ai-adk"
+  >
+    Integrate Mem0 with Google Agent Development Kit for persistent memory across multi-agent workflows.
+  </Card>
+  <Card
+    title="Flowise"
+    icon="diagram-project"
+    href="/integrations/flowise"
+  >
+    Add persistent Mem0 memory to Flowise chatflows for context-aware conversations in the low-code builder.
+  </Card>
+  <Card
+    title="AWS Bedrock"
+    icon="cloud"
+    href="/integrations/aws-bedrock"
+  >
+    Use Mem0 with AWS Bedrock and OpenSearch Service for cloud-native persistent semantic memory storage.
+  </Card>
+  <Card
+    title="ChatDev"
+    icon="comments"
+    href="/integrations/chatdev"
+  >
+    Add persistent cloud-managed memory to ChatDev multi-agent workflows with zero-code YAML configuration.
+  </Card>
 </CardGroup>

docs/integrations/agentops.mdx

@@ -24,7 +24,7 @@ pip install mem0ai agentops python-dotenv
 2. Valid API keys:
    - [AgentOps API Key](https://app.agentops.ai/dashboard/api-keys)
    - OpenAI API Key (for LLM operations)
-   - [Mem0 API Key](https://app.mem0.ai/dashboard/api-keys) (optional, for cloud operations)
+   - <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">Mem0 API Key</a> (optional, for cloud operations)
 
 ## Basic Integration Example
 
@@ -50,7 +50,7 @@ local_config = {
     "llm": {
         "provider": "openai",
         "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
             "temperature": 0.1,
             "max_tokens": 2000,
         },
@@ -103,7 +103,7 @@ def demonstrate_sync_memory(local_config, sample_messages, sample_preferences, u
         ]
 
         for query in search_queries:
-            results = memory.search(query, user_id=user_id)
+            results = memory.search(query, filters={"user_id": user_id})
         
             if results and "results" in results:
                 for j, result in enumerate(results['results']): 
@@ -111,7 +111,7 @@ def demonstrate_sync_memory(local_config, sample_messages, sample_preferences, u
             else:
                 print("No results found")
 
-        all_memories = memory.get_all(user_id=user_id)
+        all_memories = memory.get_all(filters={"user_id": user_id})
         if all_memories and "results" in all_memories:
             print(f"Total memories: {len(all_memories['results'])}")
 

docs/integrations/agno.mdx

@@ -23,7 +23,7 @@ pip install agno mem0ai python-dotenv
 ```
 
 2. Valid API keys:
-   - [Mem0 API Key](https://app.mem0.ai/dashboard/api-keys)
+   - <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">Mem0 API Key</a>
    - OpenAI API Key (for the agent model)
 
 ## Quick Integration (Using `Mem0Tools`)
@@ -37,7 +37,7 @@ from agno.tools.mem0 import Mem0Tools
 
 agent = Agent(
     name="Memory Agent",
-    model=OpenAIChat(id="gpt-4.1-nano-2025-04-14"),
+    model=OpenAIChat(id="gpt-5-mini"),
     tools=[Mem0Tools()],
     description="An assistant that remembers and personalizes using Mem0 memory."
 )
@@ -126,7 +126,7 @@ def chat_user(
 
     if user_input:
         # Search for relevant memories
-        memories = client.search(user_input, user_id=user_id)
+        memories = client.search(user_input, filters={"user_id": user_id})
         memory_context = "\n".join(f"- {m['memory']}" for m in memories['results'])
 
         # Construct the prompt

docs/integrations/autogen.mdx

@@ -19,7 +19,7 @@ pip install autogen mem0ai openai python-dotenv
 
 First, we'll import the necessary libraries and set up our configurations.
 
-<Note>Remember to get the Mem0 API key from [Mem0 Platform](https://app.mem0.ai).</Note>
+<Note>Remember to get the Mem0 API key from <a href="https://app.mem0.ai" rel="nofollow">Mem0 Platform</a>.</Note>
 
 ```python
 import os
@@ -72,7 +72,7 @@ Create a function to get context-aware responses based on user's question and pr
 
 ```python
 def get_context_aware_response(question):
-    relevant_memories = memory_client.search(question, user_id=USER_ID)
+    relevant_memories = memory_client.search(question, filters={"user_id": USER_ID})
     context = "\n".join([m["memory"] for m in relevant_memories.get('results', [])])
 
     prompt = f"""Answer the user question considering the previous interactions:
@@ -104,7 +104,7 @@ manager = ConversableAgent(
 )
 
 def escalate_to_manager(question):
-    relevant_memories = memory_client.search(question, user_id=USER_ID)
+    relevant_memories = memory_client.search(question, filters={"user_id": USER_ID})
     context = "\n".join([m["memory"] for m in relevant_memories.get('results', [])])
 
     prompt = f"""

docs/integrations/aws-bedrock.mdx

@@ -107,10 +107,10 @@ messages = [
 m.add(messages, user_id="alice", metadata={"category": "movie_recommendations"})
 
 # Search for memory
-relevant = m.search("What kind of movies does Alice like?", user_id="alice")
+relevant = m.search("What kind of movies does Alice like?", filters={"user_id": "alice"})
 
 # Retrieve all user memories
-all_memories = m.get_all(user_id="alice")
+all_memories = m.get_all(filters={"user_id": "alice"})
 ```
 
 ## Key Features
@@ -125,8 +125,5 @@ all_memories = m.get_all(user_id="alice")
   <Card title="AWS Bedrock Cookbook" icon="aws" href="/cookbooks/integrations/aws-bedrock">
     Complete guide to using Bedrock with Mem0
   </Card>
-  <Card title="Neptune Analytics Cookbook" icon="database" href="/cookbooks/integrations/neptune-analytics">
-    Build graph memory with AWS Neptune
-  </Card>
 </CardGroup>
 

docs/integrations/chatdev.mdx

@@ -0,0 +1,243 @@
+---
+title: ChatDev
+description: "Add persistent, cloud-managed memory to ChatDev multi-agent workflows with Mem0 — no code required, just YAML configuration."
+---
+
+Build multi-agent workflows in [ChatDev](https://github.com/OpenBMB/ChatDev) with persistent memory powered by Mem0. ChatDev is a zero-code multi-agent platform where agents, tools, and workflows are defined entirely in YAML. Mem0 integrates as a built-in memory store (`type: mem0`), giving your agents cloud-managed semantic search and cross-session persistence — all without writing any code.
+
+## Overview
+
+In this guide, you'll:
+1. Set up ChatDev with the Mem0 memory store
+2. Configure agents with persistent memory using YAML
+3. Enable automatic memory retrieval and storage across conversations
+4. Leverage cross-session persistence for personalized multi-agent interactions
+
+## Prerequisites
+
+- **Python 3.12+**
+- **[uv](https://docs.astral.sh/uv/)** — Python package manager
+- **Node.js 18+** and **npm** — only needed if using the web console
+- A **Mem0 API key** from <a href="https://app.mem0.ai" rel="nofollow">app.mem0.ai</a>
+- An **OpenAI API key** (or another LLM provider supported by ChatDev)
+
+## Setup and Configuration
+
+Install ChatDev and its dependencies (includes `mem0ai`):
+
+```bash
+git clone https://github.com/OpenBMB/ChatDev.git
+cd ChatDev
+uv sync
+```
+
+If you plan to use the web console, also install the frontend:
+
+```bash
+cd frontend && npm install && cd ..
+```
+
+Set up your environment variables in a `.env` file:
+
+<Note>Get your Mem0 API key from <a href="https://app.mem0.ai" rel="nofollow">Mem0 Platform</a>.</Note>
+
+```bash
+MEM0_API_KEY=your-mem0-api-key
+API_KEY=your-openai-api-key
+BASE_URL=https://api.openai.com/v1
+```
+
+## Configure Mem0 Memory Store
+
+In your ChatDev workflow YAML, add a Mem0 memory store in the `memory` section:
+
+```yaml
+memory:
+  - name: mem0_store
+    type: mem0
+    config:
+      api_key: ${MEM0_API_KEY}
+      user_id: my-user-123       # optional: scope memories to a user
+      agent_id: my-agent         # optional: scope memories to an agent
+```
+
+Mem0 handles all storage, embeddings, and search server-side — no local vector databases or embedding models are needed.
+
+## Attach Memory to an Agent
+
+Reference the memory store in your agent node's `memories` list:
+
+```yaml
+nodes:
+  - id: writer
+    type: agent
+    config:
+      role: |
+        You are a knowledgeable writer. Use your memories to build
+        on past interactions.
+      memories:
+        - name: mem0_store
+          top_k: 5
+          similarity_threshold: 0.5   # minimum relevance score (0.0–1.0); set to -1.0 to disable
+          retrieve_stage:
+            - gen
+          read: true
+          write: true
+```
+
+- **`read: true`** — Agent retrieves relevant memories before generating a response
+- **`write: true`** — Agent stores new memories from user input after each interaction
+- **`top_k`** — Number of memories to retrieve per query
+- **`similarity_threshold`** — Minimum relevance score for retrieved memories. Set to `-1.0` to return all results regardless of score
+- **`retrieve_stage`** — When to retrieve memories. Options: `pre_gen_thinking` (before generation), `gen` (during generation), `post_gen_thinking` (after generation), `finished` (after completion)
+
+## Full Example Workflow
+
+Here's a complete workflow YAML that creates a memory-backed conversational agent:
+
+```yaml
+version: 0.4.0
+graph:
+  description: Memory-backed conversation using Mem0
+
+  nodes:
+    - id: writer
+      type: agent
+      config:
+        base_url: ${BASE_URL}
+        api_key: ${API_KEY}
+        provider: openai
+        name: gpt-5.4
+        role: |
+          You are a knowledgeable writer. Use your memories to build
+          on past interactions. If memory sections are provided
+          (wrapped by ===== Related Memories =====), incorporate
+          relevant context from those memories into your response.
+        params:
+          temperature: 0.7
+          max_tokens: 2000
+        memories:
+          - name: mem0_store
+            top_k: 5
+            retrieve_stage:
+              - gen
+            read: true
+            write: true
+
+  memory:
+    - name: mem0_store
+      type: mem0
+      config:
+        api_key: ${MEM0_API_KEY}
+        user_id: project-user-123
+        agent_id: writer-agent
+
+  start:
+    - writer
+  end: []
+```
+
+Run the workflow:
+
+```bash
+# Option 1: CLI (recommended for quick testing)
+uv run python run.py --path yaml_instance/demo_mem0_memory.yaml --name my_project
+
+# Option 2: Web console
+make dev
+# Backend starts at http://localhost:6400, frontend at http://localhost:5173
+```
+
+To use the web console, open `http://localhost:5173`, create a new workflow, and paste your YAML configuration into the editor. The web console provides a visual chat interface for interacting with your memory-backed agents.
+
+## How It Works
+
+When an agent with Mem0 memory receives input, the following cycle runs automatically:
+
+**1. Retrieve** — Before generating a response, ChatDev queries Mem0 with the user's input using semantic search. Relevant memories are injected into the agent's context in this format:
+
+```
+===== Related Memories =====
+--- mem0_store ---
+1. User's favorite language is Rust
+2. User lives in San Francisco
+===== End of Memory =====
+```
+
+This is why the role prompt in the example references `===== Related Memories =====` — the agent needs to know how to use this injected context.
+
+**2. Generate** — The agent produces a response using the retrieved memories as additional context.
+
+**3. Store** — After generation, the user's input is sent to Mem0 via `client.add()`. Mem0's extraction model automatically identifies and stores facts, preferences, and key information. Only user input is stored — agent output is excluded to keep memories clean.
+
+Memories persist in Mem0's cloud across all sessions. The next time the same `user_id` or `agent_id` is used, previous memories are automatically retrieved.
+
+## Dual-Scope Memory (User + Agent)
+
+When both `user_id` and `agent_id` are configured, Mem0 uses an OR filter to search across both scopes in a single query:
+
+```yaml
+memory:
+  - name: shared_store
+    type: mem0
+    config:
+      api_key: ${MEM0_API_KEY}
+      user_id: alice              # stores user preferences ("Alice prefers dark mode")
+      agent_id: support-bot       # stores agent-learned context ("Resolved Alice's billing issue")
+```
+
+This means retrieval returns memories from **both** the user's scope and the agent's scope. Writes include both IDs, so each memory is accessible from either dimension. Use this when you want an agent to remember both what the user told it *and* what the agent learned across sessions.
+
+## Configuration Reference
+
+### Memory Store Config
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `api_key` | Yes | Mem0 API key from <a href="https://app.mem0.ai" rel="nofollow">app.mem0.ai</a> |
+| `user_id` | No | Scope memories to a specific user |
+| `agent_id` | No | Scope memories to a specific agent |
+
+### Memory Attachment Config
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `top_k` | `3` | Number of memories to retrieve |
+| `similarity_threshold` | `-1.0` (disabled) | Minimum relevance score. Set a value between `0.0` and `1.0` to filter low-relevance results. Default (`-1.0`) returns all matches without filtering |
+| `retrieve_stage` | `["gen"]` | When to retrieve: `pre_gen_thinking`, `gen`, `post_gen_thinking`, or `finished` |
+| `read` | `true` | Whether the agent retrieves memories |
+| `write` | `true` | Whether the agent stores new memories |
+
+## Tips and Common Pitfalls
+
+<Info>
+**Indexing delay** — Freshly stored memories may take a few seconds to become searchable. If a memory isn't retrieved immediately after being stored, wait a moment and try again.
+</Info>
+
+- **No memories returned on first run** — This is expected. Memories are stored *after* the agent responds, so the first interaction has no prior context. Memories appear starting from the second interaction onward.
+- **`mem0ai` not installed** — If you see `ImportError: mem0ai is required for Mem0Memory`, run `uv add mem0ai` or `pip install mem0ai` to add the dependency.
+- **Invalid API key** — A wrong or expired `MEM0_API_KEY` will log errors like `Mem0 search failed` or `Mem0 add failed` but won't crash the agent. Check your key at <a href="https://app.mem0.ai" rel="nofollow">app.mem0.ai</a>.
+- **Pipeline headers in memories** — ChatDev automatically strips internal pipeline headers (e.g., `=== INPUT FROM TASK (user) ===`) before sending text to Mem0, so your memories stay clean.
+- **Clearing test memories** — To delete memories created during testing, use the Mem0 dashboard at <a href="https://app.mem0.ai" rel="nofollow">app.mem0.ai</a> or the Python SDK: `MemoryClient().delete_all(user_id="your-test-user")`.
+
+## Key Features
+
+1. **Zero-Code Integration** — Configure Mem0 entirely through YAML, no Python code required
+2. **Cloud-Managed Storage** — Mem0 handles embeddings, persistence, and search server-side
+3. **Semantic Search** — Retrieve contextually relevant memories, not just keyword matches
+4. **Cross-Session Persistence** — Memories survive across runs, sessions, and restarts
+5. **Multi-Agent Memory Sharing** — Multiple agents can share memories through common `user_id` or `agent_id` scopes
+6. **Intelligent Input Processing** — Only user input is stored; agent output is excluded to prevent noisy memories
+
+## Conclusion
+
+By adding Mem0 as a memory store in ChatDev, your multi-agent workflows gain persistent, intelligent memory with zero code changes. Agents automatically remember past interactions and use that context to provide personalized, coherent responses across sessions.
+
+<CardGroup cols={2}>
+  <Card title="CrewAI Integration" icon="users" href="/integrations/crewai">
+    Build multi-agent systems with CrewAI and Mem0
+  </Card>
+  <Card title="AutoGen Integration" icon="robot" href="/integrations/autogen">
+    Build conversational agents with AutoGen and Mem0
+  </Card>
+</CardGroup>

docs/integrations/claude-code.mdx

@@ -0,0 +1,156 @@
+---
+title: Claude Code
+description: "Add persistent memory to Claude Code and Claude Cowork with the Mem0 plugin — MCP server, lifecycle hooks, and SDK skill."
+---
+
+Add persistent memory to [**Claude Code**](https://docs.anthropic.com/en/docs/claude-code) (CLI) and **Claude Cowork** (desktop app) with the Mem0 plugin. Your agent forgets everything between sessions — this plugin fixes that by connecting to Mem0's cloud memory layer via MCP, automatically capturing learnings at key lifecycle points, and retrieving relevant context before every response.
+
+## Overview
+
+1. **MCP Server** — Connect to Mem0's remote MCP server for memory tools (add, search, update, delete)
+2. **Lifecycle Hooks** — Automatic memory capture at session start, context compaction, task completion, and session end
+3. **SDK Skill** — Teaches the agent how to integrate the Mem0 SDK into your applications
+4. **Zero local dependencies** — Cloud-hosted MCP server, no local setup required
+
+## Prerequisites
+
+Before setting up Mem0 with Claude Code, ensure you have:
+
+1. A Mem0 Platform account and API key:
+   - <a href="https://app.mem0.ai" rel="nofollow">Sign up at app.mem0.ai</a>
+   - <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">Get your API key</a> (starts with `m0-`)
+
+2. Claude Code CLI or Claude Cowork desktop app installed
+
+3. Your API key exported in your shell:
+
+```bash
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+## Installation
+
+### Option A — Plugin Marketplace (Recommended)
+
+Install the full plugin including MCP server, lifecycle hooks, and SDK skill:
+
+```
+/plugin marketplace add mem0ai/mem0
+/plugin install mem0@mem0-plugins
+```
+
+**Claude Cowork desktop app:** Open the Cowork tab, click **Customize** in the sidebar, click **Browse plugins**, and install Mem0.
+
+### Option B — MCP Only
+
+Add the Mem0 MCP server directly with a single command:
+
+```bash
+npx mcp-add \
+  --name mem0-mcp \
+  --type http \
+  --url "https://mcp.mem0.ai/mcp" \
+  --clients "claude code"
+```
+
+This gives you the MCP tools but not the lifecycle hooks or SDK skill.
+
+### Option C — Manual MCP Configuration
+
+Add to your Claude Code MCP config (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mem0": {
+      "type": "http",
+      "url": "https://mcp.mem0.ai/mcp/",
+      "headers": {
+        "Authorization": "Token ${MEM0_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+<Info icon="check">
+  Start a new session and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set.
+</Info>
+
+## What's Included
+
+| Component | Plugin Install | MCP Only |
+|-----------|:--------------:|:--------:|
+| MCP Server (9 memory tools) | Yes | Yes |
+| Lifecycle Hooks | Yes | No |
+| Mem0 SDK Skill | Yes | No |
+
+## Available MCP Tools
+
+Once installed, the following tools are available in every Claude Code session:
+
+| Tool | Description |
+|------|-------------|
+| `add_memory` | Save text or conversation history for a user/agent |
+| `search_memories` | Semantic search across memories with filters |
+| `get_memories` | List memories with filters and pagination |
+| `get_memory` | Retrieve a specific memory by ID |
+| `update_memory` | Overwrite a memory's text by ID |
+| `delete_memory` | Delete a single memory by ID |
+| `delete_all_memories` | Bulk delete all memories in scope |
+| `delete_entities` | Delete a user/agent/app/run entity and its memories |
+| `list_entities` | List users/agents/apps/runs stored in Mem0 |
+
+## Lifecycle Hooks
+
+When installed via the plugin marketplace, Mem0 hooks into Claude Code's lifecycle to automatically manage memory:
+
+### Session Start
+On every new session, the plugin prompts Claude to call `search_memories` to load relevant context from prior sessions. On resumed or post-compaction sessions, it adjusts the prompt accordingly.
+
+### User Prompt
+Before processing each user message, the plugin searches Mem0 for memories relevant to the current prompt and injects them into context. Short prompts (< 20 characters) are skipped to minimize latency.
+
+### Pre-Compaction
+Before context compaction, the plugin prompts Claude to store a comprehensive session summary — including goals, accomplishments, decisions, modified files, and current state — so nothing is lost.
+
+### Task Completed
+After each task completion, the plugin prompts Claude to extract and store key learnings: successful strategies, failed approaches, architectural decisions, and new conventions.
+
+### Session End
+When Claude finishes responding, the plugin prompts for any unstored learnings and captures transcript state via the Mem0 REST API as a background safety net.
+
+## Example Workflow
+
+```text
+# Session 1: Working on a feature
+You: Let's refactor the auth module to use JWT tokens instead of sessions.
+
+# Claude searches memories, finds nothing relevant, proceeds with the work.
+# After completing the task, Mem0 stores:
+#   - Decision: "Migrated auth from sessions to JWT tokens"
+#   - Files modified: auth/middleware.ts, auth/token.ts
+#   - User preference: "Prefers TypeScript, uses ESLint"
+
+# Session 2 (days later): Related work
+You: Add refresh token rotation to the auth system.
+
+# Claude searches memories, retrieves the JWT migration context.
+# Knows the file structure, decisions made, and user preferences.
+# Continues seamlessly without re-explaining the codebase.
+```
+
+## Troubleshooting
+
+- **"Connection failed"** — Verify `MEM0_API_KEY` is set in your shell: `echo $MEM0_API_KEY`
+- **No tools appearing** — Restart your Claude Code session after installation
+- **Memories not being captured** — Ensure you installed via the plugin marketplace (Option A) for lifecycle hooks. MCP-only installs require manual memory operations.
+
+<CardGroup cols={2}>
+  <Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">
+    Detailed MCP configuration for all clients
+  </Card>
+  <Card title="Codex Integration" icon={<svg width="24" height="25" viewBox="0 0 24 25" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M20.5565 10.6338C21.0009 9.27575 20.8528 7.76958 20.1367 6.53501C19.0503 4.63378 16.8528 3.67081 14.7046 4.11526C13.7663 3.05353 12.3836 2.46094 10.9515 2.46094C8.75399 2.46094 6.82807 3.86835 6.13671 5.94242C4.7293 6.23872 3.51943 7.10291 2.80338 8.36217C1.71696 10.2634 1.96387 12.6338 3.42066 14.2634C2.97622 15.6461 3.14906 17.1276 3.8651 18.3622C4.95152 20.2634 7.14906 21.2511 9.2972 20.7819C10.2602 21.8437 11.6182 22.4609 13.0503 22.4609C15.2478 22.4609 17.1737 21.0535 17.8651 18.9795C19.2725 18.6832 20.4824 17.819 21.1984 16.5597C22.2849 14.6585 22.0379 12.2634 20.5565 10.6338ZM13.0503 21.1523C12.1614 21.1523 11.3219 20.856 10.6552 20.2881C10.6799 20.2634 10.754 20.2387 10.7787 20.214L14.754 17.9177C14.9515 17.7943 15.075 17.5967 15.075 17.3498V11.7449L16.754 12.7079C16.7787 12.7079 16.7787 12.7325 16.7787 12.7572V17.3992C16.8034 19.4733 15.1244 21.1523 13.0503 21.1523ZM5.00091 17.7202C4.55646 16.9548 4.40831 16.0659 4.55646 15.2017C4.58115 15.2264 4.63054 15.2511 4.67992 15.2758L8.65523 17.572C8.85276 17.6955 9.09967 17.6955 9.2972 17.572L14.1614 14.7572V16.7079C14.1614 16.7325 14.1614 16.7572 14.1367 16.7572L10.112 19.0782C8.33424 20.1153 6.03794 19.498 5.00091 17.7202ZM3.96387 9.02884C4.40831 8.26341 5.09967 7.69551 5.91449 7.37452V12.1153C5.91449 12.3375 6.03794 12.5597 6.23548 12.6832L11.0997 15.498L9.42066 16.4609C9.39597 16.4609 9.37128 16.4856 9.37128 16.4609L5.34659 14.1399C3.51943 13.1029 2.92683 10.8066 3.96387 9.02884ZM17.791 12.2387L12.9268 9.4239L14.6058 8.46094C14.6305 8.46094 14.6552 8.43625 14.6552 8.46094L18.6799 10.7819C20.4824 11.819 21.075 14.1153 20.0379 15.893C19.5935 16.6585 18.9021 17.2264 18.0873 17.5227V12.8066C18.112 12.5844 17.9886 12.3622 17.791 12.2387ZM19.4454 9.7202C19.4207 9.69551 19.3713 9.67081 19.3219 9.64612L15.3466 7.34983C15.1491 7.22637 14.9021 7.22637 14.7046 7.34983L9.84041 10.1646V8.21402C9.84041 8.18933 9.84041 8.16464 9.86511 8.16464L13.8898 5.84365C15.6923 4.80662 17.9639 5.4239 19.0009 7.22637C19.4454 7.96711 19.5935 8.856 19.4454 9.7202ZM8.92683 13.177L7.24782 12.214C7.22313 12.214 7.22313 12.1893 7.22313 12.1646V7.52267C7.22313 5.44859 8.90214 3.76958 10.9762 3.76958C11.8651 3.76958 12.7046 4.06588 13.3713 4.63378C13.3466 4.65847 13.2972 4.68316 13.2478 4.70785L9.27251 7.00415C9.07498 7.1276 8.95152 7.32514 8.95152 7.57205V13.177H8.92683ZM9.84041 11.2017L12.0133 9.94242L14.1861 11.2017V13.6955L12.0133 14.9548L9.84041 13.6955V11.2017Z" fill="currentColor"/></svg>} href="/integrations/codex">
+    Add Mem0 memory to OpenAI Codex workflows
+  </Card>
+</CardGroup>

docs/integrations/codex.mdx

@@ -0,0 +1,212 @@
+---
+title: Codex
+description: "Add persistent memory to OpenAI Codex with the Mem0 plugin — MCP server, memory protocol skill, and plugin marketplace support."
+---
+
+Add persistent memory to [**OpenAI Codex**](https://openai.com/index/codex/) with the Mem0 plugin. Codex forgets everything between tasks — this plugin fixes that by connecting to Mem0's cloud memory layer via MCP and using a skill-based memory protocol to automatically retrieve context and store learnings.
+
+## Overview
+
+1. **MCP Server** — Connect to Mem0's remote MCP server for memory tools (add, search, update, delete)
+2. **Memory Protocol Skill** — Instructs the agent to retrieve memories at task start, store learnings on completion, and capture session state before context loss
+3. **Plugin Marketplace** — Install via Codex's repo-level or personal plugin marketplace
+4. **Zero local dependencies** — Cloud-hosted MCP server, no local setup required
+
+## Prerequisites
+
+Before setting up Mem0 with Codex, ensure you have:
+
+1. A Mem0 Platform account and API key:
+   - <a href="https://app.mem0.ai" rel="nofollow">Sign up at app.mem0.ai</a>
+   - <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">Get your API key</a> (starts with `m0-`)
+
+2. OpenAI Codex access
+
+3. Your API key exported in your shell:
+
+```bash
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+## Installation
+
+### Option A — Repo Marketplace (Recommended for Teams)
+
+Add a `.agents/plugins/marketplace.json` to your repository root:
+
+```json
+{
+  "name": "mem0-plugins",
+  "interface": {
+    "displayName": "Mem0 Plugins"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": {
+        "source": "local",
+        "path": "./plugins/mem0"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+Then in Codex, browse the repo's plugin directory and install Mem0.
+
+### Option B — Personal Marketplace
+
+Add to `~/.agents/plugins/marketplace.json`:
+
+```json
+{
+  "name": "mem0-plugins",
+  "interface": {
+    "displayName": "Mem0 Plugins"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": {
+        "source": "local",
+        "path": "/path/to/mem0-plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+### Option C — Manual MCP Configuration
+
+Add to your Codex MCP config:
+
+```json
+{
+  "mcpServers": {
+    "mem0": {
+      "type": "http",
+      "url": "https://mcp.mem0.ai/mcp/",
+      "headers": {
+        "Authorization": "Token ${MEM0_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+<Info icon="check">
+  Start a new Codex task and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set.
+</Info>
+
+## What's Included
+
+| Component | Plugin Install | MCP Only |
+|-----------|:--------------:|:--------:|
+| MCP Server (9 memory tools) | Yes | Yes |
+| Memory Protocol Skill | Yes | No |
+| Mem0 SDK Skill | Yes | No |
+
+## Available MCP Tools
+
+Once installed, the following tools are available in every Codex session:
+
+| Tool | Description |
+|------|-------------|
+| `add_memory` | Save text or conversation history for a user/agent |
+| `search_memories` | Semantic search across memories with filters |
+| `get_memories` | List memories with filters and pagination |
+| `get_memory` | Retrieve a specific memory by ID |
+| `update_memory` | Overwrite a memory's text by ID |
+| `delete_memory` | Delete a single memory by ID |
+| `delete_all_memories` | Bulk delete all memories in scope |
+| `delete_entities` | Delete a user/agent/app/run entity and its memories |
+| `list_entities` | List users/agents/apps/runs stored in Mem0 |
+
+## Memory Protocol Skill
+
+Codex uses a skill-based approach instead of lifecycle hooks. When installed via the plugin marketplace, the memory protocol skill instructs the agent to:
+
+### On Every New Task
+1. Call `search_memories` with a query related to the current task to load relevant context
+2. Review returned memories to understand what was learned in prior sessions
+3. Optionally call `get_memories` to browse all stored memories
+
+### After Completing Significant Work
+Store key learnings using `add_memory` with structured metadata:
+
+| What to store | Metadata type |
+|--------------|---------------|
+| Architectural decisions | `{"type": "decision"}` |
+| Strategies that worked | `{"type": "task_learning"}` |
+| Failed approaches | `{"type": "anti_pattern"}` |
+| User preferences observed | `{"type": "user_preference"}` |
+| Environment discoveries | `{"type": "environmental"}` |
+| Conventions established | `{"type": "convention"}` |
+
+### Before Losing Context
+Store a comprehensive session summary including goals, accomplishments, decisions, files modified, and current state with metadata `{"type": "session_state"}`.
+
+## Plugin Manifest
+
+The Codex plugin manifest (`.codex-plugin/plugin.json`) follows the Codex plugin specification:
+
+```json
+{
+  "name": "mem0",
+  "version": "0.1.0",
+  "description": "Mem0 memory layer for AI applications.",
+  "skills": "./skills/",
+  "mcpServers": "./.codex-mcp.json",
+  "interface": {
+    "displayName": "Mem0",
+    "shortDescription": "Persistent memory layer for AI coding workflows",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"]
+  }
+}
+```
+
+## Example Workflow
+
+```text
+# Task 1: Setting up a new service
+You: Create a REST API for the notifications service using Express and TypeScript.
+
+# Codex searches memories, finds user preferences from prior tasks.
+# After completing the task, Mem0 stores:
+#   - Decision: "Notifications service uses Express + TypeScript + Zod validation"
+#   - Convention: "All API routes follow /api/v1/{resource} pattern"
+#   - Preference: "User prefers explicit error types over generic catch-all"
+
+# Task 2 (days later): Extending the service
+You: Add WebSocket support for real-time notification delivery.
+
+# Codex searches memories, retrieves the architecture decisions and conventions.
+# Follows the same patterns established in the first task.
+```
+
+## Troubleshooting
+
+- **"Connection failed"** — Verify `MEM0_API_KEY` is set in your shell: `echo $MEM0_API_KEY`
+- **No tools appearing** — Restart your Codex session after plugin installation
+- **Plugin not found** — Ensure `.agents/plugins/marketplace.json` is at the repository root and `source.path` points to the correct plugin directory
+- **Skills not loading** — Verify the `skills` field in `plugin.json` points to a valid directory containing `SKILL.md` files
+
+<CardGroup cols={2}>
+  <Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">
+    Detailed MCP configuration for all clients
+  </Card>
+  <Card title="Claude Code Integration" icon={<svg width="24" height="25" viewBox="0 0 24 25" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M5.92888 16.2181L9.86008 14.0122L9.92585 13.8199L9.86008 13.7137H9.66782L9.01009 13.6732L6.76369 13.6125L4.81581 13.5315L2.92863 13.4303L2.45304 13.3292L2.00781 12.7423L2.05335 12.4488L2.45304 12.1807L3.02476 12.2313L4.28962 12.3173L6.18692 12.4488L7.56309 12.5298L9.60204 12.7423H9.92585L9.97138 12.6107L9.86008 12.5298L9.77407 12.4488L7.811 11.1182L5.68603 9.71165L4.57295 8.90214L3.97088 8.49233L3.66731 8.10781L3.53577 7.26794L4.08219 6.66587L4.81581 6.71646L5.00301 6.76706L5.74674 7.33877L7.33541 8.56822L9.40979 10.0962L9.71335 10.3491L9.83478 10.2631L9.84996 10.2024L9.71335 9.97475L8.5851 7.93579L7.38095 5.86141L6.84465 5.00131L6.70298 4.48524C6.65239 4.27275 6.61697 4.09567 6.61697 3.87811L7.23928 3.03318L7.58332 2.92188L8.41307 3.03318L8.76218 3.33675L9.27824 4.5156L10.113 6.37242L11.4083 8.89708L11.7877 9.64588L11.9901 10.339L12.066 10.5515H12.1975V10.4301L12.3038 9.00839L12.5011 7.26288L12.6934 5.01649L12.7591 4.38406L13.0728 3.62514L13.6951 3.21532L14.1808 3.44806L14.5805 4.01978L14.5249 4.38912L14.2871 5.93225L13.8216 8.35066L13.5181 9.96969H13.6951L13.8975 9.76731L14.7171 8.67953L16.0933 6.95931L16.7005 6.27629L17.4088 5.52243L17.8641 5.16321H18.7242L19.3567 6.10427L19.0733 7.07568L18.1879 8.19888L17.4543 9.15006L16.4019 10.5667L15.7442 11.7L15.8049 11.7911L15.9618 11.7759L18.3397 11.27L19.6248 11.0372L21.1578 10.7741L21.851 11.0979L21.9269 11.4268L21.6537 12.0997L20.0144 12.5045L18.0918 12.889L15.2282 13.567L15.1927 13.5923L15.2332 13.6428L16.5234 13.7643L17.0749 13.7946H18.4257L20.9403 13.9818L21.598 14.4169L21.9926 14.9482L21.9269 15.3529L20.915 15.869L19.5489 15.5452L16.3615 14.7863L15.2686 14.5131H15.1168V14.6041L16.0275 15.4946L17.6972 17.0023L19.7867 18.9451L19.893 19.4258L19.6248 19.8053L19.3415 19.7648L17.5049 18.3835L16.7966 17.7612L15.1927 16.4104H15.0865V16.552L15.4558 17.0934L17.4088 20.0279L17.51 20.9285L17.3683 21.2219L16.8624 21.399L16.3058 21.2978L15.1624 19.6939L13.9835 17.8877L13.0324 16.2687L12.916 16.3345L12.3544 22.3805L12.0913 22.6891L11.4842 22.9219L10.9782 22.5374L10.7101 21.915L10.9782 20.6856L11.302 19.0818L11.5651 17.8068L11.8029 16.2232L11.9446 15.697L11.9345 15.6616L11.8181 15.6767L10.6241 17.316L8.80771 19.7698L7.37083 21.3079L7.02679 21.4445L6.42977 21.1359L6.48542 20.5844L6.81935 20.0936L8.80771 17.5639L10.0068 15.9955L10.7809 15.0898L10.7758 14.9583H10.7303L5.44824 18.3886L4.50718 18.51L4.10242 18.1306L4.15302 17.5083L4.34528 17.3059L5.93394 16.213L5.92888 16.2181Z" fill="currentColor"/></svg>} href="/integrations/claude-code">
+    Add Mem0 memory to Claude Code workflows
+  </Card>
+</CardGroup>