superlocalmemory 4.0.8 → 4.0.10

package/src/superlocalmemory/integrations/bounded_loops_mcp.py

@@ -96,6 +96,29 @@ async def observe_terminal_runs(
     return observed
 
 
+def _assert_trusted_executable(executable: Path) -> None:
+    """Raise BridgeUnavailable if executable does not pass the bridge trust checks."""
+    try:
+        st = executable.stat()
+    except OSError as exc:
+        raise BridgeUnavailable("bounded-loops bridge path is unavailable") from exc
+    mode = st.st_mode
+    if not stat.S_ISREG(mode) or (
+        os.name != "nt" and mode & (stat.S_IWGRP | stat.S_IWOTH)
+    ):
+        raise BridgeUnavailable("bounded-loops executable is not a trusted regular file")
+    # Windows trust-check limitation: only S_ISREG applies on Windows.
+    # The mode-bit check above (group/other writable) and the uid/owner check
+    # below are both skipped because:
+    #   - Python's os.stat() on Windows returns emulated Unix-style mode bits
+    #     that do not reflect real ACL permissions; the check would be meaningless.
+    #   - os.geteuid() does not exist on Windows (AttributeError); st_uid is
+    #     always 0 there, so the ownership check cannot identify non-root owners.
+    # Proper Windows ownership verification requires Win32 ACL APIs (advapi32),
+    # which would introduce a heavy optional dependency.  Scoped for a future release.
+    if os.name != "nt" and st.st_uid not in {0, os.geteuid()}:
+        raise BridgeUnavailable("bounded-loops executable owner is not trusted")
+
 async def observe_from_stdio(*, command: str, cwd: str, profile_id: str) -> list[dict[str, Any]]:
     """Run one bounded, explicit MCP 2 observation; never call from recall or remember."""
     executable, workspace = Path(command), Path(cwd)
@@ -112,15 +135,9 @@ async def observe_from_stdio(*, command: str, cwd: str, profile_id: str) -> list
     try:
         executable = executable.resolve(strict=True)
         workspace = workspace.resolve(strict=True)
-        mode = executable.stat().st_mode
     except OSError as exc:
         raise BridgeUnavailable("bounded-loops bridge path is unavailable") from exc
-    if not stat.S_ISREG(mode) or (
-        os.name != "nt" and mode & (stat.S_IWGRP | stat.S_IWOTH)
-    ):
-        raise BridgeUnavailable("bounded-loops executable is not a trusted regular file")
-    if executable.stat().st_uid not in {0, os.geteuid()}:
-        raise BridgeUnavailable("bounded-loops executable owner is not trusted")
+    _assert_trusted_executable(executable)
 
     from mcp import ClientSession, StdioServerParameters
     from mcp.client.stdio import stdio_client

package/src/superlocalmemory/learning/arm_catalog.py

@@ -4,8 +4,6 @@
 
 """Static 40-arm catalog for the contextual Thompson bandit.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 5.1 — arm = (semantic, bm25, entity_graph, temporal,
 cross_encoder_bias) weight bundle drawn from a 7-point canonical grid.
 
 Pure-data module — zero imports from the rest of the codebase. Audit-friendly

package/src/superlocalmemory/learning/bandit.py

@@ -4,8 +4,6 @@
 
 """Contextual Thompson-sampling bandit over discrete channel-weight arms.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Sections 3 (algorithm), 5.3 (file spec), 8 (hard rules).
 
 Schema: ``bandit_arms`` + ``bandit_plays`` live in ``learning.db``, created by
 LLD-07 M005. This module NEVER defines DDL — it only READs / WRITEs.

package/src/superlocalmemory/learning/bandit_cache.py

@@ -4,8 +4,6 @@
 
 """Per-(profile, stratum) posterior LRU cache for the contextual bandit.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 5.2.
 
 Key design:
   - Loader runs OUTSIDE the lock so DB reads never serialise across strata.

package/src/superlocalmemory/learning/dedup_hnsw.py

@@ -28,6 +28,7 @@ from pathlib import Path
 from typing import Any, Iterable, Sequence
 
 from superlocalmemory.core.ram_lock import ram_reservation
+from superlocalmemory.storage.embedding_codec import decode_embedding
 
 logger = logging.getLogger(__name__)
 
@@ -71,19 +72,18 @@ __all__ = (
 )
 
 
-def _parse_embedding(raw: str | None) -> list[float] | None:
+def _parse_embedding(raw: bytes | str | None) -> list[float] | None:
+    """Parse an embedding from either TEXT (JSON) or BLOB (binary float32).
+
+    Returns None only when the embedding is genuinely absent (None or empty).
+    Raises ValueError for malformed data so callers can distinguish absence
+    from corruption.
+    """
     if not raw:
         return None
-    try:
-        vec = json.loads(raw)
-    except (TypeError, ValueError):
-        return None
-    if not isinstance(vec, list) or not vec:
-        return None
-    try:
-        return [float(x) for x in vec]
-    except (TypeError, ValueError):
-        return None
+    # decode_embedding raises ValueError for corrupt data; callers that want
+    # to skip a bad fact should catch ValueError explicitly, not silently.
+    return decode_embedding(raw)
 
 
 # L-P-01: vectorise ``_cosine`` via NumPy when available. NumPy cold

package/src/superlocalmemory/learning/ensemble.py

@@ -4,8 +4,6 @@
 
 """Bandit / LightGBM ensemble blender.
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 5.4.
 
 D8 blend policy (``choose_ensemble``):
   - 0..199 signals OR model is None → ``EnsembleWeights(1.0, 0.0)`` (bandit-only).

package/src/superlocalmemory/learning/labeler.py

@@ -4,8 +4,6 @@
 
 """Integer-label mapping for LightGBM ``lambdarank`` training.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Section 4.7 — single source of truth for outcome-reward / position → int label.
 
 Rules:
     - Labels are integers in ``[0, 4]`` (5 relevance tiers).

package/src/superlocalmemory/learning/legacy_migration.py

@@ -4,8 +4,6 @@
 
 """Legacy ``learning_feedback`` row migration — data movement only.
 
-LLD reference: ``.backup/active-brain/lld/LLD-07-schema-migrations-and-security-primitives.md``
-Section 5 (Legacy learning_feedback Migration).
 
 Hard rule H15 (LLD-06 §10): this module MUST NOT contain any schema
 DDL. All schema definitions live in

package/src/superlocalmemory/learning/model_cache.py

@@ -4,8 +4,6 @@
 
 """Active-model cache + integrity verification.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Section 4.4 — every model load goes through here.
 
 Hard rules enforced:
     M1 — ``pickle.loads`` is FORBIDDEN on ``state_bytes``.

package/src/superlocalmemory/learning/ranker.py

@@ -4,8 +4,6 @@
 
 """3-phase adaptive ranker — from heuristic to ML.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Sections 4.4 + 4.5.
 
 Phase 1: cross-encoder score only (cold start)
 Phase 2: heuristic boosts (some data)

package/src/superlocalmemory/learning/reward_archive.py

@@ -34,6 +34,7 @@ from pathlib import Path
 from superlocalmemory.learning.fact_outcome_joins import (
     has_recent_positive_reward,
 )
+from superlocalmemory.storage.embedding_codec import decode_embedding
 from superlocalmemory.storage.write_lock import get_write_lock
 
 logger = logging.getLogger(__name__)
@@ -113,13 +114,17 @@ def run_reward_gated_archive(
                 window_days=REWARD_WINDOW_DAYS,
             ):
                 continue
+            # Decode the embedding to list[float] so json.dumps(payload)
+            # succeeds regardless of whether the row is TEXT or BLOB.
+            # ValueError (corrupt buffer) propagates — a silent None here
+            # would archive a fact with a missing embedding, which loses data.
             to_archive.append({
                 "fid": fid,
                 "content": row["content"],
                 "canonical_entities_json": row["canonical_entities_json"],
                 "importance": row["importance"],
                 "confidence": row["confidence"],
-                "embedding": row["embedding"],
+                "embedding": decode_embedding(row["embedding"], fact_id=fid),
                 "created_at": row["created_at"],
             })
     finally:

package/src/superlocalmemory/learning/reward_proxy.py

@@ -4,8 +4,6 @@
 
 """Proxy settlement for bandit plays (v3.4.22 only).
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 3.5 and 5.6.
 
 Replaced in v3.4.22 by ``reward_from_outcomes.py`` — DO NOT extend this
 module beyond the proxy window contract.

package/src/superlocalmemory/learning/signal_worker.py

@@ -4,8 +4,6 @@
 
 """Background signal drain worker.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Section 4.2 — moves signal writes off the recall hot path.
 
 Contract (hard rules, enforced by tests):
     SW1 — Hot path never waits for disk.

package/src/superlocalmemory/math/fisher.py

@@ -19,7 +19,7 @@ Geodesic distance (Atkinson & Mitchell 1981, Pinele et al. 2020):
     Diagonal multivariate (product-manifold decomposition):
         d_FR(p, q) = sqrt( sum_i  d_i^2 )
 
-Bayesian variance update (NEW in Innovation Wave 4):
+Bayesian variance update (added in v3.5):
 
     V1 bug: query always received UNIFORM variance, so Fisher degenerated
     to a monotonic transform of cosine.  FIX: every fact maintains its own

package/src/superlocalmemory/math/hopfield.py

@@ -56,7 +56,10 @@ class HopfieldConfig:
     max_iterations: int = 1
     convergence_epsilon: float = 1e-6
     prefilter_threshold: int = 10_000
-    prefilter_candidates: int = 1000
+    # MUST match HopfieldConfig.prefilter_candidates in core/config.py, where the
+    # reasoning for the value is written. This stage decides final membership, so
+    # this number is a hard limit on which memories can be returned at all.
+    prefilter_candidates: int = 500
     skip_threshold: int = 100_000
     cache_ttl_seconds: float = 60.0
 

package/src/superlocalmemory/math/langevin.py

@@ -26,7 +26,7 @@ Potential function:
     - Old / unused:       gamma term raises potential -> drift to boundary
     - Important memories: delta term lowers potential -> retain near origin
 
-V1 bugs fixed in Innovation Wave 4:
+V1 bugs fixed in v3.5:
     1. Positions were computed per-recall then DISCARDED.  Now ``step()``
        and ``batch_step()`` return new positions for the caller to persist.
     2. Weight range was [0.7, 1.0] --- too narrow to change rankings.

package/src/superlocalmemory/math/sheaf.py

@@ -24,6 +24,8 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
+from superlocalmemory.storage.embedding_codec import decode_embedding
+
 if TYPE_CHECKING:
     from superlocalmemory.storage.database import DatabaseManager
     from superlocalmemory.storage.models import AtomicFact
@@ -251,7 +253,9 @@ class SheafConsistencyChecker:
         if raw is None or raw == "":
             return None
         try:
-            data = json.loads(raw) if isinstance(raw, str) else raw
-            return np.asarray(data, dtype=np.float64)
-        except (json.JSONDecodeError, TypeError, ValueError):
+            data = decode_embedding(raw, fact_id=str(fact_id))
+        except ValueError:
+            return None
+        if data is None:
             return None
+        return np.asarray(data, dtype=np.float64)

package/src/superlocalmemory/mcp/cli_fallback.py

@@ -1,6 +1,6 @@
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Licensed under AGPL-3.0-or-later - see LICENSE file
-# WP-09: MCP→CLI fallback adapter (ships INERT — DQ-2=B)
+# MCP→CLI fallback adapter (ships inert — disabled by default, no active use yet)
 
 """MCP→CLI fallback adapter for SuperLocalMemory.
 

package/src/superlocalmemory/mcp/profiles.py

@@ -14,7 +14,7 @@ Do NOT import FastMCP, MemoryEngine, or any heavy dependency here.
 from __future__ import annotations
 
 # ---------------------------------------------------------------------------
-# v3.6.14 WP-01: Named profile definitions
+# Named profile definitions (introduced in v3.6.14)
 # ---------------------------------------------------------------------------
 
 _PROFILE_CORE: frozenset[str] = frozenset({  # 17

package/src/superlocalmemory/mcp/server.py

@@ -159,7 +159,7 @@ _all_tools = _os_reg.environ.get("SLM_MCP_ALL_TOOLS") == "1"
 _user_allowlist_str = _os_reg.environ.get("SLM_MCP_TOOLS", "").strip()
 
 # ---------------------------------------------------------------------------
-# v3.6.14 WP-01: Named profile definitions
+# Named profile definitions (introduced in v3.6.14)
 # Extracted to mcp/profiles.py (v3.8.0) — pure data, no side effects.
 # All names re-exported here for backward compatibility with existing tests
 # and any code that imports them from this module.
@@ -282,7 +282,7 @@ register_optimize_tools(_target)  # v3.6.11: Surface B Optimize tools (proxy-fre
 from superlocalmemory.mcp.tools_loops import register_loop_tools
 register_loop_tools(_target, get_engine)  # v3.8.0: bounded-loop tools (CLI+command+MCP)
 from superlocalmemory.mcp.tools_ops import register_ops_tools
-register_ops_tools(_target, get_engine)  # Wave-3: operational recovery & admin remediation
+register_ops_tools(_target, get_engine)  # operational recovery & admin remediation
 from superlocalmemory.mcp.tools_brain import register_brain_tools
 register_brain_tools(_target, get_engine)  # v4.0.2 portable Brain receipts
 from superlocalmemory.mcp.tools_summaries import register_summary_tools

package/src/superlocalmemory/mcp/session_binding.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Work out which session a tool call belongs to, the same way every time.
+
+``recall`` has resolved this through a four-step ladder since S9-DASH-10 — the
+explicit argument, then the environment, then the hook registry, then a stable
+per-agent fallback — so an engagement signal lands on the right pending outcome.
+``remember`` never had it. It took ``session_id: str = ""`` and stored whatever
+it was handed, which for a caller that does not pass one is nothing.
+
+Measured on the author's store: **192 of 3,894 genuine facts carry a session_id
+(4.9%)**, and 4 of the 200 most recent (2%). Every one of the rest was written
+through a path that could have known and did not.
+
+That is not bookkeeping. ``RetrievalEngine`` promotes results so the top of an
+answer spans more than one session (its ``sessions_in_top`` pass), and a fact
+with no session_id can never be promoted by it — so the diversity mechanism was
+running against a corpus where 95% of rows were indistinguishable. It also means
+"what did we discuss in that session" has almost nothing to match on.
+
+One implementation, called by both tools, so the read path and the write path
+cannot disagree about which session they are in.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["resolve_session_id", "SESSION_ENV_VARS"]
+
+#: Checked in order. Hosts set one or the other; SLM's own takes precedence so a
+#: user can override a host that sets its variable to something unhelpful.
+SESSION_ENV_VARS = ("SLM_SESSION_ID", "CLAUDE_SESSION_ID")
+
+
+def resolve_session_id(
+    explicit: str = "",
+    *,
+    agent_id: str = "unknown",
+    allow_agent_fallback: bool = True,
+) -> str:
+    """Best available session id for this call. Never raises.
+
+    Order, most to least specific:
+
+      1. ``explicit`` — what the caller passed. Always wins.
+      2. ``SLM_SESSION_ID`` / ``CLAUDE_SESSION_ID`` from the environment.
+      3. The hook registry: the session whose parent process is ours, else the
+         most recently active one inside 60 seconds. Parent-PID lookup is
+         collision-free across parallel host sessions, because each MCP
+         server's parent is the editor that spawned it.
+      4. ``mcp:<agent_id>`` — stable per agent, and deliberately NOT matched by
+         the Stop hook, so the reaper settles those outcomes at a neutral 0.5
+         rather than crediting or blaming a session that never existed.
+
+    ``allow_agent_fallback=False`` stops before step 4 and returns "". Use it
+    where a synthetic id would be worse than none: grouping memories under
+    ``mcp:<agent>`` would put every memory an agent ever wrote into one bucket
+    and make session-diversity promotion rank them as a single session, which
+    is the opposite of what it is for.
+    """
+    if explicit and explicit.strip():
+        return explicit.strip()
+
+    for name in SESSION_ENV_VARS:
+        value = os.environ.get(name)
+        if value and value.strip():
+            return value.strip()
+
+    try:
+        from superlocalmemory.hooks.session_registry import (
+            lookup_by_parent,
+            most_recent_active,
+        )
+
+        found = (
+            lookup_by_parent(within_seconds=60)
+            or most_recent_active(agent_type="claude", within_seconds=60)
+            or ""
+        )
+        if found:
+            return found
+    except Exception as exc:  # noqa: BLE001 — a hint must never fail a call
+        logger.debug("session registry lookup unavailable: %s", exc)
+
+    if allow_agent_fallback:
+        return f"mcp:{agent_id}"
+    return ""

package/src/superlocalmemory/mcp/tools_active.py

@@ -255,6 +255,56 @@ def _canonical_feedback_count(profile_id: str) -> int | None:
         return None
 
 
+# How far ahead a session looks for scheduled facts, and how many it shows.
+# A session preamble is not a calendar: a long horizon or a large cap turns a
+# useful heads-up into a wall of text nobody reads.
+_SCHEDULED_HORIZON_DAYS = 14
+_SCHEDULED_LIMIT = 5
+
+
+def _upcoming_scheduled_facts(engine, now: datetime.datetime) -> list[dict]:
+    """Facts scheduled from today through the horizon, soonest first.
+
+    Bounded and index-backed, because this runs on every session start. Returns
+    an empty list on any failure: a session must still open when this query
+    cannot answer, so the caller omits the surface entirely rather than showing
+    an empty section that reads like a defect.
+
+    Selects on the stored type of the fact, which is a classification recorded at
+    write time. It is unrelated to the similarly named retrieval channel despite
+    sharing the word.
+    """
+    try:
+        db = getattr(engine, "_db", None) or getattr(engine, "db", None)
+        if db is None or not hasattr(db, "execute"):
+            return []
+        # Both 'YYYY-MM-DD' and full timestamps compare correctly as text,
+        # because ISO-8601 orders lexicographically. The upper bound is
+        # exclusive, so the horizon day itself is included.
+        start = now.date().isoformat()
+        end = (now + datetime.timedelta(days=_SCHEDULED_HORIZON_DAYS + 1)).date().isoformat()
+        rows = db.execute(
+            "SELECT fact_id, content, referenced_date"
+            " FROM atomic_facts"
+            " WHERE profile_id = ?"
+            "   AND fact_type = 'temporal'"
+            "   AND referenced_date IS NOT NULL"
+            "   AND referenced_date >= ?"
+            "   AND referenced_date < ?"
+            " ORDER BY referenced_date ASC"
+            f" LIMIT {_SCHEDULED_LIMIT}",
+            (engine.profile_id, start, end),
+        )
+        return [
+            {"fact_id": r["fact_id"], "content": r["content"],
+             "scheduled_at": r["referenced_date"]}
+            for r in rows
+        ]
+    except Exception as exc:
+        logger.warning("scheduled-fact surface failed: %s", exc)
+        return []
+
+
 def register_active_tools(server, get_engine: Callable) -> None:
     """Register 3 active memory tools on *server*."""
 
@@ -519,6 +569,8 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 f"-{uuid.uuid4().hex[:8]}"
             )
 
+            _upcoming_events = _upcoming_scheduled_facts(engine, _now)
+
             return {
                 "success": True,
                 "session_id": session_id,
@@ -553,6 +605,10 @@ def register_active_tools(server, get_engine: Callable) -> None:
                         else "trained"
                     ),
                 },
+                # Scheduled-event surface: present only when facts exist in the
+                # 14-day window. Absent means the window is empty, not an error.
+                **( {"upcoming_events": _upcoming_events}
+                    if _upcoming_events else {} ),
             }
         except Exception as exc:
             logger.exception("session_init failed")

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,
@@ -560,7 +561,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             if db_path.exists():
                 db_size_mb = round(os.path.getsize(db_path) / (1024 * 1024), 2)
 
-            # WP-02 D8: additive canonical key set — provider/base_dir/db_path added.
+            # additive canonical key set — provider/base_dir/db_path added.
             # All pre-existing keys are preserved (zero removals).
             cfg = engine._config
             return {

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/optimize/cache/manager.py

@@ -223,7 +223,7 @@ class CacheManager:
             tenant_id = _hashlib.sha256(tenant_id.encode()).hexdigest()
 
         if isinstance(req, ProxyRequest) and req.provider == "vertex":
-            # CRIT-2 (WP-11, LOCKED): Vertex bodies have NO model/messages/system.
+            # LOCKED: Vertex bodies have NO model/messages/system.
             # Model is in the PATH; prompts are under 'contents'; system under
             # 'systemInstruction'. Without this branch ALL Vertex requests hash to
             # ONE key → first response poisons every subsequent prompt.
@@ -701,7 +701,7 @@ def json_dumps_bytes(d: dict) -> bytes:
 
 
 # ---------------------------------------------------------------------------
-# Vertex helpers (WP-11 / CRIT-2)
+# Vertex helpers
 # ---------------------------------------------------------------------------
 
 def _vertex_project_location_from_path(path: str) -> tuple[str, str]:

package/src/superlocalmemory/optimize/compress/ccr.py

@@ -99,7 +99,7 @@ class CCRStore:
     def delete(self, ccr_id: str, *, tenant_id: str = "default") -> None:
         """Delete a CCR row by ccr_id scoped to tenant. Idempotent — never raises.
 
-        WP-10 D6: defensive infra. Deleting a non-existent ccr_id is a no-op.
+        Defensive delete — idempotent: deleting a non-existent ccr_id is a no-op.
         H-02: tenant_id guard prevents cross-tenant deletion.
         """
         try: