switchroom 0.17.6 → 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,44 @@ 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
+    # hooks share this knob:
+    #   * Stage B (recall.py, UserPromptSubmit): regex-detects correction /
+    #     standing-rule-shaped inbound and appends a terse advisory to the
+    #     turn's additionalContext telling the model to persist the rule with
+    #     create_directive if it IS durable.
+    #   * Stage C (directive_verify.py, Stop): after the turn, re-checks the
+    #     human turn against a HIGH-PRECISION durable-rule regex and, if the
+    #     model recorded no create_directive call, blocks the stop ONCE to
+    #     re-prompt capture (closes the "model ignored the nudge" gap).
+    # Both are pure detection — no model callsite, no silent hook-side write;
+    # the model authors the directive in-session (chat-legible). Operators opt
+    # out per-agent via memory.directive_capture_nudge=false →
+    # HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE (disables BOTH hooks).
+    "directiveCaptureNudge": True,
+    # Switchroom #2873/#2903 Fix 6.2 — the BLOCKING half (Stage C
+    # directive_verify.py Stop hook) split out from the advisory nudge. When
+    # True (default) the verifier may block the stop once to re-prompt capture;
+    # when False the Stage B nudge still fires but the Stop hook NEVER blocks
+    # (advisory-only mode). Lets an operator keep the gentle nudge while dropping
+    # the more intrusive block. Gated UNDER directiveCaptureNudge: turning the
+    # nudge off disables both regardless of this knob. Operators opt out
+    # per-agent via memory.directive_capture_verify=false →
+    # HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY.
+    "directiveCaptureVerify": True,
     "recallContextTurns": 1,
     "recallMaxQueryChars": 800,
     "recallRoles": ["user", "assistant"],
