superlocalmemory 3.8.8 → 3.8.9

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.9] - 2026-07-27 — Reliable MCP recall and background processing
+
+### Fixed
+- MCP recall is reliable through both supported connection methods: local
+  stdio and Streamable HTTP. HTTP tool calls no longer hang the daemon.
+- Changing dashboard memory or model settings no longer leaves background
+  processing stuck. Your saved memories stay available while processing resumes
+  safely with the updated settings.
+- Newly saved memories remain immediately searchable while their richer
+  background indexing completes.
+
+### Notes
+- Existing memories and configuration are preserved during upgrade. No manual
+  migration is required.
+
 ## [3.8.8] - 2026-07-27 — Live-database recall and vector integrity
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.8.8",
+  "version": "3.8.9",
   "description": "Local-first agent memory with MCP and an agent-native CLI. Documented clients include Claude Code, Cursor, and Windsurf.",
   "keywords": [
     "ai-memory",

package/plugin/.claude-plugin/plugin.json

@@ -15,5 +15,5 @@
   "mcpServers": "./.mcp.json",
   "name": "superlocalmemory",
   "repository": "https://github.com/qualixar/superlocalmemory",
-  "version": "3.8.8"
+  "version": "3.8.9"
 }

package/plugin/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v3.8.8 -->
+<!-- BEGIN SuperLocalMemory v3.8.9 -->
 
 ## SuperLocalMemory (SLM) — Agent Rules
 
@@ -39,6 +39,6 @@ slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-comp
 ### Subagents
 slm-memory-advisor (memory decisions, session hygiene, scope/profile guidance) · slm-optimize-advisor (context compression + KV cache) · slm-governance-advisor (scope/roles/compliance/GDPR)
 
-<!-- END SuperLocalMemory v3.8.8 -->
+<!-- END SuperLocalMemory v3.8.9 -->
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-governance-advisor.md

@@ -77,4 +77,4 @@ slm-scope · slm-governance · slm-profile · slm-remember · slm-recall
 # What NOT to do
 Never session_init twice; never forget without dry-run preview; never store secrets; never bypass role checks; never claim an erasure succeeded without verifying via recall.
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-loop-runner.md

@@ -68,4 +68,4 @@ assessment. The gate is the authority.
 
 ---
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-memory-advisor.md

@@ -46,4 +46,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never carry ccr_ids across profile switches.
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/requirements.txt

@@ -1 +1 @@
-superlocalmemory==3.8.8
+superlocalmemory==3.8.9

package/plugin/skills/slm-cache/SKILL.md

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-compress/SKILL.md

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-governance/SKILL.md

@@ -245,4 +245,4 @@ Before running any destructive operation (`forget`, `compact_memories`):
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-graph/SKILL.md

@@ -311,4 +311,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-loop/SKILL.md

@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-mesh/SKILL.md

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-profile/SKILL.md

@@ -145,4 +145,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-recall/SKILL.md

@@ -236,4 +236,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-remember/SKILL.md

@@ -238,4 +238,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-scope/SKILL.md

@@ -173,4 +173,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-session/SKILL.md

@@ -227,4 +227,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-status/SKILL.md

@@ -163,4 +163,4 @@ multi-profile setup. To switch the active profile, see `slm-profile`.
 
 ---
 
-SuperLocalMemory v3.8.8 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.9 · Qualixar · AGPL-3.0-or-later

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.8.8"
+version = "3.8.9"
 description = "Local-first agent memory with auditable hybrid retrieval"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

package/src/superlocalmemory/__init__.py

@@ -32,7 +32,7 @@ if "OMP_NUM_THREADS" not in os.environ:
     os.environ["OMP_NUM_THREADS"] = "2"
 # ---------------------------------------------------------------------------
 
-__version__ = "3.8.8"
+__version__ = "3.8.9"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/core/embeddings.py

@@ -800,9 +800,32 @@ class EmbeddingService:
         client = self._get_http_client()
         last_error: Exception | None = None
         for attempt in range(max_retries):
