superlocalmemory 3.7.1 → 3.7.2

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.7.2] - 2026-07-16 — Reliability release
+
+### Fixed
+
+- Strengthened daemon-owned local write coordination across Mesh and MCP paths.
+- Kept durable facts queryable when optional enrichment needs a controlled retry.
+- Preserved graph-aware retrieval through the canonical fallback when sqlite-vec is unavailable.
+- Bounded local embedding-worker dependency failures to prevent repeated worker respawns.
+- Hardened Windows RAM reservations and cross-platform installer validation.
+
 ## [3.7.1] - 2026-07-16 — Installer-parity hotfix
 
 ### Fixed

package/README.md

@@ -2,10 +2,10 @@
   <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
 </p>
 
-<h1 align="center">SuperLocalMemory V3.7.1</h1>
+<h1 align="center">SuperLocalMemory V3.7.2</h1>
 <p align="center"><strong>Cache. Compress. Remember. Three surfaces — proxy, MCP tools, or skill. Every setup covered.</strong><br/>
 <em>Local-first agent memory with explicit operating modes, auditable retrieval, and optional Optimize tools.</em></p>
-<p align="center"><code>v3.7.1</code> — <strong>Installer-parity hotfix; release witnesses required before outreach.</strong><br/>
+<p align="center"><code>v3.7.2</code> — <strong>Reliability release: durable local writes, cross-platform installation, and bounded enrichment recovery.</strong><br/>
 Proxy: <code>slm wrap claude</code> &nbsp;·&nbsp; MCP: add <code>slm_compress</code> to your config &nbsp;·&nbsp; Skill: zero-config</p>
 <p align="center"><strong>3 public research preprints</strong> (arXiv + Zenodo archives) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.7.1",
+  "version": "3.7.2",
   "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

@@ -16,5 +16,5 @@
   "mcpServers": "./.mcp.json",
   "name": "superlocalmemory",
   "repository": "https://github.com/qualixar/superlocalmemory",
-  "version": "3.7.1"
+  "version": "3.7.2"
 }

package/plugin/requirements.txt

@@ -1 +1 @@
-superlocalmemory==3.7.1
+superlocalmemory==3.7.2

package/plugin/scripts/slm-launch

@@ -4,12 +4,20 @@
 # Cross-platform counterpart: slm-launch.bat (Windows)
 # Referenced by plugin/.mcp.json as the MCP server command.
 #
-# Resolves the correct venv binary for POSIX:
-#   ${CLAUDE_PLUGIN_DATA}/venv/bin/slm mcp
+# Resolves the correct venv binary for POSIX and joins the namespace daemon
+# before opening the MCP stdio transport. This preserves one writer for all
+# parallel Claude sessions that share CLAUDE_PLUGIN_DATA.
 #
 # On Windows, Claude Code invokes slm-launch.bat instead (same-stem, .bat extension).
 #
 # Environment:
 #   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
 
-exec "${CLAUDE_PLUGIN_DATA}/venv/bin/slm" mcp
+SLM_BIN="${CLAUDE_PLUGIN_DATA}/venv/bin/slm"
+
+if ! "${SLM_BIN}" serve start >&2; then
+    echo "SLM plugin: unable to start the owned daemon; refusing a direct MCP writer." >&2
+    exit 1
+fi
+
+exec "${SLM_BIN}" mcp

package/plugin/scripts/slm-launch.bat

@@ -4,8 +4,8 @@
 :: Cross-platform counterpart: slm-launch (POSIX bash)
 :: Referenced by plugin/.mcp.json as the MCP server command (Windows picks .bat automatically).
 ::
-:: Resolves the correct venv binary for Windows:
-::   %CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe mcp
+:: Resolves the correct venv binary for Windows and joins the namespace daemon
+:: before opening MCP, preserving one writer for parallel Claude sessions.
 ::
 :: On Windows, Python venv places entry points in Scripts\ (not bin\ like POSIX).
 :: This launcher bridges the path difference so ONE .mcp.json command field works
@@ -14,4 +14,10 @@
 :: Environment:
 ::   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
 
+"%CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe" serve start 1>&2
+if errorlevel 1 (
+    echo SLM plugin: unable to start the owned daemon; refusing a direct MCP writer. 1>&2
+    exit /b 1
+)
+
 "%CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe" mcp

package/plugin-src/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.7.1",
+  "version": "3.7.2",
   "pluginName": "superlocalmemory",
   "displayName": "SuperLocalMemory",
   "repository": "https://github.com/qualixar/superlocalmemory",

package/plugin-src/requirements.txt

@@ -1 +1 @@
-superlocalmemory==3.7.1
+superlocalmemory==3.7.2

package/plugin-src/scripts/slm-launch

