superlocalmemory 4.0.8 → 4.0.9

package/src/superlocalmemory/cli/commands.py

@@ -1147,7 +1147,7 @@ def _cmd_context_dispatch(args: Namespace) -> None:
 
 
 def _agents_md_source_factory():
-    """Return a callable that reads the WP-05 AGENTS.md content, or None on failure.
+    """Return a callable that reads the bundled AGENTS.md content, or None on failure.
 
     Source: plugin-src/rules/AGENTS.md (relative to package root).
     Gracefully skips if absent — never fails the MCP write.
@@ -1168,7 +1168,7 @@ def _agents_md_source_factory():
             if candidate.exists():
                 return candidate.read_text(encoding="utf-8")
         logger.warning(
-            "WP-05 AGENTS.md is not bundled — skipping AGENTS.md write"
+            "AGENTS.md is not bundled in this distribution — skipping AGENTS.md write"
         )
         return None
 
@@ -1178,15 +1178,15 @@ def _agents_md_source_factory():
 def cmd_connect(args: Namespace) -> None:
     """Configure IDE integrations.
 
-    Dispatch priority (WP-08):
+    Dispatch priority:
     1. ``slm connect <ide>`` where ide ∈ IDE_MATRIX → portable_kit.connect_ide
-       (MCP-wiring + AGENTS.md; includes claude-code short-circuit to WP-06).
+       (MCP-wiring + AGENTS.md; claude-code short-circuits to the plugin pointer).
     2. ``--cross-platform`` / ``--disable`` → LLD-05 CrossPlatformConnector.
     3. Bare ``slm connect`` / ``--list`` → legacy IDEConnector (markdown-rules).
     """
     ide_arg = getattr(args, "ide", None)
 
-    # WP-08: intercept known IDE_MATRIX ids before legacy branches (CRIT-1)
+    # Intercept known IDE_MATRIX ids before legacy branches (critical: must run first)
     if ide_arg is not None:
         from superlocalmemory.hooks.portable_kit import (
             IDE_MATRIX,
@@ -1922,7 +1922,7 @@ def cmd_status(args: Namespace) -> None:
             ])
             return
 
-        # WP-02 D8: canonical key set — db_size_mb always present (0.0 if absent).
+        # canonical key set — db_size_mb always present (0.0 if absent).
         db_size_mb = 0.0
         if config.db_path.exists():
             db_size_mb = round(config.db_path.stat().st_size / 1024 / 1024, 2)
@@ -2376,6 +2376,52 @@ def cmd_help(args: Namespace) -> None:
     print("Docs:                https://superlocalmemory.com")
 
 
