superlocalmemory 4.0.8 → 4.0.9

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -234,7 +234,7 @@ class SpreadingActivation:
 
             # Return top-K sorted by activation
             results = sorted(
-                activations.items(), key=lambda x: x[1], reverse=True,
+                activations.items(), key=lambda x: (-x[1], x[0]),
             )
             return filter_authorized_results(
                 self._db,
@@ -296,7 +296,7 @@ class SpreadingActivation:
                 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]
+        return sorted(scored, key=lambda item: (-item[1], item[0]))[:self._config.top_m]
 
     def _propagate(
         self,
@@ -391,7 +391,7 @@ class SpreadingActivation:
 
             # Step 3: Lateral inhibition -- keep only top-M
             sorted_nodes = sorted(
-                new_activations.items(), key=lambda x: x[1], reverse=True,
+                new_activations.items(), key=lambda x: (-x[1], x[0]),
             )
             top_m_nodes = sorted_nodes[: cfg.top_m]
 
@@ -445,30 +445,30 @@ class SpreadingActivation:
                     SELECT * FROM (
                         SELECT target_id AS neighbor_id, weight FROM graph_edges AS ge
                         WHERE source_id = ? AND {graph_where}
-                        ORDER BY weight DESC LIMIT ?
+                        ORDER BY weight DESC, target_id ASC LIMIT ?
                     )
                     UNION ALL
                     SELECT * FROM (
                         SELECT target_fact_id AS neighbor_id, weight
                         FROM association_edges AS ae
                         WHERE source_fact_id = ? AND {assoc_where}
-                        ORDER BY weight DESC LIMIT ?
+                        ORDER BY weight DESC, target_fact_id ASC LIMIT ?
                     )
                     UNION ALL
                     SELECT * FROM (
                         SELECT source_id AS neighbor_id, weight FROM graph_edges AS ge
                         WHERE target_id = ? AND {graph_where}
-                        ORDER BY weight DESC LIMIT ?
+                        ORDER BY weight DESC, source_id ASC LIMIT ?
                     )
                     UNION ALL
                     SELECT * FROM (
                         SELECT source_fact_id AS neighbor_id, weight
                         FROM association_edges AS ae
                         WHERE target_fact_id = ? AND {assoc_where}
-                        ORDER BY weight DESC LIMIT ?
+                        ORDER BY weight DESC, source_fact_id ASC LIMIT ?
                     )
                 )