@@ -4,12 +4,20 @@
 # Cross-platform counterpart: slm-launch.bat (Windows)
 # Referenced by plugin/.mcp.json as the MCP server command.
 #
-# Resolves the correct venv binary for POSIX:
-#   ${CLAUDE_PLUGIN_DATA}/venv/bin/slm mcp
+# Resolves the correct venv binary for POSIX and joins the namespace daemon
+# before opening the MCP stdio transport. This preserves one writer for all
+# parallel Claude sessions that share CLAUDE_PLUGIN_DATA.
 #
 # On Windows, Claude Code invokes slm-launch.bat instead (same-stem, .bat extension).
 #
 # Environment:
 #   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
 
-exec "${CLAUDE_PLUGIN_DATA}/venv/bin/slm" mcp
+SLM_BIN="${CLAUDE_PLUGIN_DATA}/venv/bin/slm"
+
+if ! "${SLM_BIN}" serve start >&2; then
+    echo "SLM plugin: unable to start the owned daemon; refusing a direct MCP writer." >&2
+    exit 1
+fi
+
+exec "${SLM_BIN}" mcp

package/plugin-src/scripts/slm-launch.bat

@@ -4,8 +4,8 @@
 :: Cross-platform counterpart: slm-launch (POSIX bash)
 :: Referenced by plugin/.mcp.json as the MCP server command (Windows picks .bat automatically).
 ::
-:: Resolves the correct venv binary for Windows:
-::   %CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe mcp
+:: Resolves the correct venv binary for Windows and joins the namespace daemon
+:: before opening MCP, preserving one writer for parallel Claude sessions.
 ::
 :: On Windows, Python venv places entry points in Scripts\ (not bin\ like POSIX).
 :: This launcher bridges the path difference so ONE .mcp.json command field works
@@ -14,4 +14,10 @@
 :: Environment:
 ::   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
 
+"%CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe" serve start 1>&2
+if errorlevel 1 (
+    echo SLM plugin: unable to start the owned daemon; refusing a direct MCP writer. 1>&2
+    exit /b 1
+)
+
 "%CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe" mcp

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.7.1"
+version = "3.7.2"
 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.7.1"
+__version__ = "3.7.2"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/core/embedding_worker.py

@@ -70,7 +70,13 @@ def _load_embedding_model(name: str) -> tuple:
 
     Returns (model, backend_name) or (None, "").
     """
-    from sentence_transformers import SentenceTransformer
+    try:
+        from sentence_transformers import SentenceTransformer
+    except Exception:
+        # Dependency/version errors must stay inside the JSON-lines protocol.
+        # Letting this import escape kills the worker before it can explain the
+        # failure, which the parent previously mislabeled as a long timeout.
+        return None, ""
 
     for backend in _embedding_backend_order():
         try:

package/src/superlocalmemory/core/embeddings.py

@@ -295,6 +295,8 @@ class EmbeddingService:
         never hangs indefinitely on cold model loads or network issues.
         """
         with self._lock:
+            if not self._available:
+                return None
             # Worker recycling: restart after N requests to prevent
             # C++ allocator fragmentation over long-running sessions.
             if self._request_count >= _WORKER_RECYCLE_AFTER and self._worker_proc is not None:
@@ -339,6 +341,12 @@ class EmbeddingService:
                 resp = json.loads(resp_line)
                 if not resp.get("ok"):
                     logger.warning("Worker error: %s", resp.get("error"))
+                    # A well-formed worker error is a terminal local
+                    # dependency/model failure, not a transient pipe race.
+                    # Disable this service and terminate the child so every
+                    # recall does not respawn a heavyweight failing process.
+                    self._available = False
+                    self._kill_worker()
                     return None
                 self._reset_idle_timer()
                 self._request_count += 1

package/src/superlocalmemory/core/engine.py

@@ -24,6 +24,7 @@ from typing import Any
 from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT, SLMConfig
 from superlocalmemory.core.engine_capabilities import Capabilities, CapabilityError
 from superlocalmemory.core.modes import get_capabilities
+from superlocalmemory.learning.outcome_queue import RecallEvent, enqueue_recall
 from superlocalmemory.storage.models import (
     AtomicFact, MemoryRecord, Mode, RecallResponse,
 )
@@ -664,9 +665,6 @@ class MemoryEngine:
         # recall correctness (LLD-02 §4.9, LLD-08 §4.1).
         if session_id:
             try:
