superlocalmemory 4.0.9 → 4.0.10

package/src/superlocalmemory/mcp/tools_core.py

@@ -73,6 +73,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
         scope: str | None = None,
         shared_with: str = "",
         idempotency_key: str = "",
+        session_date: str = "",
     ) -> dict:
         """Store content to memory with intelligent indexing.
 
@@ -82,11 +83,35 @@ def register_core_tools(server, get_engine: Callable) -> None:
         Multi-scope: ``scope`` sets visibility (personal/shared/global).
         ``shared_with`` is a comma-separated list of profile_ids for
         shared scope.
+
+        ``session_date`` says WHEN the memory is about, as opposed to when it
+        was written. Omit it and the memory is dated today, which is what every
+        memory got before 4.0.10 because there was no way to say otherwise.
+        Accepts YYYY-MM-DD or a full ISO 8601 timestamp.
         """
         # v3.6.10: resolve "mcp_client" sentinel → URL path (HTTP) or env var (stdio)
         if agent_id == "mcp_client":
             from superlocalmemory.mcp.agent_context import get_current_agent_id
             agent_id = get_current_agent_id()
+        # Bind the write to a session the same way the read path does.
+        #
+        # recall has resolved this through a four-step ladder since S9-DASH-10;
+        # remember stored whatever it was handed, which for a caller that does
+        # not pass one is nothing. Result on the author's store: 192 of 3,894
+        # facts carry a session_id (4.9%). The engine's session-diversity
+        # promotion cannot promote a fact with no session, so it was running
+        # against a corpus where 95% of rows looked like the same session.
+        #
+        # allow_agent_fallback is OFF here, unlike recall. `mcp:<agent_id>` is a
+        # useful key for settling one outcome; as a stored session_id it would
+        # file every memory an agent ever wrote under one session, and diversity
+        # promotion would then treat a whole history as a single conversation —
+        # worse than the empty string it replaces.
+        from superlocalmemory.mcp.session_binding import resolve_session_id
+
+        session_id = resolve_session_id(
+            session_id, agent_id=agent_id, allow_agent_fallback=False,
+        )
         meta = {
             "project": project,
             "importance": importance,
@@ -141,6 +166,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
                         "content": content, "tags": tags, "metadata": meta,
                         "scope": scope, "shared_with": _shared_list,
                         "session_id": session_id,
+                        "session_date": session_date,
                         "idempotency_key": effective_idempotency_key or None,
                     })
                     if resp and (resp.get("fact_ids") is not None or resp.get("ok")):
@@ -320,45 +346,20 @@ def register_core_tools(server, get_engine: Callable) -> None:
         import asyncio
         try:
             from superlocalmemory.mcp._daemon_proxy import choose_pool
-            # S9-DASH-10: priority for session_id, so engagement
-            # signals land on the right pending_outcome:
-            #   1. Explicit ``session_id`` tool-call argument.
-            #   2. ``SLM_SESSION_ID`` / ``CLAUDE_SESSION_ID`` env var.
-            #   3. Most-recent-active Claude session from the hook
-            #      registry (last 60s). This catches the common case
-            #      where Claude Code's hooks ran the UserPromptSubmit
-            #      hook right before invoking the MCP tool.
-            #   4. Stable per-agent fallback ``mcp:<agent_id>`` — the
-            #      Stop hook will NOT match this, so the reaper
-            #      settles it at neutral 0.5.
-            effective_sid = session_id
-            if not effective_sid:
-                import os as _os
-                effective_sid = (
-                    _os.environ.get("SLM_SESSION_ID")
-                    or _os.environ.get("CLAUDE_SESSION_ID")
-                    or ""
-                )
-            if not effective_sid:
-                try:
-                    from superlocalmemory.hooks.session_registry import (
-                        lookup_by_parent,
-                        most_recent_active,
-                    )
-                    # Parent-PID lookup is collision-free across multiple
-                    # parallel Claude sessions (each MCP server's parent
-                    # is the IDE that spawned it).
-                    effective_sid = (
-                        lookup_by_parent(within_seconds=60)
-                        or most_recent_active(
-                            agent_type="claude", within_seconds=60,
-                        )
-                        or ""
-                    )
-                except Exception:
-                    pass
-            if not effective_sid:
-                effective_sid = f"mcp:{agent_id}"
+            from superlocalmemory.mcp.session_binding import resolve_session_id
+
+            # S9-DASH-10's four-step ladder, now shared with remember() so the
+            # read path and the write path cannot disagree about which session
+            # they are in. remember() had no ladder at all, which is why 95% of
+            # stored facts carry no session_id. See mcp/session_binding.py.
+            #
+            # The per-agent fallback stays ON here: this id settles a pending
+            # outcome, and `mcp:<agent_id>` is deliberately not matched by the
+            # Stop hook, so the reaper settles it at a neutral 0.5 rather than
+            # attributing engagement to a session that never existed.
+            effective_sid = resolve_session_id(
+                session_id, agent_id=agent_id, allow_agent_fallback=True,
+            )
             # Resolve the daemon proxy inside the worker too. ``choose_pool``
             # verifies daemon ownership through a synchronous /health request;
             # when this tool is served by the daemon's mounted HTTP MCP app,

package/src/superlocalmemory/mcp/tools_ops.py

@@ -2,7 +2,7 @@
 # Licensed under AGPL-3.0-or-later - see LICENSE file
 # Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
 
-"""Wave-3 Operational Recovery & Admin Remediation MCP tools (2 tools).
+"""Operational Recovery & Admin Remediation MCP tools (2 tools).
 
 list_failed_operations — Surface dead-letter, degraded, and exhausted ops.
 resolve_operation      — Admin retry/force-reconcile/cancel for stuck ops.
