switchroom 0.17.10 → 0.18.3

package/vendor/hindsight-memory/scripts/lib/client.py

@@ -124,11 +124,19 @@ class HindsightClient:
         tags: Optional[list] = None,
         tags_match: Optional[str] = None,
         tag_groups: Optional[object] = None,
+        prefer_observations: Optional[bool] = None,
         timeout: int = 10,
     ) -> dict:
         """Recall memories from a bank.
 
-        Returns the raw API response dict with 'results' list.
+        Returns the raw API response dict with 'results' list. Each result
+        carries a `scores` object (`RecallScores`) whose `final` field is the
+        engine's combined ranking score — callers sort the merged multi-bank
+        set by it before applying any count cap.
+
+        `prefer_observations=True` asks the engine to prefer deduped
+        observation statements over the raw facts they supersede, backfilling
+        the freed slots — denser coverage inside the same token/count budget.
         """
         path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/memories/recall"
         body = {
@@ -145,6 +153,8 @@ class HindsightClient:
             body["tags_match"] = tags_match
         if tag_groups:
             body["tag_groups"] = tag_groups
+        if prefer_observations is not None:
+            body["prefer_observations"] = prefer_observations
         return self._request("POST", path, body, timeout=timeout)
 
     def retain(

package/vendor/hindsight-memory/scripts/lib/config.py

@@ -33,10 +33,17 @@ DEFAULTS = {
     # user's query terms and a memory's text terms. Memories below this
     # threshold are dropped before formatting. 0.0 disables the gate
     # (current behaviour: inject everything Hindsight returns up to the
-    # count cap). Hindsight's HTTP API does not expose similarity
-    # scores, so this is the switchroom-side quality filter — see #475.
+    # count cap). NOTE: Hindsight's HTTP recall API DOES return per-result
+    # relevance scores (`scores.final`, plus `.semantic`/`.keyword`/
+    # `.reranker`) — verified at runtime — and recall.py now reads and
+    # sorts the merged set by `scores.final`. This Jaccard gate is a
+    # separate lexical-overlap quality filter layered on top — see #475.
     "recallMinOverlap": 0.0,
     "recallTypes": ["world", "experience"],
+    # Switchroom-local: when True (default; Ken-approved ON) recall biases
+    # toward synthesized `observation`-tier facts. Escape hatch: pin off via
+    # `recallPreferObservations: false` in the user config — read in recall.py.
+    "recallPreferObservations": True,
     # Switchroom #2848 Stage B/C — deterministic directive capture.
     # When on (switchroom default; pinned true in the copied plugin
     # settings.json by applyHindsightSettingsOverrides), TWO deterministic

package/vendor/hindsight-memory/scripts/recall.py

@@ -373,12 +373,18 @@ def _is_demoted_memory(memory) -> bool:
 
 # Switchroom #475 — lexical-overlap relevance gate.
 #
-# Hindsight's HTTP API does not return similarity scores. Without a
-# score the existing `recallMaxMemories` cap acts as a *floor* on
-# low-relevance prompts: weak matches still fill the slot up to N,
-# mis-steering the model. This gate computes Jaccard overlap between
-# the user's query terms and each memory's text terms, and drops
-# memories below a configurable threshold.
+# Hindsight's HTTP recall API DOES return per-result relevance scores
+# (`RecallResult.scores.final`, plus `.semantic`/`.keyword`/`.reranker`);
+# the merged multi-bank set is now sorted by `scores.final` before the
+# `recallMaxMemories` cap (see the sort just before the cap in
+# process_recall) so the most relevant memories survive the head-slice
+# regardless of which bank they came from. This gate is a *complementary*,
+# opt-in absolute precision floor: `scores.final` is a relative rank that
+# still orders weakly-matching memories rather than excluding them, so on a
+# low-relevance prompt the top-N could still be low-signal. The Jaccard
+# overlap between the user's query terms and each memory's text terms is a
+# query-independent absolute measure that drops memories below a
+# configurable threshold outright — something the relative sort does not do.
 #
 # Threshold default is 0.0 (disabled) so the gate is opt-in initially.
 # Operators tune via `memory.recall.min_overlap` in switchroom.yaml or
@@ -469,6 +475,40 @@ def _filter_by_overlap(results, query: str, threshold: float):
     return kept, dropped
 
 
+def _result_final_score(m) -> float:
+    """Return a result's engine relevance score (`scores.final`).
+
+    Switchroom Phase-1 precision. The Hindsight recall response attaches a
+    `scores` object to every result whose required `final` field is the
+    engine's combined ranking score (reranker + recency/temporal/proof
+    boosts). Results missing a usable score sort last so a malformed or
+    score-less entry can never starve a properly-ranked one.
+    """
+    if isinstance(m, dict):
+        scores = m.get("scores")
+        if isinstance(scores, dict):
+            val = scores.get("final")
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                return float(val)
+    return float("-inf")
+
+
+def _sort_by_final_score(results):
+    """Sort merged multi-bank results by `scores.final` descending, in place.
+
+    Switchroom Phase-1 bank-starvation fix. The recall path appends
+    additional-bank (profile / shared / sender) results after the own-bank
+    results, then head-slices at `recallMaxMemories`. Before this sort, a
+    full own-bank result set silently dropped every additional-bank memory
+    at the cap regardless of relevance. Sorting by the engine's real
+    relevance score before the cap means the cap keeps the most relevant
+    memories cross-bank. Python's sort is stable, so ties preserve the
+    prior own-bank-first insertion order.
+    """
+    results.sort(key=_result_final_score, reverse=True)
+    return results
+
+
 def _write_recall_log(entry: dict) -> None:
     """Append a JSONL line to recall_log.jsonl. Bounded by line count.
 
@@ -986,6 +1026,11 @@ def main():
             tags=recall_tags,
             tags_match=tags_match,
             tag_groups=tag_groups,
+            # Switchroom Phase-1 precision — prefer deduped observation
+            # statements over the raw facts they supersede, backfilling freed
+            # slots for denser coverage inside the same budget. On by default;
+            # operators can pin off via `recallPreferObservations: false`.
+            prefer_observations=config.get("recallPreferObservations", True),
             # 8s in-script timeout leaves 4s headroom inside the 12s
             # UserPromptSubmit hook ceiling (see hooks.json:20) for cache
             # write + block formatting. Tightened from 10s in switchroom
@@ -1031,6 +1076,10 @@ def main():
                 tags=extra_tags,
                 tags_match=extra_tags_match,
                 tag_groups=extra_tag_groups,
+                # Switchroom Phase-1 precision — prefer deduped observation
+                # statements here too so additional banks contribute their
+                # densest statements to the merged, score-sorted set.
+                prefer_observations=config.get("recallPreferObservations", True),
                 # 8s in-script timeout leaves 4s headroom inside the 12s
                 # UserPromptSubmit hook ceiling (see hooks.json:20) for cache
                 # write + block formatting. Tightened from 10s in switchroom
@@ -1099,6 +1148,15 @@ def main():
     else:
         overlap_dropped = 0
 
+    # Switchroom Phase-1 precision — sort the merged primary + additional-bank
+    # result set by the engine's relevance score (`scores.final`) descending
+    # BEFORE the head-slice cap below. Previously additional-bank results were
+    # appended after own-bank results and sliced off, silently starving
+    # profile / shared / sender banks whenever own-bank filled the cap. Sorting
+    # by real relevance first means the cap keeps the most relevant memories
+    # regardless of source bank. Stable sort: ties keep own-bank-first order.
+    _sort_by_final_score(results)
+
     # Switchroom-local: client-side count cap. Plugin v0.4.0 has no
     # `recallTopK` in the Claude Code integration (Openclaw-only), and a
     # token budget alone doesn't bound count — a single long memory can

package/vendor/hindsight-memory/scripts/tests/test_recall_integration.py

@@ -74,6 +74,7 @@ class _FakeClient:
         tags=None,
         tags_match=None,
         tag_groups=None,
+        prefer_observations=None,
         timeout=10,
     ):
         self.recall_calls.append(

package/vendor/hindsight-memory/tests/test_client.py

@@ -274,6 +274,49 @@ class TestHindsightClientRecallTagFilters:
         assert "tag_groups" not in captured["body"]
 
 
+class TestHindsightClientPreferObservations:
+    """Switchroom Phase-1 — prefer_observations forwarded in the recall body."""
+
+    def test_forwards_prefer_observations_true(self):
+        c = HindsightClient("http://localhost:9077")
+        captured = {}
+
+        def fake_open(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp({"results": []})
+
+        with patch("urllib.request.urlopen", side_effect=fake_open):
+            c.recall("bank", "query", prefer_observations=True)
+
+        assert captured["body"]["prefer_observations"] is True
+
+    def test_forwards_prefer_observations_false(self):
+        c = HindsightClient("http://localhost:9077")
+        captured = {}
+
+        def fake_open(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp({"results": []})
+
+        with patch("urllib.request.urlopen", side_effect=fake_open):
+            c.recall("bank", "query", prefer_observations=False)
+
+        assert captured["body"]["prefer_observations"] is False
+
+    def test_omits_prefer_observations_when_unset(self):
+        c = HindsightClient("http://localhost:9077")
+        captured = {}
+
+        def fake_open(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp({"results": []})
+
+        with patch("urllib.request.urlopen", side_effect=fake_open):
+            c.recall("bank", "query")
+
+        assert "prefer_observations" not in captured["body"]
+
+
 class TestRequestTimeoutOverride:
     """Upstream 55ef70679 — the constructor override replaces the per-call
     timeout that recall/retain/_request would otherwise use. When unset,

package/vendor/hindsight-memory/tests/test_recall_precision.py

@@ -0,0 +1,114 @@
+"""Retrieval-precision measurement for the Switchroom Phase-1 memory changes.
+
+Per the RFC's outcome-UAT rule (reference/rfcs/hindsight-memory-reimagined.md,
+"Measurement"), the bank-starvation fix ships behind a check that compares
+recalled-set relevance before/after the sort. These tests assert the two
+load-bearing properties of the fix:
+
+  1. The merged multi-bank result set is ordered by the engine's real
+     relevance score (`scores.final`) descending.
+  2. A high-relevance memory from an ADDITIONAL bank is not starved by the
+     count cap when the own bank supplies enough lower-relevance hits to
+     fill it — the pre-fix bug (append-then-slice) would drop it.
+
+`_sort_by_final_score` is the in-place sort applied just before the cap in
+`process_recall`; the cap itself is a plain head-slice, reproduced here so the
+before/after relevance of the capped set is directly comparable.
+"""
+
+from recall import _result_final_score, _sort_by_final_score
+
+
+def _mem(mem_id, final, bank):
+    """A recall result as the engine returns it: text + a scores object."""
+    return {
+        "id": mem_id,
+        "text": f"memory {mem_id} from {bank}",
+        "bank": bank,
+        "scores": {"final": final, "semantic": final, "keyword": final},
+    }
+
+
+def _capped_relevance(results, cap):
+    """Mirror process_recall: head-slice at the cap, return kept scores."""
+    kept = results[:cap] if cap > 0 else results
+    return [_result_final_score(m) for m in kept]
+
+
+class TestFinalScoreExtraction:
+    def test_reads_final_score(self):
+        assert _result_final_score(_mem("a", 0.9, "own")) == 0.9
+
+    def test_missing_scores_sorts_last(self):
+        assert _result_final_score({"id": "x", "text": "t"}) == float("-inf")
+
+    def test_null_scores_sorts_last(self):
+        assert _result_final_score({"id": "x", "scores": None}) == float("-inf")
+
+    def test_missing_final_sorts_last(self):
+        assert _result_final_score({"id": "x", "scores": {"semantic": 0.5}}) == float("-inf")
+
+    def test_bool_is_not_a_score(self):
+        # True is an int subclass; it must not be mistaken for a 1.0 score.
+        assert _result_final_score({"id": "x", "scores": {"final": True}}) == float("-inf")
+
+
+class TestSortByFinalScore:
+    def test_orders_descending(self):
+        results = [_mem("a", 0.2, "own"), _mem("b", 0.9, "own"), _mem("c", 0.5, "own")]
+        _sort_by_final_score(results)
+        assert [m["id"] for m in results] == ["b", "c", "a"]
+
+    def test_stable_on_ties_preserves_own_bank_first(self):
+        # Own-bank appears before additional-bank in insertion order; on a
+        # score tie the stable sort must keep own-bank ahead.
+        results = [_mem("own1", 0.5, "own"), _mem("extra1", 0.5, "profile")]
+        _sort_by_final_score(results)
+        assert [m["id"] for m in results] == ["own1", "extra1"]
+
+    def test_scoreless_entries_sink_to_the_bottom(self):
+        results = [{"id": "noscore", "text": "t"}, _mem("scored", 0.1, "own")]
+        _sort_by_final_score(results)
+        assert results[0]["id"] == "scored"
+
+
+class TestCrossBankStarvationRegression:
+    """The bug the fix targets: a relevant additional-bank memory dropped at
+    the cap because own-bank hits were appended first."""
+
+    def test_high_relevance_additional_bank_memory_survives_cap(self):
+        # Own bank fills the cap with mediocre hits; the profile bank has the
+        # single most relevant memory. Pre-fix (append own, then extra, then
+        # head-slice) the profile hit lands at index 2 and is sliced off.
+        cap = 2
+        own = [_mem("own_lo1", 0.30, "own"), _mem("own_lo2", 0.25, "own")]
+        extra = [_mem("profile_hi", 0.95, "profile")]
+        merged = own + extra  # exactly the pre-fix append order
+
+        # Before: append-then-slice starves the profile bank.
+        pre_fix_ids = [m["id"] for m in merged[:cap]]
+        assert "profile_hi" not in pre_fix_ids
+
+        # After: sort by scores.final before the slice keeps the best memory.
+        _sort_by_final_score(merged)
+        post_fix_ids = [m["id"] for m in merged[:cap]]
+        assert "profile_hi" in post_fix_ids
+        assert post_fix_ids[0] == "profile_hi"
+
+    def test_capped_set_relevance_is_no_worse_after_sort(self):
+        # Measurement: summed relevance of the capped set must not decrease.
+        cap = 3
+        merged = [
+            _mem("own1", 0.4, "own"),
+            _mem("own2", 0.35, "own"),
+            _mem("own3", 0.3, "own"),
+            _mem("profile1", 0.9, "profile"),
+            _mem("shared1", 0.8, "shared"),
+        ]
+        before = sum(_capped_relevance(list(merged), cap))
+        _sort_by_final_score(merged)
+        after = sum(_capped_relevance(merged, cap))
+        assert after >= before
+        # And concretely, the two top additional-bank hits are now retained.
+        kept_ids = [m["id"] for m in merged[:cap]]
+        assert "profile1" in kept_ids and "shared1" in kept_ids