superlocalmemory 3.7.1 → 3.7.3

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/hooks/claude_code_hooks.py

@@ -28,6 +28,7 @@ import sys
 import tempfile
 from pathlib import Path
 
+from superlocalmemory import __version__
 from superlocalmemory.infra.data_root import canonical_data_root
 from superlocalmemory.infra.data_root import state_path as runtime_state_path
 
@@ -40,7 +41,7 @@ _DEFAULT_DISABLED_FILE = _DEFAULT_VERSION_DIR / ".hooks-disabled"
 VERSION_DIR = _DEFAULT_VERSION_DIR
 VERSION_FILE = _DEFAULT_VERSION_FILE
 DISABLED_FILE = _DEFAULT_DISABLED_FILE
-HOOKS_VERSION = "3.7.1"
+HOOKS_VERSION = __version__
 
 # Cross-platform temp dir and backwards-compatible marker overrides. Runtime
 # defaults are root-namespaced and resolved when hook definitions are built.

package/src/superlocalmemory/hooks/context_payload.py

@@ -19,10 +19,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Callable, Iterable
 
+from superlocalmemory import __version__
 from superlocalmemory.core.security_primitives import redact_secrets
 
 
-VERSION = "3.7.1"
+VERSION = __version__
 DEFAULT_TOP_K = 10
 DEFAULT_DECISIONS_K = 5
 DEFAULT_MEMORIES_K = 10

package/src/superlocalmemory/mcp/http_transport.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 from mcp.server.fastmcp import FastMCP
 from sse_starlette.sse import EventSourceResponse
 from starlette.types import Receive, Scope, Send
+from superlocalmemory import __version__
 
 
 class ClosingEventSourceResponse(EventSourceResponse):
@@ -40,7 +41,7 @@ def install_streamable_http_resource_guard() -> None:
 class SLMFastMCP(FastMCP):
     """FastMCP with SLM release identity and deterministic SSE cleanup."""
 
-    def __init__(self, *args, product_version: str = "3.7.1", **kwargs) -> None:
+    def __init__(self, *args, product_version: str = __version__, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         # FastMCP delegates the initialize response to the low-level MCP
         # server. Without an explicit value it reports the installed ``mcp``

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/optimize/proxy/server.py

@@ -12,12 +12,13 @@ from fastapi import APIRouter
 from fastapi.requests import Request
 from fastapi.responses import Response
 
+from superlocalmemory import __version__
 from superlocalmemory.optimize.config.schema import OptimizeConfig
 from superlocalmemory.optimize.proxy.lifecycle import HookChain
 
 logger = logging.getLogger("slm.optimize.proxy")
 
-_PROXY_VERSION = "3.7.1"
+_PROXY_VERSION = __version__
 _REQUEST_TIMEOUT_S = 300.0
 _CONNECT_TIMEOUT_S = 10.0
 _MAX_CONNECTIONS = 100

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/routes/brain.py

@@ -43,6 +43,7 @@ from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request
+from superlocalmemory import __version__
 
 from superlocalmemory.core.security_primitives import (
     redact_secrets,
@@ -64,7 +65,7 @@ router = APIRouter(prefix="/api/v3", tags=["brain"])
 # LLD-03 v2 stratum space = 4 query types × 3 entity bins × 4 time buckets.
 _STRATA_TOTAL: int = 48
 
-_VERSION: str = "3.7.1"
+_VERSION: str = __version__
 
 # Banned metric names (LLD-04 U4). Kept as a tuple for grep visibility;
 # the source-level test asserts we don't accidentally reintroduce them.