+            from superlocalmemory.core.materialization_control import (
+                MaterializationDeferred,
+            )
+            from superlocalmemory.core.recall_gate import (
+                background_preempt_requested,
+                is_background_work,
+            )
+            if background_preempt_requested():
+                raise MaterializationDeferred(
+                    "background embedding yielded to runtime transition"
+                )
             try:
-                resp = client.post(endpoint, headers=headers, json=body)
+                request_kwargs = {"headers": headers, "json": body}
+                if is_background_work():
+                    # Runtime reconfigure drains admitted operations in five
+                    # seconds.  A background remote read must leave enough
+                    # scheduling margin to observe that transition and release
+                    # its lease, while interactive recall keeps the provider's
+                    # normal timeout budget.
+                    request_kwargs["timeout"] = 3.5
+                resp = client.post(endpoint, **request_kwargs)
                 resp.raise_for_status()
+                if background_preempt_requested():
+                    raise MaterializationDeferred(
+                        "background embedding yielded to runtime transition"
+                    )
                 data = resp.json()
                 if "data" not in data or not isinstance(data["data"], list):
                     raise ValueError(
@@ -818,6 +841,12 @@ class EmbeddingService:
                     )
                 return results
             except Exception as exc:
+                if isinstance(exc, MaterializationDeferred):
+                    raise
+                if background_preempt_requested():
+                    raise MaterializationDeferred(
+                        "background embedding yielded to runtime transition"
+                    ) from exc
                 last_error = exc
                 if attempt < max_retries - 1:
                     time.sleep(2 ** attempt)
@@ -857,15 +886,39 @@ class EmbeddingService:
         client = self._get_http_client()
         last_error: Exception | None = None
         for attempt in range(max_retries):
+            from superlocalmemory.core.materialization_control import (
+                MaterializationDeferred,
+            )
+            from superlocalmemory.core.recall_gate import (
+                background_preempt_requested,
+                is_background_work,
+            )
+            if background_preempt_requested():
+                raise MaterializationDeferred(
+                    "background embedding yielded to runtime transition"
+                )
             try:
-                resp = client.post(url, headers=headers, json=body)
+                request_kwargs = {"headers": headers, "json": body}
+                if is_background_work():
+                    request_kwargs["timeout"] = 3.5
+                resp = client.post(url, **request_kwargs)
                 resp.raise_for_status()
+                if background_preempt_requested():
+                    raise MaterializationDeferred(
+                        "background embedding yielded to runtime transition"
+                    )
                 data = resp.json()
                 results = []
                 for item in sorted(data["data"], key=lambda d: d["index"]):
                     results.append(item["embedding"])
                 return results
             except Exception as exc:
+                if isinstance(exc, MaterializationDeferred):
+                    raise
+                if background_preempt_requested():
+                    raise MaterializationDeferred(
+                        "background embedding yielded to runtime transition"
+                    ) from exc
                 last_error = exc
                 if attempt < max_retries - 1:
                     time.sleep(2 ** attempt)

package/src/superlocalmemory/core/engine_ingestion.py

@@ -736,6 +736,11 @@ def build_engine_ingestion_command(engine: MemoryEngine) -> IngestionCommand:
                 materialization_checkpoint=checkpoint_materialization,
             )
         except Exception as exc:
+            from superlocalmemory.core.materialization_control import (
+                MaterializationDeferred,
+            )
+            if isinstance(exc, MaterializationDeferred):
+                raise
             # ``run_store`` checkpoints the completed relational pipeline
             # immediately before post-hooks run.  Prefer that durable ledger
             # over rebuilding state from local variables: a one-time hook

package/src/superlocalmemory/core/ingestion_command.py

@@ -22,6 +22,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Callable
 
+from superlocalmemory.core.materialization_control import MaterializationDeferred
 from superlocalmemory.storage.database import DatabaseManager
 
 logger = logging.getLogger("superlocalmemory.ingestion_command")
@@ -606,6 +607,31 @@ class IngestionOperationRepository:
                 ) from exc
         return self._from_row(rows[0])
 