@@ -28,7 +28,7 @@ _VALID_ACTIONS = frozenset({"retry", "force_reconcile", "cancel"})
 
 
 def register_ops_tools(server, get_engine: Callable) -> None:
-    """Register Wave-3 operational-recovery MCP tools on *server*."""
+    """Register operational-recovery MCP tools on *server*."""
 
     # ------------------------------------------------------------------
     # 1. list_failed_operations — surface all stuck/failed/degraded ops

package/src/superlocalmemory/retrieval/bm25_channel.py

@@ -221,14 +221,10 @@ class BM25Channel:
             include_shared=include_shared,
             prefix="af",
         )
-        # Archived facts are not live; never surface them in keyword recall.
-        # Guarded on column presence: the archive column is added by a deferred
-        # migration and may be absent on an unmigrated database.
-        archive_clause = (
-            " AND COALESCE(af.archive_status, 'live') != 'archived'"
-            if self._db._has_archive_status()
-            else ""
-        )
+        # Soft-deleted and withheld rows are not live. Filtered HERE rather
+        # than only at hydration so neither spends one of this channel's top_k
+        # slots; the shared clause keeps the definition in one place.
+        archive_clause = self._db.visible_fact_clause("af")
         sql = (
             "SELECT af.fact_id AS fact_id, bm25(atomic_facts_fts) AS rank "
             "FROM atomic_facts_fts "

package/src/superlocalmemory/retrieval/entity_channel.py

@@ -398,9 +398,15 @@ class EntityGraphChannel:
                 include_global=include_global,
                 include_shared=include_shared,
             )
+            # Withheld rows must not enter the entity map at all. They carry
+            # their whole cluster's pooled entity list, which is exactly why
+            # they out-ranked real memories here in the first place — leaving
+            # them in the map would keep spending this channel's budget on
+            # candidates that hydration then discards.
             rows = self._db.execute(
                 "SELECT fact_id, canonical_entities_json "
-                f"FROM atomic_facts WHERE {where} "
+                f"FROM atomic_facts WHERE {where}"
+                f"{self._db.visible_fact_clause()} "
                 "ORDER BY created_at DESC LIMIT ?",
                 (*params, _unbounded_facts_ceiling()),
             )

package/src/superlocalmemory/retrieval/scope_policy.py

@@ -53,9 +53,30 @@ def authorized_fact_ids(
             include_shared=include_shared,
         )
         placeholders = ",".join("?" for _ in unique_ids)
+        # Mirror the primary path's visibility rule, not just its scope rule.
+        # This branch exists for lightweight wrappers that expose execute() but
+        # not get_facts_by_ids, and it was authorizing withheld and
+        # soft-deleted rows that the primary path refuses -- so any channel
+        # whose db object took this branch had a different idea of what is
+        # visible than the engine that hydrates its results.
+        # Resolved on the TYPE, not the instance. A MagicMock fabricates any
+        # attribute you ask for, so an instance check returns a callable that
+        # returns another MagicMock, whose repr then lands in the SQL string and
+        # makes the whole query a syntax error -- and this function's `except`
+        # turns that into an empty authorized set, i.e. every candidate silently
+        # dropped. tests/test_retrieval/test_spreading_activation.py caught it
+        # by passing exactly such a mock. The same reasoning is already written
+        # up in retrieval/engine.py for the reranker's optional contract.
+        visible = ""
+        clause_fn = getattr(type(db), "visible_fact_clause", None)
+        if callable(clause_fn):
+            try:
+                visible = clause_fn(db)
+            except Exception:  # noqa: BLE001 -- fall back to scope-only
+                visible = ""
         rows = db.execute(
             f"SELECT fact_id FROM atomic_facts WHERE fact_id IN ({placeholders}) "
-            f"AND {where}",
+            f"AND {where}{visible}",
             (*unique_ids, *params),
         )
         if not isinstance(rows, list):

package/src/superlocalmemory/retrieval/temporal_channel.py

@@ -231,6 +231,14 @@ class TemporalChannel:
         )
 
         for name in names[:3]:  # Limit to first 3 entity mentions
+            # An empty name would match the placeholder entity that dated
+            # facts with no resolved entity attach their temporal events to
+            # (core/store_pipeline.py::_ensure_unresolved_entity, whose
+            # canonical_name is ''). Entity extraction does not produce an
+            # empty name, so this guard costs nothing and removes the one way
+            # the placeholder could ever surface as a real entity match.
+            if not name or not name.strip():
+                continue
             # Resolve the entity and event in one scope-filtered query. Looking
             # up the entity only in the requester's profile made global events
             # owned by another profile undiscoverable before authorization was
@@ -370,10 +378,14 @@ class TemporalChannel:
             include_shared=include_shared,
             prefix="af",
         )
+        # The recency fallback is where these rows won before: they have no
+        # temporal_events at all, so they reached the top through created_at
+        # alone. Fifty slots, and 1,195 withheld rows all written recently.
         rows = self._db.execute(
             "SELECT af.fact_id, af.created_at "
             "FROM atomic_facts AS af "
-            f"WHERE {where} "
+            f"WHERE {where}"
+            f"{self._db.visible_fact_clause('af')} "
             "  AND af.created_at >= datetime('now', '-90 days') "
             "ORDER BY af.created_at DESC, af.fact_id ASC "
             "LIMIT 50",

package/src/superlocalmemory/retrieval/vector_store.py

@@ -416,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],
@@ -439,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 "
@@ -446,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)
@@ -460,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,)

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