-                ORDER BY weight DESC
+                ORDER BY weight DESC, neighbor_id ASC
                 LIMIT ?
                 """,
                 (

package/src/superlocalmemory/retrieval/strategy.py

@@ -22,6 +22,17 @@ STRATEGY_PRESETS: dict[str, dict[str, float]] = {
     "opinion": {"semantic": 1.8, "bm25": 0.6, "entity_graph": 0.8, "temporal": 0.3, "spreading_activation": 0.5, "hopfield": 0.5},
     "factual": {"semantic": 1.2, "bm25": 1.4, "entity_graph": 1.0, "temporal": 0.6, "spreading_activation": 0.8, "hopfield": 0.8},
     "entity": {"semantic": 1.0, "bm25": 1.2, "entity_graph": 3.0, "temporal": 0.5, "spreading_activation": 1.5, "hopfield": 0.9},
+    # A question about the present carries almost no topical information in its
+    # words: "what am I working on" matches anything containing "working",
+    # including a note from a month ago about a working tree. Word-matching was
+    # set to 1.5 here, ABOVE the 1.4 of the preset this one exists to replace,
+    # so the new path boosted the exact signal that caused the original failure.
+    # It is now the weakest signal, because for this question it is the least
+    # informative one; time is what the question is actually about.
+    "recency": {
+        "temporal": 2.5, "bm25": 0.7, "semantic": 1.2,
+        "entity_graph": 1.0, "spreading_activation": 0.8, "hopfield": 0.5,
+    },
     "general": {},
     "vague": {"semantic": 0.8, "bm25": 0.5, "entity_graph": 0.6, "temporal": 0.3, "spreading_activation": 1.5, "hopfield": 1.1},
 }
@@ -32,6 +43,17 @@ _TEMPORAL_WORDS: frozenset[str] = frozenset({
     "until", "while", "between", "january", "february", "march",
     "april", "may", "june", "july", "august", "september", "october",
     "november", "december",
+    "now", "today", "yesterday",
+    "tonight", "tomorrow",
+    # "current" was removed earlier because "what is the current database schema"
+    # was being answered by newest-fact recency instead of topical search.
+    # "latest" and "currently" carry the same over-trigger: in "what is the
+    # latest authentication design" or "what is the currently supported format"
+    # they mean "most recent version of X", not "at what time did X happen".
+    # Routing those queries to temporal causes the recency fallback to dump the
+    # 50 newest facts with no topic filter at temporal weight 2.0, burying the
+    # subject the user named. Present-activity phrases ("currently working",
+    # "currently doing", "currently focused") are covered by _RECENCY_PHRASES.
 })
 
 _MULTI_HOP_PHRASES: tuple[str, ...] = (
@@ -63,6 +85,20 @@ _CAUSAL_TEMPORAL_WORDS: frozenset[str] = frozenset({
     "join", "visit", "return",
 })
 
+# Phrases that signal a present-activity or ongoing-state question.
+# Checked after multi_hop, entity and temporal word filters so retrospective
+# queries ("what did I work on recently") do not short-circuit here.
+# Order inside the tuple is irrelevant; all are substring-matched against the
+# lowercased query.
+_RECENCY_PHRASES: tuple[str, ...] = (
+    "working on",
+    "am i working", "are we working", "been working",
+    "what's happening", "what is happening",
+    "right now", "these days", "at the moment",
+    "currently doing", "currently working", "currently focused",
+    "what have i been", "what am i doing", "what have we been",
+)
+
 _AGGREGATION_WORDS: frozenset[str] = frozenset({
     "all", "list", "every", "everything", "various", "different",
     "many", "several", "multiple", "summarize", "overview",
@@ -101,9 +137,42 @@ class QueryStrategy:
     confidence: float = 0.5
 
 
+
+def _recency_enabled(config: object | None = None) -> bool:
+    """Whether the present-tense path is switched on.
+
+    The env var SLM_DISABLE_RECENCY_STRATEGY=1 is checked first (incident
+    override). If unset, the RetrievalConfig.enable_recency_strategy field is
+    consulted when a config object is supplied. Defaults to on when neither
+    is present.
+
+    Kept as a module-level function so the classifier stays usable without an
+    engine, which is how the gate and several tests call it.
+    """
+    import os
+
+    if os.environ.get("SLM_DISABLE_RECENCY_STRATEGY", "0") == "1":
+        return False
+    if config is not None and not getattr(config, "enable_recency_strategy", True):
+        return False
+    return True
+
+
 class QueryStrategyClassifier:
     """Classifies queries and produces adaptive channel weights."""
 
+    def __init__(self, config: object | None = None) -> None:
+        """Initialise the classifier.
+
+        Args:
+            config: Optional RetrievalConfig-like object. When supplied,
+                ``enable_recency_strategy=False`` on that object acts as a
+                persistent rollback without requiring an env var change.
+                The env var SLM_DISABLE_RECENCY_STRATEGY=1 always takes
+                precedence.
+        """
+        self._config = config
+
     def classify(self, query: str, base_weights: dict[str, float]) -> QueryStrategy:
         """Classify query and return adapted weights."""
         qtype = self._detect_type(query)
@@ -135,6 +204,18 @@ class QueryStrategyClassifier:
         if len(proper_nouns) >= 2 and words & _CAUSAL_TEMPORAL_WORDS:
             return "multi_hop"
 
+        # Checked BEFORE the single-word test below. "what am I working on right
+        # now" contains "now", so the word test claimed it first and routed a
+        # question about the present down the retrospective path — which weights
+        # word-matching at 1.5 against this path's 0.7, and word-matching on
+        # "working" is exactly what surfaced a month-old note about a working
+        # tree. A whole phrase states intent; a single word only hints at it.
+        #
+        # The enable_recency_strategy config field and SLM_DISABLE_RECENCY_STRATEGY
+        # env var both feed into _recency_enabled(). When either signals disabled,
+        # this block is skipped and the query falls through to subsequent checks.
+        if _recency_enabled(self._config) and any(p in q for p in _RECENCY_PHRASES):
+            return "recency"
         if words & _TEMPORAL_WORDS:
             return "temporal"
         if words & _AGGREGATION_WORDS:
@@ -152,3 +233,16 @@ class QueryStrategyClassifier:
         if any(p in q for p in _VAGUE_PHRASES):
             return "vague"
         return "general"
+
+
+_DEFAULT_CLASSIFIER = QueryStrategyClassifier()
+
+
+def classify_query(query: str, base_weights: dict[str, float] | None = None) -> QueryStrategy:
+    """Classify a query and return adapted channel weights.
+
+    Convenience function for callers that do not maintain a classifier instance.
+    Uses an empty weight dict when base_weights is omitted, which leaves
+    absolute weights undefined — useful for type-detection only.
+    """
+    return _DEFAULT_CLASSIFIER.classify(query, base_weights or {})

package/src/superlocalmemory/retrieval/temporal_channel.py

@@ -81,6 +81,7 @@ class TemporalChannel:
         top_k: int = 30,
         include_global: bool | None = None,
         include_shared: bool | None = None,
+        query_type: str = "general",
     ) -> list[tuple[str, float]]:
         """Search for temporally relevant facts.
 
