superlocalmemory 4.1.0 → 4.1.3

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

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

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

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -323,4 +323,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -270,4 +270,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · 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 v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -253,4 +253,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · 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 v4.1.0 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later

package/plugin-src/rules/AGENTS.md

@@ -137,4 +137,4 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 - **slm-optimize-advisor** — context compression and KV cache
 - **slm-governance-advisor** — scope/role compliance, retention policies, GDPR
 
-SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later

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

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

package/plugin-src/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 v4.1.0 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later

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

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

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

@@ -312,4 +312,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later

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

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

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

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -323,4 +323,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

@@ -270,4 +270,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

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

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

@@ -253,4 +253,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v4.1.0 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.3 · Qualixar · AGPL-3.0-or-later*

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

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

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "4.1.0"
+version = "4.1.3"
 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__ = "4.1.0"
+__version__ = "4.1.3"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/cli/commands.py

@@ -2577,6 +2577,56 @@ def _migration_error_logs() -> list:
         return []
 
 
+def _slm_version() -> str:
+    """The installed package version, or "unknown"."""
+    try:
+        from importlib.metadata import version
+        return version("superlocalmemory")
+    except Exception:  # noqa: BLE001
+        return "unknown"
+
+
+def _installed_plugin_versions() -> dict:
+    """Version of each editor plugin found on this machine, by install name.
+
+    The skills, agents and commands live in the editor's plugin channel rather
+    than in the Python package, so upgrading with pip leaves them exactly where
+    they were. This looks for them where each editor puts them, and returns an
+    empty mapping when none is installed -- which is itself the answer worth
+    reporting, because it means pip is the only thing being upgraded.
+
+    Best effort by design: an editor this does not know about should produce
+    "not detected", never an error.
+    """
+    import json
+    from pathlib import Path
+
+    found: dict[str, str] = {}
+    roots = (
+        # Claude Code: marketplace installs and directly-added plugins.
+        Path.home() / ".claude" / "plugins",
+        # Codex and VS Code copies, when placed by hand.
+        Path.home() / ".codex" / "plugins",
+        Path.home() / ".vscode" / "extensions",
+    )
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for manifest in list(root.glob("*/.claude-plugin/plugin.json")) + \
+                list(root.glob("*/plugin.json")) + \
+                list(root.glob("*/*/.claude-plugin/plugin.json")):
+            try:
+                data = json.loads(manifest.read_text(encoding="utf-8"))
+            except Exception:  # noqa: BLE001 — a sibling plugin's bad json is not ours
+                continue
+            if str(data.get("name", "")) != "superlocalmemory":
+                continue
+            found[str(manifest.parent.parent.name)] = str(
+                data.get("version", "unknown")
+            )
+    return found
+
+
 def _detect_all_installs() -> list:
     """Thin shim so cmd_doctor can be tested without importing install_detector."""
     try:
@@ -3093,6 +3143,50 @@ def cmd_doctor(args: Namespace) -> None:
     except Exception as _inst_exc:  # noqa: BLE001 — never break doctor
         _check("install_versions", "WARN", f"could not probe installs: {_inst_exc}")
 
+    # 14. The skills, agents and commands are NOT in the Python package.
+    #     They ship through the editor's own plugin channel -- `plugin/` in the
+    #     repository -- so `pip install --upgrade` cannot move them, and until now
+    #     nothing said so. 4.1 changed 76 files across those trees; a user who
+    #     upgraded the package and read a clean `slm doctor` had every reason to
+    #     believe they had all of it, and no way to find out otherwise.
+    try:
+        _pkg_version = _slm_version()
+        _pl = _installed_plugin_versions()
+        if not _pl:
+            _check(
+                "plugin_skills",
+                "WARN",
+                f"package is {_pkg_version}; no editor plugin detected, so the "
+                f"skills, agents and commands are not installed or updated by "
+                f"pip",
+                fix="Claude Code:  claude plugin marketplace add "
+                    "qualixar/superlocalmemory  &&  claude plugin install "
+                    "superlocalmemory@qualixar     "
+                    "Codex / VS Code: copy codex-plugin/ or copilot-plugin/ "
+                    "from the tag you are on",
+            )
+        else:
+            _stale = {n: v for n, v in _pl.items() if v != _pkg_version}
+            if _stale:
+                _check(
+                    "plugin_skills",
+                    "WARN",
+                    "package is %s; plugin content still at %s" % (
+                        _pkg_version,
+                        ", ".join(f"{n}={v}" for n, v in sorted(_stale.items())),
+                    ),
+                    fix="claude plugin marketplace update qualixar && "
+                        "claude plugin update superlocalmemory@qualixar",
+                )
+            else:
+                _check(
+                    "plugin_skills",
+                    "PASS",
+                    f"plugin content matches the package ({_pkg_version})",
+                )
+    except Exception as _pl_exc:  # noqa: BLE001 — never break doctor
+        _check("plugin_skills", "WARN", f"could not probe plugins: {_pl_exc}")
+
     # 14. Migration error logs — surface any unresolved failure from a previous
     #     upgrade attempt. The daemon writes these and they persist until the
     #     user takes action; doctor is the right place to surface them.