+def _migration_error_logs() -> list:
+    """Return a sorted list of migration-error log files in the SLM home dir.
+
+    Returns an empty list when none exist or when the directory is not readable.
+    """
+    try:
+        from superlocalmemory.core.config import SLMConfig
+        from superlocalmemory.infra.data_root import canonical_data_root
+        from superlocalmemory.storage.models import Mode
+
+        # The daemon writes this log beside the memory database it was actually
+        # configured with, which is not necessarily the canonical data root —
+        # any of SLM_DATA_DIR / SL_MEMORY_PATH / SLM_HOME can move it. Globbing
+        # only the canonical root reported "clean" while the log sat unread in
+        # the real directory. Search both, de-duplicated.
+        roots = {canonical_data_root()}
+        try:
+            cfg = SLMConfig.for_mode(Mode.A)
+            db = getattr(cfg, "memory_db_path", None) or getattr(cfg, "db_path", None)
+            if db:
+                roots.add(pathlib.Path(db).parent)
+        except Exception:
+            pass
+
+        found: list = []
+        for root in roots:
+            try:
+                found.extend(root.glob("migration-error-*.log"))
+            except OSError:
+                continue
+        return sorted(set(found))
+    except Exception:
+        return []
+
+
+def _detect_all_installs() -> list:
+    """Thin shim so cmd_doctor can be tested without importing install_detector."""
+    try:
+        from superlocalmemory.core.install_detector import (
+            _detect_all_installs as _real,
+        )
+        return _real()
+    except Exception:
+        return []
+
+
 def cmd_doctor(args: Namespace) -> None:
     """Comprehensive pre-flight check — verify everything works.
 
@@ -2728,7 +2774,7 @@ def cmd_doctor(args: Namespace) -> None:
     else:
         _check("Database", "PASS", "not yet created (will initialize on first use)")
 
-    # 11. PEP 668 advisory — WP-07: detect EXTERNALLY-MANAGED marker and
+    # 11. PEP 668 advisory: detect EXTERNALLY-MANAGED marker and
     #     recommend pipx when the system Python is managed by the OS package
     #     manager (e.g. Homebrew, Debian/Ubuntu, Fedora 38+).
     try:
@@ -2782,6 +2828,70 @@ def cmd_doctor(args: Namespace) -> None:
     except Exception as _cr_exc:
         _check("Component registry", "WARN", f"probe failed: {_cr_exc}")
 
+    # 13. Install version convergence — detect all copies of SLM on this machine
+    #     and warn when they are at different versions. Silent divergence is the
+    #     most common source of unexpected behaviour after an upgrade.
+    try:
+        _installs = _detect_all_installs()  # shim defined above cmd_doctor
+        _versions = {i["version"] for i in _installs}
+        if not _installs:
+            _check(
+                "install_versions",
+                "PASS",
+                "No additional SLM installs detected on this machine",
+            )
+        elif len(_versions) > 1:
+            _detail = "Version divergence: " + ", ".join(
+                f"{i['type']}={i['version']}" for i in _installs
+            )
+            _check(
+                "install_versions",
+                "WARN",
+                _detail,
+                fix="Upgrade all installs: "
+                    "pipx upgrade superlocalmemory  |  "
+                    "pip install -U superlocalmemory (in ~/.slm-venv)  |  "
+                    "npm install -g superlocalmemory@latest",
+            )
+        else:
+            _unified = next(iter(_versions))
+            _types = ", ".join(i["type"] for i in _installs)
+            _check(
+                "install_versions",
+                "PASS",
+                f"All installs at {_unified} ({_types})",
+            )
+    except Exception as _inst_exc:  # noqa: BLE001 — never break doctor
+        _check("install_versions", "WARN", f"could not probe installs: {_inst_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.
+    try:
+        _err_logs = _migration_error_logs()
+        if _err_logs:
+            _latest = _err_logs[-1]
+            _check(
+                "migration_errors",
+                "FAIL",
+                f"Unresolved migration failure: {_latest.name}",
+                # `--fix` heals models, sqlite-vec and stale locks. It does NOT
+                # re-run a migration or restore a snapshot, so pointing here at
+                # `--fix` sent the user round a loop that could never clear this
+                # check. The log itself carries the restore command.
+                fix=(
+                    f"Read {_latest} — it names what failed and, if a snapshot "
+                    f"was taken, the exact command to restore it. Restart the "
+                    f"daemon to retry the upgrade. Delete the log once resolved."
+                ),
+            )
+        else:
+            # Reporting nothing when clean made "no failures" and "the check
+            # never ran" look identical in the output.
+            _check("migration_errors", "PASS", "no unresolved migration failures")
+    except Exception as _mel_exc:  # noqa: BLE001 — never break doctor
+        _check("migration_errors", "WARN", f"could not check error logs: {_mel_exc}")
+
     # 12. Optimize (Surface B) — reads daemon-persisted metrics (≤60s stale).
     info = _gather_optimize_surface_b()
     _enabled = info["enabled"]
@@ -3332,7 +3442,7 @@ def _cmd_init_auto(
     config_exists: bool,
     force: bool,
 ) -> None:
-    """WP-07: non-interactive --auto branch for slm init.
+    """Non-interactive --auto branch for slm init.
 
     Best-effort at every step; only exits non-zero when config save fails.
     No TTY required.  Does NOT run IDE connect (AC6).
@@ -3394,7 +3504,7 @@ def cmd_init(args: Namespace) -> None:
     slm_data_dir = slm_home()
     config_exists = (slm_data_dir / "config.json").exists()
 
-    # WP-07: --auto branch — fully non-interactive, no TTY required (AC6).
+    # --auto branch — fully non-interactive, no TTY required.
     if auto:
         os.environ["SLM_NON_INTERACTIVE"] = "1"
         _cmd_init_auto(args, slm_data_dir, config_exists, force)

package/src/superlocalmemory/cli/db_migrate.py

@@ -4,8 +4,6 @@
 
 """CLI handler for ``slm db migrate``.
 
-LLD reference: ``.backup/active-brain/lld/LLD-06-windows-binary-and-legacy-migration.md``
-Section 7.2 (slm db migrate CLI).
 
 Thin wrapper over the canonical runner in
 ``superlocalmemory.storage.migration_runner``. This module owns only

package/src/superlocalmemory/cli/gdpr_io.py

@@ -73,7 +73,7 @@ def _audit_chain_path() -> Path:
 # ─────────────────────────────────────────────────────────────────────────────
 
 # Known gaps in this release — reported honestly so a DPO can plan remediation.