@@ -119,6 +153,16 @@ ENV_OVERRIDES = {
     # from agents.<name>.memory.recall.skip_trivial only on override; the
     # switchroom default is on (recall.py falls back to True).
     "HINDSIGHT_RECALL_SKIP_TRIVIAL": ("recallSkipTrivial", bool),
+    # Switchroom #2848 Stage B: directive-capture nudge on/off. Set by
+    # start.sh from agents.<name>.memory.directive_capture_nudge only when
+    # the operator overrode it; the switchroom default is on (settings.json
+    # pins true; recall.py falls back to True).
+    "HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE": ("directiveCaptureNudge", bool),
+    # Switchroom #2873/#2903 Fix 6.2: the Stage C block on/off, independent of
+    # the Stage B nudge. Set by start.sh from
+    # agents.<name>.memory.directive_capture_verify only when the operator
+    # overrode it; the switchroom default is on.
+    "HINDSIGHT_DIRECTIVE_CAPTURE_VERIFY": ("directiveCaptureVerify", bool),
     "HINDSIGHT_RECALL_MAX_QUERY_CHARS": ("recallMaxQueryChars", int),
     "HINDSIGHT_RECALL_CONTEXT_TURNS": ("recallContextTurns", int),
     # Upstream 962140eef — recall tag filters. The tags env var accepts JSON

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

@@ -16,6 +16,7 @@ stderr. We never raise to the caller — directives are nice-to-have on the
 recall path; a directive-fetch failure must not kill the recall block.
 """
 
+import re
 import sys
 from typing import Optional
 
@@ -117,3 +118,90 @@ def format_active_directives_block(directives: list, max_directives: int = MAX_D
 
     lines.append("</active_directives>")
     return "\n".join(lines)
+
+
+# --- Directive dedup (switchroom #2903 Fix 6.2) --------------------------------
+#
+# A user restating a rule that is ALREADY an active directive should not get
+# re-nudged, and the Stage C verifier must not BLOCK the turn where the model
+# correctly declines to re-create the duplicate. The verifier can see the
+# directives that were injected THIS turn (recall.py emits the
+# <active_directives> block into the prompt), so it reads them back out of the
+# transcript and treats a rule already covered there as "already captured".
+#
+# Matching is a deterministic lexical-overlap heuristic (no model call, no API
+# call — the verifier is on the Stop critical path). It is intentionally
+# lenient: a false "already captured" only means we skip a re-prompt (the rule
+# is genuinely already stored in that case), whereas a false "not captured"
+# re-blocks a turn the model correctly finished. So we err toward treating a
+# strong token overlap as a duplicate.
+
+# Parses the numbered "N. [P<pri>] <name>: <content>" body lines out of a
+# rendered <active_directives> block (see format_active_directives_block).
+_ACTIVE_DIRECTIVE_LINE_RE = re.compile(
+    r"^\s*\d+\.\s*\[P-?\d+\]\s*[^:]*:\s*(?P<content>.+?)\s*$"
+)
+
+# Low-signal words stripped before overlap scoring so "always"/"you"/"please"
+# framing doesn't inflate similarity between two unrelated rules.
+_DEDUP_STOPWORDS = frozenset(
+    {
+        "the", "a", "an", "to", "of", "and", "or", "for", "in", "on", "at",
+        "is", "are", "be", "you", "your", "i", "we", "me", "my", "it", "that",
+        "this", "with", "as", "so", "do", "dont", "don", "not", "never",
+        "always", "please", "should", "must", "want", "from", "now", "on",
+        "going", "forward", "forwards", "future", "rule", "remember", "call",
+        "use", "using", "make", "sure", "when", "if", "just", "will", "can",
+    }
+)
+
+
+def _dedup_tokens(text: str) -> set:
+    """Normalize text into a set of significant lower-case word tokens."""
+    if not isinstance(text, str):
+        return set()
+    words = re.findall(r"[a-z0-9]+", text.lower())
+    return {w for w in words if w not in _DEDUP_STOPWORDS and len(w) > 1}
+
+
+def parse_active_directives_block(text: str) -> list:
+    """Extract the directive CONTENT strings from a rendered
+    <active_directives> block (as produced by format_active_directives_block).
+
+    Returns [] when the block is absent or malformed. Pure string parsing.
+    """
+    if not isinstance(text, str) or "<active_directives>" not in text:
+        return []
+    # Isolate the block body between the tags (tolerate missing close tag).
+    body = text.split("<active_directives>", 1)[1]
+    body = body.split("</active_directives>", 1)[0]
+    contents = []
+    for line in body.splitlines():
+        m = _ACTIVE_DIRECTIVE_LINE_RE.match(line)
+        if m:
+            contents.append(m.group("content").strip())
+    return contents
+
+
+def rule_already_captured(
+    rule_text: str, directive_contents: list, threshold: float = 0.6
+) -> bool:
+    """True when ``rule_text`` is lexically well-covered by an EXISTING active
+    directive in ``directive_contents``.
+
+    Coverage = |rule_tokens ∩ directive_tokens| / |rule_tokens| for the
+    best-matching directive. A high coverage ratio means the restated rule adds
+    (almost) no new significant words over one already stored — i.e. a
+    duplicate. Deterministic; no model/API call.
+    """
+    rule_tokens = _dedup_tokens(rule_text)
+    if not rule_tokens:
+        return False
+    for content in directive_contents:
+        d_tokens = _dedup_tokens(content)
+        if not d_tokens:
+            continue
+        covered = len(rule_tokens & d_tokens) / len(rule_tokens)
+        if covered >= threshold:
+            return True
+    return False

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

@@ -0,0 +1,77 @@
+"""Switchroom gateway inbound-envelope grammar — the ONE place this vendored
+Python knows about switchroom's ``<channel source="...">`` wire format.
+
+SWITCHROOM DIVERGENCE (not upstream Hindsight). This module isolates the
+coupling between the vendored Python hooks and the switchroom telegram-plugin
+gateway's inbound envelope. It exists so a change to the TS-side envelope
+grammar has ONE obvious Python counterpart to update — instead of the grammar
+being buried inline inside directive_verify.py where a silent TS format change
+could break a Python guard undetected (#2903 Fix 6.3).
+
+The gateway prepends a leading ``<channel source="..." ...>`` envelope to every
+SYNTHESIZED / non-human inbound it injects into the model (cron fires, reaction
+dispatches, resume synthetics, vault-grant approvals, sub-agent handbacks,
+obligation representations, …). See, on the TS side:
+
+  * telegram-plugin/gateway/*-inbound-builder.ts (and the reaction / resume /
+    vault-grant / subagent / obligation builders) — they emit
+    ``<channel source="<name>" ...>``.
+  * A genuine human message from the primary channel carries
+    ``source="telegram"``; interactive (non-gateway) sessions carry NO envelope
+    at all.
+
+Contract pinned here (keep in lockstep with the gateway):
+  * ``CHANNEL_SOURCE_RE`` — extracts the ``source`` attribute from the leading
+    envelope. Handles both open (``<channel source="telegram" ...>``) and
+    self-closing (``<channel source="reaction"/>``) forms.
+  * ``HUMAN_INBOUND_SOURCES`` — the whitelist of ``source`` values that denote a
+    GENUINE human turn. A whitelist (not a blacklist) so any NEW synthetic
+    source the gateway adds is treated as machine-authored by default rather
+    than accidentally classified human.
+
+If the gateway ever renames the envelope tag, changes the attribute name, or
+adds a new human-facing channel, update THIS module (and its test,
+tests/test_switchroom_envelope.py). Nothing else in the Python tree should hard
+-code the ``<channel source=`` grammar.
+"""
+
+import re
+
+# Genuine human inbound channels. A "user" turn whose `<channel source="...">`
+# envelope names anything else is a SYNTHESIZED / cron inbound built by the
+# gateway — a machine turn, NOT a human correction.
+HUMAN_INBOUND_SOURCES = frozenset({"telegram"})
+
+# Pulls the source attribute out of the gateway's leading `<channel ...>`
+# envelope. Handles both open (`<channel source="telegram" ...>`) and
+# self-closing (`<channel source="reaction"/>`) forms.
+CHANNEL_SOURCE_RE = re.compile(r"""<channel\b[^>]*\bsource=["']([^"']+)["']""")
+
+
+def envelope_source(text) -> "str | None":
+    """Return the lower-cased ``source`` of the leading channel envelope, or
+    None when there is no envelope (interactive session). Pure regex."""
+    if not isinstance(text, str):
+        return None
+    m = CHANNEL_SOURCE_RE.search(text)
+    if not m:
+        return None
+    return m.group(1).strip().lower()
+
+
+def is_synthetic_inbound(text) -> bool:
+    """True when this turn's opening message is a synthesized/cron inbound
+    rather than a genuine human message.
+
+    Detection is purely on the gateway-prepended ``<channel source="...">``
+    envelope: a ``source`` outside ``HUMAN_INBOUND_SOURCES`` (``cron``,
+    ``reaction``, ``resume_interrupted``, ``vault_grant_approved``,
+    ``subagent_handback``, ``obligation_represent``, …) marks a non-human turn.
+    No envelope (interactive session) → treated as human. Injected channel tags
+    in a human's own body are neutralised upstream by the channel-envelope
+    sanitiser, so the only real ``<channel source=`` is the gateway's.
+    """
+    source = envelope_source(text)
+    if source is None:
+        return False
+    return source not in HUMAN_INBOUND_SOURCES

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.
 
@@ -597,6 +637,128 @@ def _is_trivial_stateless(ack_form, stripped):
     return False
 
 
+# Switchroom #2848 Stage B — deterministic directive-capture nudge.
+#
+# Stage A audit (issue #2848) measured a ~55% miss rate on durable
+# corrections: the model is instructed (guidance-only, in
+# profiles/default/CLAUDE.md.hbs) to persist standing rules with
+# mcp__hindsight__create_directive, but does so inconsistently — capture
+# is a per-agent lottery (the same broadcast correction was captured by
+# one agent and silently dropped by two others). This adds DETERMINISTIC
+# detection of correction / standing-rule-shaped inbound (pure regex — NO
+# model callsite; the claude-native invariant forbids a classifier call)
+# and appends a terse advisory nudge to the UserPromptSubmit
+# additionalContext. The MODEL makes the judgment IN-SESSION and calls
+# create_directive itself (visible in chat); the hook NEVER writes a
+# directive on its own — a silent hook-side write would break
+# chat-legibility and edge the no-self-escalation invariant.
+#
+# On by default (Stage A proved a real gap → defaults principle);
+# operators opt out per-agent via memory.directive_capture_nudge=false in
+# switchroom.yaml, which start.sh exports as
+# HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE=false (recall.py falls back to the
+# settings.json default, which switchroom pins on).
+#
+# Detection is intentionally inclusive (the nudge is cheap + advisory, so
+# a modest false-positive rate is acceptable — the model just ignores it
+# on a one-off), but a negative guard scrubs the obvious pleasantry
+# shapes ("always happy to help", "never mind") BEFORE the positive
+# match, so those don't fire on a bare "always"/"never".
+_DIRECTIVE_NUDGE_NEGATIVE_RE = re.compile(
+    r"""(?ix)
+    (?:
+        never \s* mind
+      | nevermind
+      | always \s+ (?: happy | glad | welcome | here \s+ to \s+ help | open \s+ to )
+      | never \s+ (?: fails? | hurts? | too \s+ late | a \s+ dull )
+      | as \s+ always
+      | thanks? \s+ as \s+ always
+      | forever \s+ grateful
+    )
+    """
+)
+
+_DIRECTIVE_NUDGE_RE = re.compile(
+    r"""(?ix)
+    (?:
+      # --- explicit standing-rule framings ---
+        \b from \s+ now \s+ on \b
+      | \b going \s+ forward \b
+      | \b in \s+ (?: the \s+ )? future \b
+      | \b (?: as \s+ a \s+ )? general \s+ (?: rule | behaviou?r | policy | principle | agent \s+ behaviou?r ) \b
+      | \b as \s+ a \s+ rule \b
+      | \b i \s+ want \s+ you \s+ to \b
+      | \b you \s+ should \s+ (?: always | never ) \b
+      # --- always / never (pleasantries pre-scrubbed by the negative guard) ---
+      | \b always \b
+      | \b never \b
+      | \b no \s+ longer \b
+      | \b anymore \b
+      # --- prohibitions / behavioural corrections ---
+      | \b stop \s+ (?: doing | saying | using | calling | adding | making | being | sending | putting ) \b
+      | \b (?: do \s* n['’]? t | don['’]? t | do \s+ not ) \s+ (?: ever \s+ )?
+            (?: make | guess | assume | use | say | add | send | call | include | do | put | write | reply | respond | mention ) \b
+      | \b (?: do \s* n['’]? t | don['’]? t | do \s+ not ) \b [^.?!]{0,40} \b again \b
+      | \b (?: should \s* n['’]? t | shouldn['’]? t | should \s+ not ) \b
+      # --- preferences / identity ---
+      | \b (?: i | we ) \s+ (?: prefer | always \s+ want | never \s+ want ) \b
+      | \b i['’]? d \s+ prefer \b
+      | \b call \s+ me \b
+      # --- memory / reinforcement ---
+      | \b remember \s+ (?: to | that | this | always | never ) \b
+      | \b make \s+ sure \s+ (?: you | to | that | not | it ) \b
+      # --- explicit wrongness + restatement ---
+      | \b that['’]? s \s+ (?: wrong | not \s+ right | incorrect | not \s+ what ) \b
+      | \b (?: no ,? \s+ )? it['’]? s \s+ (?: actually | not ) \b
+      | \b (?: that['’]? s | it['’]? s ) \s+ (?: dead | deprecated | retired | closed ) \b
+      | \b we \s+ (?: now \s+ )? (?: use \s+ only | only \s+ use | no \s+ longer \s+ use ) \b
+    )
+    """
+)
+
+# Terse, advisory. The model decides IN-SESSION whether this is a durable
+# rule and, if so, calls create_directive itself (chat-legible). Kept
+# short so it costs a handful of tokens on a false positive.
+_DIRECTIVE_CAPTURE_NUDGE = (
+    "<directive_capture_check>\n"
+    "The latest user message is correction- or standing-rule-shaped "
+    '(e.g. "always/never …", "from now on …", "stop doing …", a stated '
+    'preference, or "that’s wrong, it’s …"). If it states a DURABLE rule '
+    "for how you should behave going forward — not a one-off request for "
+    "this task — persist it NOW with mcp__hindsight__create_directive "
+    "(verbatim, in the user’s own words) BEFORE you answer, so the "
+    "correction survives future sessions. UNLESS an equivalent active "
+    "directive already exists (see any <active_directives> block above) — "
+    "in that case it is already saved; do NOT create a duplicate. If it’s "
+    "only a one-off instruction, ignore this note and just answer.\n"
+    "</directive_capture_check>"
+)
+
+
+def looks_like_standing_rule(text) -> bool:
+    """Deterministic (regex-only) test for correction / standing-rule shape.
+
+    Pleasantry shapes ("always happy to help", "never mind") are scrubbed
+    BEFORE the positive match so they can't trip the bare always/never
+    signals. Returns False on empty / non-string input. No model call —
+    the model does the actual judgment in-session (issue #2848).
+    """
+    if not isinstance(text, str) or not text.strip():
+        return False
+    scrubbed = _DIRECTIVE_NUDGE_NEGATIVE_RE.sub(" ", text)
+    return bool(_DIRECTIVE_NUDGE_RE.search(scrubbed))
+
+
+def _combine_context(base, nudge) -> str:
+    """Join the recall/directives context with the directive-capture nudge,
+    skipping empties. Either may be None/empty. The nudge is kept OUT of the
+    cached / last-recall context (it's transient per-inbound) and appended
+    only at emit time, so a cache hit re-derives it from the current prompt
+    rather than replaying a stale one."""
+    parts = [p for p in (base, nudge) if p]
+    return "\n\n".join(parts)
+
+
 def main():
     config = load_config()
 
@@ -665,6 +827,22 @@ def main():
         debug_log(config, f"Prompt is trivial/stateless ({_ack_form!r}), skipping recall")
         return
 
+    # Switchroom #2848 Stage B — directive-capture nudge. Deterministic
+    # (regex) detection of correction / standing-rule-shaped inbound; when
+    # it fires we append a terse advisory to the additionalContext telling
+    # the model to persist the rule with create_directive if it IS durable.
+    # Computed on `_stripped` (the channel-envelope-stripped text) so the
+    # `<channel …>` wrapper never trips detection. Runs AFTER the ack/
+    # trivial-skip gates (those return early and genuinely need no nudge)
+    # and leaves the recall/directive path below untouched — it only adds
+    # to whatever additionalContext that path emits. On by default;
+    # HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE=false (or memory.directive_capture_nudge:
+    # false) turns it off. No model callsite (claude-native invariant).
+    nudge_block = None
+    if config.get("directiveCaptureNudge", True) and looks_like_standing_rule(_stripped):
+        nudge_block = _DIRECTIVE_CAPTURE_NUDGE
+        debug_log(config, "Directive-capture nudge: inbound looks like a standing rule")
+
     session_id = hook_input.get("session_id") or ""
 
     # Switchroom #303 — push a "📚 recalling memories" status to the
@@ -771,7 +949,10 @@ def main():
             cached_context = None
         if cached_context is not None:
             debug_log(config, f"Recall cache HIT (key={cache_key[:12]}…) — skipping API call")
-            _emit_cached_context(cached_context)
+            # #2848 — append the nudge to the cached context at emit time
+            # (the cache stores nudge-free context; the nudge is re-derived
+            # from the current prompt, so a hit can't replay a stale one).
+            _emit_cached_context(_combine_context(cached_context, nudge_block))
             _write_recall_log({
                 "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
                 "session_id": (session_id or "")[:32],
@@ -790,6 +971,7 @@ def main():
                 "active_thread_id": active_thread_id,
                 "active_topic_alias": active_topic_alias,
                 "topic_filter_mode": _topic_filter_mode(),
+                "directive_nudge": bool(nudge_block),
             })
             return
         debug_log(config, f"Recall cache MISS (key={cache_key[:12]}…)")
@@ -844,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
@@ -889,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
@@ -957,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
@@ -1025,8 +1225,12 @@ def main():
         update_placeholder(placeholder_chat_id, "💭 thinking")
 
     # If neither block has content, there's nothing to inject — exit
-    # silently to avoid emitting an empty hookSpecificOutput.
+    # silently to avoid emitting an empty hookSpecificOutput. #2848: unless
+    # the directive-capture nudge fired, in which case emit the nudge alone
+    # (a correction with no memories/directives still needs the reminder).
     if not directives_block and not memories_block:
+        if nudge_block:
+            _emit_cached_context(nudge_block)
         return
 
     # Compose final context. Directives block goes ABOVE memories so the
@@ -1092,13 +1296,16 @@ def main():
         "source_topics": source_topic_summary,
         "topic_filter_mode": topic_filter_mode,
         "topic_dropped": topic_dropped,
+        "directive_nudge": bool(nudge_block),
     })
 
-    # Output JSON for Claude Code hook system
+    # Output JSON for Claude Code hook system. #2848: append the
+    # directive-capture nudge (if it fired) at emit time — it's kept out of
+    # the cached / last-recall context above so it can't go stale.
     output = {
         "hookSpecificOutput": {
             "hookEventName": "UserPromptSubmit",
-            "additionalContext": context_message,
+            "additionalContext": _combine_context(context_message, nudge_block),
         }
     }
     json.dump(output, sys.stdout)

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

@@ -147,6 +147,23 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
 
     debug_log(config, f"Retain hook_input keys: {list(hook_input.keys())} force={force}")
 
+    # Blocked-Stop double-fire guard (switchroom #2848 Phase 3): when
+    # directive_verify.py blocks a Stop, the model continues and the Stop
+    # event fires AGAIN, this time carrying ``stop_hook_active: true``.
+    # Retaining on that second fire would (a) POST a duplicate transcript
+    # document and (b) at retainEveryNTurns>1 call increment_turn_count a
+    # second time for the SAME logical turn — drifting the cadence throttle.
+    # Skip the re-fire entirely BEFORE any store or turn-count increment.
+    # A forced SessionEnd sweep (force=True) is a distinct hook event and
+    # must always flush, so it is exempt.
+    if not force and hook_input.get("stop_hook_active"):
+        debug_log(
+            config,
+            "Stop re-fire (stop_hook_active=true) — skipping retain to avoid "
+            "duplicate document / turn-count drift",
+        )
+        return {"status": "skipped", "reason": "stop_hook_active"}
+
     session_id = hook_input.get("session_id", "unknown")
     transcript_path = hook_input.get("transcript_path", "")
 

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

@@ -44,6 +44,15 @@ def build_hooks(plugin_root: str) -> dict:
             }
         ],
         "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/directive_verify.py"',
+                        "timeout": 10,
+                    }
+                ]
+            },
             {
                 "hooks": [
                     {