chore: release v10.24.0 — fix external embedding API silent fallback

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: doobidoo

CHANGELOG.md

@@ -10,6 +10,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [10.24.0] - 2026-03-05
+
+### Fixed
+
+- **[#551] External embedding API silent fallback corrupts vector space**: When an external embedding provider (vLLM, Ollama, TEI, OpenAI-compatible) returned an error, `sqlite_vec.py` silently fell back to the local ONNX model. This produced embeddings in a different vector space than the rest of the database, causing all subsequent semantic searches to return incorrect or irrelevant results with no warning to the user. The fix replaces the silent `logger.warning + fallback` path with a hard `raise RuntimeError(...)` that clearly states the API failure reason and, when detectable, the existing database embedding dimension (read from `sqlite_master` via `_get_existing_db_embedding_dimension()` using `asyncio.to_thread()` for non-blocking execution). A stale integration test that asserted a `version` field on `/api/health` (removed in the GHSA-73hc-m4hx-79pj security hardening) was also corrected.
+
+### Tests
+
+- 10 regression tests in `tests/storage/test_issue_551_external_embedding_fallback.py` covering: hard failure on API error, dimension mismatch detection, DRY error message format, `asyncio.to_thread` integration, and interaction with the existing DB dimension helper
+- 1,397 total tests
+
 ## [10.23.0] - 2026-03-05
 
 ### Fixed

CLAUDE.md

@@ -16,7 +16,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with th
 
 MCP Memory Service is a Model Context Protocol server providing semantic memory and persistent storage for Claude Desktop and 13+ AI applications. It uses vector embeddings for semantic search, supports multiple storage backends (SQLite-vec, Cloudflare, Hybrid), and includes advanced features like memory consolidation, quality scoring, and OAuth 2.1 team collaboration.
 
-**Current Version:** v10.23.0 - Quality scorer fix, consolidator improvements, two new opt-out flags: fix asyncio NameError in ai_evaluator.py (#544), fix consolidator invalid memory_type and dedup bug (#545), MCP_TYPED_EDGES_ENABLED opt-out (#546), MCP_CONSOLIDATION_STORE_ASSOCIATIONS opt-out (#547) — 14 new tests, 1,387 total — see [CHANGELOG.md](CHANGELOG.md) for details
+**Current Version:** v10.24.0 - External embedding API silent fallback fixed: raises RuntimeError on API failure instead of mixing embedding spaces (#551), DRY error messages with DB dimension detection, stale health endpoint integration test corrected — 10 new tests, 1,397 total — see [CHANGELOG.md](CHANGELOG.md) for details
 
 > **🎯 v10.0.0 Milestone**: This major release represents a complete API consolidation - 34 tools unified into 12 with enhanced capabilities. All deprecated tools continue working with warnings until v11.0. See `docs/MIGRATION.md` for migration guide.
 

README.md

@@ -265,20 +265,20 @@ Export memories from mcp-memory-service → Import to shodh-cloudflare → Sync
 ---
 
 
-## Latest Release: **v10.23.0** (March 5, 2026)
+## Latest Release: **v10.24.0** (March 5, 2026)
 
-**Quality scorer fix, consolidator improvements, two new opt-out flags**
+**Bug fix: external embedding API failure now raises an error instead of silently corrupting the vector space**
 
 **What's New:**
-- **Fix asyncio NameError in batch quality scoring** (closes #544): Missing `import asyncio` in `ai_evaluator.py` caused `NameError` crashes for all users without ONNX Runtime, leaving 41%+ of memories unscored.
-- **Fix consolidator memory_type and dedup bugs** (closes #545): Invalid `memory_type="association"` (not in ontology) and missing `skip_semantic_dedup=True` caused association content to be rejected as duplicates; store() failure reason now logged.
-- **MCP_TYPED_EDGES_ENABLED=false opt-out** (closes #546): Disable typed edge inference — all inferred relationships return as `"related"` when disabled (default: `true`).
-- **MCP_CONSOLIDATION_STORE_ASSOCIATIONS=false opt-out** (closes #547): Suppress writing association entries to `memories` table during consolidation; associations remain in `memory_graph` (default: `true`).
-- **1,387 tests** now passing (14 new regression tests for all four issues)
+- **Fix silent fallback on external embedding API failure** (closes #551): When an external embedding provider (vLLM, Ollama, TEI, OpenAI-compatible) returned an error, the service silently fell back to the local ONNX model, mixing embedding spaces and causing all semantic searches to return incorrect results. Now raises a hard `RuntimeError` with the API failure reason and, when detectable, the existing DB dimension.
+- **DRY, informative error messages**: Error includes the detected DB embedding dimension from `sqlite_master` (via `_get_existing_db_embedding_dimension()`) to help diagnose mismatches.
+- **Stale integration test corrected**: `/api/health` integration test updated to match the security-hardened endpoint (GHSA-73hc-m4hx-79pj stripped the `version` field).
+- **1,397 tests** now passing (10 new regression tests for issue #551)
 
 ---
 
 **Previous Releases**:
+- **v10.23.0** - Quality scorer fix, consolidator improvements, two new opt-out flags: fix asyncio NameError in ai_evaluator.py (#544), fix consolidator invalid memory_type and dedup bug (#545), MCP_TYPED_EDGES_ENABLED opt-out (#546), MCP_CONSOLIDATION_STORE_ASSOCIATIONS opt-out (#547) — 14 new tests
 - **v10.22.0** - Consolidation engine stability: fix memory_consolidate status KeyError (#542), prevent exponential metadata prefix nesting (#543), reduce RelationshipInferenceEngine false positive rate (#541) — 40 new tests
 - **v10.21.1** - Security: Resolve 5 CodeQL code scanning alerts — removed unused imports, fixed empty except clause with explanatory comment, mitigated stack-trace exposure via `repr()` in consolidation API responses
 - **v10.21.0** - Security: Harden health endpoints against info disclosure (GHSA-73hc-m4hx-79pj, CVSS 5.3 Medium) — status-only `/api/health`, auth required on `/api/health/detailed`, default binding `127.0.0.1` (BREAKING), 7 regression tests

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-memory-service"
-version = "10.23.0"
+version = "10.24.0"
 description = "Open-source persistent memory for AI agent pipelines and Claude. REST API + semantic search + knowledge graph + autonomous consolidation. Self-host, zero cloud cost."
 readme = "README.md"
 requires-python = ">=3.10"

src/mcp_memory_service/_version.py

@@ -1,3 +1,3 @@
 """Version information for MCP Memory Service."""
 
-__version__ = "10.23.0"
+__version__ = "10.24.0"