@@ -117,11 +118,41 @@ class TemporalChannel:
         )
 
         # Strategy 2: Date proximity search
-        if query_dt is None and not entity_results:
-            return []
+        if query_dt is None:
+            recent: list[tuple[str, float]] = []
+            # For a question that IS about the present ("what am I working on"),
+            # recency is the answer, and it runs regardless of what else matched.
+            # It used to sit inside a guard that also required the entity search
+            # to be empty — inherited from the case where there is simply nothing
+            # to do — so on a real store, where something almost always matches,
+            # it effectively never ran.
+            #
+            # For a merely time-FLAVOURED question ("what is the latest
+            # authentication design"), recency is a last resort, not the answer:
+            # this channel returns up to 50 newest facts with no regard for topic,
+            # and at temporal's weight of 2.0 that buries the very subject the
+            # user named. So there it runs only when nothing else matched at all.
+            if query_type == "recency" or (
+                query_type == "temporal" and not entity_results
+            ):
+                recent = self._recency_fallback(
+                    profile_id,
+                    include_global=include_global,
+                    include_shared=include_shared,
+                )
+            if not entity_results:
+                return recent
+            if recent:
+                # Both signals are real: an entity the question named, and the
+                # fact that the question is about now. Recency leads because
+                # that is what this channel was asked about; entity matches
+                # follow, and anything already present keeps its better place.
+                seen = {fid for fid, _ in recent}
+                return recent + [(f, s) for f, s in entity_results if f not in seen]
 
         events = self._load_events(
             profile_id, include_global=include_global, include_shared=include_shared,
+            near_date=query_dt.date().isoformat() if query_dt is not None else None,
         )
         scored: dict[str, float] = {}
 
@@ -155,7 +186,7 @@ class TemporalChannel:
                     fid = ev["fact_id"]
                     scored[fid] = max(scored.get(fid, 0.0), best)
 
-        results = sorted(scored.items(), key=lambda x: x[1], reverse=True)
+        results = sorted(scored.items(), key=lambda x: (-x[1], x[0]))
         return results[:top_k]
 
     def _entity_temporal_search(
@@ -208,7 +239,13 @@ class TemporalChannel:
                 "SELECT te.fact_id FROM temporal_events AS te "
                 "JOIN canonical_entities AS ce ON ce.entity_id = te.entity_id "
                 "JOIN atomic_facts AS af ON af.fact_id = te.fact_id "
-                f"WHERE {where} AND LOWER(ce.canonical_name) = LOWER(?)",
+                f"WHERE {where} AND LOWER(ce.canonical_name) = LOWER(?) "
+                # The score below is derived from each row's POSITION in this
+                # result. Position must reflect temporal order so that the comment
+                # "first events more likely relevant" holds: oldest fact first,
+                # tie-broken by fact_id so two facts created in the same instant
+                # produce the same score on two runs.
+                "ORDER BY af.created_at ASC, te.fact_id ASC",
                 (*params, name),
             )
             for row in rows:
@@ -227,7 +264,102 @@ class TemporalChannel:
         profile_id: str,
         include_global: bool | None = None,
         include_shared: bool | None = None,
+        near_date: str | None = None,
     ) -> list[dict]:
+        """Load a bounded slice of temporal events.
+
+        ``near_date`` decides WHICH slice. Without it the newest events are
+        taken, which suits "what is recent". With it the events closest to that
+        date are taken, which is the only slice that can answer a question about
+        a particular time — the newest-first bound silently excluded anything
+        old, so a question about last year returned nothing rather than slowly.
+        """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
+        where, params = _scope_where(
+            profile_id,
+            include_global=include_global,
+            include_shared=include_shared,
+            prefix="af",
+        )
+        # The bound has to match what the caller is looking for. Taking the
+        # newest 5,000 rows is right when the question is "what is recent", and
+        # wrong when it is "what happened in March 2024" — those events carry old
+        # rowids and were simply never loaded, so the answer was missing rather
+        # than slow. When a target date is known, bound by proximity to THAT date
+        # instead; the scan stays bounded either way.
+        if near_date is not None:
+            # Include events that carry only interval_start/interval_end with no
+            # referenced_date or observation_date. The original filter required
+            # at least one of the point-date columns to be non-NULL, which
+            # excluded duration events ("during March 2024") entirely. The
+            # ORDER BY now uses the best available date column so that duration
+            # events are ranked by their interval_start when no point date exists.
+            rows = self._db.execute(
+                "SELECT te.fact_id, te.observation_date, te.referenced_date, "
+                "te.interval_start, te.interval_end, af.created_at "
+                "FROM temporal_events AS te "
+                "JOIN atomic_facts AS af ON af.fact_id = te.fact_id "
+                f"WHERE {where} "
+                "  AND (te.referenced_date IS NOT NULL "
+                "       OR te.observation_date IS NOT NULL "
+                "       OR te.interval_start IS NOT NULL) "
+                # Thousands of events can tie on the proximity expression when
+                # they share a date, and a tie with no secondary key is broken by
+                # storage order. That decides which of them survive the LIMIT.
+                "ORDER BY ABS(julianday(COALESCE(te.referenced_date, "
+                "                               te.observation_date, "
+                "                               te.interval_start)) "
+                "             - julianday(?)) ASC, te.fact_id ASC "
+                "LIMIT 5000",
+                (*params, near_date),
+            )
+        else:
+            rows = self._db.execute(
+                "SELECT te.fact_id, te.observation_date, te.referenced_date, "
+                "te.interval_start, te.interval_end, af.created_at "
+                "FROM temporal_events AS te "
+                "JOIN atomic_facts AS af ON af.fact_id = te.fact_id "
+                f"WHERE {where} "
+                "ORDER BY te.rowid DESC LIMIT 5000",
+                (*params,),
+            )
+        return [dict(r) for r in rows]
+
+    def _recency_fallback(
+        self,
+        profile_id: str,
+        include_global: bool | None,
+        include_shared: bool | None,
+    ) -> list[tuple[str, float]]:
+        """Return recently created facts with Gaussian age-decay scoring.
+
+        Called when the query carries no date and the caller has said the
+        question is about the present. It deliberately does not depend on the
+        entity search being empty — requiring that made this unreachable on any
+        store where something matches, which is most of them.
+
+        One entry per fact. Facts scored here compete in fusion against semantic
+        and BM25 results, and fusion ranks facts, so repeating a fact spends
+        ranks without adding candidates.
+
+        Scoring: Gaussian with sigma=7 days. Facts older than 90 days score
+        below 0.01 and are excluded. Returns at most 50 (fact_id, score) pairs,
+        ordered highest-score first.
+
+        Source table: atomic_facts, not temporal_events. The materializer
+        populates temporal_events asynchronously and only for facts with both
+        canonical entities and resolved dates. A plain note written moments ago
+        never receives a temporal_events row until that background pass runs, so
+        a join against temporal_events makes newly written facts structurally
+        invisible here — exactly when the caller needs them most.
+        """
+        _SIGMA = 7.0          # days — tighter than _proximity_score's 30d
+        _MAX_AGE_DAYS = 90.0  # cut-off: exp(-(90^2)/(2*7^2)) ≈ 0.0
+        now_dt = datetime.now(tz=timezone.utc)
+
         if include_global is None:
             include_global = bool(getattr(self, "include_global", False))
         if include_shared is None:
@@ -239,14 +371,39 @@ class TemporalChannel:
             prefix="af",
         )
         rows = self._db.execute(
-            "SELECT te.fact_id, te.observation_date, te.referenced_date, "
-            "te.interval_start, te.interval_end "
-            "FROM temporal_events AS te "
-            "JOIN atomic_facts AS af ON af.fact_id = te.fact_id "
-            f"WHERE {where}",
+            "SELECT af.fact_id, af.created_at "
+            "FROM atomic_facts AS af "
+            f"WHERE {where} "
+            "  AND af.created_at >= datetime('now', '-90 days') "
+            "ORDER BY af.created_at DESC, af.fact_id ASC "
+            "LIMIT 50",
             (*params,),
         )