-# Gaps C1 and C2 are tracked as open items in the Wave 3 backlog.
+# Gaps C1 and C2 (cross-device erase verification and audit-log replay) remain open.
 KNOWN_GAPS = [
     {
         "ref": "C1",

package/src/superlocalmemory/cli/main.py

@@ -134,7 +134,7 @@ def main() -> None:
         and "--apply" not in sys.argv[2:]
     )
 
-    # WP-07: lazy first-run init — runs after hook/mcp fast-paths so stdout
+    # lazy first-run init — runs after hook/mcp fast-paths so stdout
     # is never polluted on those paths (CRIT-3, MCP JSON-RPC purity).
     # Guarded: any failure must not crash the CLI (AC4).
     _is_mcp_cmd = len(sys.argv) >= 2 and sys.argv[1] == "mcp"
@@ -169,7 +169,7 @@ def main() -> None:
                 from superlocalmemory.migrations.v3_4_25_to_v3_4_26 import (
                     migrate_if_safe as _migrate_if_safe,
                 )
-                # WP-07: route through slm_home() so all 3 env aliases are honoured.
+                # route through slm_home() so all 3 env aliases are honoured.
                 from superlocalmemory.cli._lazy_init import slm_home as _slm_home
                 _data = _slm_home()
                 _res = _migrate_if_safe(_data)
@@ -209,7 +209,7 @@ def main() -> None:
         "--gate", action="store_true",
         help="Enable PreToolUse gate (experimental — blocks tools until session_init)",
     )
-    # WP-07: non-interactive auto setup (pip post-install, CI, scripts).
+    # non-interactive auto setup (pip post-install, CI, scripts).
     init_p.add_argument(
         "--auto", action="store_true",
         help="Non-interactive setup: mode A + hooks (no TTY required, for CI/scripts)",
@@ -243,7 +243,7 @@ def main() -> None:
         "--list", action="store_true", help="List all supported IDEs",
     )
     connect_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
-    # WP-08 CRIT-1: declare missing flags so cmd_connect can read them without getattr fallback
+    # declare missing flags so cmd_connect can read them without getattr fallback
     connect_p.add_argument(
         "--here", action="store_true", default=False,
         help="Write config relative to current working directory (project scope)",
@@ -258,7 +258,7 @@ def main() -> None:
     )
     connect_p.add_argument(
         "--profile", metavar="PROFILE", default=None,
-        help="Inject SLM_MCP_PROFILE env var into the MCP server block (WP-01)",
+        help="Inject SLM_MCP_PROFILE env var into the MCP server block (named profile selection)",
     )
     connect_p.add_argument(
         "--dry-run", action="store_true", dest="dry_run", default=False,

package/src/superlocalmemory/cli/service_installer.py

@@ -19,7 +19,6 @@ from __future__ import annotations
 
 import logging
 import os
-import plistlib
 import subprocess
 import sys
 from pathlib import Path
@@ -56,6 +55,8 @@ def _macos_plist_path() -> Path:
 
 
 def _macos_plist_content() -> str:
+    import plistlib  # macOS-only stdlib module; deferred so non-macOS platforms can import this module safely
+
     python = get_python_path()
     log = get_log_path()
     err_log = get_error_log_path()

package/src/superlocalmemory/cli/setup_wizard.py

@@ -29,7 +29,7 @@ from typing import Any
 # Constants
 # ---------------------------------------------------------------------------
 
-# WP-07: resolve via slm_home() so all 3 env aliases are honoured.
+# resolve via slm_home() so all 3 env aliases are honoured.
 # Fallback keeps stdlib-only path if the import fails during early bootstrap.
 def _resolve_slm_home() -> Path:
     from superlocalmemory.infra.data_root import canonical_data_root

package/src/superlocalmemory/core/config.py

@@ -23,7 +23,7 @@ logger = logging.getLogger(__name__)
 
 
 # ---------------------------------------------------------------------------
-# Canonical limits (WP-02 — single source of truth across all surfaces)
+# Canonical limits — single source of truth across all surfaces
 # ---------------------------------------------------------------------------
 
 #: Default number of results returned by recall across MCP, CLI, daemon, and
@@ -387,6 +387,21 @@ class RetrievalConfig:
     # fail-open — never a per-query LLM call. Kill-switch for tuning.
     enable_community_context: bool = True
 
+    # Recency query strategy.
+    # When False, queries matching present-activity phrases fall through to
+    # factual routing — one-line rollback without touching strategy.py.
+    enable_recency_strategy: bool = True
+    # Strength of the recency prior applied during final-score fusion.
+    # 0.0 = no recency bias (restores previous ranking exactly).
+    # Consumed by a separate ranking stage; this field makes the knob
+    # configurable without further edits to this class.
+    recency_prior_strength: float = 0.5
+    # A fact written moments ago has no embedding yet, so it scores zero on the
+    # semantic channel — the same score a genuinely unrelated fact gets. Inside
+    # this window that zero is read as "not computed yet", not as "unrelated".
+    write_recency_floor_enabled: bool = True
+    write_recency_floor_minutes: float = 60.0
+
 
 # ---------------------------------------------------------------------------
 # Math Config
@@ -564,7 +579,26 @@ class HopfieldConfig:
     max_iterations: int = 1
     convergence_epsilon: float = 1e-6
     prefilter_threshold: int = 10_000
-    prefilter_candidates: int = 1000
+    # How many candidates the index hands to this stage. This stage decides final
+    # membership, so a fact ranked past this number by the index never reaches it
+    # and can never be returned — the size of this pool is a direct limit on which
+    # memories are reachable at all.
+    #
+    #
+    # Chosen by measurement against the 2 s recall ceiling, on a 517 MB store:
+    #   150 -> p95   998 ms, 0 channel timeouts
+    #   300 -> p95 1054 ms, 0
+    #   500 -> p95 1140 ms, 0      <- here: 3.3x the reachability of 150 for +142 ms
+    #   750 -> p95 1278 ms, 0
+    #  1000 -> p95 1947-2737 ms, 2-25 timeouts
+    #
+    # 1000 is excluded twice over: it breaches the ceiling, and a channel that
+    # misses its deadline contributes nothing to fusion — so whether it lands
+    # varies with machine load and the same question stops returning the same
+    # answer. 500 keeps ~860 ms of headroom, which is several times the observed
+    # run-to-run variance, and stays clear of the region where the cost curve
+    # turned non-linear for reasons that were never explained.
+    prefilter_candidates: int = 500
     skip_threshold: int = 100_000
     cache_ttl_seconds: float = 60.0
 
@@ -1727,7 +1761,7 @@ class SLMConfig:
         embedding_dimension: int = 0,
     ) -> SLMConfig:
         """Create config with mode-appropriate defaults."""