package/src/superlocalmemory/server/recall_health.py

@@ -39,6 +39,7 @@ from __future__ import annotations
 
 import logging
 import threading
+import time
 from contextlib import nullcontext
 from dataclasses import dataclass
 
@@ -67,6 +68,17 @@ class RecallHealth:
     checks: int = 0
     last_semantic_score: float = 0.0
     last_error: str = ""
+    #: When the last tick finished, as a unix timestamp. A tick that finds
+    #: nothing wrong logs nothing, which is correct -- a monitor that narrates
+    #: every success is a monitor whose real warnings get skimmed past. But it
+    #: left no way to tell a monitor that is ticking quietly from a thread that
+    #: died or never started, and that ambiguity cost someone an hour of looking
+    #: for log lines that were never going to appear. So the fact of the tick is
+    #: recorded here and surfaced on /health, where it can be checked instead of
+    #: inferred.
+    last_tick_at: float = 0.0
+    #: Whether the embedder could produce a vector at the last tick.
+    embedder_alive: bool = True
 
 
 def _max_semantic(results) -> float:
@@ -91,6 +103,38 @@ def _get_embedder(engine):
     return emb
 
 
+def _embedder_is_dead(engine) -> bool:
+    """Can the embedder produce a vector right now?
+
+    Asked directly, because it cannot be inferred from a recall. The monitor
+    used to decide the embedder was fine whenever the probe recall came back
+    with no results at all -- and a dead embedder is one of the reasons a recall
+    comes back with no results, so the one symptom that should have triggered a
+    heal was read as proof that none was needed.
+
+    That is not hypothetical. An idle-timeout kill leaves no worker; the next
+    probe finds nothing by meaning, finds nothing by keyword either because the
+    probe phrase appears in nobody's memories, and returns zero results. The
+    monitor then recorded "healthy", logged nothing, and never respawned the
+    worker -- so ``readiness.embedding`` stayed false and the daemon sat in
+    ``warming`` until someone restarted it by hand, with not one line in the log
+    to say why.
+
+    Fails safe in the opposite direction from before: an embedder this cannot
+    reach is reported dead, so the worst case is one unnecessary re-warm rather
+    than a silent outage.
+    """
+    emb = _get_embedder(engine)
+    if emb is None:
+        return False  # BM25-only by configuration; nothing to heal.
+    warm = getattr(emb, "is_warm", None)
+    if warm is not None and not warm:
+        return True
+    if getattr(emb, "_available", True) is False:
+        return True
+    return False
+
+
 def _heal_embedder(engine, *, log) -> bool:
     """Tier 3: reset the cached availability flag and re-exercise the embedder.
 
@@ -169,10 +213,27 @@ def run_health_tick(engine, state: RecallHealth, *, probe: str = DEFAULT_PROBE,
     results = list(getattr(resp, "results", []) or [])
     sem = _max_semantic(results)
     state.last_semantic_score = sem
-
-    # Tier 2: readiness. Rows present but semantic never fired == warm-but-broken.
-    # Zero results is NOT this signature (could be an empty/filtered corpus).
-    broken = bool(results) and sem <= 0.0
+    state.last_tick_at = time.time()
+
+    # Tier 2: readiness. Two independent signatures, and the second one is why
+    # this monitor exists.
+    #
+    #   * rows present but semantic never fired  -> warm-but-broken
+    #   * the embedder cannot produce a vector   -> dead, whatever the recall said
+    #
+    # The second used to be missing, and its absence was load-bearing: zero
+    # results was treated as "not this signature", so the case where the embedder
+    # is dead AND the probe matches nothing by keyword -- which is the normal
+    # shape of an idle-timeout kill -- came out as healthy, silently.
+    dead = _embedder_is_dead(engine)
+    state.embedder_alive = not dead
+    broken = dead or (bool(results) and sem <= 0.0)
+    if dead:
+        log.critical(
+            "recall-health: embedder cannot produce a vector (%d probe results) "
+            "— attempting self-heal",
+            len(results),
+        )
     if not broken:
         if not state.healthy:
             log.warning(
@@ -184,12 +245,16 @@ def run_health_tick(engine, state: RecallHealth, *, probe: str = DEFAULT_PROBE,
         state.last_error = ""
         return state
 
-    # Tier 3: self-heal.
-    log.critical(
-        "recall-health: semantic channel DEAD (%d results, max semantic=0.0) "
-        "— embedder returning None; attempting self-heal",
-        len(results),
-    )
+    # Tier 3: self-heal. The dead-embedder case already said so above; saying
+    # "semantic channel DEAD (max semantic=0.0)" as well would be a second,
+    # differently-worded CRITICAL about the same tick, and one of the two would
+    # be describing a symptom the reader does not have.
+    if not dead:
+        log.critical(
+            "recall-health: semantic channel DEAD (%d results, max semantic=0.0) "
+            "— embedder returning None; attempting self-heal",
+            len(results),
+        )
     if _heal_embedder(engine, log=log):
         state.total_heals += 1
         state.healthy = True
@@ -256,6 +321,7 @@ def start_recall_health_monitor(engine, *, interval_s: int = DEFAULT_INTERVAL_S,
 def get_recall_health() -> dict:
     """Snapshot for /health surfacing (visibility — never silent degradation)."""
     s = _GLOBAL_STATE
+    now = time.time()
     return {
         "recall_healthy": s.healthy,
         "consecutive_failures": s.consecutive_failures,
@@ -263,4 +329,15 @@ def get_recall_health() -> dict:
         "checks": s.checks,
         "last_semantic_score": round(s.last_semantic_score, 4),
         "last_error": s.last_error,
+        # Proof of life. A tick that finds nothing wrong logs nothing, so there
+        # was no way to tell this monitor apart from a thread that never started
+        # -- someone spent an hour reading logs for lines that were never going
+        # to be written. These two answer that without needing the log at all:
+        # if seconds_since_last_tick keeps climbing past the interval, the thread
+        # is gone.
+        "last_tick_at": round(s.last_tick_at, 3) if s.last_tick_at else None,
+        "seconds_since_last_tick": (
+            round(now - s.last_tick_at, 1) if s.last_tick_at else None
+        ),
+        "embedder_alive": s.embedder_alive,
     }

package/src/superlocalmemory/server/unified_daemon.py

@@ -511,6 +511,49 @@ _MIGRATION_EXEMPT_PATH_PREFIXES: tuple[str, ...] = (
 )
 
 
+def _serving_blocked_by(migration_result: dict) -> list[str]:
+    """Failed migrations that should stop this daemon serving. Fail-closed.
+
+    A failed migration used to 503 every route without asking what had failed.
+    For a missing table that is right. For a data invariant that ordinary use can
+    re-violate it is not: one drifted row made the whole store unreachable until
+    somebody restarted it by hand, and the restart fixed nothing that a
+    background repair would not have fixed on its own.
+
+    A migration may answer for itself by exposing ``blocks_serving(conn)``.
+    Anything that does not is treated as blocking, so this cannot quietly open a
+    door for a migration nobody has thought about.
+    """
+    failed = list(migration_result.get("failed") or [])
+    if not failed:
+        return []
+    try:
+        import sqlite3
+
+        from superlocalmemory.infra.data_root import state_path
+        from superlocalmemory.storage._migration_internals import _MODULES
+    except Exception:  # noqa: BLE001 — never let this decide by crashing
+        return failed
+
+    blocking: list[str] = []
+    for name in failed:
+        decide = getattr(_MODULES.get(name), "blocks_serving", None)
+        if not callable(decide):
+            blocking.append(name)
+            continue
+        try:
+            db = state_path("memory.db")
+            conn = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+            try:
+                if decide(conn):
+                    blocking.append(name)
+            finally:
+                conn.close()
+        except Exception:  # noqa: BLE001 — unknown means blocking
+            blocking.append(name)
+    return blocking
+
+
 def _is_migration_exempt_path(path: str) -> bool:
     """Return True for health, status, and repair paths that must stay reachable
     even when the daemon reports a schema migration failure.
