refactor(opencode): native SDK tools, drop MCP, trim skills, expand telemetry

Reworks @mem0/opencode-plugin to expose memory operations as native OpenCode
tools (via the @opencode-ai/plugin `tool()` helper, backed by the mem0ai SDK)
instead of delegating to the remote MCP server. Skills load via the `config`
hook (`skills.paths`) instead of being copied into the project `.opencode/`.

- Drop MCP: remove the regex-based MCP tool interception, the bundled
  opencode.json MCP registration, and the cli.ts installer (mem0-opencode bin).
- Native tools: add_memory, search_memories, get_memories, get_memory,
  update_memory, delete_memory, delete_all_memories, delete_entities,
  list_entities, get_event_status.
- Trim skills 16 -> 8 (context-loader, dream, forget, health, peek, pin,
  remember, tour); remove import, export, memory-reviewer, mem0, list-projects,
  switch-project, stats, onboard. De-MCP/onboard wording in kept skills.
- Telemetry: emit the full shared plugin.* schema (adds user_prompt, bash_error,
  pre_compact, session_stop alongside session_start, tool_use); tool_use now
  fires from inside each native tool; add project_hash + os_version props.
- Fix duplicate error-search (single topK:6); correct the documented
  experimental.chat.messages.transform hook name.
- Bump to 0.2.0.

.agents/plugins/marketplace.json

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

.claude-plugin/marketplace.json

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

.codex-plugin/marketplace.json

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

.cursor-plugin/marketplace.json

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

.github/workflows/cd.yml

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

.github/workflows/ci-gate.yml

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

.github/workflows/ci.yml

@@ -1,9 +1,11 @@
 name: ci
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main runs remain standalone.
 on:
   push:
     branches: [main]
-  pull_request:
+  workflow_call:
 
 jobs:
   changelog_check:

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

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

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

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

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

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

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

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

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

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

.github/workflows/openclaw-cd.yml

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

.github/workflows/openclaw-checks.yml

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

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

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

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

@@ -1,23 +1,22 @@
 name: opencode-plugin checks
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
     branches: [main]
     paths:
-      - 'mem0-plugin/.opencode-plugin/**'
-      - '.github/workflows/opencode-plugin-checks.yml'
-  pull_request:
-    paths:
-      - 'mem0-plugin/.opencode-plugin/**'
+      - 'integrations/mem0-plugin/.opencode-plugin/**'
       - '.github/workflows/opencode-plugin-checks.yml'
+  workflow_call:
 
 jobs:
   build:
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: mem0-plugin/.opencode-plugin
+        working-directory: integrations/mem0-plugin/.opencode-plugin
     steps:
       - uses: actions/checkout@v4
 

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

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

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

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

.github/workflows/release.yml

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

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

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

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

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

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

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

.gitmodules

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

AGENTS.md

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

LLM.md

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

README.md

@@ -186,9 +186,10 @@ npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk
 ```bash
 npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
 npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform
 ```
 
-Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture.
+Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. Use `/mem0-oss-to-platform` to migrate an existing project from Mem0 OSS to the hosted Platform SDK. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture.
 
 ### Basic Usage
 

cli/node/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to `@mem0/cli` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.8] — 2026-06-01
+
+### Security
+
+- Pinned transitive dependencies via pnpm overrides to remediate high-severity CVEs:
+  - `jws` → 4.0.1 (CVE-2025-65945)
+  - `langsmith` → ^0.6.0 (CVE-2026-45134)
+  - `tar-fs` → ^2.1.4 (CVE-2025-48387, CVE-2025-59343)
+  - `picomatch` → ^2.3.2 (CVE-2026-33671)
+  - `minimatch` → ^3.1.3 / ^5.1.8 / ^9.0.7 (CVE-2026-27903, CVE-2026-27904, CVE-2026-26996)
+  - `path-to-regexp` → ^8.4.0 (CVE-2026-4926)
+  - `rollup` → ^4.59.0 (CVE-2026-27606)
+  - `glob` → ^10.5.0 (CVE-2025-64756)
+  - `@modelcontextprotocol/sdk` → ^1.25.4 (CVE-2025-66414, CVE-2026-0621)
+
 ## [0.2.7] — 2026-05-20
 
 ### Added

cli/node/package.json

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

cli/node/pnpm-workspace.yaml

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

cli/node/vitest.config.ts

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

cli/python/tests/test_agent_mode.py

@@ -32,12 +32,13 @@ def _run(args: list[str], home_dir: str | None = None) -> subprocess.CompletedPr
         if key.startswith("MEM0_"):
             del env[key]
     env.pop("FORCE_COLOR", None)
+    env["PYTHONIOENCODING"] = "utf-8"
     if home_dir:
         env["HOME"] = home_dir
     result = subprocess.run(
         [sys.executable, "-m", "mem0_cli", *args],
         capture_output=True,
-        text=True,
+        encoding="utf-8",
         env=env,
         timeout=15,
     )
@@ -99,12 +100,13 @@ class TestArgvPreprocessing:
         result = subprocess.run(
             [sys.executable, "-m", "mem0_cli", "init", "--agent"],
             capture_output=True,
-            text=True,
+            encoding="utf-8",
             env={
                 **{k: v for k, v in os.environ.items() if not k.startswith("MEM0_")},
                 "HOME": clean_home,
                 "MEM0_BASE_URL": "http://127.0.0.1:1",  # blackhole
                 "FORCE_COLOR": "0",
+                "PYTHONIOENCODING": "utf-8",
             },
             timeout=15,
         )
@@ -133,12 +135,13 @@ class TestJsonEnvelopeParity:
         result = subprocess.run(
             [sys.executable, "-m", "mem0_cli", "init", "--agent", "--json"],
             capture_output=True,
-            text=True,
+            encoding="utf-8",
             env={
                 **{k: v for k, v in os.environ.items() if not k.startswith("MEM0_")},
                 "HOME": clean_home,
                 "MEM0_BASE_URL": "http://127.0.0.1:1",
                 "FORCE_COLOR": "0",
+                "PYTHONIOENCODING": "utf-8",
             },
             timeout=15,
         )

cli/python/tests/test_cli_integration.py

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

cli/python/tests/test_commands.py

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

cli/python/tests/test_config.py

@@ -67,7 +67,8 @@ class TestConfig:
         from mem0_cli.config import CONFIG_FILE
 
         mode = os.stat(CONFIG_FILE).st_mode & 0o777
-        assert mode == 0o600
+        if os.name != "nt":
+            assert mode == 0o600
 
     def test_defaults_save_and_load(self, isolate_config):
         config = Mem0Config()

docs/changelog/openclaw.mdx

@@ -4,6 +4,39 @@ description: "Release notes for the OpenClaw plugin and agent harness."
 mode: "wide"
 ---
 