-                from superlocalmemory.learning.outcome_queue import (
-                    RecallEvent, enqueue_recall,
-                )
                 fact_ids = tuple(
                     getattr(r.fact, "fact_id", "") or ""
                     for r in getattr(response, "results", [])

package/src/superlocalmemory/core/engine_wiring.py

@@ -388,11 +388,6 @@ def _init_spreading_activation(
     vector_store: Any,
 ) -> Any | None:
     """Create SpreadingActivation for Phase 3 5th retrieval channel."""
-    # V3.3.21: Guard against None vector_store. Without embeddings, SA's
-    # search() crashes with "'NoneType' has no attribute 'search'".
-    if vector_store is None:
-        logger.debug("SpreadingActivation skipped: no vector_store")
-        return None
     try:
         from superlocalmemory.retrieval.spreading_activation import (
             SpreadingActivation,

package/src/superlocalmemory/core/ram_lock.py

@@ -15,12 +15,13 @@ Design notes:
   available before we even try — better to defer than thrash.
 - Lock file lives at ``~/.superlocalmemory/ram_lock.sem`` by default,
   tests may monkeypatch ``RAM_LOCK_PATH``.
-- POSIX only; Windows build is deferred per LLD-00 §7 and MASTER-PLAN H-01.
+- Uses a standard-library advisory lock on POSIX and Windows.  The lock is
+  deliberately file-backed so independent daemon, CLI, and worker processes
+  share the same RAM reservation.
 """
 
 from __future__ import annotations
 
-import fcntl
 import os
 import time
 from contextlib import contextmanager
@@ -29,6 +30,11 @@ from typing import Iterator
 
 import psutil
 
+try:  # POSIX advisory locks (macOS/Linux)
+    import fcntl as _fcntl
+except ImportError:  # Windows uses the stdlib byte-range equivalent below.
+    _fcntl = None
+
 # Public override retained for tests and embedders. ``None`` means resolve the
 # lock dynamically so a long-lived process can switch canonical namespaces
 # without retaining the first root it observed.
@@ -44,6 +50,38 @@ def _ram_lock_path() -> Path:
     return state_path("ram_lock.sem")
 
 
+def _acquire_lock(fd: int) -> None:
+    """Acquire one non-blocking cross-process lock for the semaphore."""
+    if _fcntl is not None:
+        _fcntl.flock(fd, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
+        return
+
+    import msvcrt
+
+    # ``msvcrt.locking`` cannot reserve an empty file.  The marker byte is
+    # purely structural; the human-readable audit marker is written after the
+    # reservation is acquired.
+    if os.fstat(fd).st_size == 0:
+        os.write(fd, b"\0")
+    os.lseek(fd, 0, os.SEEK_SET)
+    try:
+        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+    except OSError as exc:
+        raise BlockingIOError("RAM reservation is already held") from exc
+
+
+def _release_lock(fd: int) -> None:
+    """Release a reservation acquired by :func:`_acquire_lock`."""
+    if _fcntl is not None:
+        _fcntl.flock(fd, _fcntl.LOCK_UN)
+        return
+
+    import msvcrt
+
+    os.lseek(fd, 0, os.SEEK_SET)
+    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+
+
 @contextmanager
 def ram_reservation(
     name: str,
@@ -96,7 +134,7 @@ def ram_reservation(
         deadline = time.time() + timeout_s
         while True:
             try:
-                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                _acquire_lock(fd)
                 break
             except BlockingIOError:
                 if time.time() >= deadline:
@@ -114,7 +152,7 @@ def ram_reservation(
         yield
     finally:
         try:
-            fcntl.flock(fd, fcntl.LOCK_UN)
+            _release_lock(fd)
         finally:
             os.close(fd)
 

package/src/superlocalmemory/evolution/budget.py

@@ -20,7 +20,6 @@ Author: Varun Pratap Bhardwaj / Qualixar
 
 from __future__ import annotations
 
-import fcntl
 import logging
 import os
 import sqlite3
@@ -35,8 +34,44 @@ from superlocalmemory.core.security_primitives import safe_resolve_identifier
 
 logger = logging.getLogger(__name__)
 
+try:  # POSIX advisory locks (macOS/Linux)
+    import fcntl as _fcntl
+except ImportError:  # Windows has no fcntl; use its stdlib byte-range lock.
+    _fcntl = None
 
-# M-P-07: path-component hints for filesystems where ``fcntl.flock`` is
+
+def _acquire_profile_lock(fd: int) -> None:
+    """Acquire a non-blocking cross-process lock on every supported OS."""
+    if _fcntl is not None:
+        _fcntl.flock(fd, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
+        return
+
+    import msvcrt
+
+    # ``msvcrt.locking`` cannot lock an empty file. Reserve one marker byte;
+    # the file content is diagnostic only and never a correctness signal.
+    if os.fstat(fd).st_size == 0:
+        os.write(fd, b"\0")
+    os.lseek(fd, 0, os.SEEK_SET)
+    try:
+        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+    except OSError as exc:
+        raise BlockingIOError("evolution profile lock is held") from exc
+
+
+def _release_profile_lock(fd: int) -> None:
+    """Release the lock acquired by :func:`_acquire_profile_lock`."""
+    if _fcntl is not None:
+        _fcntl.flock(fd, _fcntl.LOCK_UN)
+        return
+
+    import msvcrt
+
+    os.lseek(fd, 0, os.SEEK_SET)
+    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+
+
+# M-P-07: path-component hints for filesystems where advisory locking is
 # known to degrade to a no-op. We do NOT abort — some users accept the
 # risk — but we emit a one-shot warning so a double-cycle is at least
 # attributable to a known root cause. If/when we ship a threading-only
@@ -127,7 +162,7 @@ class EvolutionBudget:
         )
         self._lock_path = safe_stem.with_suffix(".lock")
         # M-P-07: warn once per lock-path when we detect the lock sits on
-        # a known sync-backed filesystem. ``fcntl.flock`` silently
+        # a known sync-backed filesystem. Advisory locking silently
         # degrades on iCloud/OneDrive/Dropbox — two concurrent cycles
         # would each acquire and burn LLM budget. Documentation-only for
         # now; a future release may refuse to run until the lock_dir is
@@ -141,7 +176,7 @@ class EvolutionBudget:
             if key not in _WARNED_SYNC_PATHS:
                 _WARNED_SYNC_PATHS.add(key)
                 logger.warning(
-                    "evolution lock at %s lives under %r — fcntl.flock "
+                    "evolution lock at %s lives under %r — advisory locking "
                     "may silently no-op on sync-backed filesystems. "
                     "Concurrent cycles could double-bill LLM cost. Move "
                     "the lock_dir off the sync root to make single-flight "
@@ -258,12 +293,12 @@ class EvolutionBudget:
                 f"cap={MAX_CYCLES_PER_DAY}",
             )
 
-        # Single-flight lock (non-blocking flock). A second concurrent
+        # Single-flight lock (non-blocking advisory lock). A second concurrent
         # acquire raises BlockingIOError — surface as BudgetExhausted.
         fd = os.open(str(self._lock_path), os.O_CREAT | os.O_RDWR, 0o600)
         try:
             try:
-                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                _acquire_profile_lock(fd)
             except BlockingIOError as e:
                 os.close(fd)
                 raise BudgetExhausted(
@@ -296,7 +331,7 @@ class EvolutionBudget:
             # Release lock before propagating — a failed cycle-record should
             # not leave the lock dangling.
             try:
-                fcntl.flock(fd, fcntl.LOCK_UN)
+                _release_profile_lock(fd)
             finally:
                 os.close(fd)
                 self._lock_fd = None
@@ -312,7 +347,7 @@ class EvolutionBudget:
         finally:
             self._cycle_start_mono = None
             try:
-                fcntl.flock(fd, fcntl.LOCK_UN)
+                _release_profile_lock(fd)
             finally:
                 try:
                     os.close(fd)

package/src/superlocalmemory/mcp/tools_core.py

@@ -149,35 +149,52 @@ def register_core_tools(server, get_engine: Callable) -> None:
             # is_daemon_running() and daemon_request() both use blocking urllib
             # against the same uvicorn server — run in threads so the MCP
             # event loop stays unblocked (#34 class bug).
-            if await _asyncio.to_thread(is_daemon_running):
-                resp = await _asyncio.to_thread(daemon_request, "POST", "/remember", {
-                    "content": content, "tags": tags, "metadata": meta,
-                    "scope": scope, "shared_with": _shared_list,
-                    "session_id": session_id,
-                    "idempotency_key": effective_idempotency_key or None,
-                })
-                if resp and (resp.get("fact_ids") is not None or resp.get("ok")):
-                    fids = resp.get("fact_ids") or []
-                    materialization_state = resp.get("materialization_state")
-                    if materialization_state is None:
-                        materialization_state = (
-                            "complete" if resp.get("status") == "stored" else "queryable"
-                        )
-                    pending = materialization_state != "complete"
-                    return {
-                        "success": True,
-                        "fact_ids": fids,
-                        "count": int(resp.get("count", len(fids))),
-                        "pending": pending,
-                        "pending_id": resp.get("pending_id") if pending else None,
-                        "operation_id": resp.get("operation_id"),
-                        "materialization_state": materialization_state,
-                        "message": (
-                            "Stored through canonical daemon ingestion."
-                            if not pending
-                            else "Queryable now; canonical enrichment is still running."
-                        ),
-                    }
+            daemon_owned = await _asyncio.to_thread(is_daemon_running)
+            if daemon_owned:
+                # A positively identified daemon owns this database. Never
+                # spawn a WorkerPool writer after a transient daemon failure:
+                # that creates the competing writers which SQLite WAL cannot
+                # support. Retry the canonical path, then return an explicit
+                # retryable result to the MCP client.
+                for attempt in range(3):
+                    resp = await _asyncio.to_thread(daemon_request, "POST", "/remember", {
+                        "content": content, "tags": tags, "metadata": meta,
+                        "scope": scope, "shared_with": _shared_list,
+                        "session_id": session_id,
+                        "idempotency_key": effective_idempotency_key or None,
+                    })
+                    if resp and (resp.get("fact_ids") is not None or resp.get("ok")):
+                        fids = resp.get("fact_ids") or []
+                        materialization_state = resp.get("materialization_state")
+                        if materialization_state is None:
+                            materialization_state = (
+                                "complete" if resp.get("status") == "stored" else "queryable"
+                            )
+                        pending = materialization_state != "complete"
+                        return {
+                            "success": True,
+                            "fact_ids": fids,
+                            "count": int(resp.get("count", len(fids))),
+                            "pending": pending,
+                            "pending_id": resp.get("pending_id") if pending else None,
+                            "operation_id": resp.get("operation_id"),
+                            "materialization_state": materialization_state,
+                            "message": (
+                                "Stored through canonical daemon ingestion."
+                                if not pending
+                                else "Queryable now; canonical enrichment is still running."
+                            ),
+                        }
+                    if attempt < 2:
+                        await _asyncio.sleep(0.05 * (attempt + 1))
+                return {
+                    "success": False,
+                    "retryable": True,
+                    "error": (
+                        "Canonical daemon is temporarily unavailable; retry the "
+                        "same remember operation without starting a second writer."
+                    ),
+                }
         except Exception as dexc:
             logger.debug("MCP remember via daemon failed, pending fallback: %s", dexc)
 

package/src/superlocalmemory/mesh/broker.py

@@ -19,7 +19,7 @@ import time
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable, TypeVar
 
 logger = logging.getLogger("superlocalmemory.mesh")
 import os as _os
@@ -38,6 +38,11 @@ MAX_MESSAGE_SIZE = 4096  # 4KB cap — mesh messages are notifications, not data
 MESSAGE_TTL_HOURS = 48   # Offline messages expire after 48h
 MAX_QUEUED_PER_TARGET = 50  # Max unread messages per broadcast/project target
 
+_T = TypeVar("_T")
+_WRITE_RETRY_ATTEMPTS = 6
+_WRITE_RETRY_BASE_SECONDS = 0.025
+_WRITE_BUSY_TIMEOUT_MS = 250
+
 
 class MeshBroker:
     """Lightweight mesh broker for SLM's unified daemon.
@@ -109,22 +114,64 @@ class MeshBroker:
     # -- Connection helper --
 
     def _conn(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(self._db_path)
-        conn.execute("PRAGMA journal_mode=WAL")
-        conn.execute("PRAGMA busy_timeout=5000")
+        # WAL is configured during database initialization and persists with the
+        # database. Reissuing journal_mode=WAL for every short-lived mesh
+        # connection is itself a schema-level write that can contend with the
+        # daemon. Mesh writes below use bounded whole-transaction retries.
+        conn = sqlite3.connect(
+            self._db_path,
+            timeout=_WRITE_BUSY_TIMEOUT_MS / 1000,
+        )
+        conn.execute(f"PRAGMA busy_timeout={_WRITE_BUSY_TIMEOUT_MS}")
         conn.row_factory = sqlite3.Row
         return conn
 
+    @staticmethod
+    def _is_transient_lock(exc: sqlite3.OperationalError) -> bool:
+        message = str(exc).lower()
+        return "database is locked" in message or "database is busy" in message
+
+    def _write_with_retry(
+        self,
+        operation: Callable[[sqlite3.Connection], _T],
+    ) -> _T:
+        """Run one idempotent mesh mutation with a bounded SQLite retry budget.
+
+        SQLite WAL lets reads continue while a write is in progress, but it
+        still permits a single writer. Retrying the entire short transaction on
+        a fresh connection avoids leaking a transient writer collision to an
+        agent heartbeat or mesh command.
+        """
+        last_error: sqlite3.OperationalError | None = None
+        for attempt in range(_WRITE_RETRY_ATTEMPTS):
+            conn = self._conn()
+            try:
+                return operation(conn)
+            except sqlite3.OperationalError as exc:
+                if not self._is_transient_lock(exc):
+                    raise
+                last_error = exc
+                try:
+                    conn.rollback()
+                except sqlite3.Error:
+                    pass
+            finally:
+                conn.close()
+
+            if attempt < _WRITE_RETRY_ATTEMPTS - 1:
+                time.sleep(_WRITE_RETRY_BASE_SECONDS * (2 ** attempt))
+
+        assert last_error is not None
+        raise last_error
+
     # -- Peers --
 
     def register_peer(self, session_id: str, summary: str = "",
                       host: str = "", port: int = 0,
                       project_path: str = "", agent_type: str = "unknown") -> dict:
-        conn = self._conn()
-        try:
+        def _register(conn: sqlite3.Connection) -> dict:
             now = datetime.now(timezone.utc).isoformat()
-            if not host:
-                host = self._host
+            effective_host = host or self._host
             # Idempotent: update if same session_id exists
             existing = conn.execute(
                 "SELECT peer_id FROM mesh_peers WHERE session_id = ?",
@@ -135,7 +182,7 @@ class MeshBroker:
                 conn.execute(
                     "UPDATE mesh_peers SET summary=?, host=?, port=?, last_heartbeat=?, "
                     "status='active', project_path=?, agent_type=? WHERE peer_id=?",
-                    (summary, host, port, now, project_path, agent_type, peer_id),
+                    (summary, effective_host, port, now, project_path, agent_type, peer_id),
                 )
             else:
                 peer_id = str(uuid.uuid4())[:12]
@@ -143,7 +190,7 @@ class MeshBroker:
                     "INSERT INTO mesh_peers (peer_id, session_id, summary, status, host, port, "
                     "registered_at, last_heartbeat, project_path, agent_type) "
                     "VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)",
-                    (peer_id, session_id, summary, host, port, now, now, project_path, agent_type),
+                    (peer_id, session_id, summary, effective_host, port, now, now, project_path, agent_type),
                 )
             self._log_event(conn, "peer_registered", peer_id, {
                 "session_id": session_id, "project_path": project_path,
@@ -153,12 +200,11 @@ class MeshBroker:
             # v3.4.6: Deliver pending broadcast/project messages on registration
             pending = self._get_pending_for_peer(conn, peer_id, project_path)
             return {"peer_id": peer_id, "ok": True, "pending_messages": len(pending)}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_register)
 
     def deregister_peer(self, peer_id: str) -> dict:
-        conn = self._conn()
-        try:
+        def _deregister(conn: sqlite3.Connection) -> dict:
             row = conn.execute("SELECT 1 FROM mesh_peers WHERE peer_id=?", (peer_id,)).fetchone()
             if not row:
                 return {"ok": False, "error": "peer not found"}
@@ -166,12 +212,11 @@ class MeshBroker:
             self._log_event(conn, "peer_deregistered", peer_id)
             conn.commit()
             return {"ok": True}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_deregister)
 
     def heartbeat(self, peer_id: str) -> dict:
-        conn = self._conn()
-        try:
+        def _heartbeat(conn: sqlite3.Connection) -> dict:
             now = datetime.now(timezone.utc).isoformat()
             cursor = conn.execute(
                 "UPDATE mesh_peers SET last_heartbeat=?, status='active' WHERE peer_id=?",
@@ -181,12 +226,11 @@ class MeshBroker:
                 return {"ok": False, "error": "peer not found"}
             conn.commit()
             return {"ok": True}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_heartbeat)
 
     def update_summary(self, peer_id: str, summary: str) -> dict:
-        conn = self._conn()
-        try:
+        def _update_summary(conn: sqlite3.Connection) -> dict:
             cursor = conn.execute(
                 "UPDATE mesh_peers SET summary=? WHERE peer_id=?",
                 (summary, peer_id),
@@ -195,8 +239,8 @@ class MeshBroker:
                 return {"ok": False, "error": "peer not found"}
             conn.commit()
             return {"ok": True}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_update_summary)
 
     def list_peers(self) -> list[dict]:
         conn = self._conn()
@@ -219,8 +263,19 @@ class MeshBroker:
             return {"ok": False, "error": f"message too large ({len(content)} bytes, max {MAX_MESSAGE_SIZE}). "
                     "Mesh messages are notifications — reference a file path instead."}
 
-        conn = self._conn()
-        try:
+        # Remote delivery is an external side effect, so do it outside the
+        # retry envelope. Local writes below are retried as a whole short
+        # transaction when another daemon-owned operation has SQLite's writer.
+        if to_peer in self._remote_peers and self._sync_client:
+            return self._sync_client.send_to_remote(to_peer, {
+                "from_peer": from_peer,
+                "to": to_peer,
+                "content": content,
+                "type": msg_type,
+            })
+
+        def _send(conn: sqlite3.Connection) -> dict:
+            nonlocal to_peer, project_path
             now = datetime.now(timezone.utc).isoformat()
             expires_at = self._compute_expires(now)
 
@@ -233,14 +288,6 @@ class MeshBroker:
                 to_peer = "project"
             else:
                 target_type = "peer"
-                # Check if this is a remote peer — proxy to remote SLM
-                if to_peer in self._remote_peers and self._sync_client:
-                    return self._sync_client.send_to_remote(to_peer, {
-                        "from_peer": from_peer,
-                        "to": to_peer,
-                        "content": content,
-                        "type": msg_type,
-                    })
                 # Verify recipient exists for direct messages
                 if not conn.execute("SELECT 1 FROM mesh_peers WHERE peer_id=?", (to_peer,)).fetchone():
                     return {"ok": False, "error": "recipient peer not found"}
@@ -272,8 +319,8 @@ class MeshBroker:
             conn.commit()
             return {"ok": True, "id": cursor.lastrowid, "target_type": target_type,
                     "expires_at": expires_at}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_send)
 
     def get_inbox(self, peer_id: str, project_path: str = "") -> list[dict]:
         """Get all messages for this peer: direct + broadcast + project."""
@@ -331,8 +378,7 @@ class MeshBroker:
             conn.close()
 
     def mark_read(self, peer_id: str, message_ids: list[int]) -> dict:
-        conn = self._conn()
-        try:
+        def _mark_read(conn: sqlite3.Connection) -> dict:
             now = datetime.now(timezone.utc).isoformat()
             for msg_id in message_ids:
                 # Check if this is a direct message or broadcast/project
@@ -356,8 +402,8 @@ class MeshBroker:
                     )
             conn.commit()
             return {"ok": True, "marked": len(message_ids)}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_mark_read)
 
     # -- State --
 