+    def defer_enriching(
+        self,
+        operation_id: str,
+        *,
+        owner: str,
+    ) -> IngestionOperation:
+        """Release a transition-preempted lease without consuming a retry.
+
+        Queryable evidence remains durable.  The compare-and-swap owner check
+        prevents a stale worker from requeueing work that another process has
+        already reclaimed.
+        """
+        rows = self.db.execute(
+            "UPDATE ingestion_operations SET state='queryable', "
+            "lease_owner='', lease_expires_at=0, next_retry_at=0, "
+            "attempt_count=CASE WHEN attempt_count > 0 THEN attempt_count - 1 ELSE 0 END, "
+            "last_error='', updated_at=strftime('%Y-%m-%dT%H:%M:%fZ', 'now') "
+            "WHERE operation_id=? AND state='enriching' AND lease_owner=? "
+            "RETURNING *",
+            (operation_id, owner),
+        )
+        if not rows:
+            raise InvalidStateTransition("enriching lease ownership was lost")
+        return self._from_row(rows[0])
+
     def reap_stuck_enriching(
         self,
         *,
@@ -936,6 +962,11 @@ class IngestionCommand:
                 )
         except LeaseLost:
             raise
+        except MaterializationDeferred:
+            return self.repository.defer_enriching(
+                operation_id,
+                owner=self._owner,
+            )
         except Exception as exc:
             return self.repository.finish_enriching(
                 operation_id,
@@ -983,6 +1014,11 @@ class IngestionCommand:
             )
         except LeaseLost:
             raise