@@ -4009,7 +4052,7 @@ def _register_dashboard_routes(application: FastAPI) -> None:
     @application.middleware("http")
     async def _migration_readiness_gate(request, call_next):
         migration_result = getattr(application.state, "migration_result", None)
-        if migration_result and migration_result.get("failed"):
+        if migration_result and _serving_blocked_by(migration_result):
             if not _is_migration_exempt_path(request.url.path):
                 from fastapi.responses import JSONResponse
                 return JSONResponse(
@@ -4278,7 +4321,14 @@ def _register_daemon_routes(application: FastAPI) -> None:
             (migration_result or {}).get("failed", []) or []
         )
         migration_details = (migration_result or {}).get("details", {}) or {}
-        migrations_ready = bool(migration_result) and not migration_failures
+        # Ready means "can serve", so it keys off the failures that actually
+        # stop this daemon serving -- not off every failure. A data invariant
+        # that ordinary use re-violated leaves every route working; reporting
+        # not-ready for it told operators to restart, which fixed nothing a
+        # background repair would not have fixed. Everything still shows up in
+        # migration_failures and migration_failure_reasons below, named.
+        migration_blocking = _serving_blocked_by(migration_result or {})
+        migrations_ready = bool(migration_result) and not migration_blocking
         if migration_details.get("_crash"):
             migrations_ready = False
         writer_runtime = getattr(
@@ -4296,6 +4346,9 @@ def _register_daemon_routes(application: FastAPI) -> None:
             "embedding": embedding_ready,
             "recall_health": recall_health.get("recall_healthy") is True,
             "migration_failures": migration_failures,
+            # Which of those are the reason this daemon will not serve, as
+            # opposed to the ones it is reporting while serving normally.
+            "migration_blocking": migration_blocking,
             # WHY each one failed, not just which. The runner already produces
             # a precise sentence per migration -- "safe repair did not restore
             # M043_...", "schema verification failed ... : <sqlite error>" --

package/src/superlocalmemory/storage/_migration_internals.py

@@ -332,6 +332,22 @@ def _delete_log(conn: sqlite3.Connection, name: str) -> None:
     conn.execute("DELETE FROM migration_log WHERE name = ?", (name,))
 
 
+def _why_unmet(mod, conn) -> str:
+    """The migration's own account of which check does not hold.
+
+    A migration may expose ``unmet(conn)`` returning a sentence. Most do not,
+    and for those the caller keeps its generic wording. Never raises: this runs
+    while reporting a failure and must not become a second one.
+    """
+    fn = getattr(mod, "unmet", None)
+    if not callable(fn):
+        return ""
+    try:
+        return str(fn(conn) or "")
+    except Exception:  # noqa: BLE001 - a detail string is not worth a crash
+        return ""
+
+
 def _apply_single(
     conn: sqlite3.Connection,
     migration: Migration,
@@ -414,9 +430,12 @@ def _apply_single(
                         try:
                             repair_fn(conn)
                             if not bool(verify_fn(conn)):
+                                _why = _why_unmet(mod, conn)
                                 return (
                                     "failed",
-                                    f"safe repair did not restore {migration.name}",
+                                    f"safe repair did not restore "
+                                    f"{migration.name}"
+                                    + (f": {_why}" if _why else ""),
                                 )
                             _upsert_log(conn, migration.name, ddl_hash, "complete")
                             return (
@@ -482,9 +501,11 @@ def _apply_single(
                 )
             try:
                 if not bool(verify_fn(conn)):
+                    _why = _why_unmet(mod, conn)
                     return (
                         "failed",
-                        f"safe repair did not restore {migration.name}",
+                        f"safe repair did not restore {migration.name}"
+                        + (f": {_why}" if _why else ""),
                     )
             except sqlite3.Error as exc:
                 return (