@@ -370,8 +416,7 @@ class MeshBroker:
             conn.close()
 
     def set_state(self, key: str, value: str, set_by: str) -> dict:
-        conn = self._conn()
-        try:
+        def _set_state(conn: sqlite3.Connection) -> dict:
             now = datetime.now(timezone.utc).isoformat()
             conn.execute(
                 "INSERT INTO mesh_state (key, value, set_by, updated_at) VALUES (?, ?, ?, ?) "
@@ -380,8 +425,8 @@ class MeshBroker:
             )
             conn.commit()
             return {"ok": True}
-        finally:
-            conn.close()
+
+        return self._write_with_retry(_set_state)
 
     def get_state_key(self, key: str) -> dict | None:
         conn = self._conn()
@@ -396,8 +441,23 @@ class MeshBroker:
     # -- Locks --
 
     def lock_action(self, file_path: str, locked_by: str, action: str) -> dict:
-        conn = self._conn()
-        try:
+        if action == "query":
+            conn = self._conn()
+            try:
+                row = conn.execute(
+                    "SELECT locked_by, locked_at FROM mesh_locks WHERE file_path=?",
+                    (file_path,),
+                ).fetchone()
+                if row:
+                    return {"locked": True, "by": row["locked_by"], "since": row["locked_at"]}
+                return {"locked": False}
+            finally:
+                conn.close()
+
+        if action not in {"acquire", "release"}:
+            return {"ok": False, "error": f"unknown action: {action}"}
+
+        def _lock_action(conn: sqlite3.Connection) -> dict:
             now = datetime.now(timezone.utc).isoformat()
 
             if action == "acquire":
