superlocalmemory 4.0.8 → 4.0.10

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 ----------------------------------------------------
 
@@ -404,6 +416,29 @@ class VectorStore:
                     logger.debug("upsert failed for fact_id=%s: %s", fact_id, exc)
                     return False
 
+    def _has_quarantine_column(self) -> bool:
+        """Whether atomic_facts carries ``quarantined`` in this database.
+
+        Cached once True; re-probed while absent so a schema pass that lands
+        later is picked up. Mirrors DatabaseManager._has_quarantine_column --
+        an unmigrated store must degrade to the old query rather than raise on
+        every semantic search.
+        """
+        cached = getattr(self, "_quarantine_col", None)
+        if cached is True:
+            return True
+        try:
+            with self._managed_connection() as conn:
+                present = any(
+                    row[1] == "quarantined"
+                    for row in conn.execute("PRAGMA table_info(atomic_facts)")
+                )
+        except Exception:  # noqa: BLE001 -- a probe must never break search
+            return False
+        if present:
+            self._quarantine_col = True
+        return present
+
     def search(
         self,
         query_embedding: list[float],
@@ -427,6 +462,42 @@ class VectorStore:
             with self._managed_connection() as conn:
                 if top_k <= 0:
                     return []
+                # A withheld fact must not occupy a nearest-neighbour slot.
+                #
+                # Its vector stays in the index — quarantine is reversible and
+                # deleting the projection would cost a re-embed to undo — so it
+                # is filtered here instead.
+                #
+                # Measured on the author's store: 1,192 of 5,086 projections
+                # (23.4%) belong to withheld rows, and because model-written
+                # summaries of the same clusters land close together in
+                # embedding space they crowd each other. Searching with a vector
+                # taken from one of them returned 50 of 50 neighbours withheld
+                # without this join, and 0 of 50 with it. So for any query near
+                # that cluster the semantic channel was contributing nothing at
+                # all — every slot spent on a candidate that hydration would
+                # discard — while looking like it had answered.
+                #
+                # The expansion loop below already exists for exactly this
+                # shape of problem (orphaned vec0 rows losing a slot to the
+                # relational join) and compensates automatically: it doubles k
+                # until top_k surviving pairs are found. Nothing new is needed
+                # to make the slots back.
+                # LEFT, not INNER. An inner join would make a projection
+                # depend on its corpus row still existing, so a legacy orphan
+                # metadata row would stop being returned at all -- a behaviour
+                # change well beyond quarantine, and one the existing
+                # vector-store tests caught immediately by building a store
+                # with no matching facts. LEFT leaves af.quarantined NULL for a
+                # missing row, and COALESCE keeps it.
+                quarantine_join = (
+                    " LEFT JOIN atomic_facts AS af ON af.fact_id = em.fact_id "
+                    if self._has_quarantine_column() else ""
+                )
+                quarantine_filter = (
+                    " AND COALESCE(af.quarantined, 0) = 0 "
+                    if self._has_quarantine_column() else ""
+                )
                 if profile_id is not None:
                     sql = (
                         "SELECT fe.rowid, fe.distance, em.fact_id "
@@ -434,8 +505,10 @@ class VectorStore:
                         "JOIN embedding_metadata AS em "
                         "ON em.vec_rowid = fe.rowid "
                         "AND em.profile_id = fe.profile_id "
+                        + quarantine_join +
                         "WHERE fe.embedding MATCH ? "
                         "AND fe.profile_id = ? "
+                        + quarantine_filter +
                         "AND fe.k = ?"
                     )
                     base_params: tuple[object, ...] = (vec_bytes, profile_id)
@@ -448,7 +521,9 @@ class VectorStore:
                         "JOIN embedding_metadata AS em "
                         "ON em.vec_rowid = fe.rowid "
                         "AND em.profile_id = fe.profile_id "
+                        + quarantine_join +
                         "WHERE fe.embedding MATCH ? "
+                        + quarantine_filter +
                         "AND fe.k = ?"
                     )
                     base_params = (vec_bytes,)
@@ -478,14 +553,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 +685,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/api.py

@@ -246,7 +246,12 @@ def create_app() -> FastAPI:
                 "<p><a href='/docs'>API Documentation</a></p>"
                 "</body></html>"
             )