-        # WP-07: resolve base dir via slm_home() at call time when not explicit.
+        # resolve base dir via slm_home() at call time when base_dir is not explicit.
         if base_dir is None:
             try:
                 from superlocalmemory.cli._lazy_init import slm_home as _slm_home
@@ -1895,7 +1929,7 @@ class SLMConfig:
 
         Returns ``\"b\"`` (the default) if the file doesn't exist.
         """
-        # WP-07: resolve via slm_home() at call time when base_dir not explicit.
+        # resolve via slm_home() at call time when base_dir is not explicit.
         if base_dir is None:
             try:
                 from superlocalmemory.cli._lazy_init import slm_home as _slm_home
@@ -1913,7 +1947,7 @@ class SLMConfig:
     @staticmethod
     def write_current_mode(mode: str, base_dir: Path | None = None) -> None:
         """Write the current mode letter to ``current_mode``."""
-        # WP-07: resolve via slm_home() at call time when base_dir not explicit.
+        # resolve via slm_home() at call time when base_dir is not explicit.
         if base_dir is None:
             try:
                 from superlocalmemory.cli._lazy_init import slm_home as _slm_home
@@ -1956,7 +1990,7 @@ class SLMConfig:
         import dataclasses
 
         from superlocalmemory.storage.models import Mode as _M
-        # WP-07: resolve via slm_home() at call time when base_dir not explicit.
+        # resolve via slm_home() at call time when base_dir is not explicit.
         if base_dir is None:
             try:
                 from superlocalmemory.cli._lazy_init import slm_home as _slm_home
@@ -2031,7 +2065,7 @@ class SLMConfig:
         Called on daemon boot. Idempotent — if ``current_mode`` already
         exists, this is a no-op. Returns True if migration was performed.
         """
-        # WP-07: resolve via slm_home() at call time when base_dir not explicit.
+        # resolve via slm_home() at call time when base_dir is not explicit.
         if base_dir is None:
             try:
                 from superlocalmemory.cli._lazy_init import slm_home as _slm_home

package/src/superlocalmemory/core/context_cache.py

@@ -4,8 +4,6 @@
 
 """Context cache — separate SQLite WAL DB, read-path <10 ms.
 
-LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
-Section 4.1.
 
 Two concerns in one module:
   - Writer (``ContextCache``) — used by the daemon only. Owns pragmas,