superlocalmemory 3.7.0 → 3.7.1

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

@@ -0,0 +1,149 @@
+---
+name: slm-status
+description: Health and optimization stats for SuperLocalMemory — call slm_optimize_stats() for live compression and cache counters (compress_runs, tokens_saved_compress, cache_proxy_hits, cache_proxy_misses, cache_kv_hits, cache_kv_misses); run slm status [--json] for system state (mode, profile, DB size, fact/entity/edge counts) and slm doctor [--json] for preflight including the "Optimize (Surface B)" health line; use together to confirm optimization is actually saving tokens.
+when_to_use: "check slm status, health check, is slm working, optimize stats, tokens saved, cache hits, compress runs, slm doctor, preflight, db size, slm info, diagnose slm"
+allowed-tools: slm_optimize_stats, Bash
+---
+
+# slm-status — Health and Optimize Stats
+
+## Purpose
+
+Use this skill to answer: "Is SLM healthy?", "Is compression/caching actually saving tokens?", and "What does the system look like right now?" It covers three surfaces: the MCP stats tool, the `slm status` CLI, and the `slm doctor` preflight.
+
+## Primary MCP Tool: slm_optimize_stats
+
+```
+slm_optimize_stats() -> dict
+```
+
+No arguments. Returns counters from the current daemon and MCP process session.
+
+### Return dict (all keys always present)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` on success; `False` on internal error |
+| `compress_runs` | int | Total compress calls recorded by the daemon (persisted across restarts) |
+| `tokens_saved_compress` | int | Cumulative tokens saved by compression (daemon-persisted) |
+| `cache_proxy_hits` | int | Proxy-layer cache hits (daemon-persisted) |
+| `cache_proxy_misses` | int | Proxy-layer cache misses (daemon-persisted) |
+| `cache_kv_hits` | int | MCP KV cache hits — **this MCP process session only**, resets on restart |
+| `cache_kv_misses` | int | MCP KV cache misses — **this MCP process session only**, resets on restart |
+| `ccr_note` | str \| None | Note about CCR entry count (not tracked per-session; see daemon `/api/v1/metrics`) |
+| `note` | str \| None | Scope clarification or error detail |
+
+### Important scope distinction
+
+`compress_runs`, `tokens_saved_compress`, `cache_proxy_hits`, and `cache_proxy_misses` are **daemon-persisted** — they survive MCP restarts and accumulate over the full install lifetime.
+
+`cache_kv_hits` and `cache_kv_misses` are **in-process counters** — they reset to 0 each time the MCP server starts. Use them to gauge cache effectiveness within the current session only.
+
+### Reading whether optimization is saving tokens
+
+```python
+stats = await slm_optimize_stats()
+if stats["ok"]:
+    savings = stats["tokens_saved_compress"]
+    kv_hit_rate = (
+        stats["cache_kv_hits"] / max(stats["cache_kv_hits"] + stats["cache_kv_misses"], 1)
+    )
+    # savings > 0 and kv_hit_rate > 0.5 means Surface B is actively reducing costs
+```
+
+If `compress_runs` is 0 after several sessions, compression is not being triggered — check daemon config and whether `slm_compress` is being called.
+
+If `cache_kv_hits` is 0 after repeated work, verify key naming consistency (the same key string must be used for set and get).
+
+## Secondary CLI: slm status
+
+```bash
+slm status [--json] [--verbose]
+```
+
+Reports system-level state — not optimization counters. Canonical fields (WP-02):
+
+- **mode** — active operation mode (e.g. `local`)
+- **profile** — current memory profile name
+- **DB size** — database file size on disk
+- **fact count** — number of stored memory facts
+- **entity count** — entity graph node count
+- **edge count** — entity graph edge count
+
+`--verbose` / `-v` adds: migration log, daemon port, disabled marker, last version.
+
+`--json` outputs a machine-readable dict with the same fields — preferred for agent consumption.
+
+Example agent-native invocation:
+
+```bash
+slm status --json
+```
+
+Typical JSON shape (exact field names depend on runtime; use `--json` and read what arrives):
+
+```json
+{
+  "mode": "local",
+  "profile": "code",
+  "db_size_mb": 12.4,
+  "facts": 384,
+  "entities": 201,
+  "edges": 519
+}
+```
+
+Do not rely on the human-readable format for parsing — always use `--json` when the output feeds another tool.
+
+## Secondary CLI: slm doctor
+
+```bash
+slm doctor [--json] [--quick]
+```
+
+Preflight check covering dependencies, embedding worker, daemon connectivity, and Surface B health. The **"Optimize (Surface B)"** line (WP-03) confirms whether the compression and cache subsystem initialised correctly.
+
+`--quick` skips the daemon and embedding probes — runs only dependency and config checks; faster but incomplete.
+
+`--json` outputs structured results per check — use this in automated health pipelines.
+
+A passing doctor output confirms:
+- Python deps present
+- Embedding worker reachable
+- Daemon responding
+- Surface B (Optimize) initialised
+
+A failing "Optimize (Surface B)" line means `slm_compress`, `slm_cache_set`, and `slm_cache_get` may not function correctly — investigate daemon config before relying on those tools.
+
+## Secondary CLI: slm optimize status
+
+```bash
+slm optimize status [--json]
+```
+
+Shows whether the Optimize module (cache + compress) is currently enabled or disabled at the daemon level. Available subcommands also include `optimize on`, `optimize off`, and `optimize savings`.
+
+The `optimize savings` subcommand accepts:
+
+```bash
+slm optimize savings [--since <days>] [--provider anthropic|openai|gemini] [--json]
+```
+
+`--since` defaults to 7 days. `--provider` filters by the target AI provider.
+
+Note: the `slm optimize` subcommands have known pre-existing parse-test failures — if a subcommand errors, use `slm_optimize_stats()` via MCP as the authoritative source.
+
+## Recommended Health Workflow
+
+1. Run `slm doctor --json` at session start to confirm all subsystems are up.
+2. Call `slm_optimize_stats()` after a batch of work to check token savings.
+3. Run `slm status --json` when you need DB size or memory counts.
+4. If `ok: false` on any MCP tool — check `note` field, then run `slm doctor` to isolate the failure.
+
+## Fail-Open
+
+`slm_optimize_stats()` never raises. On internal error it returns `ok: false` with all counters at 0. Continue the session — stats unavailability does not affect compression or caching operations.
+
+---
+
+SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later