@@ -429,18 +489,9 @@ class MeshBroker:
                 return {"ok": False, "action": "not_released",
                         "error": "no lock held by this peer for that file"}
 
-            elif action == "query":
-                row = conn.execute(
-                    "SELECT locked_by, locked_at FROM mesh_locks WHERE file_path=?",
-                    (file_path,),
-                ).fetchone()
-                if row:
-                    return {"locked": True, "by": row["locked_by"], "since": row["locked_at"]}
-                return {"locked": False}
+            raise AssertionError("validated action was not handled")
 
-            return {"ok": False, "error": f"unknown action: {action}"}
-        finally:
-            conn.close()
+        return self._write_with_retry(_lock_action)
 
     # -- Helpers (v3.4.6) --
 
@@ -527,8 +578,7 @@ class MeshBroker:
                 logger.debug("Mesh cleanup error: %s", exc)
 
     def _run_cleanup(self) -> None:
-        conn = self._conn()
-        try:
+        def _cleanup(conn: sqlite3.Connection) -> None:
             now = datetime.now(timezone.utc)
             now_iso = now.isoformat()
             # Mark stale peers (no heartbeat for 5 min)
@@ -572,5 +622,5 @@ class MeshBroker:
                 (now_iso,),
             )
             conn.commit()
-        finally:
-            conn.close()
+
+        self._write_with_retry(_cleanup)

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -93,7 +93,7 @@ class SpreadingActivation:
     def __init__(
         self,
         db: Any,
-        vector_store: Any,
+        vector_store: Any | None,
         config: SpreadingActivationConfig | None = None,
     ) -> None:
         self._db = db