-        return index_path.read_text()
+        from superlocalmemory.server.asset_versions import render_index
+        from superlocalmemory import __version__ as _v
+
+        return render_index(
+            index_path, UI_DIR, substitutions={"__SLM_VERSION__": _v},
+        )
 
     @application.get("/health")
     async def health_check():

package/src/superlocalmemory/server/asset_versions.py

@@ -0,0 +1,171 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Derive the dashboard's asset cache-busters from the files themselves.
+
+``index.html`` referenced 64 static assets. 35 carried a hand-written
+``?v=`` literal and 29 carried nothing, and not one of them was derived from the
+file it pointed at. So the version strings looked like cache-busting and were
+not: editing a JS or CSS file left its ``?v=`` reading whatever the last person
+typed, which during 4.0.10 was ``022ff653`` on a file that had changed.
+
+WHAT THIS DOES AND DOES NOT FIX
+-------------------------------
+It does not fix a live user-facing bug, and it would be dishonest to claim it
+does. Three mechanisms already stop a stale asset reaching a browser on this
+server, and the first was verified against the running daemon rather than read:
+
+  * ``/static/*`` is served ``Cache-Control: no-cache, must-revalidate`` with an
+    ETag (``server/security_middleware.py``), so a browser must revalidate and
+    cannot serve a cached copy without asking.
+  * The unified daemon copies the whole UI tree into the data directory on every
+    start (``unified_daemon.py``, ``state_path("ui")``), so an upgrade refreshes
+    the files it serves.
+  * ``index.html`` itself is ``no-cache``, so the page is always re-read.
+
+What it fixes is a **trap**, and unblocks a real improvement:
+
+  * 64 references, none tracking content. Anyone reading them concludes
+    cache-busting is handled here, which is how the 4.0.10 change shipped with a
+    stale literal and how the next one would too. A number that is maintained by
+    hand and consulted by nobody is worse than no number.
+  * The revalidation policy is the only thing making that safe, and it costs a
+    conditional request per asset on every page load — 64 of them. The obvious
+    optimisation is ``max-age`` with a long life, and today that change would
+    turn every hand-typed literal into an immediate live bug. With versions
+    derived from content it becomes safe to make. That policy change is NOT
+    made here; it needs its own measurement.
+  * A proxy or CDN that ignores ``no-cache`` is defeated by a URL that changes,
+    not by a header.
+
+DESIGN
+------
+Rewrite at serve time rather than at build time, because there is no build step:
+the UI ships as source files and is copied into place. The hash is computed from
+file bytes and cached on ``(size, mtime_ns)``, so a warm daemon does one ``stat``
+per asset per page load and no reads. Unresolvable references keep whatever the
+HTML said, so a missing file or an odd path degrades to today's behaviour rather
+than breaking the page.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["render_index", "asset_version", "rewrite_asset_versions"]
+
+#: Characters of hex digest used in a URL. Eight is what the existing literals
+#: used and is ample: these identify one file's revisions, not a global
+#: namespace, so a collision needs two versions of the same file agreeing on
+#: eight hex characters.
+_HASH_CHARS = 8
+
+#: ``src="static/…"`` / ``href="static/…"`` with an optional existing ``?v=``.
+#: Deliberately narrow — only the ``static/`` prefix the dashboard mounts, only
+#: double-quoted attributes, and the path is captured without its query so the
+#: rewrite cannot alter it.
+_ASSET_REF = re.compile(
+    r'(?P<attr>\b(?:src|href)=")'
+    r'(?P<path>static/[^"?#]+)'
+    r'(?P<query>\?[^"#]*)?'
+    r'(?P<fragment>#[^"]*)?'
+    r'(?P<close>")'
+)
+
+#: (resolved path) -> (size, mtime_ns, digest). Keyed on the path so a daemon
+#: serving from the data-directory copy and one serving from the source tree do
+#: not share entries.
+_CACHE: dict[Path, tuple[int, int, str]] = {}
+
+
+def asset_version(asset_path: Path) -> str | None:
+    """Short content hash of ``asset_path``, or None if it cannot be read.
+
+    Cached on ``(size, mtime_ns)``. That pair is what ETag generators use for
+    the same reason: it changes on every practical edit, and re-reading a file
+    that has not changed costs a page-load's worth of I/O for nothing.
+
+    ``mtime_ns`` rather than ``mtime``: the UI is installed with
+    ``shutil.copytree``, which preserves timestamps, so two files written inside
+    the same filesystem tick are a real possibility on a fast copy.
+    """
+    try:
+        stat = asset_path.stat()
+    except OSError:
+        return None
+
+    key = (stat.st_size, stat.st_mtime_ns)
+    cached = _CACHE.get(asset_path)
+    if cached is not None and cached[:2] == key:
+        return cached[2]
+
+    try:
+        digest = hashlib.sha256(asset_path.read_bytes()).hexdigest()[:_HASH_CHARS]
+    except OSError as exc:
+        logger.debug("asset version unavailable for %s: %s", asset_path, exc)
+        return None
+
+    _CACHE[asset_path] = (*key, digest)
+    return digest
+
+
+def rewrite_asset_versions(html: str, ui_root: Path) -> str:
+    """Replace every ``static/…?v=`` with a version derived from the file.
+
+    ``ui_root`` is the directory mounted at ``/static``, so a reference to
+    ``static/js/core.js`` resolves to ``ui_root/js/core.js`` — the ``static/``
+    segment is the mount point, not a directory on disk. Getting that wrong
+    silently resolves nothing and leaves all 64 literals in place, which is why
+    the test asserts a version actually moved rather than only that the call
+    returned.
+
+    Assets with no existing query gain one. That is a URL change, and it is the
+    point: 29 of the 64 references had no cache-buster at all, so they were the
+    ones a policy change would break first.
+    """
+
+    def _replace(match: re.Match[str]) -> str:
+        path = match.group("path")
+        version = asset_version(ui_root / path[len("static/"):])
+        if version is None:
+            # Keep whatever the HTML said. A reference we cannot resolve is not
+            # a reason to serve a page that cannot load its own stylesheet.
+            return match.group(0)
+        return (
+            f"{match.group('attr')}{path}?v={version}"
+            f"{match.group('fragment') or ''}{match.group('close')}"
+        )
+
+    return _ASSET_REF.sub(_replace, html)
+
+
+def render_index(
+    index_path: Path,
+    ui_root: Path | None = None,
+    *,
+    substitutions: dict[str, str] | None = None,
+) -> str:
+    """Read ``index.html`` and prepare it for serving.
+
+    One function for the three ``root()`` handlers (``api.py``, ``ui.py``,
+    ``unified_daemon.py``) that each read this file and returned it. They had
+    drifted: only the daemon substituted ``__SLM_VERSION__``, so the upgrade
+    detector the dashboard relies on silently did nothing on the other two.
+
+    ``ui_root`` defaults to the file's own directory, which is correct for every
+    caller today — ``index.html`` sits at the root of the tree mounted at
+    ``/static``.
+
+    Raises ``OSError`` if the index itself cannot be read; every caller already
+    checks ``exists()`` and has its own fallback page.
+    """
+    html = index_path.read_text()
+    html = rewrite_asset_versions(html, ui_root or index_path.parent)
+    for placeholder, value in (substitutions or {}).items():
+        html = html.replace(placeholder, value)
+    return html

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/abstraction.py

@@ -9,6 +9,8 @@ down to source atoms:
 
   GET /api/v3/abstraction/persona      — the per-profile persona roll-up
   GET /api/v3/abstraction/communities  — community summaries (Q2)
+  GET /api/v3/abstraction/consolidated — display-only cluster summaries
+  GET /api/v3/abstraction/health       — can my memories be found? (4.0.10)
   GET /api/v3/abstraction/sources      — drill-down (node -> source atoms)
 
 Read-only, profile-scoped (Rule 01), direct sqlite3 (Rule 06). All handlers
@@ -30,6 +32,31 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/v3/abstraction", tags=["abstraction"])
 
+#: How many summary rows /consolidated will read before ranking them by
+#: quality. Bounded because this runs on a request thread: a store with tens of
+#: thousands of summaries must not turn one card into a full-table scan.
+_SCAN_CEILING = 400
+
+#: Characters of normalised opening text that make two summaries "the same
+#: summary" for display. Long enough that two genuinely different subjects
+#: diverge within it, short enough to catch the same sentence with a different
+#: tail — which is the shape the summarizer actually produces.
+_OPENING_KEY_CHARS = 90
+
+
+def _opening_key(content: object) -> str:
+    """Normalised opening of a summary, for near-duplicate collapsing.
+
+    Case-folded with runs of whitespace flattened, so two summaries differing
+    only in line wrapping or capitalisation collapse together. Returns "" for
+    anything too short to judge, which is then never collapsed — better to show
+    a duplicate than to hide a distinct summary on a weak signal.
+    """
+    text = " ".join(str(content or "").split()).casefold()
+    if len(text) < 40:
+        return ""
+    return text[:_OPENING_KEY_CHARS]
+
 
 class _ReadDB:
     """Adapt a raw sqlite3 connection to the .execute(...) -> list contract
@@ -111,3 +138,177 @@ def get_sources(
         return JSONResponse({"profile": pid, "sources": empty})
     finally:
         conn.close()
+
+
+@router.get("/consolidated")
+def get_consolidated(
+    profile: str = Query(""),
+    limit: int = Query(50, ge=1, le=200),
+    include_unusable: bool = Query(False),
+) -> JSONResponse:
+    """Cluster summaries, read from the DISPLAY table and nowhere else.
+
+    ``consolidated_summaries`` is the only source. Reading ``atomic_facts``
+    here would put the boundary back where it was: these summaries were in the
+    retrieval corpus until 4.0.10 and the whole point of moving them is that
+    exactly one surface shows them, and it is this one.
+
+    ``summaries`` holds only rows worth reading. The rest are REPORTED, not
+    returned: ``unusable`` and ``near_duplicates`` are counts over the scanned
+    window. A reader is better served by "62 of these came back empty" than by a
+    page that silently shows a handful and looks complete — and hiding the fact
+    that they came back empty would hide the problem this endpoint exists to make
+    visible. ``include_unusable=true`` returns them for inspection.
+
+    Two orderings, both measured rather than chosen:
+
+    * Ranking by ``source_count`` alone put the junk on top, because the
+      summaries merging the largest clusters are exactly the ones the model had
+      least in common to work with. On the author's store **0 of the top 24 by
+      source_count were usable**, so a card asking for 24 rendered empty against
+      a store holding a thousand summaries.
+    * Rows covering real memories rank above rows covering none. 353 of these
+      are summaries of summaries; their honest ``source_count`` is 0, and a
+      digest of the summarizer's own output is worth less to a reader than a
+      digest of their own words.
+
+    Quality is a Python predicate rather than a SQL expression, which is why the
+    window is read to at most ``_SCAN_CEILING`` rows, classified, and then
+    ordered.
+    """
+    pid = profile or get_active_profile()
+    conn = _conn()
+    if conn is None:
+        return JSONResponse({
+            "profile": pid, "summaries": [], "unusable": 0, "scanned": 0,
+        })
+    try:
+        from superlocalmemory.summaries.base import clean_llm_summary
+        from superlocalmemory.summaries.non_answer import (
+            MIN_USEFUL_CHARS,
+            is_non_answer,
+        )
+
+        scan = min(_SCAN_CEILING, max(int(limit) * 8, int(limit)))
+        rows = conn.execute(
+            "SELECT summary_id, entity_name, content, source_count, "
+            "       generated_by, source_earliest, source_latest, created_at "
+            "  FROM consolidated_summaries "
+            " WHERE profile_id = ? "
+            " ORDER BY source_count DESC, created_at DESC, summary_id ASC "
+            " LIMIT ?",
+            (pid, scan),
+        ).fetchall()
+
+        classified: list[dict[str, Any]] = []
+        unusable = 0
+        for row in rows:
+            item = dict(row)
+            # CLEAN, THEN JUDGE — the same order the write path uses, and for
+            # the same reason. Rows migrated from the old corpus were never
+            # cleaned, so their scaffolding is still attached: judging first let
+            # "Here is a concise summary paragraph incorporating all 10 facts..."
+            # through as usable and put it at the top of the card, because it
+            # does contain a summary and the non-answer rules are about refusals,
+            # not preambles. Cleaning is also what the reader should see: the
+            # scaffolding is addressed to a conversation they cannot read.
+            item["content"] = clean_llm_summary(str(item.get("content") or ""))
+            rejected, why = is_non_answer(
+                item["content"], min_chars=MIN_USEFUL_CHARS,
+            )
+            item["quality"] = why if rejected else "ok"
+            if rejected:
+                unusable += 1
+            classified.append(item)
+
+        # Usable first, then rows that cover real memories, then the SQL
+        # ordering within each group. Stable sort, so two runs of one request
+        # return the same rows in the same order — a summary card that
+        # reshuffles itself on refresh reads as a bug even when every row is
+        # correct.
+        classified.sort(key=lambda item: (
+            0 if item["quality"] == "ok" else 1,
+            0 if (item.get("source_count") or 0) > 0 else 1,
+        ))
+
+        # Collapse near-duplicates.
+        #
+        # The table's UNIQUE constraint is on exact content, so summaries that
+        # differ by a clause survive as separate rows. On the author's store the
+        # first 24 usable rows all opened "The Pro and SuperLocalMemory (SLM)
+        # projects have made significant progress in..." — twenty-four cards
+        # saying one thing, which reads as a broken page rather than as a view
+        # of a memory.
+        #
+        # Collapsed on a normalised opening, keeping the row that merged the
+        # most memories (the ordering above already put it first). The count is
+        # reported, not swallowed: that these summaries repeat each other is a
+        # real property of the store and worth a reader knowing.
+        deduped: list[dict[str, Any]] = []
+        seen_openings: set[str] = set()
+        collapsed = 0
+        for item in classified:
+            key = _opening_key(item.get("content"))
+            if key and key in seen_openings:
+                collapsed += 1
+                continue
+            if key:
+                seen_openings.add(key)
+            deduped.append(item)
+
+        # Only rows worth reading occupy the window.
+        #
+        # A first draft returned everything, usable first, and truncated at
+        # `limit`. Because the usable rows on this store collapse to a handful
+        # of distinct openings, the tail of a limit-10 request filled with
+        # refusals — and a card asking for 10 got 2 it could render and 8 it
+        # threw away. The counts carry what the reader needs to know about the
+        # rest; the rows themselves add nothing to a card.
+        shown = (
+            deduped[:int(limit)] if include_unusable
+            else [i for i in deduped if i["quality"] == "ok"][:int(limit)]
+        )
+        return JSONResponse({
+            "profile": pid,
+            "summaries": shown,
+            "unusable": unusable,
+            "near_duplicates": collapsed,
+            "scanned": len(rows),
+        })
+    except sqlite3.Error as exc:
+        # A store that predates the display table. Empty, not an error.
+        logger.debug("consolidated summaries read failed: %s", exc)
+        return JSONResponse({
+            "profile": pid, "summaries": [], "unusable": 0, "scanned": 0,
+        })
+    finally:
+        conn.close()
+
+
+@router.get("/health")
+def get_memory_health() -> JSONResponse:
+    """Whether this store's memories can actually be found.
+
+    Same measurement ``slm doctor`` prints, so the dashboard and the CLI cannot
+    tell the owner two different things. Read-only and fail-soft.
+    """
+    try:
+        from superlocalmemory.core.memory_health import describe, measure
+
+        health = measure(DB_PATH)
+        return JSONResponse({
+            "live_facts": health.live_facts,
+            "findable_by_meaning": health.findable_by_meaning,
+            "missing_vector": health.missing_vector,
+            "withheld_summaries": health.withheld_summaries,
+            "display_summaries": health.display_summaries,
+            "hidden_by_forgetting": health.hidden_by_forgetting,
+            "inconsistently_hidden": health.inconsistently_hidden,
+            "reachability": round(health.reachability, 4),
+            "healthy": health.healthy,
+            "unavailable": list(health.unavailable),
+            "summary": describe(health),
+        })
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("memory health read failed: %s", exc)
+        return JSONResponse({"healthy": None, "summary": [], "unavailable": ["error"]})

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)