superlocalmemory 4.0.9 → 4.1.0

package/src/superlocalmemory/learning/reward_from_outcomes.py

@@ -0,0 +1,365 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Settle a bandit play from an authenticated outcome.
+
+WHY THIS FILE EXISTS
+--------------------
+``reward_proxy.py`` has said since v3.4.22:
+
+    Replaced in v3.4.22 by ``reward_from_outcomes.py`` — DO NOT extend this
+    module beyond the proxy window contract.
+
+That file was never written. So the replacement never arrived, and the module
+that tells you not to extend it remained the only settlement path — one that
+cannot work. Measured, not inferred:
+
+* ``reward_proxy._tool_event_hit`` selects ``payload_json`` from ``tool_events``
+  ``WHERE occurred_at BETWEEN ? AND ?``. **Neither column exists** on that
+  table, on this install or in any DDL in the codebase. The query raises
+  ``no such column: payload_json``, a bare ``except sqlite3.Error`` returns
+  False, and the "cited" branch of the ladder is therefore unreachable.
+* Even with the names corrected there would be nothing to find: **0 of 2,002**
+  ``tool_events`` rows on a live store contain a 16-hex token, let alone a
+  real ``fact_id``. That table records tool names and summaries, not the
+  memories a recall returned.
+
+So every settlement fell through to the 120-second default of 0.5, which is
+visible in the arms as an exact tie::
+
+    SUM(alpha) = SUM(beta) = 867.5 = 165 priors + 1,405 plays x 0.5
+
+WHAT THIS USES INSTEAD
+----------------------
+``action_outcomes`` (memory.db, M006) — the table an *explicit* outcome report
+already writes, with a reward the reporter chose:
+``success=1.0 / failure=0.0 / partial=0.5``. That is an authenticated signal
+about whether the memories helped, which is exactly what a play needs and what
+an exposure is not.
+
+It carries ``recall_query_id``, a join key straight to ``bandit_plays.query_id``.
+**0 of 162 rows populate it** — the column was added and never written. This
+module reads it when present, and otherwise falls back to overlap between the
+outcome's ``fact_ids_json`` and the ``shown_fact_ids`` the play recorded (M044).
+
+The fallback is the load-bearing path, not a nicety: recall does not return its
+``query_id`` to the caller (``server/recall_serializer.py`` has no such field),
+so no existing client *can* supply one. Overlap on the memories actually shown,
+inside a time window, is the strongest link available without changing every
+caller first.
+
+THE GRACE WINDOW, AND WHY IT IS NOT 120 SECONDS
+-----------------------------------------------
+``reward_proxy`` defaults a play to 0.5 once it is 120 seconds old. A human or
+an agent deciding whether a memory helped does not do so within two minutes, so
+that deadline would claim every play before any real outcome arrived — the
+default would win a race it should not be in.
+
+A play that recorded ``shown_fact_ids`` therefore waits ``_GRACE_SEC`` (default
+900) before it may be defaulted. A play with no recorded facts keeps the old
+120-second behaviour, because nothing can ever settle it from evidence and
+holding it open buys nothing.
+
+NOTHING HERE FABRICATES A REWARD. If no outcome is reported, the play settles
+neutral and is *labelled* ``default`` so it stays distinguishable from a
+genuinely neutral outcome. Those two were indistinguishable before, which is why
+this went unnoticed for months.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sqlite3
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from superlocalmemory.learning.bandit import ContextualBandit
+from superlocalmemory.learning.pcos import update_scores
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["settle_from_outcomes", "GRACE_SEC", "SETTLEMENT_KIND"]
+
+#: How long a play that recorded its shown memories waits for a reported
+#: outcome before it may be defaulted. Deliberately far longer than the proxy's
+#: 120 s: see the module docstring.
+GRACE_SEC: float = float(os.environ.get("SLM_OUTCOME_GRACE_SEC", "900"))
+
+#: How far after a play an outcome may arrive and still be attributed to it.
+#: Same order as the grace window — an outcome reported later than this is about
+#: something else.
+_MATCH_WINDOW_SEC: float = GRACE_SEC
+
+#: Written to ``bandit_plays.settlement_type``. A settlement that came from a
+#: real report must never be mistaken for the neutral default.
+SETTLEMENT_KIND = "outcome_reported"
+
+_MAX_PLAYS_PER_PASS = 500
+
+
+def _parse_iso(ts: str | None) -> datetime | None:
+    if not ts:
+        return None
+    raw = str(ts).replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(raw)
+    except ValueError:
+        return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def _open(path: Path) -> sqlite3.Connection | None:
+    try:
+        conn = sqlite3.connect(str(path), timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        return conn
+    except sqlite3.Error as exc:
+        logger.debug("reward_from_outcomes: open %s failed: %s", path, exc)
+        return None
+
+
+def _shown(raw: object) -> set[str]:
+    """``shown_fact_ids`` JSON -> set. Empty on anything unexpected."""
+    if not raw:
+        return set()
+    try:
+        parsed = json.loads(str(raw))
+    except (TypeError, ValueError):
+        return set()
+    if not isinstance(parsed, list):
+        return set()
+    return {str(f) for f in parsed if f}
+
+
+def _unsettled_plays(
+    conn: sqlite3.Connection, profile_id: str,
+) -> list[sqlite3.Row]:
+    """Unsettled plays, oldest first. Degrades if M044 has not run."""
+    for columns in (
+        "play_id, query_id, played_at, shown_fact_ids",
+        "play_id, query_id, played_at, NULL AS shown_fact_ids",
+    ):
+        try:
+            return conn.execute(
+                f"SELECT {columns} FROM bandit_plays "
+                "WHERE profile_id = ? AND settled_at IS NULL "
+                "ORDER BY played_at ASC LIMIT ?",
+                (str(profile_id), _MAX_PLAYS_PER_PASS),
+            ).fetchall()
+        except sqlite3.Error as exc:
+            logger.debug("reward_from_outcomes: play fetch (%s): %s", columns, exc)
+    return []
+
+
+def _candidate_outcomes(
+    conn: sqlite3.Connection, profile_id: str, since: datetime,
+) -> list[dict]:
+    """Reported outcomes from ``since`` onward, newest first.
+
+    Read once per pass rather than once per play: the window holds a handful of
+    rows in practice, and a per-play query would scan this table N times on the
+    settlement thread.
+    """
+    try:
+        rows = conn.execute(
+            "SELECT outcome_id, fact_ids_json, outcome, reward, timestamp, "
+            "       recall_query_id "
+            "FROM action_outcomes "
+            "WHERE profile_id = ? AND timestamp >= ? "
+            "ORDER BY timestamp DESC LIMIT 2000",
+            (str(profile_id), since.isoformat()),
+        ).fetchall()
+    except sqlite3.Error as exc:
+        logger.debug("reward_from_outcomes: outcome fetch: %s", exc)
+        return []
+
+    out: list[dict] = []
+    for r in rows:
+        at = _parse_iso(r["timestamp"])
+        if at is None:
+            continue
+        try:
+            facts = json.loads(r["fact_ids_json"] or "[]")
+        except (TypeError, ValueError):
+            facts = []
+        if not isinstance(facts, list):
+            facts = []
+        try:
+            reward = float(r["reward"])
+        except (TypeError, ValueError):
+            continue
+        out.append({
+            "id": str(r["outcome_id"]),
+            "at": at,
+            "facts": {str(f) for f in facts if f},
+            "reward": max(0.0, min(1.0, reward)),
+            "query_id": str(r["recall_query_id"] or ""),
+        })
+    return out
+
+
+def _match(
+    play_at: datetime,
+    query_id: str,
+    shown: set[str],
+    outcomes: list[dict],
+    claimed: set[str],
+) -> dict | None:
+    """The one outcome attributable to this play, or None.
+
+    Returns the outcome itself rather than its reward, because the caller needs
+    to know WHICH memories that outcome named — see ``settle_from_outcomes``.
+
+    AN OUTCOME IS EVIDENCE ABOUT ONE RECALL, AND IS CONSUMED
+    -------------------------------------------------------
+    The first version of this matched an outcome against every unsettled play
+    whose shown memories intersected it, and never consumed it. Both audits
+    reproduced the consequence and it is severe: five recalls that happened to
+    display the same memory, plus one reported outcome, settled **five** plays
+    and moved five arms; twenty recalls settled twenty. One person saying "that
+    helped" became twenty pieces of evidence about twenty different retrieval
+    strategies, most of which had nothing to do with it.
+
+    It also inflated confidence. ``play_count`` is what
+    ``pcos.confidence_weight`` reads, so the same fan-out could push a memory to
+    "proven" — full bonus — on a single judgement.
+
+    The effect on the learning claim is the part that matters: Thompson sampling
+    would be learning which memories were *nearby*, not which strategy helped.
+    That is how arms come off their prior and the ranker is still random.
+
+    So ``claimed`` carries the outcome ids already spent this pass, and an
+    outcome may be spent once. Plays are offered outcomes oldest-first, so the
+    recall that ran first gets the credit — the report is far more likely to be
+    about the answer the user actually saw.
+
+    THE EXACT PATH IS ALSO BOUNDED IN TIME. A ``recall_query_id`` is a stronger
+    statement of intent than overlap and is tried first, but it used to skip the
+    horizon check entirely: an outcome ten days later, naming completely
+    different memories, settled a long-closed play at reward 0.0. Reproduced.
+    Both paths now require the outcome to fall inside the window.
+    """
+    horizon = play_at + timedelta(seconds=_MATCH_WINDOW_SEC)
+
+    def _in_window(o: dict) -> bool:
+        return play_at <= o["at"] <= horizon
+
+    def _first(candidates: list[dict]) -> dict | None:
+        fresh = [o for o in candidates if o["id"] not in claimed]
+        return min(fresh, key=lambda o: o["at"]) if fresh else None
+
+    if query_id:
+        exact = _first([
+            o for o in outcomes
+            if o["query_id"] and o["query_id"] == query_id and _in_window(o)
+        ])
+        if exact is not None:
+            return exact
+
+    if not shown:
+        return None
+    return _first([
+        o for o in outcomes if _in_window(o) and (o["facts"] & shown)
+    ])
+
+
+def settle_from_outcomes(
+    profile_id: str,
+    learning_db: Path | str,
+    memory_db: Path | str,
+    *,
+    now: datetime | None = None,
+    bandit: ContextualBandit | None = None,
+) -> int:
+    """Settle plays from reported outcomes. Returns the count. Never raises.
+
+    Run this BEFORE ``reward_proxy.settle_stale_plays`` on any pass. The proxy
+    defaults a play at 120 seconds; if it goes first it takes every play with
+    it and a reported outcome arriving at minute five finds nothing left to
+    settle.
+    """
+    current = now or datetime.now(timezone.utc)
+    learning_conn = _open(Path(learning_db))
+    if learning_conn is None:
+        return 0
+    memory_conn = _open(Path(memory_db))
+    if memory_conn is None:
+        learning_conn.close()
+        return 0
+
+    owns_bandit = bandit is None
+    if bandit is None:
+        bandit = ContextualBandit(Path(learning_db), profile_id=str(profile_id))
+
+    settled = 0
+    try:
+        plays = _unsettled_plays(learning_conn, profile_id)
+        if not plays:
+            return 0
+        oldest = min(
+            (p for p in (_parse_iso(r["played_at"]) for r in plays)
+             if p is not None),
+            default=current,
+        )
+        outcomes = _candidate_outcomes(memory_conn, profile_id, oldest)
+        if not outcomes:
+            return 0
+
+        # Outcome ids spent this pass. An outcome is evidence about one recall.
+        claimed: set[str] = set()
+
+        for row in plays:
+            played = _parse_iso(row["played_at"])
+            if played is None:
+                continue
+            shown = _shown(row["shown_fact_ids"])
+            outcome = _match(
+                played, str(row["query_id"] or ""), shown, outcomes, claimed,
+            )
+            if outcome is None:
+                continue
+            if bandit.update(int(row["play_id"]), outcome["reward"],
+                             kind=SETTLEMENT_KIND):
+                settled += 1
+                claimed.add(outcome["id"])
+                # Credit ONLY the memories the outcome actually named. Writing
+                # it to everything the play displayed spread one judgement
+                # across up to five memories: an outcome naming one of them
+                # moved all five to 0.55 with play_count 1. Co-displayed
+                # memories inherited credit, the bonus then lifted them, and
+                # they were shown again — the rich-get-richer path this was
+                # built to prevent, one hop removed.
+                judged = sorted(outcome["facts"] & shown) if shown else []
+                if judged:
+                    try:
+                        update_scores(
+                            memory_conn, profile_id, judged, outcome["reward"],
+                        )
+                        memory_conn.commit()
+                    except Exception as exc:  # pragma: no cover — defensive
+                        logger.debug("pcos update skipped: %s", exc)
+    except sqlite3.Error as exc:  # pragma: no cover — defensive
+        logger.warning("reward_from_outcomes: %s", exc)
+    finally:
+        for conn in (learning_conn, memory_conn):
+            try:
+                conn.close()
+            except sqlite3.Error:  # pragma: no cover
+                pass
+        if owns_bandit:
+            try:
+                from superlocalmemory.learning.bandit import (
+                    close_threadlocal_conn,
+                )
+
+                close_threadlocal_conn()
+            except Exception:  # pragma: no cover — defensive
+                pass
+    if settled:
+        logger.info(
+            "reward_from_outcomes: settled %d play(s) from reported outcomes",
+            settled,
+        )
+    return settled

package/src/superlocalmemory/learning/reward_proxy.py

@@ -27,6 +27,7 @@ Hard rules:
 
 from __future__ import annotations
 
+import json
 import logging
 import sqlite3
 from datetime import datetime, timedelta, timezone
@@ -76,18 +77,62 @@ def _fetch_unsettled(
     now: datetime,
 ) -> list[sqlite3.Row]:
     try:
-        return learning_conn.execute(
-            "SELECT play_id, query_id, played_at, stratum "
-            "FROM bandit_plays "
-            "WHERE profile_id = ? AND settled_at IS NULL "
-            "ORDER BY played_at ASC LIMIT 500",
-            (profile_id,),
-        ).fetchall()
+        # shown_fact_ids arrives with M044; the NULL alias keeps this working
+        # on a store where it has not run yet.
+        for columns in (
+            "play_id, query_id, played_at, stratum, shown_fact_ids",
+            "play_id, query_id, played_at, stratum, NULL AS shown_fact_ids",
+        ):
+            try:
+                return learning_conn.execute(
+                    f"SELECT {columns} FROM bandit_plays "
+                    "WHERE profile_id = ? AND settled_at IS NULL "
+                    "ORDER BY played_at ASC LIMIT 500",
+                    (profile_id,),
+                ).fetchall()
+            except sqlite3.Error:
+                continue
+        return []
     except sqlite3.Error as exc:
         logger.debug("reward_proxy: fetch_unsettled: %s", exc)
         return []
 
 
+def _shown_fact_ids(
+    learning_conn: sqlite3.Connection,
+    play_id: int,
+) -> list[str]:
+    """The fact_ids this play recorded at recall time (M044), or [].
+
+    Preferred over the ``learning_signals`` lookup below because it does not
+    depend on the exposure enqueue, which is off: twenty rows per query, and
+    the source of a 2,675x inflation in the ranking-phase counter. With no
+    signals rows there was nothing to look for, so every play settled as the
+    120-second default and 165 arms sat at alpha == beta.
+
+    Returns [] on a store where M044 has not run — "no such column" is an
+    ``sqlite3.Error`` and is caught, so an unmigrated install falls back to the
+    old lookup rather than losing settlement entirely.
+    """
+    try:
+        row = learning_conn.execute(
+            "SELECT shown_fact_ids FROM bandit_plays WHERE play_id = ?",
+            (int(play_id),),
+        ).fetchone()
+    except sqlite3.Error:
+        return []
+    raw = (row[0] if row else None) or ""
+    if not raw:
+        return []
+    try:
+        parsed = json.loads(raw)
+    except (TypeError, ValueError):
+        return []
+    if not isinstance(parsed, list):
+        return []
+    return [str(f) for f in parsed[:3] if f]
+
+
 def _top3_fact_ids(
     learning_conn: sqlite3.Connection,
     query_id: str,
@@ -95,6 +140,8 @@ def _top3_fact_ids(
     """Return up to 3 fact_ids for this query_id ordered by position ASC.
 
     Returns [] if learning_signals is missing or has no rows for this qid.
+    Kept as the fallback for plays written before M044 and for installs that
+    do run the exposure enqueue.
     """
     try:
         rows = learning_conn.execute(
@@ -281,6 +328,44 @@ def _extract_query(payload_json: str | None) -> str:
     return ""
 
 
+def _default_deadline(
+    learning_conn: sqlite3.Connection, play: sqlite3.Row,
+) -> float:
+    """Age in seconds at which this play may be defaulted to 0.5.
+
+    120 s for a play that recorded nothing — no evidence can ever arrive for
+    it, so holding it open buys nothing but an unsettled row.
+
+    Longer for a play that recorded which memories it showed (M044), because a
+    reported outcome CAN settle it and two minutes is not long enough for
+    anyone to decide whether an answer helped. Defaulting first would make the
+    neutral fallback win a race it should not be in — which is how 1,405
+    consecutive plays came to apply exactly 0.5.
+    """
+    try:
+        from superlocalmemory.learning.reward_from_outcomes import GRACE_SEC
+    except Exception:  # pragma: no cover — defensive
+        return float(_MAX_AGE_SEC)
+    try:
+        raw = play["shown_fact_ids"]
+    except (IndexError, KeyError):
+        return float(_MAX_AGE_SEC)
+    # PARSE, do not test the raw string. "[]" is truthy, so a play that recorded
+    # no memories used to buy the full grace window it could never use: nothing
+    # can overlap an empty set, so it stayed unsettled forever, and the
+    # retention sweep only removes SETTLED rows. Reproduced: "[]" returned
+    # 900 s where it should return 120 s.
+    try:
+        parsed = json.loads(raw) if raw else []
+    except (TypeError, ValueError):
+        parsed = []
+    has_evidence = bool(parsed) if isinstance(parsed, list) else False
+    return (
+        max(float(_MAX_AGE_SEC), GRACE_SEC) if has_evidence
+        else float(_MAX_AGE_SEC)
+    )
+
+
 def settle_stale_plays(
     profile_id: str,
     db_path: Path | str,
@@ -315,7 +400,12 @@ def settle_stale_plays(
             if age < _MIN_AGE_SEC:
                 continue  # not yet settleable
 
-            top3 = _top3_fact_ids(learning_conn, row["query_id"])
+            # The play's own record first; the signals table only as a
+            # fallback for rows written before M044.
+            top3 = (
+                _shown_fact_ids(learning_conn, row["play_id"])
+                or _top3_fact_ids(learning_conn, row["query_id"])
+            )
             reward: float | None = None
             kind = "default"
             if memory_conn is not None and _tool_event_hit(
@@ -328,8 +418,8 @@ def settle_stale_plays(
             ):
                 reward = 0.0
                 kind = "proxy_requery"
-            elif age > _MAX_AGE_SEC:
-                # P1: uncertain default after 120 s window closes.
+            elif age > _default_deadline(learning_conn, row):
+                # P1: uncertain default once the window closes.
                 reward = 0.5
                 kind = "default"
             else:

package/src/superlocalmemory/learning/signal_kinds.py

@@ -0,0 +1,79 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Which ``learning_signals`` rows are feedback, and which are just exposure.
+
+THE DISTINCTION, AND WHY IT DECIDES A RANKING PHASE
+---------------------------------------------------
+An **exposure** records that a fact was shown. A **feedback** signal records
+that something happened afterwards. Only the second says anything about whether
+the memory was any good, and the ranker's phase gate is meant to count the
+second.
+
+It counted both. Measured on a live ``learning.db``::
+
+    candidate         5,350      exposure — one row per fact shown at recall
+    legacy_feedback       2      the only real feedback in the table
+                      ─────
+                      5,352      what count_signals() returned
+
+An inflation of 2,675x. Every surface that resolves a phase from that number
+believed it had Phase 3 data — LightGBM active — on two feedback events, and
+the model it activated had been trained on 972 rows whose labels were all 0.0.
+So it reordered results at random and outranked the heuristic that would
+otherwise have been used.
+
+Correcting the count drops the system to Phase 1 (heuristic). That is not a
+regression; it is the honest state, and the heuristic is the better ranker of
+the two.
+
+WHY A SHARED SET RATHER THAN A LITERAL AT EACH CALL SITE
+--------------------------------------------------------
+There are two ``count_signals()`` implementations — ``learning/database.py``
+and the read-only view in ``core/recall_pipeline.py`` — and a phase computed
+from one is compared against a threshold computed from the other. Two literals
+is how they drift.
+
+This module deliberately has no imports: ``_ReadOnlyLearningView`` exists to
+read a learning DB *without* being able to initialise or mutate one, so it must
+not pull the writer module in just to learn a set of strings.
+
+EXCLUDING EXPOSURES RATHER THAN NAMING FEEDBACK. A new feedback kind (``dwell``,
+``explicit``, ``cited``) must count the day it is introduced, without anyone
+remembering to add it here — so the predicate is a NOT IN over the exposure
+kinds, not an IN over the feedback kinds. The failure modes are not symmetric:
+forgetting to add a feedback kind under-counts and quietly holds the ranker in
+an earlier phase, while forgetting to add an exposure kind re-creates the 2,675x
+inflation above.
+"""
+
+from __future__ import annotations
+
+__all__ = ["EXPOSURE_SIGNAL_TYPES", "FEEDBACK_ONLY_SQL", "is_feedback"]
+
+#: Signal kinds that record only that a fact was displayed.
+#:
+#: ``candidate`` is written once per fact per recall. ``shown`` is its sibling
+#: in ``_fetch_training_rows``; there are no rows of it on a live store,
+#: and it is listed here because the alternative is a predicate that counts it
+#: as feedback the moment one appears.
+EXPOSURE_SIGNAL_TYPES: frozenset[str] = frozenset({"candidate", "shown"})
+
+#: AND-clause selecting feedback rows only. ``signal_type`` is ``NOT NULL`` in
+#: the schema, so no COALESCE is needed — verified against the table definition
+#: rather than assumed, because ``x != 'candidate'`` is NULL (and therefore
+#: false) for a NULL x, which would silently drop rows.
+FEEDBACK_ONLY_SQL: str = " AND signal_type NOT IN ({})".format(
+    ", ".join(f"'{kind}'" for kind in sorted(EXPOSURE_SIGNAL_TYPES))
+)
+
+
+def is_feedback(signal_type: str | None) -> bool:
+    """Whether ``signal_type`` counts toward the ranker's phase gate.
+
+    The Python twin of :data:`FEEDBACK_ONLY_SQL`, for callers holding a row
+    rather than building a query. A missing type counts as feedback: it is not
+    one of the two known exposure writers, and under-counting is the failure
+    mode that hides a phase transition.
+    """
+    return (signal_type or "") not in EXPOSURE_SIGNAL_TYPES

package/src/superlocalmemory/mcp/profiles.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 # Named profile definitions (introduced in v3.6.14)
 # ---------------------------------------------------------------------------
 
-_PROFILE_CORE: frozenset[str] = frozenset({  # 17
+_PROFILE_CORE: frozenset[str] = frozenset({  # 18
     "remember", "recall", "search", "fetch", "list_recent", "update_memory", "forget",
     "session_init", "close_session",
     "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
@@ -28,6 +28,13 @@ _PROFILE_CORE: frozenset[str] = frozenset({  # 17
     # natural caller is the agent holding the conversation — an assistant
     # asked "what did I work on yesterday" should not need a power profile.
     "get_memory_summary",
+    # v4.1.0: every memory operation is scoped to a profile, so a surface that
+    # can read or write memory must also be able to say which profile it means.
+    # Without this, the smallest profile can store and recall but can never
+    # leave the profile it happened to start in, and a second workspace is
+    # unreachable from the surface most hosts ship. The route stays RBAC
+    # member-gated, so company-mode isolation is unaffected.
+    "switch_profile",
 })
 
 # Portable Brain evidence must reach the coding-host profile shipped by the
@@ -48,6 +55,11 @@ _PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  #
     # v3.8.0: bounded loops on the MCP surface. Coding agents (the /slm-loop
     # command's audience) run gated, bounded loops and inspect the ledger.
     "slm_loop_run", "slm_loop_history", "slm_loop_show",
+    # Retrieval ranks a memory partly on whether it has actually helped, and
+    # the only evidence of that comes from the assistant that used it. The
+    # plugin ships SLM_MCP_PROFILE=code, so without these two the ranker has
+    # no input at all for the audience it exists to serve.
+    "report_outcome", "report_feedback",
 })
 
 _PROFILE_FULL_MESH: frozenset[str] = frozenset({  # 8
@@ -74,7 +86,7 @@ _PROFILE_FULL: frozenset[str] = frozenset({
     # prestage_context remains registered but deliberately raw-server-only.
 }) | _PROFILE_FULL_MESH  # 50
 
-_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 61
+_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 62
     "get_version", "get_mode", "health", "consistency_check", "recall_trace",
     "get_lifecycle_status", "set_retention_policy", "compact_memories",
     "get_behavioral_patterns", "audit_trail", "quantize", "get_retention_stats",

package/src/superlocalmemory/mcp/server.py

@@ -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