@@ -122,8 +122,11 @@ class SpreadingActivation:
         include_shared = bool(getattr(self, "include_shared", False))
         try:
             # Step 0: Get seed nodes from VectorStore KNN
-            seed_results = self._vector_store.search(
-                query, top_k=self._config.top_m, profile_id=profile_id,
+            seed_results = self._seed_search(
+                query,
+                profile_id,
+                include_global=include_global,
+                include_shared=include_shared,
             )
             # Owner-partitioned vector indexes cannot discover opted-in peers.
             # Add visible external embeddings with the same cosine seed signal.
@@ -216,6 +219,53 @@ class SpreadingActivation:
             )
             return []
 
+    def _seed_search(
+        self,
+        query: Any,
+        profile_id: str,
+        *,
+        include_global: bool,
+        include_shared: bool,
+    ) -> list[tuple[str, float]]:
+        """Return bounded semantic graph seeds from vec0 or canonical SQLite.
+
+        sqlite-vec is an acceleration projection, not a prerequisite for the
+        graph retrieval layer.  When it is unavailable on a platform, use the
+        canonical stored embeddings and the same cosine signal as the
+        cross-profile supplement below.  This keeps spreading activation
+        present and truthful rather than silently removing a retrieval layer.
+        """
+        if self._vector_store is not None and getattr(
+            self._vector_store, "available", False,
+        ):
+            return self._vector_store.search(
+                query, top_k=self._config.top_m, profile_id=profile_id,
+            )
+
+        q_vec = np.array(query, dtype=np.float32)
+        q_norm = float(np.linalg.norm(q_vec))
+        if q_norm <= 1e-8:
+            return []
+        facts = self._db.get_all_facts(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+        )
+        scored: list[tuple[str, float]] = []
+        for fact in facts:
+            embedding = getattr(fact, "embedding", None)
+            if embedding is None:
+                continue
+            fact_vec = np.array(embedding, dtype=np.float32)
+            if fact_vec.shape != q_vec.shape:
+                continue
+            denominator = q_norm * float(np.linalg.norm(fact_vec))
+            if denominator <= 1e-8:
+                continue
+            score = (float(np.dot(q_vec, fact_vec) / denominator) + 1.0) / 2.0
+            scored.append((fact.fact_id, score))
+        return sorted(scored, key=lambda item: item[1], reverse=True)[:self._config.top_m]
+
     def _propagate(
         self,
         seeds: list[tuple[str, float]],

package/src/superlocalmemory/server/unified_daemon.py

@@ -2138,18 +2138,33 @@ def _register_daemon_routes(application: FastAPI) -> None:
             ))
 
             result = command.materialize(receipt.operation_id) if wait else receipt