+<Update label="2026-06-12" description="v1.0.13">
+
+**Fixes:**
+- **Custom categories payload:** `customCategories` (a `Record<string, string>` map) is now converted via the new `customCategoryMapToList()` helper into the `Array<Record<string, string>>` shape the Mem0 SDK expects on `add` calls — previously the raw object was passed as `custom_categories` and silently ignored ([#5345](https://github.com/mem0ai/mem0/pull/5345))
+- **Skip runtime setup during metadata registration:** `register()` now detects `registrationMode === "cli-metadata"`, registers only the CLI commands, and returns early — avoiding backend initialization, service/tool registration, and hook installation during OpenClaw's metadata-only registration pass ([#5383](https://github.com/mem0ai/mem0/pull/5383))
+
+**Security:**
+- Bumped `mem0ai` from `3.0.3` to `3.0.7` (latest Node SDK) — includes the transitive axios CVE remediation shipped in `3.0.6` ([#5460](https://github.com/mem0ai/mem0/pull/5460))
+- Added pnpm override `uuid@<11.1.1` → `>=11.1.1` to resolve an open MEDIUM Dependabot alert ([#5489](https://github.com/mem0ai/mem0/pull/5489))
+
+**Improvements:**
+- **Repo consolidation:** Plugin moved from repo-root `openclaw/` to `integrations/openclaw/`; `package.json` `repository.directory` updated to match so npm provenance links to the correct subdirectory ([#5491](https://github.com/mem0ai/mem0/pull/5491))
+
+**Tests:**
+- Added `customCategoryMapToList` unit tests and a `PlatformProvider` test asserting `custom_categories` is passed to the Mem0 SDK as a list ([#5345](https://github.com/mem0ai/mem0/pull/5345))
+- Added a regression test asserting `cli-metadata` registration registers only CLI commands and triggers no runtime side effects ([#5383](https://github.com/mem0ai/mem0/pull/5383))
+
+</Update>
+
+<Update label="2026-06-02" description="v1.0.12">
+
+**Docs:**
+- **Agent Mode onboarding:** README now documents an autonomous setup path for AI agents — `mem0 init --agent --json` mints an evaluation Mem0 API key with no email, OTP, or browser and exports it as `MEM0_API_KEY` for `openclaw mem0 init`; a human owner can later run `mem0 init --email <email>` to claim ownership without disrupting the agent ([#5123](https://github.com/mem0ai/mem0/pull/5123))
+
+**Security:**
+- Added pnpm overrides to remediate advisories in transitive dependencies: `langsmith@<0.6.0` → `^0.6.0`, `picomatch@<2.3.2` → `^2.3.2`, `vite` → `^8.0.5`, and `@qdrant/js-client-rest` → `^1.18.0` ([#5294](https://github.com/mem0ai/mem0/pull/5294))
+
+**Dependencies:**
+- Bumped `mem0ai` from `3.0.2` to `3.0.3` ([#5212](https://github.com/mem0ai/mem0/pull/5212))
+- Bumped dev dependencies `@vitest/coverage-v8` and `vitest` from `^4.0.18` to `^4.1.7`; added `vite@^8.0.5` and `@qdrant/js-client-rest@^1.18.0` ([#5294](https://github.com/mem0ai/mem0/pull/5294))
+
+</Update>
+
 <Update label="2026-04-29" description="v1.0.11">
 
 **New Features:**

docs/changelog/sdk.mdx

@@ -7,6 +7,42 @@ mode: "wide"
 <Tabs>
 <Tab title="Python">
 
+<Update label="2026-06-13" description="v2.0.6">
+
+**New Features:**
+- **Memory:** Add a contextual OSS-to-Platform notices system that surfaces occasional, situation-aware messages (first run, scale/performance thresholds, slow queries, and when temporal/decay features are relevant) pointing to the corresponding Mem0 Platform capabilities; disable via `MEM0_TELEMETRY=false` ([#5494](https://github.com/mem0ai/mem0/pull/5494))
+
+**Bug Fixes:**
+- **Memory:** Prevent a crash in `parse_vision_messages` when vision support is disabled ([#5487](https://github.com/mem0ai/mem0/pull/5487))
+- **Vector Stores:** Expose the `https` option on the Qdrant vector store configuration so TLS endpoints can be targeted explicitly ([#5380](https://github.com/mem0ai/mem0/pull/5380))
+- **Vector Stores:** Use valid S3 Vectors entity index names, fixing index operations that failed on invalid names ([#5416](https://github.com/mem0ai/mem0/pull/5416))
+- **Vector Stores:** Fix `search()` crashing with a `TypeError` in the LangChain vector store when a result score is `None` ([#5072](https://github.com/mem0ai/mem0/pull/5072))
+- **Vector Stores:** Use `is not None` instead of a truthiness check for vector/payload in the PGVector `update()` path, so valid empty/zero values are no longer skipped ([#5488](https://github.com/mem0ai/mem0/pull/5488))
+- **Vector Stores:** Index the Valkey `memory` field as `TEXT` rather than `TAG` so full-text search behaves correctly ([#5443](https://github.com/mem0ai/mem0/pull/5443))
+- **Vector Stores:** Implement `$not` filter support in the ChromaDB vector store ([#5485](https://github.com/mem0ai/mem0/pull/5485))
+
+</Update>
+
+<Update label="2026-06-10" description="v2.0.5">
+
+**New Features:**
+- **Memory:** Warn at init time when hybrid/BM25 search silently degrades to semantic-only because the configured vector store does not implement `keyword_search`. Affected stores: Chroma, FAISS, Cassandra, LangChain, Neptune Analytics, S3 Vectors, Supabase, TurboPuffer, Valkey ([#5444](https://github.com/mem0ai/mem0/pull/5444))
+- **Memory:** Add opt-in `explain=True` parameter to `Memory.search()` and `AsyncMemory.search()`. When enabled, each result includes a `score_breakdown` dict with `semantic`, `keyword` (normalized BM25), `entity_boost`, and `temporal_boost` signals so callers can understand and tune retrieval ranking ([#5102](https://github.com/mem0ai/mem0/pull/5102))
+
+**Bug Fixes:**
+- **Vector Stores:** Normalize similarity scores to `[0, 1]` (higher = better) consistently across all backends. 11 adapters previously returned raw distance metrics (lower = better) — FAISS, Chroma, Milvus, Redis, Cassandra, PGVector, S3 Vectors, Supabase, Valkey, Azure MySQL, and Vertex AI Vector Search — causing incorrect ranking in multi-store setups ([#5391](https://github.com/mem0ai/mem0/pull/5391))
+- **Memory:** Parallelize entity boost searches in `Memory.search()` and `AsyncMemory.search()`. Previously up to 8 entities were embedded and queried sequentially (16 serial round-trips with remote embedders); all entity lookups now run concurrently, eliminating multi-second latency on entity-rich queries ([#5377](https://github.com/mem0ai/mem0/pull/5377))
+- **Memory:** Reject empty or whitespace-only queries in `Memory.search()`, `AsyncMemory.search()`, `MemoryClient.search()`, and `AsyncMemoryClient.search()` before any embedding or API call is made. Also strips leading/trailing whitespace from valid queries ([#5258](https://github.com/mem0ai/mem0/pull/5258))
+- **LLMs:** Add `is_reasoning_model: Optional[bool]` override to `BaseLlmConfig` (surfaced on `OpenAILlmConfig` and `AzureOpenAILlmConfig`). Fixes silent zero-extraction when using Azure deployments with versioned `gpt-5.x` names that the automatic name-based heuristic cannot recognize ([#5327](https://github.com/mem0ai/mem0/pull/5327))
+- **LLMs:** Fix xAI LLM provider: add `XAIConfig` with `xai_base_url`, forward `tools`/`tool_choice` in `generate_response()`, and parse `tool_calls` in the response. Previously the provider raised `AttributeError` at init and silently dropped tool results ([#5190](https://github.com/mem0ai/mem0/pull/5190))
+- **Vector Stores:** Fix PGVector `ConnectionPool` hang in Docker Compose environments where the app container starts before Postgres is DNS-resolvable — switched to `open=False` to avoid blocking constructor or silent zombie pool ([#5155](https://github.com/mem0ai/mem0/pull/5155))
+- **Vector Stores:** Fix PGVector `sslmode` handling for PostgreSQL URIs — the `sslmode` query parameter is now correctly extracted and forwarded when building the async connection pool ([#5308](https://github.com/mem0ai/mem0/pull/5308))
+- **Vector Stores:** Fix S3 Vectors `list()` not applying metadata filters — filtering is now done client-side after fetching, with pagination preserved and `top_k` applied after filtering to prevent pre-truncation of matching rows ([#5018](https://github.com/mem0ai/mem0/pull/5018))
+- **Vector Stores:** Fix Upstash Vector `search()` routing all queries to the default namespace — `namespace` is now passed as a top-level keyword argument to `query_many()` instead of inside the per-query dict where it was silently ignored ([#5202](https://github.com/mem0ai/mem0/pull/5202))
+- **Core:** Replace mutable default arguments with `None` sentinels in embedder configs and the proxy module, preventing cross-request state contamination ([#5302](https://github.com/mem0ai/mem0/pull/5302))
+
+</Update>
+
 <Update label="2026-05-27" description="v2.0.4">
 
 **New Features:**
@@ -939,6 +975,38 @@ See the [OSS v1 to v2 migration guide](https://docs.mem0.ai/migration/oss-v1-to-
 </Tab>
 
 <Tab title="TypeScript">
+
+<Update label="2026-06-13" description="v3.0.8">
+
+**New Features:**
+- **Memory:** Add a contextual OSS-to-Platform notices system that surfaces occasional, situation-aware messages (first run, scale/performance thresholds, slow queries, and when temporal/decay features are relevant) pointing to the corresponding Mem0 Platform capabilities; disable via `MEM0_TELEMETRY=false` ([#5494](https://github.com/mem0ai/mem0/pull/5494))
+
+**Security:**
+- **Dependencies:** Upgrade `@langchain/community` to `^1.1.18` to remediate CVE-2026-27795 and CVE-2026-26019 ([#5510](https://github.com/mem0ai/mem0/pull/5510))
+- **Dependencies:** Resolve all open MEDIUM Dependabot alerts via pnpm overrides ([#5489](https://github.com/mem0ai/mem0/pull/5489))
+
+</Update>
+
+<Update label="2026-06-10" description="v3.0.7">
+
+**New Features:**
+- **Embeddings:** Add `LMStudioEmbedding` provider for local embeddings via the LM Studio server ([#5377](https://github.com/mem0ai/mem0/pull/5377))
+- **Memory:** Add opt-in `explain: true` option to `Memory.search()`. When enabled, each result includes a `scoreBreakdown` object with `semantic`, `keyword`, `entityBoost`, and `temporalBoost` fields so callers can inspect and tune retrieval ranking ([#5102](https://github.com/mem0ai/mem0/pull/5102))
+
+**Bug Fixes:**
+- **Memory:** Parallelize entity boost searches in `Memory.search()`. All entity embed + store lookups now run concurrently instead of sequentially, eliminating multi-second latency on entity-rich queries with remote embedding providers ([#5377](https://github.com/mem0ai/mem0/pull/5377))
+- **Vector Stores:** Normalize similarity scores to `[0, 1]` (higher = better) — fixed score inversion in the Redis vector store adapter ([#5391](https://github.com/mem0ai/mem0/pull/5391))
+- **Embeddings:** Request `encoding_format: "float"` from the OpenAI embedder in both `embed()` and `embedBatch()`. Fixes incorrect vector dimensions when using OpenAI-compatible proxies that default to base64 encoding ([#5170](https://github.com/mem0ai/mem0/pull/5170))
+
+</Update>
+
+<Update label="2026-06-01" description="v3.0.6">
+
+**Security:**
+- **Dependencies:** Bumped `axios` to `^1.16.0` to remediate high-severity prototype-pollution CVEs (credential theft, MITM, DoS). Pinned transitive dependencies via pnpm overrides: `jws` → 4.0.1 (CVE-2025-65945), `langsmith` → ^0.6.0 (CVE-2026-45134), `tar-fs` → ^2.1.4 (CVE-2025-48387, CVE-2025-59343), `picomatch` → ^2.3.2 (CVE-2026-33671), `minimatch` → ^3.1.3 / ^5.1.8 / ^9.0.7 (CVE-2026-27903, CVE-2026-27904, CVE-2026-26996), `path-to-regexp` → ^8.4.0 (CVE-2026-4926), `rollup` → ^4.59.0 (CVE-2026-27606), `glob` → ^10.5.0 (CVE-2025-64756), `@modelcontextprotocol/sdk` → ^1.25.4 (CVE-2025-66414, CVE-2026-0621)
+
+</Update>
+
 <Update label="2026-05-27" description="v3.0.5">
 
 **New Features:**
@@ -1352,6 +1420,13 @@ See the [TypeScript SDK migration guide](https://docs.mem0.ai/migration/ts-v2-to
 
 <Tab title="CLI">
 
+<Update label="2026-06-01" description="Node v0.2.8">
+
+**Security:**
+- **Dependencies:** Pinned transitive dependencies via pnpm overrides to remediate high-severity CVEs: `jws` → 4.0.1 (CVE-2025-65945), `langsmith` → ^0.6.0 (CVE-2026-45134), `tar-fs` → ^2.1.4 (CVE-2025-48387, CVE-2025-59343), `picomatch` → ^2.3.2 (CVE-2026-33671), `minimatch` → ^3.1.3 / ^5.1.8 / ^9.0.7 (CVE-2026-27903, CVE-2026-27904, CVE-2026-26996), `path-to-regexp` → ^8.4.0 (CVE-2026-4926), `rollup` → ^4.59.0 (CVE-2026-27606), `glob` → ^10.5.0 (CVE-2025-64756), `@modelcontextprotocol/sdk` → ^1.25.4 (CVE-2025-66414, CVE-2026-0621)
+
+</Update>
+
 <Update label="2026-05-16" description="Python v0.2.6 / Node v0.2.6">
 
 **Bug Fixes:**
@@ -1468,6 +1543,43 @@ A full-featured command-line interface for Mem0, available in both Python and No
 
 <Tab title="Plugins">
 
+<Update label="2026-06-01" description="openclaw-mem0 v1.0.12">
+
+**Security:**
+- **Dependencies:** Pinned transitive dependencies via pnpm overrides to remediate high-severity CVEs: `protobufjs` → ^7.5.5, `vite` → ^8.0.5, `langsmith` → ^0.6.0 (CVE-2026-45134), `picomatch` → ^2.3.2 (CVE-2026-33671), `@qdrant/js-client-rest` → ^1.18.0
+
+</Update>
+
+<Update label="2026-06-10" description="Vercel AI SDK v3.0.0">
+
+**Major Release** — Migrated to Vercel AI SDK v6 (`LanguageModelV3` / `ProviderV3`) and Mem0 v3 API.
+
+**Breaking Changes:**
+- **AI SDK v6:** Upgraded from AI SDK v5 (`LanguageModelV2`) to v6 (`LanguageModelV3`). Users must upgrade `ai` to `^6.0.199` and all `@ai-sdk/*` provider packages to `^3.x` ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Mem0 v3 API:** Memory endpoints migrated from `/v1/memories/` and `/v2/memories/search/` to `/v3/memories/add/` and `/v3/memories/search/`. Entity IDs (`user_id`, `agent_id`, `run_id`) now go inside the `filters` object for search requests ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Graph memory removed:** All `enable_graph`, graph prompts, and relation-extraction code removed. Graph memory is now a project-level setting on the Platform ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Deprecated params removed:** `org_id`, `project_id`, `org_name`, `project_name`, `output_format`, `filter_memories`, `async_mode`, `enable_graph`, `version`, `api_version` removed from `Mem0ConfigSettings` ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+
+**New Features:**
+- **V3 provider contract:** `specificationVersion: 'v3'`, `supportedUrls` property, V3 content array in `doGenerate`, V3 stream lifecycle events in `doStream` ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Mem0 source in responses:** Memories are attached as a `source` in `generateText`/`streamText` responses with `providerMetadata.mem0.memories` for programmatic access ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+
+**Bug Fixes:**
+- **Async memory storage:** `addMemories` is now properly `await`ed — memories no longer silently fail to store ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Prompt mutation:** Prompt array is now cloned before injecting memory context, preventing side effects on the caller's array ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Null guard on content:** `doGenerate` guards against null `content` from upstream providers ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Stream response:** `doStream` now returns the full `LanguageModelV3StreamResult` object preserving all V3 fields ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+- **Response normalization:** `getMemories` and `retrieveMemories` now handle both array and `{results: [...]}` envelope responses from the v3 API ([#4741](https://github.com/mem0ai/mem0/pull/4741))
+
+</Update>
+
+<Update label="2026-06-01" description="Vercel AI SDK v2.0.6">
+
+**Security:**
+- **Dependencies:** Pinned transitive dependencies via pnpm overrides to remediate high-severity CVEs: `glob` → ^10.5.0 (CVE-2025-64756), `minimatch` → ^3.1.3 / ^5.1.8 / ^9.0.7 (CVE-2026-27903, CVE-2026-27904, CVE-2026-26996), `picomatch` → ^2.3.2 (CVE-2026-33671), `rollup` → ^4.59.0 (CVE-2026-27606)
+
+</Update>
+
 <Update label="2026-04-02" description="mem0-plugin v1.0.0">
 
 **Mem0 Plugin for Claude Code, Cursor, and Codex**

docs/components/vectordbs/dbs/neon.mdx

@@ -0,0 +1,156 @@
+---
+title: "Neon"
+description: "Use Neon as a vector store in Mem0, powered by PostgreSQL and pgvector."
+---
+
+Use [Neon](https://neon.com/) as a vector store in Mem0, powered by PostgreSQL and the
+[pgvector extension](https://neon.com/docs/extensions/pgvector).
+
+Neon is a serverless Postgres platform. Since Mem0 supports Postgres through the
+`pgvector` provider, Neon can be used with a standard Postgres connection string.
+
+## Usage
+
+<CodeGroup>
+```python Python
+import os
+
+from dotenv import load_dotenv
+from mem0 import Memory
+
+load_dotenv()
+
+config = {
+    "vector_store": {
+        "provider": "pgvector",
+        "config": {
+            "connection_string": os.environ["DATABASE_URL"],
+            "collection_name": "memories",
+            "embedding_model_dims": 1536,
+            "hnsw": True,
+        },
+    },
+}
+
+m = Memory.from_config(config)
+messages = [
+    {"role": "user", "content": "I'm planning to watch a movie tonight. Any recommendations?"},
+    {"role": "assistant", "content": "How about 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."},
+]
+m.add(messages, user_id="alice", metadata={"category": "movies"})
+
+results = m.search(
+    "What movies should I recommend?",
+    filters={"user_id": "alice"},
+)
+
+print(results)
+```
+
+```typescript TypeScript
+import "dotenv/config";
+import { Memory } from "mem0ai/oss";
+
+const databaseUrl = new URL(process.env.DATABASE_URL!);
+
+const m = new Memory({
+  vectorStore: {
+    provider: "pgvector",
+    config: {
+      user: decodeURIComponent(databaseUrl.username),
+      password: decodeURIComponent(databaseUrl.password),
+      host: databaseUrl.hostname,
+      port: Number(databaseUrl.port || 5432),
+      dbname: databaseUrl.pathname.slice(1) || "neondb",
+      collectionName: "memories",
+      dimension: 1536,
+      embeddingModelDims: 1536,
+      hnsw: true,
+    },
+  },
+});
+
+const messages = [
+  { role: "user" as const, content: "I'm planning to watch a movie tonight. Any recommendations?" },
+  { role: "assistant" as const, content: "How about thriller movies? They can be quite engaging." },
+  { role: "user" as const, content: "I'm not a big fan of thriller movies but I love sci-fi movies." },
+  { role: "assistant" as const, content: "Got it! I'll avoid thriller recommendations and suggest sci-fi movies in the future." },
+];
+
+await m.add(messages, {
+  userId: "alice",
+  metadata: { category: "movies" },
+});
+
+const results = await m.search("What movies should I recommend?", {
+  filters: { user_id: "alice" },
+});
+
+console.log(results);
+```
+</CodeGroup>
+
+## SQL Migration
+
+You don't need to run any SQL migrations. Mem0 creates the collection table when it initializes the `pgvector` store.
+
+## Environment
+
+```env
+OPENAI_API_KEY=sk-xx...
+DATABASE_URL=postgresql://user:password@ep-example.us-east-2.aws.neon.tech/neondb?sslmode=require
+```
+
+## Config
+
+<Tabs>
+<Tab title="Python">
+| Parameter | Description | Default Value |
+| --- | --- | --- |
+| `connection_string` | Neon Postgres connection string. | Required |
+| `collection_name` | Name for the vector collection. | `mem0` |
+| `embedding_model_dims` | Embedding model dimensions. | `1536` |
+| `hnsw` | Enables HNSW indexing. | `False` |
+| `sslmode` | PostgreSQL SSL mode. Use `require` for Neon. | Driver default |
+</Tab>
+<Tab title="TypeScript">
+The current Mem0 TypeScript `pgvector` adapter takes individual Postgres fields,
+so parse `DATABASE_URL` before creating `Memory`.
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| `user` | Database user. | Required |
+| `password` | Database password. | Required |
+| `host` | Database host. | Required |
+| `port` | Database port. | `5432` |
+| `dbname` | Database name. | `vector_store` |
+| `collectionName` | Name for the vector collection. | `memories` |
+| `dimension` | Vector dimension for Mem0 config. | Auto-detected |
+| `embeddingModelDims` | Embedding model dimensions for table creation. | Required |
+| `hnsw` | Enables HNSW indexing. | `false` |
+</Tab>
+</Tabs>
+
+### Indexing
+
+The `pgvector` provider can create an HNSW index for faster vector search.
+
+- Set `hnsw` to `true` to enable a Hierarchical Navigable Small World index.
+- Leave `hnsw` as `false` if you want to create or manage indexes yourself.
+
+### Similarity Search
+
+The `pgvector` provider uses cosine similarity for vector search. Make sure your
+embedding dimensions match the configured `embedding_model_dims` value.
+
+### Best Practices
+
+1. **Index Selection**:
+   - Use `hnsw` for faster search performance when memory usage is not a constraint
+   - Manage indexes manually if you need a different pgvector index strategy
+
+2. **Connection String**:
+   - Always use environment variables or even better, a secret manager for sensitive information in the connection string
+   - Format: `postgresql://user:password@host:port/database`

docs/components/vectordbs/dbs/qdrant.mdx

@@ -76,6 +76,7 @@ Let's see the available parameters for the `qdrant` config:
 | `path` | Path for the qdrant database | `/tmp/qdrant` |
 | `url` | Full URL for the qdrant server | `None` |
 | `api_key` | API key for the qdrant server | `None` |
+| `https` | Whether to force HTTPS on or off. `None` lets the client decide; set `False` for plain HTTP Qdrant with API key authentication. | `None` |
 | `on_disk` | For enabling persistent storage | `False` |
 </Tab>
 <Tab title="TypeScript">
@@ -90,4 +91,4 @@ Let's see the available parameters for the `qdrant` config:
 | `apiKey` | API key for the Qdrant server | `None` |
 | `onDisk` | For enabling persistent storage | `False` |
 </Tab>
-</Tabs>
+</Tabs>

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

@@ -156,6 +156,33 @@ const memories = memory.search("food preferences", {
   On Mem0 Platform v3, time-aware queries use Temporal Reasoning internally while preserving the normal search response shape. See <Link href="/platform/features/temporal-reasoning">Temporal Reasoning</Link>.
 </Note>
 
+### Explain OSS search scores
+
+OSS search combines semantic similarity with optional keyword and entity signals. Pass `explain=True` when tuning retrieval quality or debugging why a memory ranked where it did:
+
+<CodeGroup>
+```python Python
+results = m.search(
+    "food preferences",
+    filters={"user_id": "alice"},
+    explain=True,
+)
+
+print(results["results"][0]["score_details"])
+```
+
+```javascript JavaScript
+const results = await memory.search("food preferences", {
+    filters: { user_id: "alice" },
+    explain: true,
+});
+
+console.log(results.results[0].score_details);
+```
+</CodeGroup>
+
+Each result includes `score_details` with the semantic score, normalized BM25 score, entity boost, raw combined score, maximum possible score, final score, and threshold used for filtering. The field is omitted unless `explain` is enabled, so existing response shapes stay unchanged.
+
 ## Filter patterns
 
 Filters help narrow down search results. Common use cases:

docs/docs.json

@@ -143,7 +143,8 @@
                     "icon": "robot",
                     "pages": [
                       "integrations/openclaw",
-                      "integrations/hermes"
+                      "integrations/hermes",
+                      "integrations/pi-agent"
                     ]
                   }
                 ]
@@ -245,6 +246,7 @@
                               "components/vectordbs/dbs/cassandra",
                               "components/vectordbs/dbs/s3_vectors",
                               "components/vectordbs/dbs/databricks",
+                              "components/vectordbs/dbs/neon",
                               "components/vectordbs/dbs/neptune_analytics",
                               "components/vectordbs/dbs/turbopuffer"
                             ]
@@ -302,7 +304,8 @@
                     "group": "Migration",
                     "icon": "arrow-right",
                     "pages": [
-                      "migration/oss-v2-to-v3"
+                      "migration/oss-v2-to-v3",
+                      "migration/server-pgvector-upgrade"
                     ]
                   },
                   {
@@ -462,7 +465,8 @@
                     "icon": "robot",
                     "pages": [
                       "integrations/openclaw",
-                      "integrations/hermes"
+                      "integrations/hermes",
+                      "integrations/pi-agent"
                     ]
                   }
                 ]

docs/integrations/antigravity.mdx

@@ -28,7 +28,7 @@ echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc && source ~/.bashrc
 
 ```bash
 # Install the plugin (MCP server, hooks, scripts)
-npx degit mem0ai/mem0/mem0-plugin ~/.gemini/config/plugins/mem0
+npx degit mem0ai/mem0/integrations/mem0-plugin ~/.gemini/config/plugins/mem0
 ```
 
 This installs the MCP server, lifecycle hooks, and shared scripts.

docs/integrations/google-ai-adk.mdx

@@ -7,285 +7,338 @@ Integrate [**Mem0**](https://github.com/mem0ai/mem0) with [Google ADK (Agent Dev
 
 ## Overview
 
-1. Store and retrieve memories from Mem0 within Google ADK agents
-2. Multi-agent workflows with shared memory across hierarchies
-3. Retrieve relevant memories from past conversations
-4. Personalized responses based on user history
+In this guide, we'll create a Google ADK agent that:
+1. Uses ADK's native `MemoryService` interface to connect Mem0
+2. Automatically injects relevant memories using ADK's built-in `load_memory` tool
+3. Persists session history to Mem0 after each turn via an after-agent callback
+4. Shares memory seamlessly across multi-agent hierarchies
 
-## Prerequisites
+## Setup and Configuration
 
-Before setting up Mem0 with Google ADK, ensure you have:
+Install the necessary libraries:
 
-1. Installed the required packages:
 ```bash
 pip install google-adk mem0ai python-dotenv
 ```
 
-2. Valid API keys:
+Set up your API keys:
    - <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-google-ai-adk" rel="nofollow">Mem0 API Key</a>
    - Google AI Studio API Key
 
-## Basic Integration Example
-
-The following example demonstrates how to create a Google ADK agent with Mem0 memory integration:
+<Note>Remember to get your API key from <a href="https://app.mem0.ai" rel="nofollow">Mem0 Platform</a> and set up a [Google AI Studio API Key](https://aistudio.google.com/apikey).</Note>
 
 ```python
 import os
-import asyncio
-from google.adk.agents import Agent
-from google.adk.runners import Runner
-from google.adk.sessions import InMemorySessionService
-from google.genai import types
-from mem0 import MemoryClient
 from dotenv import load_dotenv
 
 load_dotenv()
 
-# Set up environment variables
 # os.environ["GOOGLE_API_KEY"] = "your-google-api-key"
 # os.environ["MEM0_API_KEY"] = "your-mem0-api-key"
+```
 
-# Initialize Mem0 client
-mem0 = MemoryClient()
+## Implement Mem0MemoryService
 
-# Define memory function tools
-def search_memory(query: str, user_id: str) -> dict:
-    """Search through past conversations and memories"""
-    # For Platform API, user_id goes in filters
-    filters = {"user_id": user_id}
-    memories = mem0.search(query, filters=filters)
-    if memories.get('results', []):
-        memory_list = memories['results']
-        memory_context = "\n".join([f"- {mem['memory']}" for mem in memory_list])
-        return {"status": "success", "memories": memory_context}
-    return {"status": "no_memories", "message": "No relevant memories found"}
+Create a custom `MemoryService` by implementing ADK's `BaseMemoryService`. Save the following as **`mem0_memory_service.py`**:
 
-def save_memory(content: str, user_id: str) -> dict:
-    """Save important information to memory"""
+```python
+import asyncio
+import os
+from typing import Optional
+from typing_extensions import override
+
+from google.adk.memory.base_memory_service import BaseMemoryService, SearchMemoryResponse
+from google.adk.memory.memory_entry import MemoryEntry
+from google.adk.sessions import Session
+from google.genai.types import Content, Part
+from mem0 import MemoryClient
+
+
+class Mem0MemoryService(BaseMemoryService):
+    """MemoryService implementation backed by the Mem0 Platform."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        super().__init__()
+        api_key = api_key or os.environ.get("MEM0_API_KEY")
+        self._client: Optional[MemoryClient] = MemoryClient(api_key=api_key) if api_key else None
+
+    @override
+    async def search_memory(
+        self, *, app_name: str, user_id: str, query: str
+    ) -> SearchMemoryResponse:
+        """Search for memories relevant to the current user and query."""
+        if not self._client:
+            return SearchMemoryResponse(memories=[])
+
+        try:
+            results = await asyncio.to_thread(
+                self._client.search,
+                query,
+                filters={"AND": [{"user_id": user_id}, {"app_id": app_name}]},
+                top_k=5,
+            )
+
+            entries = []
+            for mem in results.get("results", []):
+                text = mem.get("memory", "")
+                if not text:
+                    continue
+
+                raw_ts = mem.get("created_at") or mem.get("updated_at")
+                entries.append(
+                    MemoryEntry(
+                        content=Content(parts=[Part(text=text)]),
+                        author=mem.get("metadata", {}).get("author", "user"),
+                        timestamp=str(raw_ts) if raw_ts else None,
+                    )
+                )
+
+            return SearchMemoryResponse(memories=entries)
+
+        except Exception as e:
+            print(f"[Mem0MemoryService] search_memory error: {e}")
+            return SearchMemoryResponse(memories=[])
+
+    @override
+    async def add_session_to_memory(self, session: Session) -> None:
+        """Persist a completed ADK session into Mem0."""
+        if not self._client:
+            return
+
+        user_id = session.user_id
+        if not user_id:
+            return
+
+        app_name = getattr(session, "app_name", None)
+
+        try:
+            messages = []
+            for event in session.events:
+                if not (event.content and event.content.parts):
+                    continue
+                role = getattr(event.content, "role", None) or "user"
+                if role == "model":
+                    role = "assistant"
+                elif role not in ("user", "assistant"):
+                    continue
+                text_parts = [
+                    p.text for p in event.content.parts if hasattr(p, "text") and p.text
+                ]
+                if text_parts:
+                    messages.append({"role": role, "content": " ".join(text_parts)})
+
+            if messages:
+                metadata = {"app_id": app_name} if app_name else {}
+                await asyncio.to_thread(
+                    self._client.add, messages, user_id=user_id, metadata=metadata
+                )
+
+        except Exception as e:
+            print(f"[Mem0MemoryService] add_session_to_memory error: {e}")
+```
+
+## Add Auto-Save Callback
+
+This after-agent callback fires at the end of every turn and saves the session to Mem0. Save as **`memory_callbacks.py`**:
+
+```python
+async def save_session_to_memory(callback_context) -> None:
+    """Persist the completed session to Mem0 after each agent turn."""
     try:
-        result = mem0.add([{"role": "user", "content": content}], user_id=user_id)
-        return {"status": "success", "message": "Information saved to memory", "result": result}
+        await callback_context.add_session_to_memory()
+    except ValueError:
+        pass
     except Exception as e:
-        return {"status": "error", "message": f"Failed to save memory: {str(e)}"}
+        print(f"[save_session_to_memory] error: {e}")
+```
 
-# Create agent with memory capabilities
-personal_assistant = Agent(
+## Basic Integration Example
+
+The following example demonstrates creating an ADK agent with automatic Mem0 memory:
+
+```python
+import asyncio
+from google.adk.agents import LlmAgent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.adk.tools import load_memory
+from google.genai.types import Content, Part
+
+from mem0_memory_service import Mem0MemoryService
+from memory_callbacks import save_session_to_memory
+
+memory_service = Mem0MemoryService()
+session_service = InMemorySessionService()
+
+agent = LlmAgent(
     name="personal_assistant",
     model="gemini-2.0-flash",
-    instruction="""You are a helpful personal assistant with memory capabilities.
-    Use the search_memory function to recall past conversations and user preferences.
-    Use the save_memory function to store important information about the user.
-    Always personalize your responses based on available memory.""",
+    instruction="""You are a helpful personal assistant.
+    Relevant memories from past conversations are provided to you automatically.
+    Use them to personalize your responses.""",
     description="A personal assistant that remembers user preferences and past interactions",
-    tools=[search_memory, save_memory]
+    tools=[load_memory],
+    after_agent_callback=save_session_to_memory,
 )
 
-async def chat_with_agent(user_input: str, user_id: str) -> str:
-    """
-    Handle user input with automatic memory integration.
+runner = Runner(
+    agent=agent,
+    session_service=session_service,
+    memory_service=memory_service,
+    app_name="memory_assistant",
+)
 
-    Args:
-        user_input: The user's message
-        user_id: Unique identifier for the user
 
-    Returns:
-        The agent's response
-    """
-    # Set up session and runner
-    session_service = InMemorySessionService()
+async def chat(user_input: str, user_id: str) -> str:
     session = await session_service.create_session(
         app_name="memory_assistant",
         user_id=user_id,
-        session_id=f"session_{user_id}"
     )
-    runner = Runner(agent=personal_assistant, app_name="memory_assistant", session_service=session_service)
-
-    # Create content and run agent
-    content = types.Content(role='user', parts=[types.Part(text=user_input)])
-    events = runner.run(user_id=user_id, session_id=session.id, new_message=content)
-
-    # Extract final response
-    for event in events:
-        if event.is_final_response():
-            response = event.content.parts[0].text
-
-            return response
-
+    content = Content(role="user", parts=[Part(text=user_input)])
+    async for event in runner.run_async(user_id=user_id, session_id=session.id, new_message=content):
+        if event.is_final_response() and event.content and event.content.parts:
+            return event.content.parts[0].text
     return "No response generated"
 
-# Example usage
+
 if __name__ == "__main__":
-    response = asyncio.run(chat_with_agent(
+    print(asyncio.run(chat(
         "I love Italian food and I'm planning a trip to Rome next month",
-        user_id="alice"
-    ))
-    print(response)
+        user_id="alice",
+    )))
+
+    print(asyncio.run(chat(
+        "Any food recommendations for my trip?",
+        user_id="alice",
+    )))
 ```
 
 ## Multi-Agent Hierarchy with Shared Memory
 
-Create specialized agents in a hierarchy that share memory:
+Because `memory_service` is passed to the `Runner`, every agent in the hierarchy shares the same memory automatically. Only the root coordinator needs the auto-save callback — ADK fires it once when the full turn completes:
 
 ```python
+import asyncio
+from google.adk.agents import LlmAgent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
 from google.adk.tools.agent_tool import AgentTool
+from google.adk.tools import load_memory
+from google.genai.types import Content, Part
 
-# Travel specialist agent
-travel_agent = Agent(
+from mem0_memory_service import Mem0MemoryService
+from memory_callbacks import save_session_to_memory
+
+memory_service = Mem0MemoryService()
+session_service = InMemorySessionService()
+
+travel_agent = LlmAgent(
     name="travel_specialist",
     model="gemini-2.0-flash",
-    instruction="""You are a travel planning specialist. Use search_memory to
-    understand the user's travel preferences and history before making recommendations.
-    After providing advice, use save_memory to save travel-related information.""",
+    instruction="""You are a travel planning specialist.
+    Relevant memories about the user's travel preferences are provided automatically.
+    Use them to make personalized recommendations.""",
     description="Specialist in travel planning and recommendations",
-    tools=[search_memory, save_memory]
+    tools=[load_memory],
 )
 
-# Health advisor agent
-health_agent = Agent(
+health_agent = LlmAgent(
     name="health_advisor",
     model="gemini-2.0-flash",
-    instruction="""You are a health and wellness advisor. Use search_memory to
-    understand the user's health goals and dietary preferences.
-    After providing advice, use save_memory to save health-related information.""",
+    instruction="""You are a health and wellness advisor.
+    Relevant memories about the user's health goals are provided automatically.
+    Use them to give personalized advice.""",
     description="Specialist in health and wellness advice",
-    tools=[search_memory, save_memory]
+    tools=[load_memory],
 )
 
-# Coordinator agent that delegates to specialists
-coordinator_agent = Agent(
+coordinator = LlmAgent(
     name="coordinator",
     model="gemini-2.0-flash",
     instruction="""You are a coordinator that delegates requests to specialist agents.
-    For travel-related questions (trips, hotels, flights, destinations), delegate to the travel specialist.
-    For health-related questions (fitness, diet, wellness, exercise), delegate to the health advisor.
-    Use search_memory to understand the user before delegation.""",
+    For travel-related questions, delegate to the travel specialist.
+    For health-related questions, delegate to the health advisor.
+    Relevant memories about the user are provided automatically.""",
     description="Coordinates requests between specialist agents",
     tools=[
+        load_memory,
         AgentTool(agent=travel_agent, skip_summarization=False),
-        AgentTool(agent=health_agent, skip_summarization=False)
-    ]
+        AgentTool(agent=health_agent, skip_summarization=False),
+    ],
+    after_agent_callback=save_session_to_memory,
 )
 
-def chat_with_specialists(user_input: str, user_id: str) -> str:
-    """
-    Handle user input with specialist agent delegation and memory.
+runner = Runner(
+    agent=coordinator,
+    session_service=session_service,
+    memory_service=memory_service,
+    app_name="specialist_system",
+)
 
-    Args:
-        user_input: The user's message
-        user_id: Unique identifier for the user
 
-    Returns:
-        The specialist agent's response
-    """
-    session_service = InMemorySessionService()
-    session = session_service.create_session(
+async def chat_with_specialists(user_input: str, user_id: str) -> str:
+    session = await session_service.create_session(
         app_name="specialist_system",
         user_id=user_id,
-        session_id=f"session_{user_id}"
     )
-    runner = Runner(agent=coordinator_agent, app_name="specialist_system", session_service=session_service)
-
-    content = types.Content(role='user', parts=[types.Part(text=user_input)])
-    events = runner.run(user_id=user_id, session_id=session.id, new_message=content)
-
-    for event in events:
-        if event.is_final_response():
-            response = event.content.parts[0].text
-
-            # Store the conversation in shared memory
-            conversation = [
-                {"role": "user", "content": user_input},
-                {"role": "assistant", "content": response}
-            ]
-            mem0.add(conversation, user_id=user_id)
-
-            return response
-
+    content = Content(role="user", parts=[Part(text=user_input)])
+    async for event in runner.run_async(user_id=user_id, session_id=session.id, new_message=content):
+        if event.is_final_response() and event.content and event.content.parts:
+            return event.content.parts[0].text
     return "No response generated"
 
-# Example usage
-response = chat_with_specialists("Plan a healthy meal for my Italy trip", user_id="alice")
-print(response)
-```
-
-
-
-## Quick Start Chat Interface
-
-Simple interactive chat with memory and Google ADK:
-
-```python
-def interactive_chat():
-    """Interactive chat interface with memory and ADK"""
-    user_id = input("Enter your user ID: ") or "demo_user"
-    print(f"Chat started for user: {user_id}")
-    print("Type 'quit' to exit")
-    print("=" * 50)
-
-    while True:
-        user_input = input("\nYou: ")
-
-        if user_input.lower() == 'quit':
-            print("Goodbye! Your conversation has been saved to memory.")
-            break
-        else:
-            response = chat_with_specialists(user_input, user_id)
-            print(f"Assistant: {response}")
 
 if __name__ == "__main__":
-    interactive_chat()
+    response = asyncio.run(chat_with_specialists("Plan a healthy meal for my Italy trip", user_id="alice"))
+    print(response)
 ```
 
 ## Key Features
 
-### 1. Memory-Enhanced Function Tools
-- **Function Tools**: Standard Python functions that can search and save memories
-- **Tool Context**: Access to session state and memory through function parameters
-- **Structured Returns**: Dictionary-based returns with status indicators for better LLM understanding
-
-### 2. Multi-Agent Memory Sharing
-- **Agent-as-a-Tool**: Specialists can be called as tools while maintaining shared memory
-- **Hierarchical Delegation**: Coordinator agents route to specialists based on context
-- **Memory Categories**: Store interactions with metadata for better organization
-
-### 3. Flexible Memory Operations
-- **Search Capabilities**: Retrieve relevant memories through conversation history
-- **User Segmentation**: Organize memories by user ID
-- **Memory Management**: Built-in tools for saving and retrieving information
+1. **Automatic Memory Injection**: ADK's built-in `load_memory` tool searches Mem0 at the start of each turn and injects relevant memories directly into the agent context — no prompt instructions needed.
+2. **Automatic Session Saving**: The `save_session_to_memory` callback persists every completed turn to Mem0 without any manual calls.
+3. **Native ADK Integration**: `Mem0MemoryService` implements ADK's `BaseMemoryService` and integrates via the `Runner` — works natively across the entire agent hierarchy.
+4. **User Scoping**: `user_id` is passed automatically from the ADK session context, ensuring memories are always scoped to the correct user.
+5. **Multi-Agent Support**: A single `Mem0MemoryService` instance shared through the `Runner` gives all agents — coordinators and specialists — access to the same user memory.
 
 ## Configuration Options
 
-Customize memory behavior and agent setup:
+### Using Vertex AI
+
+To use Google Cloud Vertex AI instead of AI Studio, set the following environment variables before creating agents:
 
 ```python
-# Configure memory search with filters
-# For Platform API, all filters including user_id go in filters object
-memories = mem0.search(
-    query="travel preferences",
-    filters={
-        "AND": [
-            {"user_id": "alice"},
-            {"categories": {"contains": "travel"}}
-        ]
-    },
-    top_k=5
-)
-
-# Configure agent with custom model settings
-agent = Agent(
-    name="custom_agent",
-    model="gemini-2.0-flash",  # or use LiteLLM for other models
-    instruction="Custom agent behavior",
-    tools=[memory_tools],
-    # Additional ADK configurations
-)
-
-# Use Google Cloud Vertex AI instead of AI Studio
+import os
 os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
 os.environ["GOOGLE_CLOUD_PROJECT"] = "your-project-id"
 os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
 ```
 
+### Advanced Memory Filtering
+
+You can customize how memories are searched by modifying `Mem0MemoryService.search_memory`. For example, to filter by category:
+
+```python
+results = await asyncio.to_thread(
+    self._client.search,
+    query,
+    filters={
+        "AND": [
+            {"user_id": user_id},
+            {"app_id": app_name},
+            {"categories": {"contains": "travel"}}
+        ]
+    },
+    top_k=10,
+)
+```
+
+<Note>`InMemorySessionService` stores sessions in memory and is intended for prototyping. For production, use a persistent session service and clean up sessions when they are no longer needed.</Note>
+
+## Conclusion
+
+By implementing `Mem0MemoryService` as an ADK `BaseMemoryService`, you get persistent, user-scoped memory across single agents and complex multi-agent hierarchies with minimal code. Memory injection and session saving happen automatically, keeping your agent prompts clean and your token usage efficient.
+
 <CardGroup cols={2}>
   <Card title="Healthcare Agent Cookbook" icon="heart-pulse" href="/cookbooks/integrations/healthcare-google-adk">
     Build HIPAA-compliant healthcare agents with Google ADK
@@ -294,4 +347,3 @@ os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
     Compare with OpenAI's agent framework
   </Card>
 </CardGroup>
-

docs/integrations/opencode.mdx

@@ -1,6 +1,6 @@
 ---
 title: OpenCode
-description: "Add persistent memory to OpenCode with the Mem0 plugin — MCP server, lifecycle hooks, and slash commands."
+description: "Add persistent memory to OpenCode with the Mem0 plugin — native SDK-backed memory tools, lifecycle hooks, and skills."
 ---
 
 Add persistent memory to [**OpenCode**](https://opencode.ai) with the Mem0 plugin. Your agent forgets everything between sessions — Mem0 fixes that by storing decisions, preferences, and learnings so they carry over automatically.
@@ -30,27 +30,17 @@ echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc && source ~/.bashrc
 opencode plugin @mem0/opencode-plugin
 ```
 
-
-Or using this command which does the same thing:
-
-
-```bash
-bunx @mem0/opencode-plugin@latest install
-```
-
-
-
 **Or let your agent do it** — paste this into OpenCode:
 
 ```
-Install @mem0/opencode-plugin by following https://raw.githubusercontent.com/mem0ai/mem0/main/mem0-plugin/.opencode-plugin/README.md
+Install @mem0/opencode-plugin by following https://raw.githubusercontent.com/mem0ai/mem0/main/integrations/mem0-plugin/.opencode-plugin/README.md
 ```
 
-All commands auto-add the plugin and MCP server to your `~/.config/opencode/opencode.json`. Restart OpenCode — you get the MCP server, lifecycle hooks, and all `/mem0:` slash commands.
+This adds the plugin to your `~/.config/opencode/opencode.json`. Restart OpenCode — you get the native memory tools, lifecycle hooks, and all `/mem0:` slash commands. The memory tools are registered by the plugin itself via the `mem0ai` SDK — no MCP server to configure.
 
-### Option B — MCP Only
+### Option B — Standalone MCP Server
 
-If you only need the memory tools without hooks or skills, add this to your `opencode.json` (project-level or global at `~/.config/opencode/opencode.json`):
+If you only need the memory tools without the plugin's hooks or skills, point OpenCode at Mem0's hosted MCP server directly. Add this to your `opencode.json` (project-level or global at `~/.config/opencode/opencode.json`):
 
 ```json
 {
@@ -69,13 +59,13 @@ If you only need the memory tools without hooks or skills, add this to your `ope
 
 ## What's Included
 
-| Component | Plugin (A) | MCP Only (B) |
-|-----------|:----------:|:------------:|
-| MCP Server (9 memory tools) | Yes | Yes |
+| Component | Plugin (A) | Standalone MCP (B) |
+|-----------|:----------:|:------------------:|
+| 9 memory tools | Native (SDK) | Remote MCP server |
 | Lifecycle Hooks | Yes | No |
-| 16 Slash Commands | Yes | No |
+| 8 Skills | Yes | No |
 
-## Available MCP Tools
+## Available Memory Tools
 
 | Tool | Description |
 |------|-------------|
@@ -95,10 +85,11 @@ The plugin uses the [mem0ai](https://www.npmjs.com/package/mem0ai) TypeScript SD
 
 | OpenCode Event | Hook | What happens |
 |----------------|------|-------------|
+| `config` | **Config** | Registers the bundled skills (`skills.paths`) and `/mem0:*` slash commands at startup |
 | `chat.message` | **Chat message** | Searches prior memories on session start, searches relevant memories before each prompt, auto-captures learnings periodically |
-| `tool.execute.before` | **Pre-tool** | Blocks MEMORY.md writes, injects `user_id`/`app_id` on mem0 tool calls |
-| `tool.execute.after` | **Post-tool** | Tracks stats, scans Bash errors and pre-fetches related error memories |
-| `experimental.chat.system.transform` | **System transform** | Injects memory context (session memories, search results, error lookups) into the system prompt |
+| `tool.execute.before` | **Pre-tool** | Blocks MEMORY.md writes, steering them to the `add_memory` tool |
+| `tool.execute.after` | **Post-tool** | Scans Bash errors and pre-fetches related error memories |
+| `experimental.chat.messages.transform` | **Messages transform** | Injects memory context (session memories, search results, error lookups) into the prompt |
 | `experimental.session.compacting` | **Compaction** | Stores session state memory, then injects prior memories into compaction context so nothing is lost |
 | `shell.env` | **Shell env** | Exports `MEM0_USER_ID`, `MEM0_APP_ID`, `MEM0_SESSION_ID`, and `MEM0_BRANCH` to all shell executions |
 

docs/integrations/pi-agent.mdx

@@ -0,0 +1,184 @@
+---
+title: Pi Agent
+description: "Add persistent memory to Pi Agent with the Mem0 plugin semantic search, auto-capture, and dream consolidation."
+---
+
+Add persistent memory to [**Pi Agent**](https://pi.dev) with `@mem0/pi-agent-plugin`. Your agent forgets everything between sessions — this plugin fixes that by automatically capturing knowledge from conversations, storing it in Mem0's cloud memory layer, and retrieving relevant context before every response.
+
+## Overview
+
+The plugin provides:
+1. **Auto-capture** — Extracts durable facts from both user and assistant messages automatically
+2. **Semantic recall** — Retrieves relevant memories via the `mem0_memory` tool before each response
+3. **Dream consolidation** — Periodic maintenance: merges duplicates, resolves contradictions, prunes stale entries
+4. **Monorepo-aware scoping** — Uses git root for project detection, consistent across subdirectories
+5. **Confirmation dialogs** — Destructive commands ask before acting via Pi's built-in UI
+6. **8 skills + 8 commands** — Essential memory management from slash commands and agent-guided workflows
+
+## Prerequisites
+
+1. A Mem0 Platform account and API key:
+   - <a href="https://app.mem0.ai?utm_source=oss&utm_medium=integration-pi-agent" rel="nofollow">Sign up at app.mem0.ai</a>
+   - <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-pi-agent" rel="nofollow">Get your API key</a> (starts with `m0-`)
+
+2. Pi Agent installed ([pi.dev](https://pi.dev))
+
+3. Your API key added to your shell profile:
+
+<CodeGroup>
+```bash zsh
+echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+```bash bash
+echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
+source ~/.bashrc
+```
+</CodeGroup>
+
+## Installation
+
+```bash
+pi install npm:@mem0/pi-agent-plugin
+```
+
+That's it. The extension loads automatically on every Pi session. No config files needed — `MEM0_API_KEY` from your environment is picked up automatically.
+
+<Info>
+  Start a new Pi session and run `/mem0-status` to verify the connection. You should see your user ID, detected project, and memory count.
+</Info>
+
+### Optional Configuration
+
+For advanced settings, create `~/.pi/agent/mem0-config.json`:
+
+```json
+{
+  "apiKey": "m0-your-key-here",
+  "userId": "your-username",
+  "autoCapture": true,
+  "defaultScope": "project",
+  "searchThreshold": 0.3,
+  "dream": {
+    "enabled": true,
+    "auto": true,
+    "minHours": 24,
+    "minSessions": 5,
+    "minMemories": 20
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `apiKey` | `string` | `$MEM0_API_KEY` | Mem0 API key. Environment variable takes precedence. |
+| `userId` | `string` | `$MEM0_USER_ID` or `"default"` | User identity for memory scoping |
+| `autoCapture` | `boolean` | `true` | Store facts from conversations automatically |
+| `defaultScope` | `string` | `"project"` | Default memory scope: `project`, `session`, or `global` |
+| `searchThreshold` | `number` | `0.3` | Minimum similarity score (0–1) a memory must reach to count as a match for `/mem0-search`, `/mem0-forget`, and `/mem0-pin`, enforced on each result's relevance score. Raise it to be stricter; lower it if relevant results are missed. |
+| `dream.enabled` | `boolean` | `true` | Enable dream consolidation |
+| `dream.auto` | `boolean` | `true` | Auto-trigger dreams when thresholds are met |
+| `dream.minHours` | `number` | `24` | Minimum hours between auto-dreams |
+| `dream.minSessions` | `number` | `5` | Minimum sessions before first auto-dream |
+| `dream.minMemories` | `number` | `20` | Minimum memories before auto-dream triggers |
+
+
+## What's Included
+
+| Component | Description |
+|-----------|-------------|
+| `mem0_memory` tool | Agent-callable tool for search, add, get_all, delete, delete_all |
+| 8 slash commands | Essential memory management from the command line |
+| 8 skills | Guide the agent on how to use each capability |
+| Auto-capture | Extracts and stores facts on every `agent_end` event |
+| System prompt | Appends memory policy to every agent turn |
+| Dream consolidation | Automated memory maintenance with session/time/count gates |
+
+## Agent Tool
+
+The `mem0_memory` tool is registered with Pi and callable by the agent during conversations:
+
+| Action | Required Params | Description |
+|--------|----------------|-------------|
+| `search` | `query` | Semantic search across memories |
+| `add` | `content` | Store a new memory |
+| `get_all` | — | List all memories in scope |
+| `delete` | `memory_id` | Delete a specific memory |
+| `delete_all` | — | Delete all memories in scope |
+
+All actions accept an optional `scope` parameter: `project` (default), `session`, or `global`.
+
+Tool output is truncated to 200 lines / 50KB to prevent context overflow.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/mem0-remember <text>` | Store a memory verbatim (no inference) |
+| `/mem0-forget <query>` | Search and delete memories (with confirmation dialog) |
+| `/mem0-search <query>` | Semantic search across memories |
+| `/mem0-tour [scope]` | Browse all memories grouped by category |
+| `/mem0-dream` | Consolidate — merge duplicates, prune stale, resolve contradictions |
+| `/mem0-pin <query>` | Pin a memory to protect from dream pruning (preserves memory ID) |
+| `/mem0-scope <scope>` | Change default scope for this session (project, session, global) |
+| `/mem0-status` | Connection health, identity, and memory count |
+
+## Memory Scopes
+
+Memories are scoped using Mem0's `user_id`, `app_id`, and `run_id` parameters:
+
+| Scope | Filters | Use Case |
+|-------|---------|----------|
+| `project` | user_id + app_id (git root) | **Default.** Project-specific knowledge — decisions, architecture, config |
+| `session` | user_id + app_id + run_id | Ephemeral context for the current session only |
+| `global` | user_id only | All memories across all your projects |
+
+The `app_id` is auto-detected from the git repository root (`git rev-parse --show-toplevel`), so all subdirectories within a monorepo share the same memory pool. Falls back to the working directory name for non-git directories. The `run_id` is derived from Pi's session file path.
+
+## Dream Consolidation
+
+### Confirmation Dialogs
+
+Destructive and mutating commands use Pi's built-in `ctx.ui.confirm()` dialog before acting:
+
+- `/mem0-forget` asks "Delete this memory?" before deleting a single match
+- `/mem0-pin` asks "Pin this memory?" before modifying it
+- Cancelling either operation is always safe — no changes are made
+
+### Pin
+
+`/mem0-pin` uses Mem0's `update()` API to prepend `[PINNED]` to the memory text. This preserves the original memory ID — no add+delete cycle that would lose history or change the UUID.
+
+### Dream Consolidation
+
+The plugin includes automated memory maintenance ("dream") that merges duplicates, resolves contradictions, and prunes stale entries. When enabled, dreams auto-trigger after enough sessions, time, and memories accumulate (configurable via `dream.*` settings). Run `/mem0-dream` to trigger consolidation manually at any time. Pinned memories (via `/mem0-pin`) are protected from pruning.
+
+## Example Workflow
+
+```text
+# Session 1
+You: I prefer dark mode and concise answers.
+# Mem0 auto-captures preferences
+
+# Session 2 (days later)
+You: What do you know about my preferences?
+# Pi retrieves stored memories — no re-explaining needed
+```
+
+## Troubleshooting
+
+- **"No API key found"** — Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`. If empty, add it to your shell profile (see Prerequisites)
+- **Extension not loading** — Check Pi startup output for errors. Run `pi -e ./src/entry.ts` from the plugin directory for verbose output
+- **Memories not capturing** — Verify `autoCapture` is `true` (default). Check `/mem0-status` for connection health
+- **Wrong project detected** — The plugin uses the git repository root as `app_id`. If not in a git repo, it falls back to the working directory name. Run `/mem0-status` to see the detected project
+- **Dream not triggering** — All three gates must pass (time, sessions, memories). Use `/mem0-dream` to force it manually
+
+<CardGroup cols={2}>
+  <Card title="Claude Code Integration" icon="terminal" href="/integrations/claude-code">
+    Add Mem0 memory to Claude Code
+  </Card>
+  <Card title="OpenClaw Integration" icon="plug" href="/integrations/openclaw">
+    Add Mem0 memory to OpenClaw agents
+  </Card>
+</CardGroup>

docs/integrations/vercel-ai-sdk.mdx

@@ -6,25 +6,33 @@ description: "Use the Mem0 AI SDK Provider with Vercel AI SDK for persistent mem
 The [**Mem0 AI SDK Provider**](https://www.npmjs.com/package/@mem0/vercel-ai-provider) is a library developed by **Mem0** to integrate with the Vercel AI SDK. This library brings enhanced AI interaction capabilities to your applications by introducing persistent memory functionality.
 
 <Note type="info">
-  Mem0 AI SDK now supports <strong>Vercel AI SDK V5</strong>.
+  Mem0 AI SDK Provider v3.0.0 supports <strong>Vercel AI SDK v6</strong> (<code>LanguageModelV3</code> / <code>ProviderV3</code>). If you are upgrading from v2.x, see the <a href="https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0">AI SDK v6 migration guide</a>.
 </Note>
 
 ## Overview
 
 1. Offers persistent memory storage for conversational AI
-2. Enables smooth integration with the Vercel AI SDK
-3. Ensures compatibility with multiple LLM providers
+2. Enables smooth integration with the Vercel AI SDK v6
+3. Ensures compatibility with multiple LLM providers (OpenAI, Anthropic, Google, Groq, Cohere)
 4. Supports structured message formats for clarity
 5. Facilitates streaming response capabilities
+6. Attaches Mem0 memories as sources in responses for programmatic access
 
 ## Setup and Configuration
 
-Install the SDK provider using npm:
+Install the SDK provider and AI SDK:
 
 ```bash
-npm install @mem0/vercel-ai-provider
+npm install @mem0/vercel-ai-provider ai@^6
 ```
 
+### Peer Dependencies
+
+`@mem0/vercel-ai-provider` v3.0.0 requires:
+- `ai` v6+ (`^6.0.199`)
+- `@ai-sdk/provider` v3+ (`^3.0.10`)
+- Provider packages at v3+: `@ai-sdk/openai@^3`, `@ai-sdk/anthropic@^3`, `@ai-sdk/google@^3`, `@ai-sdk/groq@^3`, `@ai-sdk/cohere@^3`
+
 ## Getting Started
 
 ### Setting Up Mem0
@@ -41,7 +49,7 @@ npm install @mem0/vercel-ai-provider
       mem0ApiKey: "m0-xxx",
       apiKey: "provider-api-key",
       config: {
-        // Options for LLM Provider
+        // Options for the upstream LLM provider (e.g. baseURL)
       },
       // Optional Mem0 Global Config
       mem0Config: {
@@ -57,154 +65,153 @@ npm install @mem0/vercel-ai-provider
 3. Add Memories to Enhance Context:
 
     ```typescript
-    import { LanguageModelV2Prompt } from "@ai-sdk/provider";
     import { addMemories } from "@mem0/vercel-ai-provider";
 
-    const messages: LanguageModelV2Prompt = [
+    const messages = [
       { role: "user", content: [{ type: "text", text: "I love red cars." }] },
     ];
 
     await addMemories(messages, { user_id: "borat" });
     ```
 
-### Standalone Features:
+### Standalone Features
 
-    ```typescript
-    await addMemories(messages, { user_id: "borat", mem0ApiKey: "m0-xxx" });
-    await retrieveMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
-    await getMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
-    ```
-     > For standalone features, such as `addMemories`, `retrieveMemories`, and `getMemories`, you must either set `MEM0_API_KEY` as an environment variable or pass it directly in the function call.
+```typescript
+await addMemories(messages, { user_id: "borat", mem0ApiKey: "m0-xxx" });
+await retrieveMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
+await getMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
+```
 
-     > `getMemories` will return raw memories in the form of an array of objects, while `retrieveMemories` will return a response in string format with a system prompt ingested with the retrieved memories.
+> For standalone features, such as `addMemories`, `retrieveMemories`, and `getMemories`, you must either set `MEM0_API_KEY` as an environment variable or pass it directly in the function call.
 
-     > `getMemories` returns an array of memory objects.
+> `getMemories` will return raw memories in the form of an array of objects, while `retrieveMemories` will return a response in string format with a system prompt ingested with the retrieved memories.
 
 ### 1. Basic Text Generation with Memory Context
 
-    ```typescript
-    import { generateText } from "ai";
-    import { createMem0 } from "@mem0/vercel-ai-provider";
+```typescript
+import { generateText } from "ai";
+import { createMem0 } from "@mem0/vercel-ai-provider";
 
-    const mem0 = createMem0();
+const mem0 = createMem0();
 
-    const { text } = await generateText({
-      model: mem0("gpt-4-turbo", { user_id: "borat" }),
-      prompt: "Suggest me a good car to buy!",
-    });
-    ```
+const { text } = await generateText({
+  model: mem0("gpt-5-mini", { user_id: "borat" }),
+  prompt: "Suggest me a good car to buy!",
+});
+```
 
 ### 2. Combining OpenAI Provider with Memory Utils
 
-    ```typescript
-    import { generateText } from "ai";
-    import { openai } from "@ai-sdk/openai";
-    import { retrieveMemories } from "@mem0/vercel-ai-provider";
+```typescript
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { retrieveMemories } from "@mem0/vercel-ai-provider";
 
-    const prompt = "Suggest me a good car to buy.";
-    const memories = await retrieveMemories(prompt, { user_id: "borat" });
+const prompt = "Suggest me a good car to buy.";
+const memories = await retrieveMemories(prompt, { user_id: "borat" });
 
-    const { text } = await generateText({
-      model: openai("gpt-4-turbo"),
-      prompt: prompt,
-      system: memories,
-    });
-    ```
+const { text } = await generateText({
+  model: openai("gpt-5-mini"),
+  prompt: prompt,
+  system: memories,
+});
+```
 
 ### 3. Structured Message Format with Memory
 
-    ```typescript
-    import { generateText } from "ai";
-    import { createMem0 } from "@mem0/vercel-ai-provider";
+```typescript
+import { generateText } from "ai";
+import { createMem0 } from "@mem0/vercel-ai-provider";
 
-    const mem0 = createMem0();
+const mem0 = createMem0();
 
-    const { text } = await generateText({
-      model: mem0("gpt-4-turbo", { user_id: "borat" }),
-      messages: [
-        {
-          role: "user",
-          content: [
-            { type: "text", text: "Suggest me a good car to buy." },
-            { type: "text", text: "Why is it better than the other cars for me?" },
-          ],
-        },
+const { text } = await generateText({
+  model: mem0("gpt-5-mini", { user_id: "borat" }),
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "Suggest me a good car to buy." },
+        { type: "text", text: "Why is it better than the other cars for me?" },
       ],
-    });
-    ```
+    },
+  ],
+});
+```
 
-### 3. Streaming Responses with Memory Context
+### 4. Streaming Responses with Memory Context
 
-    ```typescript
-    import { streamText } from "ai";
-    import { createMem0 } from "@mem0/vercel-ai-provider";
+```typescript
+import { streamText } from "ai";
+import { createMem0 } from "@mem0/vercel-ai-provider";
 
-    const mem0 = createMem0();
+const mem0 = createMem0();
 
-    const { textStream } = streamText({
-        model: mem0("gpt-4-turbo", {
-            user_id: "borat",
-        }),
-        prompt: "Suggest me a good car to buy! Why is it better than the other cars for me? Give options for every price range.",
-    });
+const { textStream } = streamText({
+  model: mem0("gpt-5-mini", {
+    user_id: "borat",
+  }),
+  prompt: "Suggest me a good car to buy! Why is it better than the other cars for me? Give options for every price range.",
+});
 
-    for await (const textPart of textStream) {
-        process.stdout.write(textPart);
-    }
-    ```
+for await (const textPart of textStream) {
+  process.stdout.write(textPart);
+}
+```
 
-### 4. Generate Responses with Tools Call
+### 5. Generate Responses with Tools Call
 
-    ```typescript
-    import { generateText } from "ai";
-    import { createMem0 } from "@mem0/vercel-ai-provider";
-    import { z } from "zod";
+```typescript
+import { generateText, tool } from "ai";
+import { createMem0 } from "@mem0/vercel-ai-provider";
+import { z } from "zod";
 
-    const mem0 = createMem0({
-      provider: "anthropic",
-      apiKey: "anthropic-api-key",
-      mem0Config: {
-        // Global User ID
-        user_id: "borat"
-      }
-    });
+const mem0 = createMem0({
+  provider: "anthropic",
+  apiKey: "anthropic-api-key",
+  mem0Config: {
+    user_id: "borat"
+  }
+});
 
-    const prompt = "What the temperature in the city that I live in?"
+const result = await generateText({
+  model: mem0('claude-sonnet-4-20250514'),
+  tools: {
+    weather: tool({
+      description: 'Get the weather in a location',
+      parameters: z.object({
+        location: z.string().describe('The location to get the weather for'),
+      }),
+      execute: async ({ location }) => ({
+        location,
+        temperature: 72 + Math.floor(Math.random() * 21) - 10,
+      }),
+    }),
+  },
+  prompt: "What the temperature in the city that I live in?",
+});
 
-    const result = await generateText({
-      model: mem0('claude-3-5-sonnet-20240620'),
-      tools: {
-        weather: tool({
-          description: 'Get the weather in a location',
-          parameters: z.object({
-            location: z.string().describe('The location to get the weather for'),
-          }),
-          execute: async ({ location }) => ({
-            location,
-            temperature: 72 + Math.floor(Math.random() * 21) - 10,
-          }),
-        }),
-      },
-      prompt: prompt,
-    });
+console.log(result);
+```
 
-    console.log(result);
-    ```
+### 6. Get Sources from Memory
 
-### 5. Get sources from memory
+`generateText` and `streamText` responses include Mem0 memories as a source, giving you programmatic access to the memories that influenced the response:
 
 ```typescript
 const { text, sources } = await generateText({
-    model: mem0("gpt-4-turbo"),
-    prompt: "Suggest me a good car to buy!",
+  model: mem0("gpt-5-mini", { user_id: "borat" }),
+  prompt: "Suggest me a good car to buy!",
 });
 
+// sources[0].title === "Mem0 Memories"
+// sources[0].providerMetadata.mem0.memories — array of memory objects
 console.log(sources);
 ```
 
 The same can be done for `streamText` as well.
 
-### 6. File Support with Memory Context
+### 7. File Support with Memory Context
 
 Mem0 AI SDK supports file processing with memory context. Here's an example of analyzing a PDF file:
 
@@ -226,15 +233,11 @@ const mem0 = createMem0({
 });
 
 async function main() {
-  // Read the PDF file
   const filePath = join(process.cwd(), 'my_pdf.pdf');
   const fileBuffer = readFileSync(filePath);
 
-  // Convert the file's arrayBuffer to a Base64 data URL
   const arrayBuffer = fileBuffer.buffer.slice(fileBuffer.byteOffset, fileBuffer.byteOffset + fileBuffer.byteLength);
   const uint8Array = new Uint8Array(arrayBuffer);
-
-  // Convert Uint8Array to an array of characters
   const charArray = Array.from(uint8Array, byte => String.fromCharCode(byte));
   const binaryString = charArray.join('');
   const base64Data = Buffer.from(binaryString, 'binary').toString('base64');
@@ -274,24 +277,56 @@ main();
 
 | Provider | Configuration Value |
 |----------|-------------------|
-| OpenAI | openai |
-| Anthropic | anthropic |
-| Google | google |
-| Groq | groq |
+| OpenAI | `openai` |
+| Anthropic | `anthropic` |
+| Google / Gemini | `google` or `gemini` |
+| Groq | `groq` |
+| Cohere | `cohere` |
 
-> **Note**: You can use `google` as provider for Gemini (Google) models. They are same and internally they use `@ai-sdk/google` package.
+> **Note**: You can use either `google` or `gemini` as the provider value for Google Gemini models. Both map to the `@ai-sdk/google` package internally.
+
+## Configuration Options
+
+### Mem0ConfigSettings
+
+These options can be passed per-request when creating a model instance:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `user_id` | `string` | User identifier for memory scoping |
+| `agent_id` | `string` | Agent identifier |
+| `app_id` | `string` | Application identifier |
+| `run_id` | `string` | Run/session identifier |
+| `metadata` | `object` | Custom metadata for memories |
+| `filters` | `object` | Filters for memory search |
+| `infer` | `boolean` | Enable inference-based retrieval |
+| `top_k` | `number` | Number of memories to retrieve (default: 10) |
+| `threshold` | `number` | Relevance threshold for search |
+| `rerank` | `boolean` | Enable reranking of results |
+| `page` | `number` | Page number for pagination |
+| `page_size` | `number` | Results per page |
 
 ## Key Features
 
-- `createMem0()`: Initializes a new Mem0 provider instance.
-- `retrieveMemories()`: Retrieves memory context for prompts.
+- `createMem0()`: Initializes a new Mem0 provider instance implementing `ProviderV3`.
+- `retrieveMemories()`: Retrieves memory context for prompts as a formatted system prompt string.
 - `getMemories()`: Get memories from your profile in array format.
 - `addMemories()`: Adds user memories to enhance contextual responses.
 
+## Migrating from v2.x
+
+If you're upgrading from `@mem0/vercel-ai-provider` v2.x:
+
+1. **Upgrade AI SDK**: `npm install ai@^6` and update all `@ai-sdk/*` provider packages to `^3.x`
+2. **Remove deprecated params**: Remove `org_id`, `project_id`, `output_format`, `filter_memories`, `async_mode`, `enable_graph` from your config
+3. **Remove graph memory**: All graph-related options (`enable_graph`, graph prompts) have been removed. Graph memory is now a project-level setting on the Mem0 Platform
+4. **Update imports**: `LanguageModelV2Prompt` is now `LanguageModelV3Prompt` if you import types directly
+
 ## Best Practices
 
 1. **User Identification**: Use a unique `user_id` for consistent memory retrieval.
 2. **Memory Cleanup**: Regularly clean up unused memory data.
+3. **Sources**: Access `result.sources` to inspect which memories influenced the response.
 
     > **Note**: We also have support for `agent_id`, `app_id`, and `run_id`. Refer [Docs](/api-reference/memory/add-memories).
 

docs/llms.txt

@@ -228,6 +228,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f
 - [OSS v2 to v3 Migration](https://docs.mem0.ai/migration/oss-v2-to-v3) [OSS]: Use when upgrading a self-hosted deployment across major versions.
 - [Platform v2 to v3 Migration](https://docs.mem0.ai/migration/platform-v2-to-v3) [Platform]: Use when upgrading a Platform integration across major versions.
 - [API Changes](https://docs.mem0.ai/migration/api-changes) [Both]: Use when the upgrade involves API surface changes.
+- [Server pgvector Image Upgrade](https://docs.mem0.ai/migration/server-pgvector-upgrade) [OSS]: Use when upgrading the self-hosted server Docker image from ankane/pgvector to pgvector/pgvector.
 - [Changelog](https://docs.mem0.ai/changelog/highlights) [Both]: Use when the user asks what shipped recently.
 
 ## Open Source
@@ -258,6 +259,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f
 - [Camel AI](https://docs.mem0.ai/integrations/camel-ai) [Both]: Use when the user is on Camel AI.
 - [ChatDev](https://docs.mem0.ai/integrations/chatdev) [Both]: Use when the user is on ChatDev.
 - [Hermes](https://docs.mem0.ai/integrations/hermes) [Both]: Use when the user is on Hermes.
+- [Pi Agent](https://docs.mem0.ai/integrations/pi-agent) [Platform]: Use when adding persistent memory to Pi Agent with the Mem0 plugin.
 - [OpenAI Agents SDK](https://docs.mem0.ai/integrations/openai-agents-sdk) [Both]: Use when the user is on the OpenAI Agents SDK.
 - [Google AI ADK](https://docs.mem0.ai/integrations/google-ai-adk) [Both]: Use when the user is on Google's Agent Development Kit.
 - [Mastra](https://docs.mem0.ai/integrations/mastra) [Both]: Use when the user is on Mastra (TypeScript).
@@ -396,9 +398,9 @@ Each subdirectory is a Claude Code Skill (`SKILL.md` + supporting assets). Load
 
 ### Editor Plugin (shared glue)
 
-Source: https://github.com/mem0ai/mem0/tree/main/mem0-plugin
+Source: https://github.com/mem0ai/mem0/tree/main/integrations/mem0-plugin
 
-The `mem0-plugin/` directory provides MCP server connection, lifecycle hooks, and skill bundling for Claude Code, Cursor, Codex, OpenCode, and Antigravity. It exposes 9 MCP tools: `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities`.
+The `integrations/mem0-plugin/` directory provides MCP server connection, lifecycle hooks, and skill bundling for Claude Code, Cursor, Codex, OpenCode, and Antigravity. It exposes 9 MCP tools: `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities`.
 
 Editor-specific setup docs (already listed above under `## Integrations > AI Coding Tools`):
 
@@ -474,6 +476,7 @@ Everything below is OSS-only provider configuration. Skip this entire section wh
 - [Elasticsearch](https://docs.mem0.ai/components/vectordbs/dbs/elasticsearch) [OSS]: Use when Elasticsearch is the backing store.
 - [OpenSearch](https://docs.mem0.ai/components/vectordbs/dbs/opensearch) [OSS]: Use when OpenSearch is the backing store.
 - [Supabase](https://docs.mem0.ai/components/vectordbs/dbs/supabase) [OSS]: Use when Supabase with pgvector is the backing store.
+- [Neon](https://docs.mem0.ai/components/vectordbs/dbs/neon) [OSS]: Use when Neon Postgres with pgvector is the backing store.
 - [Upstash Vector](https://docs.mem0.ai/components/vectordbs/dbs/upstash-vector) [OSS]: Use for serverless Upstash Vector.
 - [Vectorize](https://docs.mem0.ai/components/vectordbs/dbs/vectorize) [OSS]: Use when the store is Cloudflare Vectorize.
 - [Vertex AI Vector Search](https://docs.mem0.ai/components/vectordbs/dbs/vertex_ai) [OSS]: Use when the store is Google Cloud Vertex Vector Search.

docs/migration/oss-to-platform.mdx

@@ -6,17 +6,15 @@ versionFrom: "Open Source"
 versionTo: "Platform"
 ---
 
-# Migrate from Open Source to Platform
-
-Move your Mem0 implementation to managed infrastructure with enterprise features.
+## Overview
 
 | Scope                 | Effort         | Downtime                     |
 | --------------------- | -------------- | ---------------------------- |
 | Infrastructure & Code | Low (~30 mins) | None (Parallel run possible) |
 
-<Info>
+<Note>
   Using Mem0 Open Source with **hosted Qdrant**? You can migrate your existing memories to Mem0 Platform with a one-line script below.
-</Info>
+</Note>
 
 <Info>
   **Why migrate to Platform?**
@@ -30,12 +28,29 @@ Move your Mem0 implementation to managed infrastructure with enterprise features
   - **Production Grade**: Auto-scaling, high availability, dedicated support
 </Info>
 
-## Plan
+### Plan
 
 1. **Sign up**: Create an account on <a href="https://app.mem0.ai?utm_source=oss&utm_medium=migration-oss-to-platform" rel="nofollow">Mem0 Platform</a>.
 2. **Get API Key**: Navigate to **Settings > API Keys** and generate a new key.
 3. **Review Usage**: Identify where you instantiate `Memory` and where you call `search` or `get_all`.
 
+## Migrate with Agent Skill
+
+Paste this prompt into your coding agent. It uses a migration skill to produce a plan; once you review and approve it, the agent implements the changes.
+
+```text
+Migrate my project from Mem0 OSS to the Mem0 Platform SDK using the
+mem0-oss-to-platform skill in the mem0ai/mem0 repo, at
+skills/mem0-oss-to-platform/
+
+Get the skill whichever way is easiest:
+- install it: npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform
+- if the mem0 repo is cloned locally, read it from skills/mem0-oss-to-platform/
+- otherwise fetch that folder from github.com/mem0ai/mem0 (SKILL.md + references/)
+
+Then read SKILL.md and begin the migration.
+```
+
 ## Migrate
 
 ### 1. Import Memories Into Platform

docs/migration/server-pgvector-upgrade.mdx

@@ -0,0 +1,158 @@
+---
+title: "Server: Upgrading the pgvector Docker Image"
+description: "Migrate your self-hosted Mem0 server from the archived ankane/pgvector image to the official pgvector/pgvector image."
+icon: "arrow-right"
+iconType: "solid"
+---
+
+## Overview
+
+The self-hosted Mem0 server has upgraded its PostgreSQL Docker image:
+
+| | Before | After |
+| --- | --- | --- |
+| Docker image | `ankane/pgvector:v0.5.1` | `pgvector/pgvector:pg17` |
+| PostgreSQL | 15 | 17 |
+| pgvector | 0.5.1 | 0.8.0 |
+| Credentials | Hardcoded `postgres` / `postgres` | Set via `POSTGRES_USER` / `POSTGRES_PASSWORD` env vars |
+
+<Warning>
+The `ankane/pgvector` image is **archived and no longer maintained**. The new `pgvector/pgvector` image is the official distribution maintained by the pgvector project.
+</Warning>
+
+<Info>
+**Should you migrate?**
+- You are running the Mem0 server via `docker-compose.yaml` in the `server/` directory.
+- You want to stay on a maintained, actively-patched PostgreSQL + pgvector image.
+- You want pgvector 0.8.0 features (improved HNSW performance, parallel index builds).
+</Info>
+
+## Fresh Installs
+
+No migration is needed. Copy the example env file, set your password, and start the stack:
+
+```bash
+cd server
+cp .env.example .env
+# Edit .env — set POSTGRES_PASSWORD (required) and OPENAI_API_KEY at minimum
+make up
+```
+
+## Migrating an Existing Install
+
+PostgreSQL 17 cannot read data files created by PostgreSQL 15 directly. You need to export your data from the old container and import it into the new one.
+
+### 1. Back Up Your Data
+
+With the **old** stack still running:
+
+```bash
+cd server
+docker compose exec -T postgres pg_dumpall -U postgres > mem0_backup.sql
+```
+
+Verify the dump is non-empty:
+
+```bash
+ls -lh mem0_backup.sql
+```
+
+<Warning>
+Do not skip this step. The next step permanently deletes your Postgres data volume.
+</Warning>
+
+### 2. Stop the Old Stack and Remove the Volume
+
+```bash
+docker compose down
+docker compose down -v
+```
+
+### 3. Update Your `.env`
+
+Postgres credentials are no longer hardcoded in `docker-compose.yaml`. Add them to your `.env`:
+
+```bash
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_DB=postgres
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=<your-password>    # required — compose will refuse to start without it
+POSTGRES_COLLECTION_NAME=memories
+```
+
+<Info>
+`POSTGRES_PASSWORD` is **required** — `docker compose up` will refuse to start without it. If you previously relied on the hardcoded default, set `POSTGRES_PASSWORD=postgres`.
+</Info>
+
+### 4. Start Only Postgres
+
+Start **only** the Postgres container first — do **not** start the mem0 API yet.
+The API runs `alembic upgrade head` on startup, which creates empty tables that
+would conflict with the restore.
+
+```bash
+docker compose up -d postgres
+```
+
+Wait for Postgres to become healthy:
+
+```bash
+docker compose exec -T postgres pg_isready -q && echo "ready" || echo "not ready"
+```
+
+### 5. Restore Your Data
+
+```bash
+docker compose exec -T postgres psql -U postgres < mem0_backup.sql
+```
+
+You may see notices like `role "postgres" already exists` — these are safe to ignore.
+
+<Warning>
+You must restore **before** starting the mem0 API container. The API runs
+database migrations on startup which create empty tables — restoring after
+that would fail with duplicate-key errors and lose your API keys and settings.
+</Warning>
+
+### 6. Start the API
+
+Now start the mem0 API container. Alembic will detect the existing tables and
+only apply any new migrations:
+
+```bash
+docker compose up -d mem0
+```
+
+### 7. Verify
+
+```bash
+# Check service health
+cd server && make health
+
+# Confirm memories are accessible
+curl -s http://localhost:8888/memories?user_id=<your-user-id> \
+  -H "X-API-Key: <your-api-key>"
+```
+
+## Rollback
+
+If something goes wrong, revert the image tag in `docker-compose.yaml`:
+
+```yaml
+postgres:
+    image: ankane/pgvector:v0.5.1
+```
+
+Then destroy the new volume, start the old image, and restore from your backup:
+
+```bash
+docker compose down -v
+docker compose up -d --build
+docker compose exec -T postgres psql -U postgres < mem0_backup.sql
+```
+
+## Need Help?
+
+- Join our [Discord community](https://mem0.ai/discord) for real-time support
+- Open an issue on [GitHub](https://github.com/mem0ai/mem0/issues)

docs/open-source/features/rest-api.mdx

@@ -226,6 +226,20 @@ curl -X POST http://localhost:8888/search \
   }'
 ```
 
+Set `explain` to inspect the scoring signals used by OSS hybrid search:
+
+```bash
+curl -X POST http://localhost:8888/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "vegetable pizza",
+    "user_id": "alice",
+    "explain": true
+  }'
+```
+
+Each returned memory includes `score_details` only when explanation mode is enabled.
+
 ### Explore with OpenAPI docs
 
 1. Navigate to `http://localhost:8888/docs` (Compose) or `http://localhost:8000/docs` (raw Docker / uvicorn).

docs/vibecoding.mdx

@@ -45,10 +45,12 @@ Let your assistant execute an end-to-end workflow in an existing repo. Invoked a
 ```bash
 npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
 npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform
 ```
 
 - `/mem0-integrate` — wire Mem0 into an existing repository using a goal-driven, test-first pipeline. Detects the stack, asks whether to use Platform or OSS, writes failing tests first, and keeps the integration additive and feature-flagged.
 - `/mem0-test-integration` — verify what `/mem0-integrate` produced. Runs the repo's native test suite and a real end-to-end smoke flow against your API key, then produces a scorecard.
+- `/mem0-oss-to-platform` — migrate an existing project from Mem0 OSS to the hosted Platform SDK. Audits where Mem0 is used, writes a reviewable migration plan, then executes it on approval.
 
 See the [skills index](https://github.com/mem0ai/mem0/tree/main/skills) for the full catalog.
 

evaluation/Makefile

@@ -1,31 +0,0 @@
-
-# Run the experiments
-run-mem0-add:
-	python run_experiments.py --technique_type mem0 --method add
-
-run-mem0-search:
-	python run_experiments.py --technique_type mem0 --method search --output_folder results/ --top_k 30
-
-run-mem0-plus-add:
-	python run_experiments.py --technique_type mem0 --method add --is_graph
-
-run-mem0-plus-search:
-	python run_experiments.py --technique_type mem0 --method search --is_graph --output_folder results/ --top_k 30
-
-run-rag:
-	python run_experiments.py --technique_type rag --chunk_size 500 --num_chunks 1 --output_folder results/
-
-run-full-context:
-	python run_experiments.py --technique_type rag --chunk_size -1 --num_chunks 1 --output_folder results/
-
-run-langmem:
-	python run_experiments.py --technique_type langmem --output_folder results/
-
-run-zep-add:
-	python run_experiments.py --technique_type zep --method add --output_folder results/
-
-run-zep-search:
-	python run_experiments.py --technique_type zep --method search --output_folder results/
-
-run-openai:
-	python run_experiments.py --technique_type openai --output_folder results/

evaluation/README.md

@@ -1,198 +0,0 @@
-# Mem0: Building Production‑Ready AI Agents with Scalable Long‑Term Memory
-
-[![arXiv](https://img.shields.io/badge/arXiv-Paper-b31b1b.svg)](https://arxiv.org/abs/2504.19413)
-[![Website](https://img.shields.io/badge/Website-Project-blue)](https://mem0.ai/research)
-
-This repository contains the code and dataset for our paper: **Mem0: Building Production‑Ready AI Agents with Scalable Long‑Term Memory**.
-
-## 📋 Overview
-
-This project evaluates Mem0 and compares it with different memory and retrieval techniques for AI systems:
-
-1. **Established LOCOMO Benchmarks**: We evaluate against five established approaches from the literature: LoCoMo, ReadAgent, MemoryBank, MemGPT, and A-Mem.
-2. **Open-Source Memory Solutions**: We test promising open-source memory architectures including LangMem, which provides flexible memory management capabilities.
-3. **RAG Systems**: We implement Retrieval-Augmented Generation with various configurations, testing different chunk sizes and retrieval counts to optimize performance.
-4. **Full-Context Processing**: We examine the effectiveness of passing the entire conversation history within the context window of the LLM as a baseline approach.
-5. **Proprietary Memory Systems**: We evaluate OpenAI's built-in memory feature available in their ChatGPT interface to compare against commercial solutions.
-6. **Third-Party Memory Providers**: We incorporate Zep, a specialized memory management platform designed for AI agents, to assess the performance of dedicated memory infrastructure.
-
-We test these techniques on the LOCOMO dataset, which contains conversational data with various question types to evaluate memory recall and understanding.
-
-## 🔍 Dataset
-
-The LOCOMO dataset used in our experiments can be downloaded from our Google Drive repository:
-
-[Download LOCOMO Dataset](https://drive.google.com/drive/folders/1L-cTjTm0ohMsitsHg4dijSPJtqNflwX-?usp=drive_link)
-
-The dataset contains conversational data specifically designed to test memory recall and understanding across various question types and complexity levels.
-
-Place the dataset files in the `dataset/` directory:
-- `locomo10.json`: Original dataset
-- `locomo10_rag.json`: Dataset formatted for RAG experiments
-
-## 📁 Project Structure
-
-```
-.
-├── src/                  # Source code for different memory techniques
-│   ├── mem0/             # Implementation of the Mem0 technique
-│   ├── openai/           # Implementation of the OpenAI memory
-│   ├── zep/              # Implementation of the Zep memory
-│   ├── rag.py            # Implementation of the RAG technique
-│   └── langmem.py        # Implementation of the Language-based memory
-├── metrics/              # Code for evaluation metrics
-├── results/              # Results of experiments
-├── dataset/              # Dataset files
-├── evals.py              # Evaluation script
-├── run_experiments.py    # Script to run experiments
-├── generate_scores.py    # Script to generate scores from results
-└── prompts.py            # Prompts used for the models
-```
-
-## 🚀 Getting Started
-
-### Prerequisites
-
-Create a `.env` file with your API keys and configurations. The following keys are required:
-
-```
-# OpenAI API key for GPT models and embeddings
-OPENAI_API_KEY="your-openai-api-key"
-
-# Mem0 API keys (for Mem0 and Mem0+ techniques)
-MEM0_API_KEY="your-mem0-api-key"
-MEM0_PROJECT_ID="your-mem0-project-id"
-MEM0_ORGANIZATION_ID="your-mem0-organization-id"
-
-# Model configuration
-MODEL="gpt-4o-mini"  # or your preferred model
-EMBEDDING_MODEL="text-embedding-3-small"  # or your preferred embedding model
-ZEP_API_KEY="api-key-from-zep"
-```
-
-### Running Experiments
-
-You can run experiments using the provided Makefile commands:
-
-#### Memory Techniques
-
-```bash
-# Run Mem0 experiments
-make run-mem0-add         # Add memories using Mem0
-make run-mem0-search      # Search memories using Mem0
-
-# Run Mem0+ experiments (with graph-based search)
-make run-mem0-plus-add    # Add memories using Mem0+
-make run-mem0-plus-search # Search memories using Mem0+
-
-# Run RAG experiments
-make run-rag              # Run RAG with chunk size 500
-make run-full-context     # Run RAG with full context
-
-# Run LangMem experiments
-make run-langmem          # Run LangMem
-
-# Run Zep experiments
-make run-zep-add          # Add memories using Zep
-make run-zep-search       # Search memories using Zep
-
-# Run OpenAI experiments
-make run-openai           # Run OpenAI experiments
-```
-
-Alternatively, you can run experiments directly with custom parameters:
-
-```bash
-python run_experiments.py --technique_type [mem0|rag|langmem] [additional parameters]
-```
-
-#### Command-line Parameters:
-
-| Parameter | Description | Default |
-|-----------|-------------|---------|
-| `--technique_type` | Memory technique to use (mem0, rag, langmem) | mem0 |
-| `--method` | Method to use (add, search) | add |
-| `--chunk_size` | Chunk size for processing | 1000 |
-| `--top_k` | Number of top memories to retrieve | 30 |
-| `--filter_memories` | Whether to filter memories | False |
-| `--is_graph` | Whether to use graph-based search | False |
-| `--num_chunks` | Number of chunks to process for RAG | 1 |
-
-### 📊 Evaluation
-
-To evaluate results, run:
-
-```bash
-python evals.py --input_file [path_to_results] --output_file [output_path]
-```
-
-This script:
-1. Processes each question-answer pair
-2. Calculates BLEU and F1 scores automatically
-3. Uses an LLM judge to evaluate answer correctness
-4. Saves the combined results to the output file
-
-### 📈 Generating Scores
-
-Generate final scores with:
-
-```bash
-python generate_scores.py
-```
-
-This script:
-1. Loads the evaluation metrics data
-2. Calculates mean scores for each category (BLEU, F1, LLM)
-3. Reports the number of questions per category
-4. Calculates overall mean scores across all categories
-
-Example output:
-```
-Mean Scores Per Category:
-         bleu_score  f1_score  llm_score  count
-category                                       
-1           0.xxxx    0.xxxx     0.xxxx     xx
-2           0.xxxx    0.xxxx     0.xxxx     xx
-3           0.xxxx    0.xxxx     0.xxxx     xx
-
-Overall Mean Scores:
-bleu_score    0.xxxx
-f1_score      0.xxxx
-llm_score     0.xxxx
-```
-
-## 📏 Evaluation Metrics
-
-We use several metrics to evaluate the performance of different memory techniques:
-
-1. **BLEU Score**: Measures the similarity between the model's response and the ground truth
-2. **F1 Score**: Measures the harmonic mean of precision and recall
-3. **LLM Score**: A binary score (0 or 1) determined by an LLM judge evaluating the correctness of responses
-4. **Token Consumption**: Number of tokens required to generate final answer.
-5. **Latency**: Time required during search and to generate response.
-
-## 📚 Citation
-
-If you use this code or dataset in your research, please cite our paper:
-
-```bibtex
-@article{mem0,
-  title={Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory},
-  author={Chhikara, Prateek and Khant, Dev and Aryan, Saket and Singh, Taranjeet and Yadav, Deshraj},
-  journal={arXiv preprint arXiv:2504.19413},
-  year={2025}
-}
-```
-
-## 📄 License
-
-[MIT License](LICENSE)
-
-## 👥 Contributors
-
-- [Prateek Chhikara](https://github.com/prateekchhikara)
-- [Dev Khant](https://github.com/Dev-Khant)
-- [Saket Aryan](https://github.com/whysosaket)
-- [Taranjeet Singh](https://github.com/taranjeet)
-- [Deshraj Yadav](https://github.com/deshraj)
-

evaluation/evals.py

@@ -1,81 +0,0 @@
-import argparse
-import concurrent.futures
-import json
-import threading
-from collections import defaultdict
-
-from metrics.llm_judge import evaluate_llm_judge
-from metrics.utils import calculate_bleu_scores, calculate_metrics
-from tqdm import tqdm
-
-
-def process_item(item_data):
-    k, v = item_data
-    local_results = defaultdict(list)
-
-    for item in v:
-        gt_answer = str(item["answer"])
-        pred_answer = str(item["response"])
-        category = str(item["category"])
-        question = str(item["question"])
-
-        # Skip category 5
-        if category == "5":
-            continue
-
-        metrics = calculate_metrics(pred_answer, gt_answer)
-        bleu_scores = calculate_bleu_scores(pred_answer, gt_answer)
-        llm_score = evaluate_llm_judge(question, gt_answer, pred_answer)
-
-        local_results[k].append(
-            {
-                "question": question,
-                "answer": gt_answer,
-                "response": pred_answer,
-                "category": category,
-                "bleu_score": bleu_scores["bleu1"],
-                "f1_score": metrics["f1"],
-                "llm_score": llm_score,
-            }
-        )
-
-    return local_results
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Evaluate RAG results")
-    parser.add_argument(
-        "--input_file", type=str, default="results/rag_results_500_k1.json", help="Path to the input dataset file"
-    )
-    parser.add_argument(
-        "--output_file", type=str, default="evaluation_metrics.json", help="Path to save the evaluation results"
-    )
-    parser.add_argument("--max_workers", type=int, default=10, help="Maximum number of worker threads")
-
-    args = parser.parse_args()
-
-    with open(args.input_file, "r") as f:
-        data = json.load(f)
-
-    results = defaultdict(list)
-    results_lock = threading.Lock()
-
-    # Use ThreadPoolExecutor with specified workers
-    with concurrent.futures.ThreadPoolExecutor(max_workers=args.max_workers) as executor:
-        futures = [executor.submit(process_item, item_data) for item_data in data.items()]
-
-        for future in tqdm(concurrent.futures.as_completed(futures), total=len(futures)):
-            local_results = future.result()
-            with results_lock:
-                for k, items in local_results.items():
-                    results[k].extend(items)
-
-    # Save results to JSON file
-    with open(args.output_file, "w") as f:
-        json.dump(results, f, indent=4)
-
-    print(f"Results saved to {args.output_file}")
-
-
-if __name__ == "__main__":
-    main()

evaluation/generate_scores.py

@@ -1,34 +0,0 @@
-import json
-
-import pandas as pd
-
-# Load the evaluation metrics data
-with open("evaluation_metrics.json", "r") as f:
-    data = json.load(f)
-
-# Flatten the data into a list of question items
-all_items = []
-for key in data:
-    all_items.extend(data[key])
-
-# Convert to DataFrame
-df = pd.DataFrame(all_items)
-
-# Convert category to numeric type
-df["category"] = pd.to_numeric(df["category"])
-
-# Calculate mean scores by category
-result = df.groupby("category").agg({"bleu_score": "mean", "f1_score": "mean", "llm_score": "mean"}).round(4)
-
-# Add count of questions per category
-result["count"] = df.groupby("category").size()
-
-# Print the results
-print("Mean Scores Per Category:")
-print(result)
-
-# Calculate overall means
-overall_means = df.agg({"bleu_score": "mean", "f1_score": "mean", "llm_score": "mean"}).round(4)
-
-print("\nOverall Mean Scores:")
-print(overall_means)

evaluation/metrics/llm_judge.py

@@ -1,130 +0,0 @@
-import argparse
-import json
-from collections import defaultdict
-
-import numpy as np
-from openai import OpenAI
-
-from mem0.memory.utils import extract_json
-
-client = OpenAI()
-
-ACCURACY_PROMPT = """
-Your task is to label an answer to a question as ’CORRECT’ or ’WRONG’. You will be given the following data:
-    (1) a question (posed by one user to another user), 
-    (2) a ’gold’ (ground truth) answer, 
-    (3) a generated answer
-which you will score as CORRECT/WRONG.
-
-The point of the question is to ask about something one user should know about the other user based on their prior conversations.
-The gold answer will usually be a concise and short answer that includes the referenced topic, for example:
-Question: Do you remember what I got the last time I went to Hawaii?
-Gold answer: A shell necklace
-The generated answer might be much longer, but you should be generous with your grading - as long as it touches on the same topic as the gold answer, it should be counted as CORRECT. 
-
-For time related questions, the gold answer will be a specific date, month, year, etc. The generated answer might be much longer or use relative time references (like "last Tuesday" or "next month"), but you should be generous with your grading - as long as it refers to the same date or time period as the gold answer, it should be counted as CORRECT. Even if the format differs (e.g., "May 7th" vs "7 May"), consider it CORRECT if it's the same date.
-
-Now it's time for the real question:
-Question: {question}
-Gold answer: {gold_answer}
-Generated answer: {generated_answer}
-
-First, provide a short (one sentence) explanation of your reasoning, then finish with CORRECT or WRONG. 
-Do NOT include both CORRECT and WRONG in your response, or it will break the evaluation script.
-
-Just return the label CORRECT or WRONG in a json format with the key as "label".
-"""
-
-
-def evaluate_llm_judge(question, gold_answer, generated_answer):
-    """Evaluate the generated answer against the gold answer using an LLM judge."""
-    response = client.chat.completions.create(
-        model="gpt-4o-mini",
-        messages=[
-            {
-                "role": "user",
-                "content": ACCURACY_PROMPT.format(
-                    question=question, gold_answer=gold_answer, generated_answer=generated_answer
-                ),
-            }
-        ],
-        response_format={"type": "json_object"},
-        temperature=0.0,
-    )
-    label = json.loads(extract_json(response.choices[0].message.content))["label"]
-    return 1 if label == "CORRECT" else 0
-
-
-def main():
-    """Main function to evaluate RAG results using LLM judge."""
-    parser = argparse.ArgumentParser(description="Evaluate RAG results using LLM judge")
-    parser.add_argument(
-        "--input_file",
-        type=str,
-        default="results/default_run_v4_k30_new_graph.json",
-        help="Path to the input dataset file",
-    )
-
-    args = parser.parse_args()
-
-    dataset_path = args.input_file
-    output_path = f"results/llm_judge_{dataset_path.split('/')[-1]}"
-
-    with open(dataset_path, "r") as f:
-        data = json.load(f)
-
-    LLM_JUDGE = defaultdict(list)
-    RESULTS = defaultdict(list)
-
-    index = 0
-    for k, v in data.items():
-        for x in v:
-            question = x["question"]
-            gold_answer = x["answer"]
-            generated_answer = x["response"]
-            category = x["category"]
-
-            # Skip category 5
-            if int(category) == 5:
-                continue
-
-            # Evaluate the answer
-            label = evaluate_llm_judge(question, gold_answer, generated_answer)
-            LLM_JUDGE[category].append(label)
-
-            # Store the results
-            RESULTS[index].append(
-                {
-                    "question": question,
-                    "gt_answer": gold_answer,
-                    "response": generated_answer,
-                    "category": category,
-                    "llm_label": label,
-                }
-            )
-
-            # Save intermediate results
-            with open(output_path, "w") as f:
-                json.dump(RESULTS, f, indent=4)
-
-            # Print current accuracy for all categories
-            print("All categories accuracy:")
-            for cat, results in LLM_JUDGE.items():
-                if results:  # Only print if there are results for this category
-                    print(f"  Category {cat}: {np.mean(results):.4f} ({sum(results)}/{len(results)})")
-            print("------------------------------------------")
-        index += 1
-
-    # Save final results
-    with open(output_path, "w") as f:
-        json.dump(RESULTS, f, indent=4)
-
-    # Print final summary
-    print("PATH: ", dataset_path)
-    print("------------------------------------------")
-    for k, v in LLM_JUDGE.items():
-        print(k, np.mean(v))
-
-
-if __name__ == "__main__":
-    main()

evaluation/metrics/utils.py

@@ -1,211 +0,0 @@
-"""
-Borrowed from https://github.com/WujiangXu/AgenticMemory/blob/main/utils.py
-
-@article{xu2025mem,
-    title={A-mem: Agentic memory for llm agents},
-    author={Xu, Wujiang and Liang, Zujie and Mei, Kai and Gao, Hang and Tan, Juntao
-           and Zhang, Yongfeng},
-    journal={arXiv preprint arXiv:2502.12110},
-    year={2025}
-}
-"""
-
-import statistics
-from collections import defaultdict
-from typing import Dict, List, Union
-
-import nltk
-from bert_score import score as bert_score
-from nltk.translate.bleu_score import SmoothingFunction, sentence_bleu
-from nltk.translate.meteor_score import meteor_score
-from rouge_score import rouge_scorer
-from sentence_transformers import SentenceTransformer
-
-# from load_dataset import load_locomo_dataset, QA, Turn, Session, Conversation
-from sentence_transformers.util import pytorch_cos_sim
-
-# Download required NLTK data
-try:
-    nltk.download("punkt", quiet=True)
-    nltk.download("wordnet", quiet=True)
-except Exception as e:
-    print(f"Error downloading NLTK data: {e}")
-
-# Initialize SentenceTransformer model (this will be reused)
-try:
-    sentence_model = SentenceTransformer("all-MiniLM-L6-v2")
-except Exception as e:
-    print(f"Warning: Could not load SentenceTransformer model: {e}")
-    sentence_model = None
-
-
-def simple_tokenize(text):
-    """Simple tokenization function."""
-    # Convert to string if not already
-    text = str(text)
-    return text.lower().replace(".", " ").replace(",", " ").replace("!", " ").replace("?", " ").split()
-
-
-def calculate_rouge_scores(prediction: str, reference: str) -> Dict[str, float]:
-    """Calculate ROUGE scores for prediction against reference."""
-    scorer = rouge_scorer.RougeScorer(["rouge1", "rouge2", "rougeL"], use_stemmer=True)
-    scores = scorer.score(reference, prediction)
-    return {
-        "rouge1_f": scores["rouge1"].fmeasure,
-        "rouge2_f": scores["rouge2"].fmeasure,
-        "rougeL_f": scores["rougeL"].fmeasure,
-    }
-
-
-def calculate_bleu_scores(prediction: str, reference: str) -> Dict[str, float]:
-    """Calculate BLEU scores with different n-gram settings."""
-    pred_tokens = nltk.word_tokenize(prediction.lower())
-    ref_tokens = [nltk.word_tokenize(reference.lower())]
-
-    weights_list = [(1, 0, 0, 0), (0.5, 0.5, 0, 0), (0.33, 0.33, 0.33, 0), (0.25, 0.25, 0.25, 0.25)]
-    smooth = SmoothingFunction().method1
-
-    scores = {}
-    for n, weights in enumerate(weights_list, start=1):
-        try:
-            score = sentence_bleu(ref_tokens, pred_tokens, weights=weights, smoothing_function=smooth)
-        except Exception as e:
-            print(f"Error calculating BLEU score: {e}")
-            score = 0.0
-        scores[f"bleu{n}"] = score
-
-    return scores
-
-
-def calculate_bert_scores(prediction: str, reference: str) -> Dict[str, float]:
-    """Calculate BERTScore for semantic similarity."""
-    try:
-        P, R, F1 = bert_score([prediction], [reference], lang="en", verbose=False)
-        return {"bert_precision": P.item(), "bert_recall": R.item(), "bert_f1": F1.item()}
-    except Exception as e:
-        print(f"Error calculating BERTScore: {e}")
-        return {"bert_precision": 0.0, "bert_recall": 0.0, "bert_f1": 0.0}
-
-
-def calculate_meteor_score(prediction: str, reference: str) -> float:
-    """Calculate METEOR score for the prediction."""
-    try:
-        return meteor_score([reference.split()], prediction.split())
-    except Exception as e:
-        print(f"Error calculating METEOR score: {e}")
-        return 0.0
-
-
-def calculate_sentence_similarity(prediction: str, reference: str) -> float:
-    """Calculate sentence embedding similarity using SentenceBERT."""
-    if sentence_model is None:
-        return 0.0
-    try:
-        # Encode sentences
-        embedding1 = sentence_model.encode([prediction], convert_to_tensor=True)
-        embedding2 = sentence_model.encode([reference], convert_to_tensor=True)
-
-        # Calculate cosine similarity
-        similarity = pytorch_cos_sim(embedding1, embedding2).item()
-        return float(similarity)
-    except Exception as e:
-        print(f"Error calculating sentence similarity: {e}")
-        return 0.0
-
-
-def calculate_metrics(prediction: str, reference: str) -> Dict[str, float]:
-    """Calculate comprehensive evaluation metrics for a prediction."""
-    # Handle empty or None values
-    if not prediction or not reference:
-        return {
-            "exact_match": 0,
-            "f1": 0.0,
-            "rouge1_f": 0.0,
-            "rouge2_f": 0.0,
-            "rougeL_f": 0.0,
-            "bleu1": 0.0,
-            "bleu2": 0.0,
-            "bleu3": 0.0,
-            "bleu4": 0.0,
-            "bert_f1": 0.0,
-            "meteor": 0.0,
-            "sbert_similarity": 0.0,
-        }
-
-    # Convert to strings if they're not already
-    prediction = str(prediction).strip()
-    reference = str(reference).strip()
-
-    # Calculate exact match
-    exact_match = int(prediction.lower() == reference.lower())
-
-    # Calculate token-based F1 score
-    pred_tokens = set(simple_tokenize(prediction))
-    ref_tokens = set(simple_tokenize(reference))
-    common_tokens = pred_tokens & ref_tokens
-
-    if not pred_tokens or not ref_tokens:
-        f1 = 0.0
-    else:
-        precision = len(common_tokens) / len(pred_tokens)
-        recall = len(common_tokens) / len(ref_tokens)
-        f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
-
-    # Calculate all scores
-    bleu_scores = calculate_bleu_scores(prediction, reference)
-
-    # Combine all metrics
-    metrics = {
-        "exact_match": exact_match,
-        "f1": f1,
-        **bleu_scores,
-    }
-
-    return metrics
-
-
-def aggregate_metrics(
-    all_metrics: List[Dict[str, float]], all_categories: List[int]
-) -> Dict[str, Dict[str, Union[float, Dict[str, float]]]]:
-    """Calculate aggregate statistics for all metrics, split by category."""
-    if not all_metrics:
-        return {}
-
-    # Initialize aggregates for overall and per-category metrics
-    aggregates = defaultdict(list)
-    category_aggregates = defaultdict(lambda: defaultdict(list))
-
-    # Collect all values for each metric, both overall and per category
-    for metrics, category in zip(all_metrics, all_categories):
-        for metric_name, value in metrics.items():
-            aggregates[metric_name].append(value)
-            category_aggregates[category][metric_name].append(value)
-
-    # Calculate statistics for overall metrics
-    results = {"overall": {}}
-
-    for metric_name, values in aggregates.items():
-        results["overall"][metric_name] = {
-            "mean": statistics.mean(values),
-            "std": statistics.stdev(values) if len(values) > 1 else 0.0,
-            "median": statistics.median(values),
-            "min": min(values),
-            "max": max(values),
-            "count": len(values),
-        }
-
-    # Calculate statistics for each category
-    for category in sorted(category_aggregates.keys()):
-        results[f"category_{category}"] = {}
-        for metric_name, values in category_aggregates[category].items():
-            if values:  # Only calculate if we have values for this category
-                results[f"category_{category}"][metric_name] = {
-                    "mean": statistics.mean(values),
-                    "std": statistics.stdev(values) if len(values) > 1 else 0.0,
-                    "median": statistics.median(values),
-                    "min": min(values),
-                    "max": max(values),
-                    "count": len(values),
-                }
-
-    return results

evaluation/prompts.py

@@ -1,147 +0,0 @@
-ANSWER_PROMPT_GRAPH = """
-    You are an intelligent memory assistant tasked with retrieving accurate information from 
-    conversation memories.
-
-    # CONTEXT:
-    You have access to memories from two speakers in a conversation. These memories contain 
-    timestamped information that may be relevant to answering the question. You also have 
-    access to knowledge graph relations for each user, showing connections between entities, 
-    concepts, and events relevant to that user.
-
-    # INSTRUCTIONS:
-    1. Carefully analyze all provided memories from both speakers
-    2. Pay special attention to the timestamps to determine the answer
-    3. If the question asks about a specific event or fact, look for direct evidence in the 
-       memories
-    4. If the memories contain contradictory information, prioritize the most recent memory
-    5. If there is a question about time references (like "last year", "two months ago", 
-       etc.), calculate the actual date based on the memory timestamp. For example, if a 
-       memory from 4 May 2022 mentions "went to India last year," then the trip occurred 
-       in 2021.
-    6. Always convert relative time references to specific dates, months, or years. For 
-       example, convert "last year" to "2022" or "two months ago" to "March 2023" based 
-       on the memory timestamp. Ignore the reference while answering the question.
-    7. Focus only on the content of the memories from both speakers. Do not confuse 
-       character names mentioned in memories with the actual users who created those 
-       memories.
-    8. The answer should be less than 5-6 words.
-    9. Use the knowledge graph relations to understand the user's knowledge network and 
-       identify important relationships between entities in the user's world.
-
-    # APPROACH (Think step by step):
-    1. First, examine all memories that contain information related to the question
-    2. Examine the timestamps and content of these memories carefully
-    3. Look for explicit mentions of dates, times, locations, or events that answer the 
-       question
-    4. If the answer requires calculation (e.g., converting relative time references), 
-       show your work
-    5. Analyze the knowledge graph relations to understand the user's knowledge context
-    6. Formulate a precise, concise answer based solely on the evidence in the memories
-    7. Double-check that your answer directly addresses the question asked
-    8. Ensure your final answer is specific and avoids vague time references
-
-    Memories for user {{speaker_1_user_id}}:
-
-    {{speaker_1_memories}}
-
-    Relations for user {{speaker_1_user_id}}:
-
-    {{speaker_1_graph_memories}}
-
-    Memories for user {{speaker_2_user_id}}:
-
-    {{speaker_2_memories}}
-
-    Relations for user {{speaker_2_user_id}}:
-
-    {{speaker_2_graph_memories}}
-
-    Question: {{question}}
-
-    Answer:
-    """
-
-
-ANSWER_PROMPT = """
-    You are an intelligent memory assistant tasked with retrieving accurate information from conversation memories.
-
-    # CONTEXT:
-    You have access to memories from two speakers in a conversation. These memories contain 
-    timestamped information that may be relevant to answering the question.
-
-    # INSTRUCTIONS:
-    1. Carefully analyze all provided memories from both speakers
-    2. Pay special attention to the timestamps to determine the answer
-    3. If the question asks about a specific event or fact, look for direct evidence in the memories
-    4. If the memories contain contradictory information, prioritize the most recent memory
-    5. If there is a question about time references (like "last year", "two months ago", etc.), 
-       calculate the actual date based on the memory timestamp. For example, if a memory from 
-       4 May 2022 mentions "went to India last year," then the trip occurred in 2021.
-    6. Always convert relative time references to specific dates, months, or years. For example, 
-       convert "last year" to "2022" or "two months ago" to "March 2023" based on the memory 
-       timestamp. Ignore the reference while answering the question.
-    7. Focus only on the content of the memories from both speakers. Do not confuse character 
-       names mentioned in memories with the actual users who created those memories.
-    8. The answer should be less than 5-6 words.
-
-    # APPROACH (Think step by step):
-    1. First, examine all memories that contain information related to the question
-    2. Examine the timestamps and content of these memories carefully
-    3. Look for explicit mentions of dates, times, locations, or events that answer the question
-    4. If the answer requires calculation (e.g., converting relative time references), show your work
-    5. Formulate a precise, concise answer based solely on the evidence in the memories
-    6. Double-check that your answer directly addresses the question asked
-    7. Ensure your final answer is specific and avoids vague time references
-
-    Memories for user {{speaker_1_user_id}}:
-
-    {{speaker_1_memories}}
-
-    Memories for user {{speaker_2_user_id}}:
-
-    {{speaker_2_memories}}
-
-    Question: {{question}}
-
-    Answer:
-    """
-
-
-ANSWER_PROMPT_ZEP = """
-    You are an intelligent memory assistant tasked with retrieving accurate information from conversation memories.
-
-    # CONTEXT:
-    You have access to memories from a conversation. These memories contain
-    timestamped information that may be relevant to answering the question.
-
-    # INSTRUCTIONS:
-    1. Carefully analyze all provided memories
-    2. Pay special attention to the timestamps to determine the answer
-    3. If the question asks about a specific event or fact, look for direct evidence in the memories
-    4. If the memories contain contradictory information, prioritize the most recent memory
-    5. If there is a question about time references (like "last year", "two months ago", etc.), 
-       calculate the actual date based on the memory timestamp. For example, if a memory from 
-       4 May 2022 mentions "went to India last year," then the trip occurred in 2021.
-    6. Always convert relative time references to specific dates, months, or years. For example, 
-       convert "last year" to "2022" or "two months ago" to "March 2023" based on the memory 
-       timestamp. Ignore the reference while answering the question.
-    7. Focus only on the content of the memories. Do not confuse character 
-       names mentioned in memories with the actual users who created those memories.
-    8. The answer should be less than 5-6 words.
-
-    # APPROACH (Think step by step):
-    1. First, examine all memories that contain information related to the question
-    2. Examine the timestamps and content of these memories carefully
-    3. Look for explicit mentions of dates, times, locations, or events that answer the question
-    4. If the answer requires calculation (e.g., converting relative time references), show your work
-    5. Formulate a precise, concise answer based solely on the evidence in the memories
-    6. Double-check that your answer directly addresses the question asked
-    7. Ensure your final answer is specific and avoids vague time references
-
-    Memories:
-
-    {{memories}}
-
-    Question: {{question}}
-    Answer:
-    """

evaluation/run_experiments.py

@@ -1,75 +0,0 @@
-import argparse
-import os
-
-from src.langmem import LangMemManager
-from src.memzero.add import MemoryADD
-from src.memzero.search import MemorySearch
-from src.openai.predict import OpenAIPredict
-from src.rag import RAGManager
-from src.utils import METHODS, TECHNIQUES
-from src.zep.add import ZepAdd
-from src.zep.search import ZepSearch
-
-
-class Experiment:
-    def __init__(self, technique_type, chunk_size):
-        self.technique_type = technique_type
-        self.chunk_size = chunk_size
-
-    def run(self):
-        print(f"Running experiment with technique: {self.technique_type}, chunk size: {self.chunk_size}")
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Run memory experiments")
-    parser.add_argument("--technique_type", choices=TECHNIQUES, default="mem0", help="Memory technique to use")
-    parser.add_argument("--method", choices=METHODS, default="add", help="Method to use")
-    parser.add_argument("--chunk_size", type=int, default=1000, help="Chunk size for processing")
-    parser.add_argument("--output_folder", type=str, default="results/", help="Output path for results")
-    parser.add_argument("--top_k", type=int, default=30, help="Number of top memories to retrieve")
-    parser.add_argument("--filter_memories", action="store_true", default=False, help="Whether to filter memories")
-    parser.add_argument("--is_graph", action="store_true", default=False, help="Whether to use graph-based search")
-    parser.add_argument("--num_chunks", type=int, default=1, help="Number of chunks to process")
-
-    args = parser.parse_args()
-
-    # Add your experiment logic here
-    print(f"Running experiments with technique: {args.technique_type}, chunk size: {args.chunk_size}")
-
-    if args.technique_type == "mem0":
-        if args.method == "add":
-            memory_manager = MemoryADD(data_path="dataset/locomo10.json", is_graph=args.is_graph)
-            memory_manager.process_all_conversations()
-        elif args.method == "search":
-            output_file_path = os.path.join(
-                args.output_folder,
-                f"mem0_results_top_{args.top_k}_filter_{args.filter_memories}_graph_{args.is_graph}.json",
-            )
-            memory_searcher = MemorySearch(output_file_path, args.top_k, args.filter_memories, args.is_graph)
-            memory_searcher.process_data_file("dataset/locomo10.json")
-    elif args.technique_type == "rag":
-        output_file_path = os.path.join(args.output_folder, f"rag_results_{args.chunk_size}_k{args.num_chunks}.json")
-        rag_manager = RAGManager(data_path="dataset/locomo10_rag.json", chunk_size=args.chunk_size, k=args.num_chunks)
-        rag_manager.process_all_conversations(output_file_path)
-    elif args.technique_type == "langmem":
-        output_file_path = os.path.join(args.output_folder, "langmem_results.json")
-        langmem_manager = LangMemManager(dataset_path="dataset/locomo10_rag.json")
-        langmem_manager.process_all_conversations(output_file_path)
-    elif args.technique_type == "zep":
-        if args.method == "add":
-            zep_manager = ZepAdd(data_path="dataset/locomo10.json")
-            zep_manager.process_all_conversations("1")
-        elif args.method == "search":
-            output_file_path = os.path.join(args.output_folder, "zep_search_results.json")
-            zep_manager = ZepSearch()
-            zep_manager.process_data_file("dataset/locomo10.json", "1", output_file_path)
-    elif args.technique_type == "openai":
-        output_file_path = os.path.join(args.output_folder, "openai_results.json")
-        openai_manager = OpenAIPredict()
-        openai_manager.process_data_file("dataset/locomo10.json", output_file_path)
-    else:
-        raise ValueError(f"Invalid technique type: {args.technique_type}")
-
-
-if __name__ == "__main__":
-    main()

evaluation/src/langmem.py

@@ -1,185 +0,0 @@
-import json
-import multiprocessing as mp
-import os
-import time
-from collections import defaultdict
-
-from dotenv import load_dotenv
-from jinja2 import Template
-from langgraph.checkpoint.memory import MemorySaver
-from langgraph.prebuilt import create_react_agent
-from langgraph.store.memory import InMemoryStore
-from langgraph.utils.config import get_store
-from langmem import create_manage_memory_tool, create_search_memory_tool
-from openai import OpenAI
-from prompts import ANSWER_PROMPT
-from tqdm import tqdm
-
-load_dotenv()
-
-client = OpenAI()
-
-ANSWER_PROMPT_TEMPLATE = Template(ANSWER_PROMPT)
-
-
-def get_answer(question, speaker_1_user_id, speaker_1_memories, speaker_2_user_id, speaker_2_memories):
-    prompt = ANSWER_PROMPT_TEMPLATE.render(
-        question=question,
-        speaker_1_user_id=speaker_1_user_id,
-        speaker_1_memories=speaker_1_memories,
-        speaker_2_user_id=speaker_2_user_id,
-        speaker_2_memories=speaker_2_memories,
-    )
-
-    t1 = time.time()
-    response = client.chat.completions.create(
-        model=os.getenv("MODEL"), messages=[{"role": "system", "content": prompt}], temperature=0.0
-    )
-    t2 = time.time()
-    return response.choices[0].message.content, t2 - t1
-
-
-def prompt(state):
-    """Prepare the messages for the LLM."""
-    store = get_store()
-    memories = store.search(
-        ("memories",),
-        query=state["messages"][-1].content,
-    )
-    system_msg = f"""You are a helpful assistant.
-
-## Memories
-<memories>
-{memories}
-</memories>
-"""
-    return [{"role": "system", "content": system_msg}, *state["messages"]]
-
-
-class LangMem:
-    def __init__(
-        self,
-    ):
-        self.store = InMemoryStore(
-            index={
-                "dims": 1536,
-                "embed": f"openai:{os.getenv('EMBEDDING_MODEL')}",
-            }
-        )
-        self.checkpointer = MemorySaver()  # Checkpoint graph state
-
-        self.agent = create_react_agent(
-            f"openai:{os.getenv('MODEL')}",
-            prompt=prompt,
-            tools=[
-                create_manage_memory_tool(namespace=("memories",)),
-                create_search_memory_tool(namespace=("memories",)),
-            ],
-            store=self.store,
-            checkpointer=self.checkpointer,
-        )
-
-    def add_memory(self, message, config):
-        return self.agent.invoke({"messages": [{"role": "user", "content": message}]}, config=config)
-
-    def search_memory(self, query, config):
-        try:
-            t1 = time.time()
-            response = self.agent.invoke({"messages": [{"role": "user", "content": query}]}, config=config)
-            t2 = time.time()
-            return response["messages"][-1].content, t2 - t1
-        except Exception as e:
-            print(f"Error in search_memory: {e}")
-            return "", t2 - t1
-
-
-class LangMemManager:
-    def __init__(self, dataset_path):
-        self.dataset_path = dataset_path
-        with open(self.dataset_path, "r") as f:
-            self.data = json.load(f)
-
-    def process_all_conversations(self, output_file_path):
-        OUTPUT = defaultdict(list)
-
-        # Process conversations in parallel with multiple workers
-        def process_conversation(key_value_pair):
-            key, value = key_value_pair
-            result = defaultdict(list)
-
-            chat_history = value["conversation"]
-            questions = value["question"]
-
-            agent1 = LangMem()
-            agent2 = LangMem()
-            config = {"configurable": {"thread_id": f"thread-{key}"}}
-            speakers = set()
-
-            # Identify speakers
-            for conv in chat_history:
-                speakers.add(conv["speaker"])
-
-            if len(speakers) != 2:
-                raise ValueError(f"Expected 2 speakers, got {len(speakers)}")
-
-            speaker1 = list(speakers)[0]
-            speaker2 = list(speakers)[1]
-
-            # Add memories for each message
-            for conv in tqdm(chat_history, desc=f"Processing messages {key}", leave=False):
-                message = f"{conv['timestamp']} | {conv['speaker']}: {conv['text']}"
-                if conv["speaker"] == speaker1:
-                    agent1.add_memory(message, config)
-                elif conv["speaker"] == speaker2:
-                    agent2.add_memory(message, config)
-                else:
-                    raise ValueError(f"Expected speaker1 or speaker2, got {conv['speaker']}")
-
-            # Process questions
-            for q in tqdm(questions, desc=f"Processing questions {key}", leave=False):
-                category = q["category"]
-
-                if int(category) == 5:
-                    continue
-
-                answer = q["answer"]
-                question = q["question"]
-                response1, speaker1_memory_time = agent1.search_memory(question, config)
-                response2, speaker2_memory_time = agent2.search_memory(question, config)
-
-                generated_answer, response_time = get_answer(question, speaker1, response1, speaker2, response2)
-
-                result[key].append(
-                    {
-                        "question": question,
-                        "answer": answer,
-                        "response1": response1,
-                        "response2": response2,
-                        "category": category,
-                        "speaker1_memory_time": speaker1_memory_time,
-                        "speaker2_memory_time": speaker2_memory_time,
-                        "response_time": response_time,
-                        "response": generated_answer,
-                    }
-                )
-
-            return result
-
-        # Use multiprocessing to process conversations in parallel
-        with mp.Pool(processes=10) as pool:
-            results = list(
-                tqdm(
-                    pool.imap(process_conversation, list(self.data.items())),
-                    total=len(self.data),
-                    desc="Processing conversations",
-                )
-            )
-
-        # Combine results from all workers
-        for result in results:
-            for key, items in result.items():
-                OUTPUT[key].extend(items)
-
-        # Save final results
-        with open(output_file_path, "w") as f:
-            json.dump(OUTPUT, f, indent=4)

evaluation/src/memzero/add.py

@@ -1,141 +0,0 @@
-import json
-import os
-import threading
-import time
-from concurrent.futures import ThreadPoolExecutor
-
-from dotenv import load_dotenv
-from tqdm import tqdm
-
-from mem0 import MemoryClient
-
-load_dotenv()
-
-
-# Update custom instructions
-custom_instructions = """
-Generate personal memories that follow these guidelines:
-
-1. Each memory should be self-contained with complete context, including:
-   - The person's name, do not use "user" while creating memories
-   - Personal details (career aspirations, hobbies, life circumstances)
-   - Emotional states and reactions
-   - Ongoing journeys or future plans
-   - Specific dates when events occurred
-
-2. Include meaningful personal narratives focusing on:
-   - Identity and self-acceptance journeys
-   - Family planning and parenting
-   - Creative outlets and hobbies
-   - Mental health and self-care activities
-   - Career aspirations and education goals
-   - Important life events and milestones
-
-3. Make each memory rich with specific details rather than general statements
-   - Include timeframes (exact dates when possible)
-   - Name specific activities (e.g., "charity race for mental health" rather than just "exercise")
-   - Include emotional context and personal growth elements
-
-4. Extract memories only from user messages, not incorporating assistant responses
-
-5. Format each memory as a paragraph with a clear narrative structure that captures the person's experience, challenges, and aspirations
-"""
-
-
-class MemoryADD:
-    def __init__(self, data_path=None, batch_size=2, is_graph=False):
-        self.mem0_client = MemoryClient(
-            api_key=os.getenv("MEM0_API_KEY"),
-            org_id=os.getenv("MEM0_ORGANIZATION_ID"),
-            project_id=os.getenv("MEM0_PROJECT_ID"),
-        )
-
-        self.mem0_client.update_project(custom_instructions=custom_instructions)
-        self.batch_size = batch_size
-        self.data_path = data_path
-        self.data = None
-        self.is_graph = is_graph
-        if data_path:
-            self.load_data()
-
-    def load_data(self):
-        with open(self.data_path, "r") as f:
-            self.data = json.load(f)
-        return self.data
-
-    def add_memory(self, user_id, message, metadata, retries=3):
-        for attempt in range(retries):
-            try:
-                _ = self.mem0_client.add(
-                    message, user_id=user_id, version="v2", metadata=metadata, enable_graph=self.is_graph
-                )
-                return
-            except Exception as e:
-                if attempt < retries - 1:
-                    time.sleep(1)  # Wait before retrying
-                    continue
-                else:
-                    raise e
-
-    def add_memories_for_speaker(self, speaker, messages, timestamp, desc):
-        for i in tqdm(range(0, len(messages), self.batch_size), desc=desc):
-            batch_messages = messages[i : i + self.batch_size]
-            self.add_memory(speaker, batch_messages, metadata={"timestamp": timestamp})
-
-    def process_conversation(self, item, idx):
-        conversation = item["conversation"]
-        speaker_a = conversation["speaker_a"]
-        speaker_b = conversation["speaker_b"]
-
-        speaker_a_user_id = f"{speaker_a}_{idx}"
-        speaker_b_user_id = f"{speaker_b}_{idx}"
-
-        # delete all memories for the two users
-        self.mem0_client.delete_all(user_id=speaker_a_user_id)
-        self.mem0_client.delete_all(user_id=speaker_b_user_id)
-
-        for key in conversation.keys():
-            if key in ["speaker_a", "speaker_b"] or "date" in key or "timestamp" in key:
-                continue
-
-            date_time_key = key + "_date_time"
-            timestamp = conversation[date_time_key]
-            chats = conversation[key]
-
-            messages = []
-            messages_reverse = []
-            for chat in chats:
-                if chat["speaker"] == speaker_a:
-                    messages.append({"role": "user", "content": f"{speaker_a}: {chat['text']}"})
-                    messages_reverse.append({"role": "assistant", "content": f"{speaker_a}: {chat['text']}"})
-                elif chat["speaker"] == speaker_b:
-                    messages.append({"role": "assistant", "content": f"{speaker_b}: {chat['text']}"})
-                    messages_reverse.append({"role": "user", "content": f"{speaker_b}: {chat['text']}"})
-                else:
-                    raise ValueError(f"Unknown speaker: {chat['speaker']}")
-
-            # add memories for the two users on different threads
-            thread_a = threading.Thread(
-                target=self.add_memories_for_speaker,
-                args=(speaker_a_user_id, messages, timestamp, "Adding Memories for Speaker A"),
-            )
-            thread_b = threading.Thread(
-                target=self.add_memories_for_speaker,
-                args=(speaker_b_user_id, messages_reverse, timestamp, "Adding Memories for Speaker B"),
-            )
-
-            thread_a.start()
-            thread_b.start()
-            thread_a.join()
-            thread_b.join()
-
-        print("Messages added successfully")
-
-    def process_all_conversations(self, max_workers=10):
-        if not self.data:
-            raise ValueError("No data loaded. Please set data_path and call load_data() first.")
-        with ThreadPoolExecutor(max_workers=max_workers) as executor:
-            futures = [executor.submit(self.process_conversation, item, idx) for idx, item in enumerate(self.data)]
-
-            for future in futures:
-                future.result()

evaluation/src/memzero/search.py

@@ -1,215 +0,0 @@
-import json
-import os
-import time
-from collections import defaultdict
-from concurrent.futures import ThreadPoolExecutor
-
-from dotenv import load_dotenv
-from jinja2 import Template
-from openai import OpenAI
-from prompts import ANSWER_PROMPT, ANSWER_PROMPT_GRAPH
-from tqdm import tqdm
-
-from mem0 import MemoryClient
-
-load_dotenv()
-
-
-class MemorySearch:
-    def __init__(self, output_path="results.json", top_k=10, filter_memories=False, is_graph=False):
-        self.mem0_client = MemoryClient(
-            api_key=os.getenv("MEM0_API_KEY"),
-            org_id=os.getenv("MEM0_ORGANIZATION_ID"),
-            project_id=os.getenv("MEM0_PROJECT_ID"),
-        )
-        self.top_k = top_k
-        self.openai_client = OpenAI()
-        self.results = defaultdict(list)
-        self.output_path = output_path
-        self.filter_memories = filter_memories
-        self.is_graph = is_graph
-
-        if self.is_graph:
-            self.ANSWER_PROMPT = ANSWER_PROMPT_GRAPH
-        else:
-            self.ANSWER_PROMPT = ANSWER_PROMPT
-
-    def search_memory(self, user_id, query, max_retries=3, retry_delay=1):
-        start_time = time.time()
-        retries = 0
-        while retries < max_retries:
-            try:
-                if self.is_graph:
-                    print("Searching with graph")
-                    memories = self.mem0_client.search(
-                        query,
-                        user_id=user_id,
-                        top_k=self.top_k,
-                        filter_memories=self.filter_memories,
-                        enable_graph=True,
-                        output_format="v1.1",
-                    )
-                else:
-                    memories = self.mem0_client.search(
-                        query, user_id=user_id, top_k=self.top_k, filter_memories=self.filter_memories
-                    )
-                break
-            except Exception as e:
-                print("Retrying...")
-                retries += 1
-                if retries >= max_retries:
-                    raise e
-                time.sleep(retry_delay)
-
-        end_time = time.time()
-        if not self.is_graph:
-            semantic_memories = [
-                {
-                    "memory": memory["memory"],
-                    "timestamp": memory["metadata"]["timestamp"],
-                    "score": round(memory["score"], 2),
-                }
-                for memory in memories
-            ]
-            graph_memories = None
-        else:
-            semantic_memories = [
-                {
-                    "memory": memory["memory"],
-                    "timestamp": memory["metadata"]["timestamp"],
-                    "score": round(memory["score"], 2),
-                }
-                for memory in memories["results"]
-            ]
-            graph_memories = [
-                {"source": relation["source"], "relationship": relation["relationship"], "target": relation["target"]}
-                for relation in memories["relations"]
-            ]
-        return semantic_memories, graph_memories, end_time - start_time
-
-    def answer_question(self, speaker_1_user_id, speaker_2_user_id, question, answer, category):
-        speaker_1_memories, speaker_1_graph_memories, speaker_1_memory_time = self.search_memory(
-            speaker_1_user_id, question
-        )
-        speaker_2_memories, speaker_2_graph_memories, speaker_2_memory_time = self.search_memory(
-            speaker_2_user_id, question
-        )
-
-        search_1_memory = [f"{item['timestamp']}: {item['memory']}" for item in speaker_1_memories]
-        search_2_memory = [f"{item['timestamp']}: {item['memory']}" for item in speaker_2_memories]
-
-        template = Template(self.ANSWER_PROMPT)
-        answer_prompt = template.render(
-            speaker_1_user_id=speaker_1_user_id.split("_")[0],
-            speaker_2_user_id=speaker_2_user_id.split("_")[0],
-            speaker_1_memories=json.dumps(search_1_memory, indent=4),
-            speaker_2_memories=json.dumps(search_2_memory, indent=4),
-            speaker_1_graph_memories=json.dumps(speaker_1_graph_memories, indent=4),
-            speaker_2_graph_memories=json.dumps(speaker_2_graph_memories, indent=4),
-            question=question,
-        )
-
-        t1 = time.time()
-        response = self.openai_client.chat.completions.create(
-            model=os.getenv("MODEL"), messages=[{"role": "system", "content": answer_prompt}], temperature=0.0
-        )
-        t2 = time.time()
-        response_time = t2 - t1
-        return (
-            response.choices[0].message.content,
-            speaker_1_memories,
-            speaker_2_memories,
-            speaker_1_memory_time,
-            speaker_2_memory_time,
-            speaker_1_graph_memories,
-            speaker_2_graph_memories,
-            response_time,
-        )
-
-    def process_question(self, val, speaker_a_user_id, speaker_b_user_id):
-        question = val.get("question", "")
-        answer = val.get("answer", "")
-        category = val.get("category", -1)
-        evidence = val.get("evidence", [])
-        adversarial_answer = val.get("adversarial_answer", "")
-
-        (
-            response,
-            speaker_1_memories,
-            speaker_2_memories,
-            speaker_1_memory_time,
-            speaker_2_memory_time,
-            speaker_1_graph_memories,
-            speaker_2_graph_memories,
-            response_time,
-        ) = self.answer_question(speaker_a_user_id, speaker_b_user_id, question, answer, category)
-
-        result = {
-            "question": question,
-            "answer": answer,
-            "category": category,
-            "evidence": evidence,
-            "response": response,
-            "adversarial_answer": adversarial_answer,
-            "speaker_1_memories": speaker_1_memories,
-            "speaker_2_memories": speaker_2_memories,
-            "num_speaker_1_memories": len(speaker_1_memories),
-            "num_speaker_2_memories": len(speaker_2_memories),
-            "speaker_1_memory_time": speaker_1_memory_time,
-            "speaker_2_memory_time": speaker_2_memory_time,
-            "speaker_1_graph_memories": speaker_1_graph_memories,
-            "speaker_2_graph_memories": speaker_2_graph_memories,
-            "response_time": response_time,
-        }
-
-        # Save results after each question is processed
-        with open(self.output_path, "w") as f:
-            json.dump(self.results, f, indent=4)
-
-        return result
-
-    def process_data_file(self, file_path):
-        with open(file_path, "r") as f:
-            data = json.load(f)
-
-        for idx, item in tqdm(enumerate(data), total=len(data), desc="Processing conversations"):
-            qa = item["qa"]
-            conversation = item["conversation"]
-            speaker_a = conversation["speaker_a"]
-            speaker_b = conversation["speaker_b"]
-
-            speaker_a_user_id = f"{speaker_a}_{idx}"
-            speaker_b_user_id = f"{speaker_b}_{idx}"
-
-            for question_item in tqdm(
-                qa, total=len(qa), desc=f"Processing questions for conversation {idx}", leave=False
-            ):
-                result = self.process_question(question_item, speaker_a_user_id, speaker_b_user_id)
-                self.results[idx].append(result)
-
-                # Save results after each question is processed
-                with open(self.output_path, "w") as f:
-                    json.dump(self.results, f, indent=4)
-
-        # Final save at the end
-        with open(self.output_path, "w") as f:
-            json.dump(self.results, f, indent=4)
-
-    def process_questions_parallel(self, qa_list, speaker_a_user_id, speaker_b_user_id, max_workers=1):
-        def process_single_question(val):
-            result = self.process_question(val, speaker_a_user_id, speaker_b_user_id)
-            # Save results after each question is processed
-            with open(self.output_path, "w") as f:
-                json.dump(self.results, f, indent=4)
-            return result
-
-        with ThreadPoolExecutor(max_workers=max_workers) as executor:
-            results = list(
-                tqdm(executor.map(process_single_question, qa_list), total=len(qa_list), desc="Answering Questions")
-            )
-
-        # Final save at the end
-        with open(self.output_path, "w") as f:
-            json.dump(self.results, f, indent=4)
-
-        return results

evaluation/src/openai/predict.py

@@ -1,131 +0,0 @@
-import argparse
-import json
-import os
-import time
-from collections import defaultdict
-
-from dotenv import load_dotenv
-from jinja2 import Template
-from openai import OpenAI
-from tqdm import tqdm
-
-load_dotenv()
-
-
-ANSWER_PROMPT = """
-    You are an intelligent memory assistant tasked with retrieving accurate information from conversation memories.
-
-    # CONTEXT:
-    You have access to memories from a conversation. These memories contain
-    timestamped information that may be relevant to answering the question.
-
-    # INSTRUCTIONS:
-    1. Carefully analyze all provided memories
-    2. Pay special attention to the timestamps to determine the answer
-    3. If the question asks about a specific event or fact, look for direct evidence in the memories
-    4. If the memories contain contradictory information, prioritize the most recent memory
-    5. If there is a question about time references (like "last year", "two months ago", etc.), 
-       calculate the actual date based on the memory timestamp. For example, if a memory from 
-       4 May 2022 mentions "went to India last year," then the trip occurred in 2021.
-    6. Always convert relative time references to specific dates, months, or years. For example, 
-       convert "last year" to "2022" or "two months ago" to "March 2023" based on the memory 
-       timestamp. Ignore the reference while answering the question.
-    7. Focus only on the content of the memories. Do not confuse character 
-       names mentioned in memories with the actual users who created those memories.
-    8. The answer should be less than 5-6 words.
-
-    # APPROACH (Think step by step):
-    1. First, examine all memories that contain information related to the question
-    2. Examine the timestamps and content of these memories carefully
-    3. Look for explicit mentions of dates, times, locations, or events that answer the question
-    4. If the answer requires calculation (e.g., converting relative time references), show your work
-    5. Formulate a precise, concise answer based solely on the evidence in the memories
-    6. Double-check that your answer directly addresses the question asked
-    7. Ensure your final answer is specific and avoids vague time references
-
-    Memories:
-
-    {{memories}}
-
-    Question: {{question}}
-    Answer:
-    """
-
-
-class OpenAIPredict:
-    def __init__(self, model="gpt-4o-mini"):
-        self.model = model
-        self.openai_client = OpenAI()
-        self.results = defaultdict(list)
-
-    def search_memory(self, idx):
-        with open(f"memories/{idx}.txt", "r") as file:
-            memories = file.read()
-
-        return memories, 0
-
-    def process_question(self, val, idx):
-        question = val.get("question", "")
-        answer = val.get("answer", "")
-        category = val.get("category", -1)
-        evidence = val.get("evidence", [])
-        adversarial_answer = val.get("adversarial_answer", "")
-
-        response, search_memory_time, response_time, context = self.answer_question(idx, question)
-
-        result = {
-            "question": question,
-            "answer": answer,
-            "category": category,
-            "evidence": evidence,
-            "response": response,
-            "adversarial_answer": adversarial_answer,
-            "search_memory_time": search_memory_time,
-            "response_time": response_time,
-            "context": context,
-        }
-
-        return result
-
-    def answer_question(self, idx, question):
-        memories, search_memory_time = self.search_memory(idx)
-
-        template = Template(ANSWER_PROMPT)
-        answer_prompt = template.render(memories=memories, question=question)
-
-        t1 = time.time()
-        response = self.openai_client.chat.completions.create(
-            model=os.getenv("MODEL"), messages=[{"role": "system", "content": answer_prompt}], temperature=0.0
-        )
-        t2 = time.time()
-        response_time = t2 - t1
-        return response.choices[0].message.content, search_memory_time, response_time, memories
-
-    def process_data_file(self, file_path, output_file_path):
-        with open(file_path, "r") as f:
-            data = json.load(f)
-
-        for idx, item in tqdm(enumerate(data), total=len(data), desc="Processing conversations"):
-            qa = item["qa"]
-
-            for question_item in tqdm(
-                qa, total=len(qa), desc=f"Processing questions for conversation {idx}", leave=False
-            ):
-                result = self.process_question(question_item, idx)
-                self.results[idx].append(result)
-
-                # Save results after each question is processed
-                with open(output_file_path, "w") as f:
-                    json.dump(self.results, f, indent=4)
-
-        # Final save at the end
-        with open(output_file_path, "w") as f:
-            json.dump(self.results, f, indent=4)
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--output_file_path", type=str, required=True)
-    args = parser.parse_args()
-    openai_predict = OpenAIPredict()
-    openai_predict.process_data_file("../../dataset/locomo10.json", args.output_file_path)

evaluation/src/rag.py

@@ -1,183 +0,0 @@
-import json
-import os
-import time
-from collections import defaultdict
-
-import numpy as np
-import tiktoken
-from dotenv import load_dotenv
-from jinja2 import Template
-from openai import OpenAI
-from tqdm import tqdm
-
-load_dotenv()
-
-PROMPT = """
-# Question: 
-{{QUESTION}}
-
-# Context: 
-{{CONTEXT}}
-
-# Short answer:
-"""
-
-
-class RAGManager:
-    def __init__(self, data_path="dataset/locomo10_rag.json", chunk_size=500, k=1):
-        self.model = os.getenv("MODEL")
-        self.client = OpenAI()
-        self.data_path = data_path
-        self.chunk_size = chunk_size
-        self.k = k
-
-    def generate_response(self, question, context):
-        template = Template(PROMPT)
-        prompt = template.render(CONTEXT=context, QUESTION=question)
-
-        max_retries = 3
-        retries = 0
-
-        while retries <= max_retries:
-            try:
-                t1 = time.time()
-                response = self.client.chat.completions.create(
-                    model=self.model,
-                    messages=[
-                        {
-                            "role": "system",
-                            "content": "You are a helpful assistant that can answer "
-                            "questions based on the provided context."
-                            "If the question involves timing, use the conversation date for reference."
-                            "Provide the shortest possible answer."
-                            "Use words directly from the conversation when possible."
-                            "Avoid using subjects in your answer.",
-                        },
-                        {"role": "user", "content": prompt},
-                    ],
-                    temperature=0,
-                )
-                t2 = time.time()
-                return response.choices[0].message.content.strip(), t2 - t1
-            except Exception as e:
-                retries += 1
-                if retries > max_retries:
-                    raise e
-                time.sleep(1)  # Wait before retrying
-
-    def clean_chat_history(self, chat_history):
-        cleaned_chat_history = ""
-        for c in chat_history:
-            cleaned_chat_history += f"{c['timestamp']} | {c['speaker']}: {c['text']}\n"
-
-        return cleaned_chat_history
-
-    def calculate_embedding(self, document):
-        response = self.client.embeddings.create(model=os.getenv("EMBEDDING_MODEL"), input=document)
-        return response.data[0].embedding
-
-    def calculate_similarity(self, embedding1, embedding2):
-        return np.dot(embedding1, embedding2) / (np.linalg.norm(embedding1) * np.linalg.norm(embedding2))
-
-    def search(self, query, chunks, embeddings, k=1):
-        """
-        Search for the top-k most similar chunks to the query.
-
-        Args:
-            query: The query string
-            chunks: List of text chunks
-            embeddings: List of embeddings for each chunk
-            k: Number of top chunks to return (default: 1)
-
-        Returns:
-            combined_chunks: The combined text of the top-k chunks
-            search_time: Time taken for the search
-        """
-        t1 = time.time()
-        query_embedding = self.calculate_embedding(query)
-        similarities = [self.calculate_similarity(query_embedding, embedding) for embedding in embeddings]
-
-        # Get indices of top-k most similar chunks
-        if k == 1:
-            # Original behavior - just get the most similar chunk
-            top_indices = [np.argmax(similarities)]
-        else:
-            # Get indices of top-k chunks
-            top_indices = np.argsort(similarities)[-k:][::-1]
-
-        # Combine the top-k chunks
-        combined_chunks = "\n<->\n".join([chunks[i] for i in top_indices])
-
-        t2 = time.time()
-        return combined_chunks, t2 - t1
-
-    def create_chunks(self, chat_history, chunk_size=500):
-        """
-        Create chunks using tiktoken for more accurate token counting
-        """
-        # Get the encoding for the model
-        encoding = tiktoken.encoding_for_model(os.getenv("EMBEDDING_MODEL"))
-
-        documents = self.clean_chat_history(chat_history)
-
-        if chunk_size == -1:
-            return [documents], []
-
-        chunks = []
-
-        # Encode the document
-        tokens = encoding.encode(documents)
-
-        # Split into chunks based on token count
-        for i in range(0, len(tokens), chunk_size):
-            chunk_tokens = tokens[i : i + chunk_size]
-            chunk = encoding.decode(chunk_tokens)
-            chunks.append(chunk)
-
-        embeddings = []
-        for chunk in chunks:
-            embedding = self.calculate_embedding(chunk)
-            embeddings.append(embedding)
-
-        return chunks, embeddings
-
-    def process_all_conversations(self, output_file_path):
-        with open(self.data_path, "r") as f:
-            data = json.load(f)
-
-        FINAL_RESULTS = defaultdict(list)
-        for key, value in tqdm(data.items(), desc="Processing conversations"):
-            chat_history = value["conversation"]
-            questions = value["question"]
-
-            chunks, embeddings = self.create_chunks(chat_history, self.chunk_size)
-
-            for item in tqdm(questions, desc="Answering questions", leave=False):
-                question = item["question"]
-                answer = item.get("answer", "")
-                category = item["category"]
-
-                if self.chunk_size == -1:
-                    context = chunks[0]
-                    search_time = 0
-                else:
-                    context, search_time = self.search(question, chunks, embeddings, k=self.k)
-                response, response_time = self.generate_response(question, context)
-
-                FINAL_RESULTS[key].append(
-                    {
-                        "question": question,
-                        "answer": answer,
-                        "category": category,
-                        "context": context,
-                        "response": response,
-                        "search_time": search_time,
-                        "response_time": response_time,
-                    }
-                )
-                with open(output_file_path, "w+") as f:
-                    json.dump(FINAL_RESULTS, f, indent=4)
-
-        # Save results
-        with open(output_file_path, "w+") as f:
-            json.dump(FINAL_RESULTS, f, indent=4)

evaluation/src/utils.py

@@ -1,3 +0,0 @@
-TECHNIQUES = ["mem0", "rag", "langmem", "zep", "openai"]
-
-METHODS = ["add", "search"]

evaluation/src/zep/add.py

@@ -1,76 +0,0 @@
-import argparse
-import json
-import os
-
-from dotenv import load_dotenv
-from tqdm import tqdm
-from zep_cloud import Message
-from zep_cloud.client import Zep
-
-load_dotenv()
-
-
-class ZepAdd:
-    def __init__(self, data_path=None):
-        self.zep_client = Zep(api_key=os.getenv("ZEP_API_KEY"))
-        self.data_path = data_path
-        self.data = None
-        if data_path:
-            self.load_data()
-
-    def load_data(self):
-        with open(self.data_path, "r") as f:
-            self.data = json.load(f)
-        return self.data
-
-    def process_conversation(self, run_id, item, idx):
-        conversation = item["conversation"]
-
-        user_id = f"run_id_{run_id}_experiment_user_{idx}"
-        session_id = f"run_id_{run_id}_experiment_session_{idx}"
-
-        # # delete all memories for the two users
-        # self.zep_client.user.delete(user_id=user_id)
-        # self.zep_client.memory.delete(session_id=session_id)
-
-        self.zep_client.user.add(user_id=user_id)
-        self.zep_client.memory.add_session(
-            user_id=user_id,
-            session_id=session_id,
-        )
-
-        print("Starting to add memories... for user", user_id)
-        for key in tqdm(conversation.keys(), desc=f"Processing user {user_id}"):
-            if key in ["speaker_a", "speaker_b"] or "date" in key:
-                continue
-
-            date_time_key = key + "_date_time"
-            timestamp = conversation[date_time_key]
-            chats = conversation[key]
-
-            for chat in tqdm(chats, desc=f"Adding chats for {key}", leave=False):
-                self.zep_client.memory.add(
-                    session_id=session_id,
-                    messages=[
-                        Message(
-                            role=chat["speaker"],
-                            role_type="user",
-                            content=f"{timestamp}: {chat['text']}",
-                        )
-                    ],
-                )
-
-    def process_all_conversations(self, run_id):
-        if not self.data:
-            raise ValueError("No data loaded. Please set data_path and call load_data() first.")
-        for idx, item in tqdm(enumerate(self.data)):
-            if idx == 0:
-                self.process_conversation(run_id, item, idx)
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--run_id", type=str, required=True)
-    args = parser.parse_args()
-    zep_add = ZepAdd(data_path="../../dataset/locomo10.json")
-    zep_add.process_all_conversations(args.run_id)

evaluation/src/zep/search.py

@@ -1,140 +0,0 @@
-import argparse
-import json
-import os
-import time
-from collections import defaultdict
-
-from dotenv import load_dotenv
-from jinja2 import Template
-from openai import OpenAI
-from prompts import ANSWER_PROMPT_ZEP
-from tqdm import tqdm
-from zep_cloud import EntityEdge, EntityNode
-from zep_cloud.client import Zep
-
-load_dotenv()
-
-TEMPLATE = """
-FACTS and ENTITIES represent relevant context to the current conversation.
-
-# These are the most relevant facts and their valid date ranges
-# format: FACT (Date range: from - to)
-
-{facts}
-
-
-# These are the most relevant entities
-# ENTITY_NAME: entity summary
-
-{entities}
-
-"""
-
-
-class ZepSearch:
-    def __init__(self):
-        self.zep_client = Zep(api_key=os.getenv("ZEP_API_KEY"))
-        self.results = defaultdict(list)
-        self.openai_client = OpenAI()
-
-    def format_edge_date_range(self, edge: EntityEdge) -> str:
-        # return f"{datetime(edge.valid_at).strftime('%Y-%m-%d %H:%M:%S') if edge.valid_at else 'date unknown'} - {(edge.invalid_at.strftime('%Y-%m-%d %H:%M:%S') if edge.invalid_at else 'present')}"
-        return f"{edge.valid_at if edge.valid_at else 'date unknown'} - {(edge.invalid_at if edge.invalid_at else 'present')}"
-
-    def compose_search_context(self, edges: list[EntityEdge], nodes: list[EntityNode]) -> str:
-        facts = [f"  - {edge.fact} ({self.format_edge_date_range(edge)})" for edge in edges]
-        entities = [f"  - {node.name}: {node.summary}" for node in nodes]
-        return TEMPLATE.format(facts="\n".join(facts), entities="\n".join(entities))
-
-    def search_memory(self, run_id, idx, query, max_retries=3, retry_delay=1):
-        start_time = time.time()
-        retries = 0
-        while retries < max_retries:
-            try:
-                user_id = f"run_id_{run_id}_experiment_user_{idx}"
-                edges_results = (
-                    self.zep_client.graph.search(
-                        user_id=user_id, reranker="cross_encoder", query=query, scope="edges", limit=20
-                    )
-                ).edges
-                node_results = (
-                    self.zep_client.graph.search(user_id=user_id, reranker="rrf", query=query, scope="nodes", limit=20)
-                ).nodes
-                context = self.compose_search_context(edges_results, node_results)
-                break
-            except Exception as e:
-                print("Retrying...")
-                retries += 1
-                if retries >= max_retries:
-                    raise e
-                time.sleep(retry_delay)
-
-        end_time = time.time()
-
-        return context, end_time - start_time
-
-    def process_question(self, run_id, val, idx):
-        question = val.get("question", "")
-        answer = val.get("answer", "")
-        category = val.get("category", -1)
-        evidence = val.get("evidence", [])
-        adversarial_answer = val.get("adversarial_answer", "")
-
-        response, search_memory_time, response_time, context = self.answer_question(run_id, idx, question)
-
-        result = {
-            "question": question,
-            "answer": answer,
-            "category": category,
-            "evidence": evidence,
-            "response": response,
-            "adversarial_answer": adversarial_answer,
-            "search_memory_time": search_memory_time,
-            "response_time": response_time,
-            "context": context,
-        }
-
-        return result
-
-    def answer_question(self, run_id, idx, question):
-        context, search_memory_time = self.search_memory(run_id, idx, question)
-
-        template = Template(ANSWER_PROMPT_ZEP)
-        answer_prompt = template.render(memories=context, question=question)
-
-        t1 = time.time()
-        response = self.openai_client.chat.completions.create(
-            model=os.getenv("MODEL"), messages=[{"role": "system", "content": answer_prompt}], temperature=0.0
-        )
-        t2 = time.time()
-        response_time = t2 - t1
-        return response.choices[0].message.content, search_memory_time, response_time, context
-
-    def process_data_file(self, file_path, run_id, output_file_path):
-        with open(file_path, "r") as f:
-            data = json.load(f)
-
-        for idx, item in tqdm(enumerate(data), total=len(data), desc="Processing conversations"):
-            qa = item["qa"]
-
-            for question_item in tqdm(
-                qa, total=len(qa), desc=f"Processing questions for conversation {idx}", leave=False
-            ):
-                result = self.process_question(run_id, question_item, idx)
-                self.results[idx].append(result)
-
-                # Save results after each question is processed
-                with open(output_file_path, "w") as f:
-                    json.dump(self.results, f, indent=4)
-
-        # Final save at the end
-        with open(output_file_path, "w") as f:
-            json.dump(self.results, f, indent=4)
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--run_id", type=str, required=True)
-    args = parser.parse_args()
-    zep_search = ZepSearch()
-    zep_search.process_data_file("../../dataset/locomo10.json", args.run_id, "results/zep_search_results.json")

examples/mem0-demo/components/assistant-ui/memory-ui.tsx

@@ -16,10 +16,10 @@ type RetrievedMemory = {
 
 type NewMemory = {
   id: string;
-  data: {
+  data?: {
     memory: string;
   };
-  event: "ADD" | "DELETE";
+  event: "ADD" | "UPDATE" | "DELETE" | "GET";
 };
 
 type NewMemoryAnnotation = {
@@ -47,14 +47,16 @@ const useMemories = (): Memory[] => {
     () =>
       annotations?.filter(isMemoryAnnotation).flatMap((a) => {
         if (a.type === "mem0-update") {
-          return a.memories.map(
-            (m): Memory => ({
-              event: m.event,
-              id: m.id,
-              memory: m.data.memory,
-              score: 1,
-            })
-          );
+          return a.memories
+            .filter((m): m is NewMemory & { data: { memory: string } } => m.data != null)
+            .map(
+              (m): Memory => ({
+                event: m.event,
+                id: m.id,
+                memory: m.data.memory,
+                score: 1,
+              })
+            );
         } else if (a.type === "mem0-get") {
           return a.memories.map((m) => ({
             event: "GET",

examples/mem0-demo/package.json

@@ -26,7 +26,7 @@
     "ai": "^4.1.46",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "js-cookie": "^3.0.5",
+    "js-cookie": "^3.0.6",
     "lucide-react": "^0.477.0",
     "next": "15.5.18",
     "react": "^19.0.0",

examples/notebooks/mem0-autogen.ipynb

@@ -555,7 +555,7 @@
     "# - Enables creation of AI agents with long-term memory and learning abilities.\n",
     "# - Improves consistency and reduces repetition in user-agent interactions.\n",
     "\n",
-    "from cookbooks.helper.mem0_teachability import Mem0Teachability\n",
+    "from helper.mem0_teachability import Mem0Teachability\n",
     "\n",
     "teachability = Mem0Teachability(\n",
     "    verbosity=2,  # for visibility of what's happening\n",

integrations/mem0-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Persistent memory for Claude Code. Remembers decisions, patterns, and preferences across sessions.",
   "author": {
     "name": "Mem0",

integrations/mem0-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Persistent memory for Codex. Remembers decisions, patterns, and preferences across sessions.",
   "author": {
     "name": "Mem0",

integrations/mem0-plugin/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search using the Mem0 Platform MCP server.",
   "author": {
     "name": "Mem0",

integrations/mem0-plugin/.opencode-plugin/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to the `@mem0/opencode-plugin` will be documented in this file.
+
+## 0.2.0 — Native SDK tools, MCP-free, leaner skill set
+
+### Changed (breaking)
+
+- **Memory tools are now native OpenCode tools** registered via the `@opencode-ai/plugin` `tool()` helper and backed by the `mem0ai` SDK directly. The plugin no longer registers or depends on the remote MCP server (`mcp.mem0.ai`); the bundled `opencode.json` and the regex-based MCP call interception have been removed. Tools: `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities`, plus a `get_event_status` helper for async-write status.
+- **Skills load via the `config` hook (`skills.paths`)** instead of being copied into the project's `.opencode/` directory on startup. The `installSkills()` filesystem copy and the `cli.ts` installer (`mem0-opencode` bin) have been removed — install with `opencode plugin @mem0/opencode-plugin`.
+- **Trimmed to 8 focused skills** (`context-loader`, `dream`, `forget`, `health`, `peek`, `pin`, `remember`, `tour`). Removed `import`, `export`, `memory-reviewer`, `mem0` (SDK reference), `list-projects`, `switch-project`, `stats`, and `onboard`.
+
+### Added
+
+- **Expanded telemetry to the full shared `plugin.*` schema.** In addition to `plugin.session_start` and `plugin.tool_use`, the plugin now emits `plugin.user_prompt`, `plugin.bash_error`, `plugin.pre_compact`, and `plugin.session_stop`. `tool_use` now fires from inside each native tool. Every event also carries `project_hash` (anonymized `sha256(app_id)`) and `os_version`, matching the editor plugin's `telemetry.py`.
+
+### Fixed
+
+- **Error-pattern lookup** in `tool.execute.after` no longer issues two identical `mem0.search()` calls; it now performs a single `topK: 6` search.
+- Corrected the documented system-prompt hook name from `experimental.chat.system.transform` to the actual `experimental.chat.messages.transform`.
+
+## 0.1.3 — File-context injection, session summaries & activity timeline, anonymous telemetry
+
+### Added
+
+- **File-context injection (`tool.execute.before` / Read):** Before the agent reads a file, the plugin searches mem0 for memories referencing that file path and injects prior work as system context. Gates on file size (>= 1,500 bytes). Gives the agent "I've worked on this file before" awareness automatically.
+- **Stop hook session summary (`experimental.session.compacting`):** Enhanced session compaction to store a structured `session_summary` memory with `infer=True`, letting the mem0 backend AI extract key facts (request, decisions, learnings, next steps). Previously only stored a raw stats string.
+- **SessionStart activity timeline:** The initial memory loading now formats recent memories with type icons (⚖️ decision, 🔴 bug_fix, 🔵 task_learning, etc.) and relative age indicators (2h ago, 1d ago) instead of bare text. Provides a visual "Recent Activity" timeline on first message.
+- **PostHog telemetry (`telemetry.ts`):** Anonymous, fire-and-forget usage events. Opt out with `MEM0_TELEMETRY=false`. Only fires when an API key is present; never sends memory content, prompts, or the API key — only an anonymized `sha256(apiKey)[:32]` identity plus event type, platform, and plugin version. Emits the same schema as the Mem0 editor plugin (`plugin.*` events, `source: "plugin"`, `platform: "opencode"`) so OpenCode appears as a `platform` in the shared plugin dashboard. Events: `plugin.session_start` (with memory count) and `plugin.tool_use` (`add` / `search` / `update` / `delete`).
+
+### Changed
+
+- **`experimental.session.compacting` handler:** Now stores `metadata.type=session_summary` with `metadata.source=opencode-stop` instead of `metadata.type=session_state` with `metadata.source=pre-compaction`. Includes a structured prompt that instructs mem0's AI to extract request, decisions, learnings, and next steps.
+- **Initial context formatting:** Memories shown on first message now include type icons and age labels for quick scanning.
+
+## 0.1.2 — Automatic coding categories & global search
+
+### Added
+
+- **Auto-configured coding categories:** The plugin now automatically sets up 17 coding categories (e.g. `architecture_decisions`, `api_design`, `security`, `debugging_notes`) on the Mem0 project at startup. Runs in the background on every session start via `autoSetupCategories()`, is fully idempotent, and never blocks initialization. Uses SHA-256 fingerprints of the category list and API key — stored in `~/.mem0/categories_setup.json` — to skip redundant API calls on subsequent sessions.
+- **Global search mode (`global_search` setting):** New `global_search` toggle in `~/.mem0/settings.json` (default: `false`). When enabled, all `search_memories` and `get_memories` calls use `{"OR": [{"user_id": "*"}]}` instead of the per-user per-project `AND` filter — returning all memories across all users and all `app_id` scopes. Writes (`add_memory`) still tag with the current `user_id` and `app_id`. Applies to all plugin search paths: initial load, per-message recall, resume detection, error-pattern lookup, and compaction context.
+- **`/mem0:switch-project --global` / `--no-global`:** Enables or disables global search via the switch-project skill. Persists to `~/.mem0/settings.json`. No manual config editing needed.
+- **`MEM0_GLOBAL_SEARCH` environment variable:** Exported to child shells via the `shell.env` hook (`"true"` or `"false"`).
+
+### Changed
+
+- **Search filters are now dynamic:** All search paths throughout the plugin construct filters based on the `global_search` setting instead of always using `AND [user_id, app_id]`.
+- **Resume-context searches broadened:** Resume and error-pattern searches no longer include `metadata.type` sub-filters (`session_state`, `decision`, `anti_pattern`, `bug_fix`), broadening recall.
+- **System context message updated:** Informs the model when global search is active (`"Global search is ON — searches return all memories across all users and projects. Writes still use user_id=..., app_id=..."`).
+- **`/mem0:onboard` Step 5 is no longer interactive:** Removed the manual category installation prompt. Categories now configure automatically in the background; the onboarding step only verifies status and stores a fallback `project_profile` memory if the background run hasn't finished yet.
+- **`/mem0:switch-project` skill expanded:** Description and execution updated to document the `--global` and `--no-global` flags alongside the existing project-name argument.
+
+## 0.1.1
+
+- CI/CD publish flow test (`#5288`).
+- Fixed tsconfig, added `publishConfig` and bun lockfile (`#5273`).
+- Renamed package to `@mem0/opencode-plugin` (`#5272`).
+- Added plugin array to bundled `opencode.json` (`#5271`).
+
+## 0.1.0 — Initial release
+
+- **OpenCode plugin** (`@mem0/opencode-plugin` on npm): Pure TypeScript plugin using the `mem0ai` TS SDK — no Python, no shell scripts. Hooks into all 6 OpenCode events (`chat.message`, `tool.execute.before`, `tool.execute.after`, `experimental.chat.system.transform`, `experimental.session.compacting`, `shell.env`). Features: session start memory loading, per-prompt semantic search, error pattern detection with memory lookup, resume/remember intent detection, auto-capture every 3rd message, periodic save nudges, full metadata defaults injection (confidence, source, type, session_id, files, branch), identity injection for search/get/delete filters, type-filtered error pre-fetch (anti_pattern + bug_fix), pre-compaction memory capture, MEMORY.md write blocking, and secret redaction.
+- **16 OpenCode-native skills** bundled in `opencode-skills/`: `context-loader`, `dream`, `export`, `forget`, `health`, `import`, `list-projects`, `mem0` (SDK reference), `memory-reviewer`, `onboard`, `peek`, `pin`, `remember`, `stats`, `switch-project`, `tour`. All skills are pure MCP-tool-based — no Python scripts, no shell scripts, no Claude Code dependencies.
+- **Auto-install skills and commands (`installSkills()`):** On plugin load, copies all 16 skills to `.opencode/skills/` and creates command wrapper files in `.opencode/commands/` so they appear in the OpenCode `/` palette.
+- **CLI installer (`cli.ts`):** `bunx @mem0/opencode-plugin install` auto-configures plugin and MCP server in `~/.config/opencode/opencode.json`.

integrations/mem0-plugin/.opencode-plugin/README.md

@@ -4,24 +4,18 @@ Persistent memory for [OpenCode](https://opencode.ai). Your agent remembers deci
 
 ## Install
 
-```bash
-bunx @mem0/opencode-plugin@latest install
-```
-
-Or using OpenCode's built-in CLI:
-
 ```bash
 opencode plugin @mem0/opencode-plugin
 ```
 
+This adds the plugin to your `~/.config/opencode/opencode.json`. The plugin registers its memory tools and skills itself — there is no MCP server to configure.
+
 **Or let your agent do it** — paste this into OpenCode:
 
 ```
-Install @mem0/opencode-plugin by following https://raw.githubusercontent.com/mem0ai/mem0/main/mem0-plugin/.opencode-plugin/README.md
+Install @mem0/opencode-plugin by following https://raw.githubusercontent.com/mem0ai/mem0/main/integrations/mem0-plugin/.opencode-plugin/README.md
 ```
 
-All commands auto-add the plugin and MCP server to your `~/.config/opencode/opencode.json`. No manual config needed.
-
 Get your API key (free): [app.mem0.ai/dashboard/api-keys](https://app.mem0.ai/dashboard/api-keys)
 
 ```bash
@@ -34,24 +28,25 @@ Restart OpenCode.
 
 | Component | Description |
 |-----------|-------------|
-| **MCP Server** | 9 memory tools — add, search, get, update, delete memories |
-| **Lifecycle Hooks** | Auto-search on session start and every prompt, metadata enforcement, error memory lookup, compaction context |
-| **16 Slash Commands** | `/mem0:remember`, `/mem0:tour`, `/mem0:stats`, `/mem0:health`, `/mem0:dream`, and more |
+| **9 Native Memory Tools** | `add_memory`, `search_memories`, `get_memories`, `update_memory`, `delete_memory`, and more — registered as OpenCode tools, backed by the `mem0ai` SDK (no MCP server required) |
+| **Lifecycle Hooks** | Auto-search on session start and every prompt, error memory lookup, compaction context, secret redaction |
+| **8 Skills** | `/mem0:remember`, `/mem0:tour`, `/mem0:peek`, `/mem0:health`, `/mem0:dream`, `/mem0:forget`, `/mem0:pin`, `/mem0:context-loader` |
 
 ## Hooks
 
-Pure TypeScript — no Python, no shell scripts. Uses the [mem0ai](https://www.npmjs.com/package/mem0ai) SDK directly.
+Pure TypeScript — no Python, no shell scripts. Memory operations are native OpenCode tools backed by the [mem0ai](https://www.npmjs.com/package/mem0ai) SDK directly.
 
 | Hook | Event | What it does |
 |------|-------|-------------|
+| **Config** | `config` | Registers the bundled skills (`skills.paths`) and `/mem0:*` slash commands at startup |
 | **Chat message** | `chat.message` | Loads prior memories on session start, searches relevant memories before each prompt, auto-captures learnings periodically |
-| **Pre-tool** | `tool.execute.before` | Blocks MEMORY.md writes, enforces `user_id`/`app_id` on mem0 tools |
-| **Post-tool** | `tool.execute.after` | Tracks stats, scans bash errors for related memories |
-| **System transform** | `experimental.chat.system.transform` | Injects memory context (session memories, search results, error lookups) into system prompt |
+| **Pre-tool** | `tool.execute.before` | Blocks MEMORY.md writes, steering them to the `add_memory` tool |
+| **Post-tool** | `tool.execute.after` | Scans bash errors and pre-fetches related memories |
+| **Messages transform** | `experimental.chat.messages.transform` | Injects memory context (session memories, search results, error lookups) into the prompt |
 | **Compaction** | `experimental.session.compacting` | Stores session state memory, then injects prior memories into compaction context so nothing is lost |
 | **Shell env** | `shell.env` | Exports `MEM0_USER_ID`, `MEM0_APP_ID`, `MEM0_SESSION_ID`, and `MEM0_BRANCH` to shell |
 
-## MCP Tools
+## Memory Tools
 
 | Tool | Description |
 |------|-------------|

integrations/mem0-plugin/.opencode-plugin/bun.lock

@@ -6,7 +6,7 @@
       "name": "@mem0/opencode-plugin",
       "dependencies": {
         "@opencode-ai/plugin": "^1.0.162",
-        "mem0ai": "^3.0.5",
+        "mem0ai": "^3.0.7",
       },
       "devDependencies": {
         "bun-types": ">=1.3.14",
@@ -462,7 +462,7 @@
 
     "md5": ["md5@2.3.0", "", { "dependencies": { "charenc": "0.0.2", "crypt": "0.0.2", "is-buffer": "~1.1.6" } }, "sha512-T1GITYmFaKuO91vxyoQMFETst+O71VUPEU3ze5GNzDm0OWdP8v1ziTaAEPUr/3kLsY3Sftgz242A1SetQiDL7g=="],
 
-    "mem0ai": ["mem0ai@3.0.5", "", { "dependencies": { "axios": "^1.15.2", "openai": "^4.93.0", "uuid": "9.0.1", "zod": "^3.24.1" }, "peerDependencies": { "@anthropic-ai/sdk": "^0.40.1", "@azure/identity": "^4.0.0", "@azure/search-documents": "^12.0.0", "@cloudflare/workers-types": "^4.20250504.0", "@google/genai": "^1.2.0", "@langchain/core": "^1.1.47", "@mistralai/mistralai": "^1.5.2", "@qdrant/js-client-rest": "1.13.0", "@supabase/supabase-js": "^2.49.1", "@types/jest": "29.5.14", "@types/pg": "8.11.0", "better-sqlite3": "^12.6.2", "cloudflare": "^4.2.0", "compromise": "^14.0.0", "groq-sdk": "0.3.0", "natural": "^8.0.1", "ollama": "^0.5.14", "pg": "8.11.3", "redis": "^4.6.13" } }, "sha512-W/R59d5fMpUGHhPEnyoo36GSz5NFJbAs+vS4BxoIvE+t19mIJfoz/2FJSKIw80mT8AkeNYpDfzc/DYRu2IzYIw=="],
+    "mem0ai": ["mem0ai@3.0.7", "", { "dependencies": { "axios": "^1.16.0", "openai": "^4.93.0", "uuid": "9.0.1", "zod": "^3.24.1" }, "peerDependencies": { "@anthropic-ai/sdk": "^0.40.1", "@azure/identity": "^4.0.0", "@azure/search-documents": "^12.0.0", "@cloudflare/workers-types": "^4.20250504.0", "@google/genai": "^1.40.0", "@langchain/core": "^1.1.47", "@mistralai/mistralai": "^1.5.2", "@qdrant/js-client-rest": "^1.18.0", "@supabase/supabase-js": "^2.49.1", "@types/jest": "29.5.14", "@types/pg": "8.11.0", "better-sqlite3": "^12.6.2", "cloudflare": "^4.2.0", "compromise": "^14.0.0", "groq-sdk": "0.3.0", "natural": "^8.0.1", "ollama": "^0.5.14", "pg": "8.11.3", "redis": "^4.6.13" } }, "sha512-CUHzX7DyeKTHcI3aDsSqY9LXTD7GcFxf988796TuOa4yJgGuF2Xd2NROcBhVFRo3r9y8fVmbo3c5TF9jv1KlKw=="],
 
     "memjs": ["memjs@1.3.2", "", {}, "sha512-qUEg2g8vxPe+zPn09KidjIStHPtoBO8Cttm8bgJFWWabbsjQ9Av9Ky+6UcvKx6ue0LLb/LEhtcyQpRyKfzeXcg=="],
 

integrations/mem0-plugin/.opencode-plugin/opencode-mem0.ts

@@ -0,0 +1,878 @@
+// Mem0 memory plugin for OpenCode: captures and recalls memories across sessions
+// (add / search / manage) via the Mem0 platform, wired through OpenCode plugin hooks.
+// Memory operations are exposed as native OpenCode tools backed by the mem0ai SDK
+// (no MCP server required).
+import type {Plugin} from "@opencode-ai/plugin";
+import {tool} from "@opencode-ai/plugin";
+import {MemoryClient} from "mem0ai";
+import {userInfo} from "os";
+import {basename, resolve, dirname} from "path";
+import {randomBytes} from "crypto";
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from "fs";
+import {homedir} from "os";
+import {join} from "path";
+import {createHash} from "crypto";
+import {readdirSync} from "node:fs";
+import {captureEvent} from "./telemetry";
+
+async function getUserId(): Promise<string> {
+  if (process.env.MEM0_USER_ID) return process.env.MEM0_USER_ID;
+  try {
+    return userInfo().username;
+  } catch {
+  }
+  return process.env.USER || process.env.USERNAME || "unknown";
+}
+
+async function getProjectId($: any): Promise<string> {
+  if (process.env.MEM0_APP_ID) return process.env.MEM0_APP_ID;
+  try {
+    const r = await $`git remote get-url origin`.quiet();
+    const remote = r.stdout.toString().trim();
+    const m = remote.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (m) return m[1].replace("/", "-");
+  } catch {
+  }
+  return basename(process.cwd());
+}
+
+async function getBranch($: any): Promise<string> {
+  try {
+    const r = await $`git branch --show-current`.quiet();
+    return r.stdout.toString().trim() || "main";
+  } catch {
+  }
+  return "main";
+}
+
+function extractMemories(res: any): Array<{ memory: string; id: string }> {
+  const arr = res?.results ?? res;
+  if (!Array.isArray(arr)) return [];
+  return arr.map((m: any) => ({memory: m.memory ?? "", id: m.id ?? ""}));
+}
+
+function generateSessionId(): string {
+  const ts = Math.floor(Date.now() / 1000);
+  const rnd = randomBytes(3).toString("hex");
+  return `ses_${ts}_${rnd}`;
+}
+
+const SECRET_PATTERNS = [
+  /sk-[A-Za-z0-9]{20,}/g,
+  /m0-[A-Za-z0-9]{20,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /xox[baprs]-[A-Za-z0-9-]{20,}/g,
+  /ghp_[A-Za-z0-9]{36,}/g,
+  /gho_[A-Za-z0-9]{36,}/g,
+];
+
+function redact(text: string): string {
+  let out = text;
+  for (const re of SECRET_PATTERNS) {
+    out = out.replace(re, "[REDACTED]");
+  }
+  return out;
+}
+
+function loadGlobalSearch(): boolean {
+  try {
+    const settingsPath = join(homedir(), ".mem0", "settings.json");
+    if (!existsSync(settingsPath)) return false;
+    const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    return settings.global_search === true;
+  } catch {
+  }
+  return false;
+}
+
+const CODING_CATEGORIES = [
+  "architecture_decisions", "api_design", "data_models", "algorithms",
+  "dependencies", "environment_setup", "testing_strategy", "debugging_notes",
+  "performance", "security", "deployment", "code_conventions",
+  "error_handling", "refactoring_history", "integrations", "onboarding",
+  "project_meta",
+];
+
+function categoriesFingerprint(): string {
+  const sorted = [...CODING_CATEGORIES].sort();
+  return createHash("sha256").update(sorted.join("\n")).digest("hex").slice(0, 16);
+}
+
+function apiKeyFingerprint(apiKey: string): string {
+  return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+}
+
+async function autoSetupCategories(mem0: MemoryClient, apiKey: string): Promise<void> {
+  const stateDir = join(homedir(), ".mem0");
+  const stateFile = join(stateDir, "categories_setup.json");
+  const keyFp = apiKeyFingerprint(apiKey);
+  const catFp = categoriesFingerprint();
+
+  let state: Record<string, string> = {};
+  try {
+    if (existsSync(stateFile)) {
+      state = JSON.parse(readFileSync(stateFile, "utf8"));
+    }
+  } catch {}
+
+  if (state[keyFp] === catFp) return;
+
+  try {
+    const project = await mem0.getProject({fields: ["customCategories"]});
+    const existing: string[] = (project as any)?.custom_categories ?? (project as any)?.customCategories ?? [];
+    const sortedExisting = [...existing].sort();
+    const sortedTarget = [...CODING_CATEGORIES].sort();
+    if (JSON.stringify(sortedExisting) === JSON.stringify(sortedTarget)) {
+      state[keyFp] = catFp;
+      mkdirSync(stateDir, {recursive: true});
+      writeFileSync(stateFile, JSON.stringify(state, null, 2) + "\n");
+      return;
+    }
+
+    await mem0.updateProject({customCategories: CODING_CATEGORIES as any});
+
+    state[keyFp] = catFp;
+    mkdirSync(stateDir, {recursive: true});
+    writeFileSync(stateFile, JSON.stringify(state, null, 2) + "\n");
+  } catch {
+  }
+}
+
+const NUDGE_RE =
+  /\b(remember\s+(this|that)|memorize|save\s+this|note\s+(this|that)|don'?t\s+forget|always\s+remember|never\s+forget|keep\s+(this|that)\s+in\s+(mind|memory)|store\s+(this|that))\b/i;
+
+const RESUME_RE =
+  /where\s+(did\s+)?(we|I)\s+(leave|left)\s+off|continue\s+(from\s+)?(where|last)|what\s+were\s+we\s+(working|doing)|pick\s+up\s+where|resume\s+(from\s+|where\s+)|what.s\s+the\s+(current|latest)\s+(state|status)|catch\s+me\s+up|where\s+are\s+we/i;
+
+const ERROR_STRONG_RE =
+  /Traceback \(most recent call last\)|panic: |FATAL:|error\[E\d+\]/;
+const ERROR_MULTI_RE = /(Error:|Exception:)/g;
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "write", "edit", "multiEdit"]);
+
+function resolveFilters(args: any, globalSearch: boolean, userId: string, appId: string): any {
+  if (args.filters) {
+    const existingFilters = args.filters;
+    if (typeof existingFilters === "object" && existingFilters !== null) {
+      const andClauses: any[] = existingFilters.AND;
+      if (Array.isArray(andClauses)) {
+        const hasUid = andClauses.some(
+          (c: any) => c && typeof c === "object" && "user_id" in c,
+        );
+        const hasAid = andClauses.some(
+          (c: any) => c && typeof c === "object" && "app_id" in c,
+        );
+        const hasAgentId = andClauses.some(
+          (c: any) => c && typeof c === "object" && "agent_id" in c,
+        );
+        const newClauses = [...andClauses];
+        if (args.agent_id || hasAgentId) {
+          if (!hasAgentId) newClauses.push({ agent_id: args.agent_id });
+        } else {
+          if (!hasUid) newClauses.push({ user_id: args.user_id ?? userId });
+        }
+        if (!hasAid) newClauses.push({ app_id: args.app_id ?? appId });
+        return { AND: newClauses };
+      } else if (andClauses === undefined) {
+        const hasUid = "user_id" in existingFilters;
+        const hasAid = "app_id" in existingFilters;
+        const hasAgentId = "agent_id" in existingFilters;
+        if (!hasAid || (!hasUid && !hasAgentId)) {
+          const existing = Object.entries(existingFilters).map(
+            ([k, v]) => ({ [k]: v }),
+          );
+          if (args.agent_id || hasAgentId) {
+            if (!hasAgentId) existing.push({ agent_id: args.agent_id });
+          } else {
+            if (!hasUid) existing.push({ user_id: args.user_id ?? userId });
+          }
+          if (!hasAid) existing.push({ app_id: args.app_id ?? appId });
+          return { AND: existing };
+        }
+      }
+    }
+    return args.filters;
+  }
+
+  if (globalSearch) {
+    return { OR: [{ user_id: "*" }] };
+  }
+
+  if (args.agent_id) {
+    return {
+      AND: [{ agent_id: args.agent_id }, { app_id: args.app_id ?? appId }],
+    };
+  }
+
+  return {
+    AND: [{ user_id: args.user_id ?? userId }, { app_id: args.app_id ?? appId }],
+  };
+}
+
+function extractUserText(input: any, output: any): string {
+  const parts: any[] = output?.parts;
+  if (Array.isArray(parts)) {
+    return parts
+      .filter((p: any) => p.type === "text" && !p.synthetic)
+      .map((p: any) => p.text ?? "")
+      .join("\n");
+  }
+  const msg = output?.message ?? input?.message;
+  if (typeof msg?.content === "string") return msg.content;
+  if (typeof msg?.text === "string") return msg.text;
+  return "";
+}
+
+const Mem0Plugin: Plugin = async (ctx) => {
+  const {$, client} = ctx;
+
+  const apiKey = process.env.MEM0_API_KEY;
+
+  if (!apiKey) {
+    try {
+      await client.app.log({
+        body: {
+          service: "mem0",
+          level: "error",
+          message:
+            "MEM0_API_KEY environment variable not set. Get one at https://app.mem0.ai/dashboard/api-keys",
+        },
+      });
+    } catch {
+    }
+    return {};
+  }
+
+  const mem0 = new MemoryClient({apiKey});
+  const userId = await getUserId();
+  const appId = await getProjectId($);
+  const branch = await getBranch($);
+  const stats = {adds: 0, searches: 0, messages: 0};
+  const sessionId = generateSessionId();
+  const globalSearch = loadGlobalSearch();
+
+  let initialized = false;
+  let memoryCount = 0;
+  let msgCount = 0;
+
+  const systemContext: string[] = [];
+
+  // Emit a session_stop telemetry event once when the process winds down.
+  let sessionStopSent = false;
+  const emitSessionStop = () => {
+    if (sessionStopSent) return;
+    sessionStopSent = true;
+    captureEvent(
+      "session_stop",
+      {adds: stats.adds, searches: stats.searches, messages: stats.messages},
+      apiKey,
+      appId,
+    );
+  };
+  try {
+    process.on("beforeExit", emitSessionStop);
+  } catch {
+  }
+
+  // Auto-configure coding categories in background (idempotent, never blocks)
+  Promise.resolve().then(() => autoSetupCategories(mem0, apiKey)).catch(() => {
+  });
+
+  function registerCommands(skillsDir: string, opencodeConfig: any) {
+    const skillEntries = readdirSync(skillsDir, {withFileTypes: true});
+    for (const entry of skillEntries) {
+      if (!entry.isDirectory()) continue;
+      const skillMd = resolve(skillsDir, entry.name, "SKILL.md");
+      if (!existsSync(skillMd)) continue;
+
+      let desc = `Mem0 ${entry.name} skill`;
+      try {
+        const content = readFileSync(skillMd, "utf8");
+        const m = content.match(/^description:\s*(.+)$/m);
+        if (m) desc = m[1].trim();
+      } catch {
+      }
+
+      opencodeConfig.command ??= {};
+      opencodeConfig.command[`mem0:${entry.name}`] = {
+        template: `Load and execute the \`mem0:${entry.name}\` skill.
+
+Use the mem0 memory tools (add_memory, search_memories, get_memories, get_memory, update_memory, delete_memory, delete_all_memories, delete_entities, list_entities, get_event_status) as instructed by the skill.
+
+Identity context (resolved at plugin startup):
+- user_id: ${userId}
+- app_id: ${appId}
+- session_id: ${sessionId}
+- branch: ${branch}`,
+        description: desc,
+      };
+    }
+  }
+
+  return {
+    "chat.message": chatMessageHook,
+    "experimental.chat.messages.transform": chatMessagesTransformHook,
+    "tool.execute.before": toolExecuteBeforeHook,
+    "tool.execute.after": toolExecuteAfterHook,
+    "experimental.session.compacting": compactionHook,
+
+    "shell.env": async (
+      _input: { cwd: string; sessionID?: string },
+      output: { env: Record<string, string> },
+    ) => {
+      if (output?.env) {
+        output.env.MEM0_USER_ID = userId;
+        output.env.MEM0_APP_ID = appId;
+        output.env.MEM0_SESSION_ID = sessionId;
+        output.env.MEM0_BRANCH = branch;
+        output.env.MEM0_GLOBAL_SEARCH = globalSearch ? "true" : "false";
+      }
+    },
+
+    config: async (opencodeConfig: any) => {
+      const pluginDir = dirname(dirname(import.meta.filename));
+      const skillsDir = resolve(pluginDir, "opencode-skills");
+
+      if (existsSync(skillsDir)) {
+        opencodeConfig.skills ??= {};
+        opencodeConfig.skills.paths ??= [];
+        if (!opencodeConfig.skills.paths.includes(skillsDir)) {
+          opencodeConfig.skills.paths.push(skillsDir);
+        }
+      }
+
+      registerCommands(skillsDir, opencodeConfig);
+    },
+
+    tool: {
+      add_memory: tool({
+        description: "Add a new memory. This method is called everytime the user informs anything about themselves, their preferences, or anything that has any relevant information which can be useful in the future conversation. This can also be called when the user asks you to remember something. Set infer to false to store the memory verbatim without LLM fact extraction.",
+        args: {
+          text: tool.schema.string().describe("Memory text content"),
+          user_id: tool.schema.string().optional().describe("User ID"),
+          app_id: tool.schema.string().optional().describe("App/Project ID"),
+          agent_id: tool.schema.string().optional().describe("Agent ID"),
+          metadata: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("Metadata key-value pairs"),
+          infer: tool.schema.boolean().optional().describe("Set to false to store memory verbatim without LLM fact extraction")
+        },
+        async execute(args) {
+          stats.adds++;
+          captureEvent("tool_use", {tool: "add_memory"}, apiKey, appId);
+          const finalUserId = args.agent_id ? args.user_id : (args.user_id ?? userId);
+          const finalAppId = args.app_id ?? appId;
+
+          const meta = args.metadata ?? {};
+          if (meta.confidence === undefined) meta.confidence = 0.7;
+          if (!meta.source) meta.source = "opencode";
+          if (!meta.type) meta.type = "task_learning";
+          if (!meta.session_id) meta.session_id = sessionId;
+          if (!meta.files) meta.files = ["*"];
+          if (!meta.branch) meta.branch = branch;
+
+          let infer = args.infer;
+          if (meta.confidence >= 1.0 && infer === undefined) {
+            infer = false;
+          }
+
+          const res = await mem0.add(
+            [{ role: "user", content: args.text }],
+            {
+              user_id: finalUserId,
+              app_id: finalAppId,
+              agent_id: args.agent_id,
+              metadata: meta,
+              infer
+            } as any
+          );
+          return JSON.stringify(res);
+        }
+      }),
+
+      search_memories: tool({
+        description: "Search through stored memories.",
+        args: {
+          query: tool.schema.string().describe("Search query"),
+          user_id: tool.schema.string().optional().describe("User ID"),
+          app_id: tool.schema.string().optional().describe("App/Project ID"),
+          agent_id: tool.schema.string().optional().describe("Agent ID"),
+          filters: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("Key-value filters (e.g. metadata or user/app filters)"),
+          limit: tool.schema.number().optional().describe("Maximum number of results to return (top_k)"),
+          top_k: tool.schema.number().optional().describe("Maximum number of results to return (alternative parameter)"),
+        },
+        async execute(args) {
+          stats.searches++;
+          captureEvent("tool_use", {tool: "search_memories"}, apiKey, appId);
+          const topK = args.limit ?? args.top_k ?? 10;
+          const filters = resolveFilters(args, globalSearch, userId, appId);
+
+          const res = await mem0.search(args.query, {
+            filters,
+            topK,
+          });
+          return JSON.stringify(res);
+        }
+      }),
+
+      get_memories: tool({
+        description: "List all memories in the memory store, optionally filtered.",
+        args: {
+          user_id: tool.schema.string().optional().describe("User ID"),
+          app_id: tool.schema.string().optional().describe("App/Project ID"),
+          agent_id: tool.schema.string().optional().describe("Agent ID"),
+          filters: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("Metadata/identity filters"),
+          page: tool.schema.number().optional().describe("Page number"),
+          page_size: tool.schema.number().optional().describe("Page size"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "get_memories"}, apiKey, appId);
+          const filters = resolveFilters(args, globalSearch, userId, appId);
+
+          const res = await mem0.getAll({
+            page: args.page,
+            pageSize: args.page_size,
+            filters,
+          });
+          return JSON.stringify(res);
+        }
+      }),
+
+      get_memory: tool({
+        description: "Retrieve a specific memory by its ID.",
+        args: {
+          id: tool.schema.string().describe("The ID of the memory to retrieve"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "get_memory"}, apiKey, appId);
+          const res = await mem0.get(args.id);
+          return JSON.stringify(res);
+        }
+      }),
+
+      update_memory: tool({
+        description: "Update the content or metadata of a specific memory.",
+        args: {
+          id: tool.schema.string().describe("The ID of the memory to update"),
+          text: tool.schema.string().optional().describe("New text content for the memory"),
+          metadata: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("New metadata key-value pairs"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "update_memory"}, apiKey, appId);
+          const res = await mem0.update(args.id, {
+            text: args.text,
+            metadata: args.metadata,
+          });
+          return JSON.stringify(res);
+        }
+      }),
+
+      delete_memory: tool({
+        description: "Delete specific memories by their ID.",
+        args: {
+          id: tool.schema.string().describe("The ID of the memory to delete"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "delete_memory"}, apiKey, appId);
+          const res = await mem0.delete(args.id);
+          return JSON.stringify(res);
+        }
+      }),
+
+      delete_all_memories: tool({
+        description: "Delete all memories.",
+        args: {
+          user_id: tool.schema.string().optional().describe("User ID whose memories to delete"),
+          app_id: tool.schema.string().optional().describe("App ID whose memories to delete"),
+          agent_id: tool.schema.string().optional().describe("Agent ID whose memories to delete"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "delete_all_memories"}, apiKey, appId);
+          const res = await mem0.deleteAll({
+            user_id: args.agent_id ? args.user_id : (args.user_id ?? userId),
+            app_id: args.app_id ?? appId,
+            agent_id: args.agent_id,
+          } as any);
+          return JSON.stringify(res);
+        }
+      }),
+
+      delete_entities: tool({
+        description: "Delete user/agent/app/run entities and all their associated memories.",
+        args: {
+          user_id: tool.schema.string().optional().describe("User ID of the entity to delete"),
+          agent_id: tool.schema.string().optional().describe("Agent ID of the entity to delete"),
+          app_id: tool.schema.string().optional().describe("App/Project ID of the entity to delete"),
+          run_id: tool.schema.string().optional().describe("Run ID of the entity to delete"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "delete_entities"}, apiKey, appId);
+          const res = await mem0.deleteUsers({
+            userId: args.user_id,
+            agentId: args.agent_id,
+            appId: args.app_id,
+            runId: args.run_id,
+          });
+          return JSON.stringify(res);
+        }
+      }),
+
+      list_entities: tool({
+        description: "List all user/agent/app/run entities.",
+        args: {
+          page: tool.schema.number().optional().describe("Page number"),
+          page_size: tool.schema.number().optional().describe("Page size"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "list_entities"}, apiKey, appId);
+          const res = await mem0.users({
+            page: args.page,
+            pageSize: args.page_size,
+          });
+          return JSON.stringify(res);
+        }
+      }),
+
+      get_event_status: tool({
+        description: "Check the status of an asynchronous memory operation by event_id.",
+        args: {
+          event_id: tool.schema.string().describe("The ID of the event/async operation to check"),
+        },
+        async execute(args) {
+          captureEvent("tool_use", {tool: "get_event_status"}, apiKey, appId);
+          const response = await mem0.client.get(`/v1/event/${args.event_id}/`);
+          return JSON.stringify(response.data);
+        }
+      }),
+    },
+  };
+
+  async function chatMessageHook(input: any, output: any) {
+    const userText = extractUserText(input, output);
+    if (!userText || userText.length < 10) return;
+
+    const safeText = redact(userText);
+    msgCount++;
+    stats.messages++;
+
+    if (!initialized) {
+      initialized = true;
+
+      const searchFilters = globalSearch
+        ? {OR: [{user_id: "*"}]}
+        : {AND: [{user_id: userId}, {app_id: appId}]};
+
+      try {
+        const all = await mem0.getAll({
+          filters: searchFilters,
+          page: 1,
+          pageSize: 1,
+        });
+        memoryCount =
+          (all as any)?.count ??
+          (all as any)?.results?.length ??
+          0;
+
+        if (globalSearch) {
+          systemContext.push(
+            `Global search is ON — searches return all memories across all users and projects. Writes still use user_id="${userId}", app_id="${appId}".`,
+          );
+        } else {
+          systemContext.push(
+            `Always include user_id="${userId}" and app_id="${appId}" in every search_memories filter and add_memory call.`,
+          );
+        }
+
+        if (memoryCount === 0) {
+          systemContext.push(
+            "New project with 0 memories. Capture decisions, conventions, and learnings as you work via the add_memory tool or the remember skill.",
+          );
+        }
+
+        if (memoryCount > 0) {
+          systemContext.push(
+            "Search mem0 for recent decisions and task learnings before responding. Run 2 parallel searches: one for decision type, one for task_learning type.",
+          );
+          try {
+            const res = await mem0.search(
+              "recent session state decisions and learnings",
+              {
+                filters: searchFilters,
+                topK: 5,
+              },
+            );
+            stats.searches++;
+            const memories = extractMemories(res);
+            if (memories.length > 0) {
+              const memLines = memories
+                .map((m) => `- ${m.memory}`)
+                .join("\n");
+              systemContext.push(`Prior context from mem0:\n${memLines}`);
+            }
+          } catch {
+          }
+        }
+
+        systemContext.push(
+          "Mem0 searches apply when user references past work, decision questions, errors, or non-trivial tasks. Queries use noun-phrases, 2-4 parallel calls with different metadata.type filters, and include user_id + app_id.",
+        );
+      } catch (err: any) {
+        try {
+          await client.app.log({
+            body: {
+              service: "mem0",
+              level: "error",
+              message: `Session init error: ${err?.message}`,
+            },
+          });
+        } catch {
+        }
+      }
+
+      captureEvent("session_start", {memory_count: memoryCount}, apiKey, appId);
+    }
+
+    const hasRemember = NUDGE_RE.test(safeText);
+    if (hasRemember) {
+      systemContext.push(
+        "[MEMORY TRIGGER] User asked to remember something. Call add_memory with the user's statement, confidence=1.0, infer=false.",
+      );
+    }
+
+    const hasResume = RESUME_RE.test(safeText);
+    if (hasResume) {
+      try {
+        const resumeFilters = globalSearch
+          ? {OR: [{user_id: "*"}]}
+          : {
+            AND: [
+              {user_id: userId},
+              {app_id: appId},
+            ],
+          };
+        const [stateRes, decisionsRes] = await Promise.all([
+          mem0.search("session state current task", {
+            filters: resumeFilters,
+            topK: 3,
+          }),
+          mem0.search("recent decisions and learnings", {
+            filters: resumeFilters,
+            topK: 3,
+          }),
+        ]);
+        stats.searches += 2;
+        const all = [
+          ...extractMemories(stateRes),
+          ...extractMemories(decisionsRes),
+        ];
+        const seen = new Set<string>();
+        const unique = all.filter((m) => {
+          if (seen.has(m.id)) return false;
+          seen.add(m.id);
+          return true;
+        });
+        if (unique.length > 0) {
+          const memLines = unique.map((m) => `- ${m.memory}`).join("\n");
+          systemContext.push(
+            `Session resume context:\n${memLines}\n\nThese memories provide context for resuming work.`,
+          );
+        }
+      } catch {
+      }
+    }
+
+    if (!hasResume && memoryCount > 0) {
+      try {
+        const msgFilters = globalSearch
+          ? {OR: [{user_id: "*"}]}
+          : {AND: [{user_id: userId}, {app_id: appId}]};
+        const res = await mem0.search(safeText, {
+          filters: msgFilters,
+          topK: 5,
+        });
+        stats.searches++;
+        const memories = extractMemories(res);
+        if (memories.length > 0) {
+          const memLines = memories.map((m) => `- ${m.memory}`).join("\n");
+          systemContext.push(`Relevant memories:\n${memLines}`);
+        }
+      } catch {
+      }
+    }
+
+    if (msgCount % 3 === 0) {
+      Promise.resolve().then(async () => {
+        try {
+          await mem0.add([{role: "user", content: safeText}], {
+            user_id: userId,
+            app_id: appId,
+            metadata: {
+              type: "auto_capture",
+              source: "opencode",
+              confidence: 0.7,
+              session_id: sessionId,
+              branch,
+            },
+            infer: true,
+          } as any);
+          stats.adds++;
+        } catch {
+        }
+      });
+    }
+
+    if (msgCount % 5 === 0 && stats.adds < Math.floor(msgCount / 3)) {
+      systemContext.push(
+        "After responding, store any new decisions, learnings, or preferences from this exchange via add_memory. Keep it to 1 sentence per memory.",
+      );
+    }
+
+    captureEvent(
+      "user_prompt",
+      {remember_detected: hasRemember, resume_detected: hasResume},
+      apiKey,
+      appId,
+    );
+  }
+
+  async function toolExecuteBeforeHook(input: any, output: any) {
+    const toolName: string = input?.tool ?? "";
+
+    if (WRITE_TOOLS.has(toolName)) {
+      const fp = String(
+        output?.args?.file_path ?? output?.args?.filePath ?? "",
+      );
+      if (/MEMORY\.md|\.claude\/memory/i.test(fp)) {
+        throw new Error(
+          "Use the add_memory tool instead of writing to MEMORY.md",
+        );
+      }
+    }
+  }
+
+  async function chatMessagesTransformHook(_input: any, output: { messages: { info: any; parts: any[] }[] }) {
+    if (systemContext.length === 0 || !output?.messages?.length) return;
+
+    const firstUser = output.messages.find(
+      (m) => m.info.role === "user",
+    );
+    if (!firstUser || !firstUser.parts.length) return;
+
+    const marker = "## Mem0 Memory Context";
+    if (firstUser.parts.some((p: any) => p.type === "text" && p.text?.includes(marker))) return;
+
+    const block = `${marker}\n\n${systemContext.join("\n\n")}`;
+    const ref = firstUser.parts[0];
+    firstUser.parts.unshift({...ref, type: "text", text: block});
+  }
+
+  async function toolExecuteAfterHook(input: any, _output: any) {
+    const toolName: string = input?.tool ?? "";
+    const toolOutput: string = input?.output ?? _output?.output ?? "";
+
+    if (toolName === "bash" && toolOutput.length >= 50) {
+      const command: string = input?.args?.command ?? "";
+      if (/git\s+(commit|merge|rebase)/.test(command)) return;
+
+      const hasStrongError = ERROR_STRONG_RE.test(toolOutput);
+      const multiErrors = (toolOutput.match(ERROR_MULTI_RE) ?? []).length;
+      if (!hasStrongError && multiErrors < 2) return;
+
+      try {
+        const errorLine =
+          toolOutput
+            .split("\n")
+            .find((l: string) =>
+              /Error:|Exception:|panic:|FAIL:|fatal:/i.test(l),
+            )
+            ?.replace(/^\s+/, "")
+            .slice(0, 120) ?? "";
+
+        const traceFiles = [
+          ...new Set(
+            toolOutput.match(
+              /[a-zA-Z0-9_./-]+\.(py|ts|tsx|js|jsx|rs|go|rb|java|sh)(:\d+)?/g,
+            ) ?? [],
+          ),
+        ].slice(0, 5);
+
+        const errorQuery = errorLine.slice(0, 80);
+        if (errorQuery.length < 10) return;
+
+        captureEvent("bash_error", {error_detected: true}, apiKey, appId);
+
+        const errorFilters = globalSearch
+          ? {OR: [{user_id: "*"}]}
+          : {
+            AND: [
+              {user_id: userId},
+              {app_id: appId},
+            ],
+          };
+        const res = await mem0.search(`error: ${errorQuery}`, {
+          filters: errorFilters,
+          topK: 6,
+        });
+        stats.searches++;
+        const unique = extractMemories(res);
+
+        let ctx = `Error detected: \`${command.slice(0, 100)}\` produced:\n> ${errorLine}`;
+        if (traceFiles.length > 0) {
+          ctx += `\nFiles in stack trace: ${traceFiles.join(", ")}`;
+        }
+        if (unique.length > 0) {
+          const lines = unique.map((m) => `- ${m.memory}`).join("\n");
+          ctx += `\nPrior error memories:\n${lines}`;
+        }
+        ctx +=
+          "\nStore resolved errors as anti_pattern or bug_fix memories for future reference.";
+        systemContext.push(ctx);
+      } catch {
+      }
+    }
+  }
+
+  async function compactionHook(input: { sessionID?: string }, output: { context: string[]; prompt?: string }) {
+    try {
+      const compactSessionId = input?.sessionID ?? sessionId;
+      captureEvent(
+        "pre_compact",
+        {adds: stats.adds, searches: stats.searches, messages: stats.messages},
+        apiKey,
+        appId,
+      );
+      const summaryContent = `Session compacting. Project: ${appId}. Branch: ${branch}. Session: ${compactSessionId}. Stats: ${stats.adds} memories stored, ${stats.searches} searches, ${stats.messages} messages.`;
+      Promise.resolve().then(async () => {
+        try {
+          await mem0.add([{role: "user", content: summaryContent}], {
+            user_id: userId,
+            app_id: appId,
+            metadata: {
+              type: "session_state",
+              source: "pre-compaction",
+              session_id: compactSessionId,
+              branch,
+            },
+            infer: true,
+          } as any);
+        } catch {
+        }
+      });
+
+      const compactFilters = globalSearch
+        ? {OR: [{user_id: "*"}]}
+        : {AND: [{user_id: userId}, {app_id: appId}]};
+      const res = await mem0.search("session state decisions learnings", {
+        filters: compactFilters,
+        topK: 10,
+      });
+      const memories = extractMemories(res);
+      if (memories.length > 0 && output?.context) {
+        const lines = memories.map((m) => `- ${m.memory}`).join("\n");
+        output.context.push(
+          `## Mem0 Memories (preserve across compaction)\n\n${lines}\n\nIMPORTANT: After compaction, store any key decisions or learnings using the add_memory tool.`,
+        );
+      }
+    } catch {
+    }
+  }
+};
+
+export default Mem0Plugin;

integrations/mem0-plugin/.opencode-plugin/opencode-skills/health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: health
-description: Diagnoses mem0 connectivity, API key validity, and memory read/write functionality. Use when memory operations fail, searches return empty, add_memory errors occur, MCP connection drops, or to verify the plugin is working correctly.
+description: Diagnoses mem0 connectivity, API key validity, and memory read/write functionality. Use when memory operations fail, searches return empty, add_memory errors occur, or to verify the plugin is working correctly.
 ---
 
 # Mem0 Health Check
@@ -37,7 +37,7 @@ echo "branch=$(git branch --show-current 2>/dev/null || echo '')"
 
 PASS if all three are non-empty. WARN if any falls back to defaults.
 
-### Check 3: MCP server connectivity
+### Check 3: Memory tool connectivity
 
 Call `search_memories` with:
 - `query="health check"`
@@ -82,7 +82,7 @@ echo "branch=${MEM0_BRANCH:-}"
 
 PASS  API Key         m0-dVe...
 PASS  Identity        user=kartik, project=mem0, branch=main
-PASS  MCP Connection  142ms
+PASS  Memory Tools    142ms
 PASS  Write/Read      write + delete OK
 PASS  Session         session_id=abc123, app_id=mem0, branch=main
 

integrations/mem0-plugin/.opencode-plugin/opencode-skills/pin/SKILL.md

@@ -29,12 +29,12 @@ Call `get_memory` with the selected memory ID. Store:
 
 ### Step 3: Pin it
 
-The MCP `update_memory` tool only accepts `memory_id`, `text`, and `source` — it
-does not accept a `metadata` parameter. To pin, append a pin marker to the text:
+The `update_memory` tool updates a memory by `id`. To pin durably, append a pin
+marker to the text so it travels with the memory:
 
 ```python
 pinned_text = "[PINNED] " + original_text if not original_text.startswith("[PINNED]") else original_text
-update_memory(memory_id=<selected_id>, text=pinned_text)
+update_memory(id=<selected_id>, text=pinned_text)
 ```
 
 **For new memories** (user wants to pin text that isn't stored yet):

integrations/mem0-plugin/.opencode-plugin/opencode-skills/tour/SKILL.md

@@ -148,7 +148,7 @@ Identity - user: <user_id>  project: <project_id>  branch: <branch>
 If zero memories found for this project, print:
 ```
 No memories stored yet for project <project_id>.
-Run /mem0-onboard to import project files, or start working - mem0 captures learnings automatically.
+Start working - mem0 captures learnings automatically, or use /mem0:remember to save something now.
 ```
 
 ## Output formatting

integrations/mem0-plugin/.opencode-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/opencode-plugin",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Mem0 persistent memory plugin for OpenCode — add, search, and manage memories across sessions",
   "main": "dist/index.js",
@@ -11,9 +11,6 @@
       "import": "./dist/index.js"
     }
   },
-  "bin": {
-    "mem0-opencode": "./cli.ts"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -23,19 +20,16 @@
     "opencode-plugin",
     "mem0",
     "memory",
-    "mcp",
     "ai-memory",
     "persistent-memory"
   ],
   "repository": {
     "type": "git",
     "url": "https://github.com/mem0ai/mem0",
-    "directory": "mem0-plugin/.opencode-plugin"
+    "directory": "integrations/mem0-plugin/.opencode-plugin"
   },
   "files": [
     "dist",
-    "cli.ts",
-    "opencode.json",
     "LICENSE",
     "opencode-skills"
   ],
@@ -49,6 +43,7 @@
   "opencode": {
     "type": "plugin",
     "hooks": [
+      "config",
       "chat.message",
       "tool.execute.before",
       "tool.execute.after",
@@ -59,7 +54,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.0.162",
-    "mem0ai": "^3.0.5"
+    "mem0ai": "^3.0.7"
   },
   "devDependencies": {
     "bun-types": ">=1.3.14",

integrations/mem0-plugin/.opencode-plugin/telemetry.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { buildEvent, captureEvent, isTelemetryEnabled } from "./telemetry";
+
+const KEY = "m0-testkey123";
+
+afterEach(() => {
+  delete process.env.MEM0_TELEMETRY;
+});
+
+describe("opencode telemetry", () => {
+  test("buildEvent uses the shared plugin.* schema with platform=opencode", () => {
+    const payload = buildEvent("session_start", { memory_count: 5 }, KEY);
+    expect(payload).not.toBeNull();
+    const props = payload!.properties as Record<string, unknown>;
+    expect(payload!.event).toBe("plugin.session_start");
+    expect(props.source).toBe("plugin");
+    expect(props.platform).toBe("opencode");
+    expect(props.memory_count).toBe(5);
+    expect(props.$process_person_profile).toBe(false);
+    expect(typeof props.plugin_version).toBe("string");
+  });
+
+  test("distinct_id is sha256(apiKey)[:32] — matches the editor plugin", async () => {
+    const { createHash } = await import("node:crypto");
+    const expected = createHash("sha256").update(KEY).digest("hex").slice(0, 32);
+    expect(buildEvent("session_start", {}, KEY)!.distinct_id).toBe(expected);
+  });
+
+  test("system properties win over caller-supplied ones", () => {
+    const props = buildEvent("x", { platform: "HACK", source: "HACK" }, KEY)!
+      .properties as Record<string, unknown>;
+    expect(props.platform).toBe("opencode");
+    expect(props.source).toBe("plugin");
+  });
+
+  test("returns null without an API key (no anonymous events)", () => {
+    expect(buildEvent("session_start", {}, undefined)).toBeNull();
+  });
+
+  test("opt-out via MEM0_TELEMETRY disables events", () => {
+    process.env.MEM0_TELEMETRY = "false";
+    expect(isTelemetryEnabled()).toBe(false);
+    expect(buildEvent("session_start", {}, KEY)).toBeNull();
+  });
+
+  test("captureEvent never throws (and sends nothing when opted out)", () => {
+    process.env.MEM0_TELEMETRY = "false";
+    expect(() => captureEvent("session_start", {}, KEY)).not.toThrow();
+    expect(() => captureEvent("session_start", {}, undefined)).not.toThrow();
+    expect(() => captureEvent("session_start", {}, KEY, "proj")).not.toThrow();
+  });
+
+  test("every event carries os_version (matches telemetry.py schema)", () => {
+    const props = buildEvent("session_start", {}, KEY)!
+      .properties as Record<string, unknown>;
+    expect(typeof props.os_version).toBe("string");
+  });
+
+  test("project_hash is sha256(projectId) when a project id is supplied", async () => {
+    const { createHash } = await import("node:crypto");
+    const expected = createHash("sha256").update("acme-repo").digest("hex");
+    const props = buildEvent("session_start", {}, KEY, "acme-repo")!
+      .properties as Record<string, unknown>;
+    expect(props.project_hash).toBe(expected);
+  });
+
+  test("project_hash is omitted when no project id is supplied (no raw ids leak)", () => {
+    const props = buildEvent("session_start", {}, KEY)!
+      .properties as Record<string, unknown>;
+    expect("project_hash" in props).toBe(false);
+  });
+
+  test("expanded event types all use the shared plugin.* namespace", () => {
+    for (const ev of ["user_prompt", "bash_error", "pre_compact", "session_stop"]) {
+      expect(buildEvent(ev, {}, KEY)!.event).toBe(`plugin.${ev}`);
+    }
+  });
+});

integrations/mem0-plugin/.opencode-plugin/telemetry.ts

@@ -0,0 +1,113 @@
+/**
+ * Plugin telemetry for the Mem0 OpenCode plugin — anonymous usage tracking
+ * via PostHog.
+ *
+ * Emits the SAME event schema as the Mem0 editor plugin's telemetry.py
+ * (event names prefixed `plugin.`, `source: "plugin"`, `platform: "opencode"`,
+ * `distinct_id = sha256(apiKey)[:32]`) so OpenCode shows up as just another
+ * `platform` value in the shared plugin dashboard instead of a separate
+ * event namespace.
+ *
+ * Fire-and-forget: never throws, never blocks, failures are swallowed. Only
+ * fires when an API key is present (same as the editor plugin — anonymous
+ * installs without a key emit nothing). Disable with MEM0_TELEMETRY=false.
+ *
+ * Never sends: memory content, API keys, raw user/project IDs. Only sends:
+ * event type, platform, plugin version, and anonymized hashes of the API key
+ * and project ID.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { release } from "node:os";
+
+const POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
+const POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/";
+const REQUEST_TIMEOUT_MS = 2_000;
+
+function _loadPluginVersion(): string {
+  // Source context: telemetry.ts sits next to package.json (./).
+  // Bundled context: dist/index.js sits one level below it (../).
+  for (const rel of ["./package.json", "../package.json"]) {
+    try {
+      const pkg = JSON.parse(readFileSync(new URL(rel, import.meta.url), "utf-8"));
+      if (pkg?.name === "@mem0/opencode-plugin" && pkg.version) return pkg.version;
+    } catch {
+      /* try next candidate */
+    }
+  }
+  return "unknown";
+}
+
+const PLUGIN_VERSION = _loadPluginVersion();
+
+export function isTelemetryEnabled(): boolean {
+  const val = process.env.MEM0_TELEMETRY;
+  if (val === undefined) return true;
+  const s = val.toLowerCase();
+  return s !== "false" && s !== "0" && s !== "no" && s !== "off";
+}
+
+function distinctId(apiKey: string): string {
+  // Matches telemetry.py `_distinct_id()` so the same user is one person in
+  // PostHog whether they use OpenCode or any other Mem0 editor plugin.
+  return createHash("sha256").update(apiKey).digest("hex").slice(0, 32);
+}
+
+/**
+ * Build the PostHog event payload, or null when telemetry is disabled or no
+ * API key is available. Pure (aside from env/version reads) and exported for
+ * testing. System-controlled properties are applied last so a caller cannot
+ * override `source`/`platform`/etc.
+ */
+export function buildEvent(
+  eventType: string,
+  properties: Record<string, unknown>,
+  apiKey: string | undefined,
+  projectId?: string,
+): Record<string, unknown> | null {
+  if (!isTelemetryEnabled() || !apiKey) return null;
+  return {
+    api_key: POSTHOG_API_KEY,
+    distinct_id: distinctId(apiKey),
+    event: `plugin.${eventType}`,
+    properties: {
+      ...properties,
+      source: "plugin",
+      platform: "opencode",
+      plugin_version: PLUGIN_VERSION,
+      os: process.platform,
+      os_version: release(),
+      sample_rate: 1.0,
+      $process_person_profile: false,
+      $lib: "posthog-node",
+      // Anonymized project segmentation, matching telemetry.py's project_hash.
+      ...(projectId
+        ? { project_hash: createHash("sha256").update(projectId).digest("hex") }
+        : {}),
+    },
+  };
+}
+
+/** Send a usage event, fire-and-forget. Never throws, never blocks. */
+export function captureEvent(
+  eventType: string,
+  properties: Record<string, unknown>,
+  apiKey: string | undefined,
+  projectId?: string,
+): void {
+  const payload = buildEvent(eventType, properties, apiKey, projectId);
+  if (!payload) return;
+  try {
+    void fetch(POSTHOG_HOST, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch(() => {
+      /* fire-and-forget */
+    });
+  } catch {
+    /* never throw */
+  }
+}

integrations/mem0-plugin/.opencode-plugin/tsconfig.json

@@ -16,5 +16,5 @@
     "emitDeclarationOnly": true
   },
   "include": ["**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }

integrations/mem0-plugin/CHANGELOG.md

@@ -2,11 +2,44 @@
 
 All notable changes to the Mem0 plugin will be documented in this file.
 
+## 0.2.10 — Accurate per-editor telemetry attribution
+
+### Fixed
+
+- **Antigravity counted as Claude Code:** `detect_platform()` (`scripts/telemetry.py`) now checks `ANTIGRAVITY_PLUGIN_ROOT` before the `CLAUDE_PLUGIN_ROOT` branch. Antigravity sets both env vars for compatibility, so every Antigravity session was previously attributed to `claude-code`. Telemetry now reports `platform: "antigravity"`.
+- **Codex fell back to the generic `plugin` bucket:** Codex installs standalone hooks with absolute paths via `install_codex_hooks.py`, so `PLUGIN_ROOT` is never set at runtime and platform auto-detection failed. Each command in `hooks/codex-hooks.json` now pins `MEM0_PLATFORM=codex` inline (Codex runs hook commands through a shell). Telemetry now reports `platform: "codex"`.
+- **Cursor attribution depended on the host env:** Cursor's `*_cursor.sh` wrappers delegate to the shared hook scripts, whose platform detection relied on Cursor exporting `CURSOR_PLUGIN_ROOT` to the subprocess. All five Cursor wrappers now `export MEM0_PLATFORM=cursor` before delegating.
+- **`plugin_version` was identical for every editor:** telemetry read `.claude-plugin/plugin.json` for all bash-hook editors, so Antigravity reported `0.2.10` instead of its real `0.1.2`. `_load_plugin_version()` now reads the manifest matching the detected platform, so each editor reports its own version.
+
+### Added
+
+- **`MEM0_PLATFORM` override in `detect_platform()`:** An explicit platform marker that wins over env-var auto-detection, letting each editor label its telemetry reliably. New tests in `tests/test_telemetry.py` cover the override, Antigravity attribution, and the Cursor/Codex platform-pinning contracts.
+
+> Attribution fixes apply to telemetry emitted after users upgrade to this version; PostHog does not backfill past events.
+
+## 0.2.9 — File-context injection, session summaries & activity timeline
+
+### Added
+
+- **File-context injection (`PreToolUse/Read` hook):** Before Claude reads a file, the new `on_file_read.sh` hook searches mem0 for memories that reference that file path and injects a compact timeline of prior work as `additionalContext`. Gives Claude "I've seen this file before and here's what I remember" context automatically. Gates on file size (>= 1,500 bytes), 5-second hard timeout, silent skip on any failure. Applies to Claude Code, Codex, and Cursor (`on_file_read_cursor.sh`).
+- **Stop hook session summary (`on_stop.sh`):** On session end, parses the transcript JSONL, extracts the last assistant message and files touched, builds a structured prompt, and stores it via the mem0 API with `infer=True` — letting the platform's backend AI extract structured facts (request, decisions, learnings, next steps). Memories are stored as `metadata.type=session_summary` with 90-day expiry. Guards: skips subagent sessions (`agent_id` present), dedup via marker file, always exits 0. Applies to Claude Code, Codex, and Cursor (`on_stop_cursor.sh`).
+- **SessionStart activity timeline (`session_timeline.py`):** On startup (when project has existing memories), fetches the 10 most recent memories and renders a compact timeline with type icons, age indicators, and short text below the existing banner. Shows recent decisions, bug fixes, and session summaries at a glance. 5-second timeout — if the API is slow, the timeline silently skips while the banner still displays.
+- **`scripts/file_context.py`:** Core Python module for file-context injection. Searches mem0 cloud API with both relative and absolute file paths, deduplicates results, formats as compact timeline with type icons and memory age.
+- **`scripts/capture_session_summary.py`:** Core Python module for Stop hook. Reads transcript JSONL (tail 3,000 lines), extracts last assistant message, extracts file paths from tool_input fields, strips system tags and `<private>` blocks, stores via mem0 API.
+- **`scripts/session_timeline.py`:** Core Python module for SessionStart timeline. Fetches recent memories from mem0 API, formats with type icons, relative age, and short text.
+
+### Changed
+
+- **`on_session_start.sh`:** On startup (when memories > 0), calls `session_timeline.py` to inject a compact recent activity timeline below the existing banner and rubric instructions.
+- **`hooks/hooks.json`:** Added `PreToolUse` matcher for `Read` (5s timeout) and `Stop` hook (30s timeout).
+- **`hooks/codex-hooks.json`:** Added `PreToolUse` matcher for `Read` (5s timeout) and `Stop` hook (30s timeout).
+- **`hooks/cursor-hooks.json`:** Added `preToolUse` matcher for `Read` (5s timeout) and `stop` hook (30s timeout).
+
 ## 0.2.8 — Automatic coding categories & global search
 
 ### Added
 
-- **Global search mode (`global_search` setting):** New `global_search` toggle in `~/.mem0/settings.json` (default: `false`). When enabled, `search_memories` and `get_memories` calls use `{"OR": [{"user_id": "*"}]}` instead of the per-user per-project `AND` filter — returning all memories across all users and all `app_id` scopes in the platform project. Writes (`add_memory`) still tag with the current `user_id` and `app_id`. Solves the team-shared-memory use case where multiple team members need access to all memories regardless of which repo or user created them. Works on Claude Code, Cursor, and Codex (not OpenCode, which has its own TypeScript identity logic).
+- **Global search mode (`global_search` setting):** New `global_search` toggle in `~/.mem0/settings.json` (default: `false`). When enabled, `search_memories` and `get_memories` calls use `{"OR": [{"user_id": "*"}]}` instead of the per-user per-project `AND` filter — returning all memories across all users and all `app_id` scopes in the platform project. Writes (`add_memory`) still tag with the current `user_id` and `app_id`. Solves the team-shared-memory use case where multiple team members need access to all memories regardless of which repo or user created them. Works on Claude Code, Cursor, and Codex.
 - **`/mem0:switch-project --global` / `--no-global`:** Enables or disables global search via the switch-project skill. Persists to `~/.mem0/settings.json`. No manual config editing needed.
 - **Session banner scope indicator:** Banner shows `scope=global` when global search is active instead of `project=<app_id>`.
 - **Global-aware memory count:** Session start memory count query uses the global filter when `global_search` is enabled.
@@ -20,17 +53,10 @@ All notable changes to the Mem0 plugin will be documented in this file.
 - **`/mem0:onboard` Step 5 is no longer interactive:** Removed the `Install coding categories? [Y/n]` prompt. Categories now configure automatically in the background; the onboarding step only verifies status and applies them if the background run hasn't finished yet — mirroring how Step 4 (project-file import) already works.
 - **Session-start "new project" hint** now notes that coding categories install automatically in the background.
 
-## 0.1.0 — OpenCode & Antigravity
+## 0.1.0 — Antigravity
 
 ### Added
 
-- **OpenCode plugin** (`@mem0/opencode-plugin` on npm): Pure TypeScript plugin using the `mem0ai` TS SDK — no Python, no shell scripts. Hooks into all 6 OpenCode events (`chat.message`, `tool.execute.before`, `tool.execute.after`, `experimental.chat.system.transform`, `experimental.session.compacting`, `shell.env`). Features: session start memory loading, per-prompt semantic search, error pattern detection with memory lookup, resume/remember intent detection, auto-capture every 3rd message, periodic save nudges, full metadata defaults injection (confidence, source, type, session_id, files, branch), identity injection for search/get/delete filters, type-filtered error pre-fetch (anti_pattern + bug_fix), pre-compaction memory capture, MEMORY.md write blocking, and secret redaction.
-- **16 OpenCode-native skills** bundled in `opencode-skills/`: `context-loader`, `dream`, `export`, `forget`, `health`, `import`, `list-projects`, `mem0` (SDK reference), `memory-reviewer`, `onboard`, `peek`, `pin`, `remember`, `stats`, `switch-project`, `tour`. All skills are pure MCP-tool-based — no Python scripts, no shell scripts, no Claude Code dependencies.
-- **Auto-install skills and commands (`installSkills()`):** On plugin load, copies all 16 skills to `.opencode/skills/` and creates command wrapper files in `.opencode/commands/` so they appear in the OpenCode `/` palette. No manual setup needed.
-- **`extractUserText()` handler:** Robust text extraction from OpenCode response shapes — handles `parts[]` array, `content[]` array, `message.content`, and plain string responses.
-- **Identity resolution:** `getUserId()` uses `os.userInfo().username` (matching Claude Code's `${USER}` convention) with `MEM0_USER_ID` env override. `getProjectId()` uses git remote with `MEM0_APP_ID` env override.
-- **Context injection via `experimental.chat.system.transform`:** All memory context (session start memories, per-prompt search results, error-related memories, compaction context) injected as system context.
-- **CLI installer (`cli.ts`):** `bunx @mem0/opencode-plugin install` auto-configures plugin and MCP server in `~/.config/opencode/opencode.json`.
 - **Antigravity plugin** (`.antigravity/`): Restructured to follow the same shared-infrastructure pattern as Claude Code, Cursor, and Codex. Self-contained plugin directory with `plugin.json`, `mcp_config.json`, `hooks/hooks.json` (own file), `scripts/` (symlink → `../scripts/`), and `skills/` (symlink → `../skills/`). Installable via `agy plugin install .antigravity` or `npx degit mem0ai/mem0/mem0-plugin/.antigravity ~/.gemini/config/plugins/mem0`. Uses `contextFileName: "AGENTS.md"` per Antigravity convention.
 - **Codex hooks parity:** Added missing `PreToolUse` Write/Edit/MultiEdit block and `PreCompact` hook to Codex hooks config, bringing it to full parity with Claude Code.
 

integrations/mem0-plugin/README.md

@@ -90,14 +90,14 @@ git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source
 codex plugin marketplace add ~/codex-plugins/mem0-source
 ```
 
-This points Codex at the repo's `.agents/plugins/marketplace.json`, which references `mem0-plugin/` as the local source. Restart Codex, run `/plugins`, and install **Mem0** from the **Mem0 Plugins** marketplace.
+This points Codex at the repo's `.agents/plugins/marketplace.json`, which references `integrations/mem0-plugin/` as the local source. Restart Codex, run `/plugins`, and install **Mem0** from the **Mem0 Plugins** marketplace.
 
-> **Don't combine with Option A.** The plugin manifest auto-registers `mem0` as an MCP server via `mem0-plugin/.codex-mcp.json` — adding a manual `[mcp_servers.mem0]` block would duplicate the registration.
+> **Don't combine with Option A.** The plugin manifest auto-registers `mem0` as an MCP server via `integrations/mem0-plugin/.codex-mcp.json` — adding a manual `[mcp_servers.mem0]` block would duplicate the registration.
 
 **Optional — enable lifecycle hooks.** Codex doesn't auto-wire hooks from plugin manifests; it only reads `~/.codex/hooks.json` (or `<repo>/.codex/hooks.json`) ([docs](https://developers.openai.com/codex/hooks)). Run the bundled installer once to merge Mem0's entries:
 
 ```bash
-python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py
+python3 ~/codex-plugins/mem0-source/integrations/mem0-plugin/scripts/install_codex_hooks.py
 ```
 
 This merges three entries into `~/.codex/hooks.json` with absolute paths pointing into your clone:
@@ -190,7 +190,7 @@ See [OpenCode integration docs](https://docs.mem0.ai/integrations/opencode) for
 
 ```bash
 # Install the plugin (MCP server, hooks, scripts)
-npx degit mem0ai/mem0/mem0-plugin ~/.gemini/config/plugins/mem0
+npx degit mem0ai/mem0/integrations/mem0-plugin ~/.gemini/config/plugins/mem0
 ```
 
 This installs the MCP server, lifecycle hooks, and shared scripts.
@@ -276,10 +276,10 @@ The background setup is idempotent and runs once per account (cached in `~/.mem0
 
 ```bash
 # Dry-run -- prints current vs proposed, no changes:
-python mem0-plugin/scripts/setup_coding_categories.py
+python integrations/mem0-plugin/scripts/setup_coding_categories.py
 
 # Write explicitly:
-python mem0-plugin/scripts/setup_coding_categories.py --apply
+python integrations/mem0-plugin/scripts/setup_coding_categories.py --apply
 ```
 
 Requires the `mem0ai` Python SDK (`pip install mem0ai`) and `MEM0_API_KEY` set. `project.update(custom_categories=[...])` always replaces the full list.

integrations/mem0-plugin/hooks.json

@@ -51,6 +51,29 @@
             "timeout": 3
           }
         ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "name": "mem0-file-context",
+            "type": "command",
+            "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/on_file_read.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "name": "mem0-session-summary",
+            "type": "command",
+            "command": "ANTIGRAVITY_PLUGIN_ROOT=${extensionPath} CLAUDE_PLUGIN_ROOT=${extensionPath} bash ${extensionPath}/scripts/on_stop.sh",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "PostToolUse": [