-        return [dict(r) for r in rows]
+
+        best: dict[str, float] = {}
+        for row in rows:
+            d = dict(row)
+            fid = d.get("fact_id")
+            if not fid:
+                continue
+            created = _parse_iso(d.get("created_at"))
+            if created is None:
+                continue
+            utc_created = _as_utc(created)
+            if utc_created is None:
+                continue
+            age_days = max(
+                0.0,
+                (now_dt - utc_created).total_seconds() / 86400.0,
+            )
+            if age_days > _MAX_AGE_DAYS:
+                continue
+            score = math.exp(-(age_days ** 2) / (2.0 * _SIGMA * _SIGMA))
+            if score > 0.01 and score > best.get(fid, 0.0):
+                best[fid] = score
+
+        out = sorted(best.items(), key=lambda kv: (-kv[1], kv[0]))
+        return out[:50]
 
     @staticmethod
     def _try_parse(text: str) -> datetime | None:

package/src/superlocalmemory/retrieval/temporal_validity_filter.py

@@ -460,7 +460,7 @@ class TemporalValidityFilter:
             ]
             # Re-sort descending so demoted facts fall below currently-valid
             # facts in this channel's rank order.
-            new_list.sort(key=lambda pair: pair[1], reverse=True)
+            new_list.sort(key=lambda pair: (-pair[1], pair[0]))
             demoted[channel_name] = new_list
         return demoted
 

package/src/superlocalmemory/retrieval/vector_store.py

@@ -25,6 +25,7 @@ from typing import Generator
 
 import numpy as np
 
+from superlocalmemory.storage.embedding_codec import encode_embedding
 from superlocalmemory.storage.write_lock import get_write_lock
 
 logger = logging.getLogger(__name__)
@@ -249,8 +250,19 @@ class VectorStore:
 
     @staticmethod
     def _serialize_f32(vector: list[float]) -> bytes:
-        """Serialize float list to raw bytes for sqlite-vec."""
-        return np.array(vector, dtype=np.float32).tobytes()
+        """Serialize float list to raw bytes for sqlite-vec.
+
+        Delegates to the shared embedding codec so that a format change in
+        that codec propagates here automatically.
+        """
+        result = encode_embedding(vector)
+        if result is None:
+            # encode_embedding returns None only for None input; _serialize_f32
+            # is never called with None, so this branch is unreachable in
+            # production.  Return empty bytes rather than raising so the caller
+            # sees an empty query result rather than an unhandled exception.
+            return b""
+        return result
 
     # -- CRUD Operations ----------------------------------------------------
 
@@ -478,14 +490,28 @@ class VectorStore:
                             (*base_params, search_k),
                         ).fetchall()
 
-            results: list[tuple[str, float]] = []
-            for row in rows[:top_k]:
-                fid = str(row["fact_id"])
-                similarity = max(0.0, 1.0 - row["distance"])
-                results.append((fid, similarity))
-
-            results.sort(key=lambda x: x[1], reverse=True)
-            return results
+            # Rank the whole candidate list, THEN cut it. The expansion above
+            # can leave `rows` longer than top_k, and the SQL has no ORDER BY —
+            # vec0 applies k, then a relational join emits the survivors in an
+            # order SQLite is free to choose. Cutting first therefore cut by
+            # position and only ranked what survived, which can drop a nearer
+            # fact in favour of a farther one.
+            #
+            # Measured on the 0.95 GB archive: 29 of 60 queries do take the
+            # expansion path (orphan vectors are common), and the produced set
+            # matched the true nearest-k in all 29 — the join does emit in
+            # distance order in practice. So this was latent, not active. It is
+            # fixed because "the planner happens to" is not a guarantee: add an
+            # index, change SQLite, or change the join and the answer moves.
+            #
+            # The tie-break on fact_id makes the cut total, so two facts at
+            # equal distance cannot swap across the top_k boundary between runs.
+            results: list[tuple[str, float]] = [
+                (str(row["fact_id"]), max(0.0, 1.0 - row["distance"]))
+                for row in rows
+            ]
+            results.sort(key=lambda x: (-x[1], x[0]))
+            return results[:top_k]
 
         except Exception as exc:
             logger.debug("search failed: %s", exc)
@@ -596,6 +622,58 @@ class VectorStore:
             except Exception:
                 return False
 
