chore: release Python SDK v2.0.5 and TypeScript SDK v3.0.7 (#5470)

.github/workflows/cd.yml

@@ -1,20 +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
     # Pure SDK version tags only (v1.2.3) — excludes package-prefixed tags
     # like vercel-ai-v* that also start with 'v'
-    if: startsWith(github.event.release.tag_name, 'v') && !contains(github.event.release.tag_name, '-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
@@ -41,7 +54,6 @@ jobs:
       #     packages_dir: dist/
 
       - name: Publish distribution 📦 to PyPI
-        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-v')
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages_dir: dist/

.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-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/openclaw-cd.yml

@@ -1,13 +1,25 @@
 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
@@ -16,6 +28,8 @@ jobs:
         working-directory: openclaw
     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/opencode-plugin-cd.yml

@@ -1,13 +1,25 @@
 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
@@ -16,6 +28,8 @@ jobs:
         working-directory: 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/pi-agent-plugin-cd.yml

@@ -1,13 +1,25 @@
 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:
-  release:
-    types: [published]
+  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(github.event.release.tag_name, 'pi-agent-v')
+    if: startsWith(inputs.tag, 'pi-agent-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +28,8 @@ jobs:
         working-directory: pi-agent-plugin
     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/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/vercel-ai-cd.yml

@@ -1,13 +1,25 @@
 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
@@ -16,6 +28,8 @@ jobs:
         working-directory: vercel-ai-sdk
     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

AGENTS.md

@@ -418,8 +418,11 @@ To add a new LLM, embedding, vector store, or reranker provider:
 
 ### 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`) |
@@ -429,8 +432,11 @@ To add a new LLM, embedding, vector store, or reranker provider:
 | 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
 

docs/changelog/sdk.mdx

@@ -7,6 +7,26 @@ mode: "wide"
 <Tabs>
 <Tab title="Python">
 
+<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 +959,20 @@ See the [OSS v1 to v2 migration guide](https://docs.mem0.ai/migration/oss-v1-to-
 </Tab>
 
 <Tab title="TypeScript">
+
+<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:**

mem0-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0ai",
-  "version": "3.0.6",
+  "version": "3.0.7",
   "description": "The Memory Layer For Your AI Apps",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mem0ai"
-version = "2.0.4"
+version = "2.0.5"
 description = "Long-term memory for AI Agents"
 authors = [
     { name = "Mem0", email = "support@mem0.ai" }