package/pyproject.toml

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

package/src/superlocalmemory/cli/_lazy_init.py

@@ -4,7 +4,7 @@
 
 """WP-07 — Lazy first-run initialisation (pip cross-install).
 
-stdlib-only — zero heavy imports, STDOUT-SILENT.
+Lightweight import only — zero heavy imports, STDOUT-SILENT.
 
 Public API
 ----------
@@ -25,6 +25,8 @@ import json
 import os
 from pathlib import Path
 
+from superlocalmemory import __version__ as _RUNTIME_VERSION
+
 
 # ---------------------------------------------------------------------------
 # Public: home resolution
@@ -55,7 +57,7 @@ def slm_home() -> Path:
 # Only mode + base_dir; everything else uses SLMConfig defaults.
 _MINIMAL_CONFIG: dict = {
     "mode": "a",
-    "version": "3.6.14",
+    "version": _RUNTIME_VERSION,
 }
 
 

package/src/superlocalmemory/core/engine_wiring.py

@@ -22,6 +22,30 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _log_reranker_warmup_status(reranker: Any) -> None:
+    """Record non-blocking reranker warmup state without alarming first-run users."""
+    ready = reranker.warmup_sync(timeout=180)
+    if ready:
+        logger.info("Cross-encoder reranker warm and ready")
+        return
+    try:
+        from superlocalmemory.retrieval.reranker import _is_reranker_worker_alive
+
+        if _is_reranker_worker_alive():
+            logger.info(
+                "Cross-encoder reranker worker held by another process "
+                "(machine-wide singleton — usually the unified daemon); "
+                "this process will route reranking through that worker"
+            )
+            return
+    except Exception:
+        pass
+    logger.info(
+        "Cross-encoder reranker did not become ready during background warmup; "
+        "recalls use fallback scoring. Run 'slm doctor' for diagnostics."
+    )
+
+
 # ---------------------------------------------------------------------------
 # init_embedder  (was MemoryEngine._init_embedder + helpers)
 # ---------------------------------------------------------------------------
@@ -552,29 +576,12 @@ def init_retrieval(
     # trust in slm health / slm doctor output.
     if reranker is not None:
         import threading
-        def _log_warmup_status() -> None:
-            ready = reranker.warmup_sync(timeout=180)
-            if ready:
-                logger.info("Cross-encoder reranker warm and ready")
-                return
-            # warmup_sync returned False. Could be (a) singleton held by
-            # another process (benign), or (b) actual model load failure.
-            # Disambiguate by probing the singleton PID file.
-            try:
-                from superlocalmemory.retrieval.reranker import _is_reranker_worker_alive
-                if _is_reranker_worker_alive():
-                    logger.info(
-                        "Cross-encoder reranker worker held by another process "
-                        "(machine-wide singleton — usually the unified daemon); "
-                        "this process will route reranking through that worker"
-                    )
-                    return
-            except Exception:
-                pass
-            logger.warning(
-                "Cross-encoder reranker warmup failed — recalls will use fallback scoring"
-            )
-        t = threading.Thread(target=_log_warmup_status, daemon=True, name="ce-init-warmup")
+        t = threading.Thread(
+            target=_log_reranker_warmup_status,
+            args=(reranker,),
+            daemon=True,
+            name="ce-init-warmup",
+        )
         t.start()
 
     # Phase A: Register forgetting filter into the channel registry

package/src/superlocalmemory/hooks/claude_code_hooks.py

@@ -40,7 +40,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.0"
+HOOKS_VERSION = "3.7.1"
 
 # 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

@@ -22,7 +22,7 @@ from typing import Callable, Iterable
 from superlocalmemory.core.security_primitives import redact_secrets
 
 
-VERSION = "3.7.0"
+VERSION = "3.7.1"
 DEFAULT_TOP_K = 10
 DEFAULT_DECISIONS_K = 5
 DEFAULT_MEMORIES_K = 10

package/src/superlocalmemory/mcp/http_transport.py

@@ -40,7 +40,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.0", **kwargs) -> None:
+    def __init__(self, *args, product_version: str = "3.7.1", **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

@@ -111,7 +111,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
         """Store content to memory with intelligent indexing.
 
         Extracts atomic facts, resolves entities, builds graph edges,