+        except MaterializationDeferred:
+            return self.repository.defer_enriching(
+                operation.operation_id,
+                owner=self._owner,
+            )
         except Exception as exc:
             return self.repository.finish_enriching(
                 operation.operation_id,

package/src/superlocalmemory/core/materialization_control.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3
+
+"""Control-flow signals for best-effort materialization work.
+
+These exceptions deliberately live outside the ingestion state machine and
+embedding implementation so either layer can request a durable deferral
+without introducing an import cycle.
+"""
+
+from __future__ import annotations
+
+
+class MaterializationDeferred(RuntimeError):
+    """Best-effort enrichment yielded to a runtime transition.
+
+    The queryable projection is already durable.  This signal must be handled
+    by :class:`IngestionCommand` as a requeue, never as a failed attempt.
+    """

package/src/superlocalmemory/core/recall_gate.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 
 import threading
 from contextlib import contextmanager
-from typing import Iterator
+from typing import Callable, Iterator
 
 _condition = threading.Condition(threading.Lock())
 _active = 0
@@ -42,19 +42,30 @@ def in_flight() -> int:
 
 
 @contextmanager
-def background_work() -> Iterator[None]:
+def background_work(
+    *,
+    preempt_requested: Callable[[], bool] | None = None,
+) -> Iterator[None]:
     """Mark best-effort work that must yield shared inference to recall.
 
     The marker is thread-local because materialization, health probes, and
     interactive handlers all share one resident engine and one embedder.
-    Nested callers restore the previous marker on exit.
+    Nested callers restore the previous marker on exit.  A daemon-owned
+    materializer may also provide a preemption callback for a profile/runtime
+    reconfigure.  Inference clients use that callback to cut a bounded
+    background request short instead of holding the transition drain lease.
     """
     previous = bool(getattr(_work_context, "background", False))
+    previous_preempt = getattr(_work_context, "preempt_requested", None)
     _work_context.background = True
+    _work_context.preempt_requested = (
+        preempt_requested if preempt_requested is not None else previous_preempt
+    )
     try:
         yield
     finally:
         _work_context.background = previous
+        _work_context.preempt_requested = previous_preempt
 
 
 def is_background_work() -> bool:
@@ -62,6 +73,19 @@ def is_background_work() -> bool:
     return bool(getattr(_work_context, "background", False))
 
 
+def background_preempt_requested() -> bool:
+    """Return whether daemon-owned background work must release its lease."""
+    callback = getattr(_work_context, "preempt_requested", None)
+    if not callable(callback):
+        return False
+    try:
+        return bool(callback())
+    except Exception:
+        # A status read is advisory.  It must not crash a materializer or turn
+        # a valid recall into an ingestion failure.
+        return False
+
+
 def wait_for_foreground_idle() -> None:
     """Block background inference while an interactive recall is active."""
     if not is_background_work():

package/src/superlocalmemory/core/store_pipeline.py

@@ -34,6 +34,14 @@ logger = logging.getLogger(__name__)
 _INIT_LANGEVIN_RADIUS = 0.05
 
 
+def _reraise_materialization_deferral(exc: Exception) -> None:
+    """Keep explicit runtime preemption out of best-effort fallbacks."""
+    from superlocalmemory.core.materialization_control import MaterializationDeferred
+
+    if isinstance(exc, MaterializationDeferred):
+        raise exc
+
+
 def _ingestion_effect_id(operation_id: str, *parts: object) -> str:
     """Return a stable ID for a relational effect owned by one ingestion."""
     if not operation_id:
@@ -247,6 +255,7 @@ def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=Non
         try:
             fact.embedding = embedder.embed(fact.content)
         except Exception as _emb_exc:  # pragma: no cover - defensive
+            _reraise_materialization_deferral(_emb_exc)
             logger.debug("on-demand embed failed for %s: %s", fact.fact_id, _emb_exc)
             return
     if not getattr(fact, "embedding", None):
@@ -429,6 +438,7 @@ def run_store(
         )
         extraction_complete = facts is not None
     except Exception as _extract_exc:
+        _reraise_materialization_deferral(_extract_exc)
         # P0-1 (remember-write-04): an extractor EXCEPTION (transient LLM/embed
         # backend error) must NOT orphan the already-committed memory. The None
         # guard below only handled a None *return*, not a raise. Treat a raise

package/src/superlocalmemory/mcp/tools_core.py

@@ -282,7 +282,6 @@ def register_core_tools(server, get_engine: Callable) -> None:
         import asyncio
         try:
             from superlocalmemory.mcp._daemon_proxy import choose_pool
-            pool = choose_pool()
             # S9-DASH-10: priority for session_id, so engagement
             # signals land on the right pending_outcome:
             #   1. Explicit ``session_id`` tool-call argument.
@@ -322,15 +321,25 @@ def register_core_tools(server, get_engine: Callable) -> None:
                     pass
             if not effective_sid:
                 effective_sid = f"mcp:{agent_id}"
-            # V3.3.19: Run in thread pool to avoid blocking MCP event loop.
+            # Resolve the daemon proxy inside the worker too. ``choose_pool``
+            # verifies daemon ownership through a synchronous /health request;
+            # when this tool is served by the daemon's mounted HTTP MCP app,
+            # resolving it on Uvicorn's event-loop thread makes that loop wait
+            # on its own health response forever. Stdio did not exhibit this
+            # because its MCP process is external to the daemon.
+            #
             # V3.4.26: WorkerPool now concurrent — parallel calls no longer
             # block behind a single threading.Lock. See worker_pool.py.
+            def _recall_via_daemon_pool():
+                pool = choose_pool()
+                return pool.recall(
+                    query, limit=limit, session_id=effective_sid,
+                    fast=fast, include_global=include_global,
+                    include_shared=include_shared, window=window or None,
+                )
+
             result = await asyncio.to_thread(
-                pool.recall, query, limit=limit, session_id=effective_sid,
-                fast=fast,
-                include_global=include_global,
-                include_shared=include_shared,
-                window=window or None,
+                _recall_via_daemon_pool,
             )
             if result.get("ok"):
                 return {

package/src/superlocalmemory/server/unified_daemon.py

@@ -4060,7 +4060,9 @@ def _run_materializer_operation(
                 "resident engine does not match pending profile"
             )
         from superlocalmemory.core.recall_gate import background_work
-        with background_work():
+        with background_work(
+            preempt_requested=lambda: bool(runtime is not None and runtime.transitioning),
+        ):
             return operation(engine)