+    def is_searchable_by_meaning(
+        self,
+        fact_id: str,
+        profile_id: str | None = None,
+    ) -> bool:
+        """Return True if search() would be able to return this fact.
+
+        The check mirrors search()'s own join:
+
+            FROM fact_embeddings AS fe
+            JOIN embedding_metadata AS em
+              ON em.vec_rowid = fe.rowid
+             AND em.profile_id = fe.profile_id
+
+        A fact that has a vector in fact_embeddings but no row in
+        embedding_metadata will NOT be returned by search(), so this method
+        returns False for it — even though raw_vector_present() would return
+        True.  Callers that need to decide whether a fact requires re-embedding
+        must use this method, not raw_vector_present().
+
+        Returns False on any error or when the store is unavailable (fail-
+        closed: never optimistic).
+        """
+        if not self._available:
+            return False
+        try:
+            with self._managed_connection() as conn:
+                if profile_id is not None:
+                    sql = (
+                        "SELECT 1 FROM fact_embeddings AS fe "
+                        "JOIN embedding_metadata AS em "
+                        "ON em.vec_rowid = fe.rowid "
+                        "AND em.profile_id = fe.profile_id "
+                        "WHERE em.fact_id = ? "
+                        "AND fe.profile_id = ? "
+                        "LIMIT 1"
+                    )
+                    row = conn.execute(sql, (fact_id, profile_id)).fetchone()
+                else:
+                    sql = (
+                        "SELECT 1 FROM fact_embeddings AS fe "
+                        "JOIN embedding_metadata AS em "
+                        "ON em.vec_rowid = fe.rowid "
+                        "AND em.profile_id = fe.profile_id "
+                        "WHERE em.fact_id = ? "
+                        "LIMIT 1"
+                    )
+                    row = conn.execute(sql, (fact_id,)).fetchone()
+                return row is not None
+        except Exception:
+            return False
+
     def count(self, profile_id: str | None = None) -> int:
         """Count complete metadata/vector pairs in the store.
 

package/src/superlocalmemory/server/recall_serializer.py

@@ -298,4 +298,14 @@ def recall_response_metadata(response: Any) -> dict:
         # Q2b: thematic community summary (pure pass-through; computed upstream
         # in the engine where DB access is available). None on most recalls.
         "thematic_context": getattr(response, "community_context", None),
+        # Channels abandoned at the hang guard, so their candidates are absent
+        # from this answer. Empty on a healthy recall, which is the normal case.
+        # Non-empty is the one situation in which asking the same question twice
+        # may legitimately give different answers, so it has to travel with the
+        # response rather than living only in a server log — otherwise a caller
+        # comparing two runs has no way to tell an incomplete answer from a
+        # changed one. A list, because JSON has no tuple.
+        "incomplete_channels": list(
+            getattr(response, "incomplete_channels", ()) or ()
+        ),
     }

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

@@ -806,7 +806,7 @@ def _compute_cross_platform() -> dict:
     ``memory.db`` (LLD-07 M004). On any adapter error, that adapter
     reports ``active: false`` with ``reason: error:<ExcName>`` rather
     than crashing the whole Brain endpoint (LLD-04 §2 — "honest, never
-    fake"). An unimportable adapter means the install is missing Wave 2C
+    fake"). An unimportable adapter means the install is missing the
     components, which is legitimate for an older 3.4.20 → 3.4.22 upgrade
     mid-migration.
     """
@@ -953,7 +953,7 @@ def _compute_active_clients(profile_id: str) -> dict:
     try:
         from superlocalmemory.hooks.session_registry import active_client_summary
         clients = active_client_summary(profile_id, within_seconds=300)
-    except Exception as exc:  # distinguish failure from emptiness (Wave 4)
+    except Exception as exc:  # distinguish failure from emptiness (important: these are different states)
         registry_ok = False
         reg_status = "error"
         logger.debug("active_clients: registry error: %s", exc)

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

@@ -4,10 +4,10 @@
 
 """POST /internal/prewarm — populates the context cache for a session.
 
-S8-SK-02 fix: Wave 2A shipped ``hooks/prewarm_auth.authorize`` (gates
-loopback → origin → install-token → body-size) and unit-tested it, but
-no FastAPI route mounted it. The hot-path ``post_tool_async_hook`` POSTs
-to ``/internal/prewarm`` after every tool call to refresh the
+Bug fix: ``hooks/prewarm_auth.authorize`` (which gates loopback →
+origin → install-token → body-size) was implemented and unit-tested,
+but no FastAPI route mounted it. The hot-path ``post_tool_async_hook``
+POSTs to ``/internal/prewarm`` after every tool call to refresh the
 ``active_brain_cache`` row for the current session/topic. Without a
 route registered here, those POSTs 404'd silently, the cache never
 populated, and every ``UserPromptSubmit`` ended up a structural miss.