-        and indexes for 4-channel retrieval.
+        and indexes for hybrid retrieval with graph-aware enhancement.
 
         Multi-scope: ``scope`` sets visibility (personal/shared/global).
         ``shared_with`` is a comma-separated list of profile_ids for
@@ -246,7 +246,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
         include_global: bool | None = None,
         include_shared: bool | None = None,
     ) -> dict:
-        """Search memories by semantic query with 4-channel retrieval, RRF fusion, and reranking.
+        """Search memories through hybrid retrieval, RRF fusion, and reranking.
 
         S9-DASH-02: optional ``session_id`` threads through to the
         engine's outcome-queue so PostToolUse / Stop hooks can attach

package/src/superlocalmemory/optimize/proxy/server.py

@@ -17,7 +17,7 @@ from superlocalmemory.optimize.proxy.lifecycle import HookChain
 
 logger = logging.getLogger("slm.optimize.proxy")
 
-_PROXY_VERSION = "3.7.0"
+_PROXY_VERSION = "3.7.1"
 _REQUEST_TIMEOUT_S = 300.0
 _CONNECT_TIMEOUT_S = 10.0
 _MAX_CONNECTIONS = 100

package/src/superlocalmemory/server/routes/brain.py

@@ -64,7 +64,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.0"
+_VERSION: str = "3.7.1"
 
 # Banned metric names (LLD-04 U4). Kept as a tuple for grep visibility;
 # the source-level test asserts we don't accidentally reintroduce them.