-            if result.state is IngestionState.FAILED:
-                raise RuntimeError(result.last_error or "materialization failed")
-
             fact_ids = list(result.fact_ids)
+            # The queryable write is a separate durable transaction.  A cold
+            # optional enrichment dependency (most often the local embedding
+            # worker) may need its bounded retry window, but must not turn an
+            # already-admitted fact into an HTTP 500.  Keep the operation's
+            # failed state truthful so the daemon materializer retries it; the
+            # response communicates that the fact is queryable, not complete.
+            enrichment_deferred = (
+                result.state is IngestionState.FAILED and bool(fact_ids)
+            )
+            if result.state is IngestionState.FAILED and not enrichment_deferred:
+                raise RuntimeError(result.last_error or "materialization failed")
+            completed = result.state is IngestionState.COMPLETE
             _emit_event(
-                "memory.stored" if wait else "memory.queued",
+                "memory.stored" if completed else "memory.queued",
                 payload={
                     "operation_id": result.operation_id,
                     "fact_ids": fact_ids,
                     "tags": req.tags or "",
                     "content_preview": req.content[:120],
-                    "path": "remember_sync" if wait else "remember_queryable",
+                    "path": (
+                        "remember_sync"
+                        if completed
+                        else "remember_sync_deferred"
+                        if enrichment_deferred
+                        else "remember_queryable"
+                    ),
                 },
             )
             return {
@@ -2160,11 +2175,13 @@ def _register_daemon_routes(application: FastAPI) -> None:
                 # One-release compatibility alias. The durable operation ID is
                 # opaque and replaces the integer pending.db row identifier.
                 "pending_id": result.operation_id,
-                "status": "stored" if wait else "queryable",
+                "status": "stored" if completed else "queryable",
                 "materialization_state": result.state.value,
                 "note": (
                     "canonical ingestion complete"
-                    if wait
+                    if completed
+                    else "queryable now; canonical enrichment will retry"
+                    if enrichment_deferred
                     else "queryable now; canonical enrichment pending"
                 ),
             }