superlocalmemory 4.0.9 → 4.1.0

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

@@ -287,7 +287,7 @@ def _upcoming_scheduled_facts(engine, now: datetime.datetime) -> list[dict]:
             "SELECT fact_id, content, referenced_date"
             " FROM atomic_facts"
             " WHERE profile_id = ?"
-            "   AND fact_type = 'temporal'"
+            "   AND fact_type = 'prospective'"
             "   AND referenced_date IS NOT NULL"
             "   AND referenced_date >= ?"
             "   AND referenced_date < ?"
@@ -312,6 +312,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
     # 1. session_init — Auto-recall project context at session start
     # ------------------------------------------------------------------
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    @admits(OperationKind.RECALL)
     async def session_init(
         project_path: str = "",
         query: str = "",

package/src/superlocalmemory/mcp/tools_core.py

@@ -20,7 +20,7 @@ from typing import Callable
 from mcp.types import ToolAnnotations
 
 from superlocalmemory.core.admission import admits
-from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
+from superlocalmemory.core.config import CANONICAL_LIST_LIMIT, CANONICAL_RECALL_LIMIT
 from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.infra.data_root import state_path
 from superlocalmemory.mcp._daemon_proxy import daemon_unavailable_error
@@ -29,6 +29,19 @@ from superlocalmemory.mcp.shared import authorize_mcp_mutation
 logger = logging.getLogger(__name__)
 
 
+def _projection_queue_depth(db: object) -> int:
+    """Facts queued for the graph and vector projections, or 0 when there are none.
+
+    Imported inside the function: this module is loaded on every MCP start over
+    stdio, where import cost is startup latency a user feels.
+    """
+    try:
+        from superlocalmemory.storage import projection_outbox
+        return projection_outbox.depth(db)
+    except Exception:
+        return 0
+
+
 async def _runtime_profile(get_engine: Callable, explicit: str = "") -> str:
     """Resolve an MCP default profile from daemon runtime truth."""
     if explicit:
@@ -73,6 +86,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 +96,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 +179,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 +359,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,
@@ -424,6 +438,9 @@ def register_core_tools(server, get_engine: Callable) -> None:
                     "score_contract_version": result.get("score_contract_version", "2"),
                     "calibration_status": result.get("calibration_status", "uncalibrated"),
                     "calibration_id": result.get("calibration_id"),
+                    # Quote this back to report_outcome and the report ties to
+                    # this exact answer instead of being matched by guesswork.
+                    "query_id": result.get("query_id", ""),
                     "answer_confidence": result.get("answer_confidence"),
                     "abstained": result.get("abstained", False),
                     "abstention_reason": result.get("abstention_reason"),
@@ -435,7 +452,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     @admits(OperationKind.RECALL)
-    async def search(query: str, limit: int = 10) -> dict:
+    async def search(query: str, limit: int = CANONICAL_RECALL_LIMIT) -> dict:
         """Full-text search across memories using FTS5 with BM25 ranking."""
         try:
             engine = get_engine()
@@ -456,6 +473,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             return {"success": False, "error": str(exc)}
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    @admits(OperationKind.RECALL)
     async def fetch(fact_ids: str) -> dict:
         """Fetch full details for specific fact IDs (comma-separated)."""
         try:
@@ -483,7 +501,8 @@ def register_core_tools(server, get_engine: Callable) -> None:
             return {"success": False, "error": str(exc)}
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
-    async def list_recent(limit: int = 20) -> dict:
+    @admits(OperationKind.RECALL)
+    async def list_recent(limit: int = CANONICAL_LIST_LIMIT) -> dict:
         """List most recently stored memories, newest first."""
         try:
             engine = get_engine()
@@ -510,6 +529,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
     async def get_status() -> dict:
         """Get memory system status: fact count, entity count, mode, profile, db size."""
         try:
+            # Same source the HTTP surface reads, imported here rather than at
+            # module scope: that module costs ~260ms and MCP starts over stdio.
+            from superlocalmemory.server.routes.helpers import SLM_VERSION
+
             import asyncio
             import os
 
@@ -539,6 +562,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
                         "profile_generation": int(
                             daemon_status.get("profile_generation", 0)
                         ),
+                        "version": SLM_VERSION,
+                        "projection_queue_depth": int(
+                            daemon_status.get("projection_queue_depth", 0)
+                        ),
                     }
 
             engine = get_engine()
@@ -575,6 +602,8 @@ def register_core_tools(server, get_engine: Callable) -> None:
                 "entity_count": entity_count,
                 "edge_count": edge_count,
                 "profile_generation": 0,
+                "version": SLM_VERSION,
+                "projection_queue_depth": _projection_queue_depth(engine._db),
             }
         except Exception as exc:
             logger.exception("get_status failed")

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/mcp/tools_v28.py

@@ -36,6 +36,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
         memory_ids: str,
         outcome: str,
         context: str = "",
+        recall_query_id: str = "",
     ) -> dict:
         """Report outcome of using recalled memories.
 
@@ -46,6 +47,10 @@ def register_v28_tools(server, get_engine: Callable) -> None:
             memory_ids: Comma-separated list of fact/memory IDs.
             outcome: One of 'success', 'failure', 'partial'.
             context: Optional freetext context about the outcome.
+            recall_query_id: The ``query_id`` that came back with the recall
+                this report is about. Passing it ties the report to that exact
+                answer; leaving it out falls back to matching on which memories
+                overlap, within a time window.
         """
         try:
             engine = get_engine()
@@ -54,7 +59,20 @@ def register_v28_tools(server, get_engine: Callable) -> None:
                 "update",
                 mutation_source="mcp-report-outcome",
             )
-            from superlocalmemory.learning.outcomes import OutcomeTracker
+            from superlocalmemory.learning.outcomes import (
+                VALID_OUTCOMES,
+                OutcomeTracker,
+            )
+            if outcome not in VALID_OUTCOMES:
+                # Answered here rather than as a stack trace: the caller is an
+                # assistant that can correct itself if told what is allowed.
+                return {
+                    "success": False,
+                    "error": (
+                        f"outcome must be one of {sorted(VALID_OUTCOMES)}, "
+                        f"not {outcome!r}"
+                    ),
+                }
             tracker = OutcomeTracker(engine._db)
             ids = [mid.strip() for mid in memory_ids.split(",") if mid.strip()]
             ctx = {"note": context} if context else None
@@ -64,6 +82,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
                 outcome=outcome,
                 profile_id=engine.profile_id,
                 context=ctx,
+                recall_query_id=str(recall_query_id or "").strip(),
             )
 
             # v3.4.7: Bridge outcomes → learning signals for two-way learning.

package/src/superlocalmemory/parameterization/pattern_extractor.py

@@ -66,7 +66,17 @@ _BEHAVIORAL_TYPE_MAP: dict[str, str] = {
     "query_type": "workflow_pattern",
     "time_of_day": "workflow_pattern",
     "refinement": "communication_style",
-    "interest": "tech_preference",
+    # An "interest" is a word that shows up often in this user's memories. It is
+    # NOT a statement about their tooling, and calling it one produced the
+    # single worst thing this subsystem has shipped: a prompt injected on every
+    # turn reading "the user's preferred technology stack includes: test, gate,
+    # practices, compliance, projects, while, their, processing, data".
+    #
+    # Every one of those words is a real and frequent topic for this user. The
+    # values were right; the claim about them was false. Measured on a live
+    # store, `_store_patterns` holds correct tech_preference rows alongside
+    # these — Node.js, Go, Git, pip — so the two kinds were never the same kind.
+    "interest": "topic_interest",
     "archival": "avoidance",
 }
 
@@ -90,6 +100,9 @@ class PatternCategory(str, Enum):
     WORKFLOW_PATTERN = "workflow_pattern"
     PROJECT_CONTEXT = "project_context"
     DECISION_HISTORY = "decision_history"
+    # Topics that come up a lot in this user's memories. Deliberately separate
+    # from TECH_PREFERENCE: a frequent word is not a tooling choice.
+    TOPIC_INTEREST = "topic_interest"
     AVOIDANCE = "avoidance"
     CUSTOM = "custom"
 

package/src/superlocalmemory/parameterization/soft_prompt_generator.py

@@ -53,6 +53,11 @@ CATEGORY_TEMPLATES: dict[str, str] = {
         "Current active project: {project_name}. "
         "Key context: {context_summary}."
     ),
+    # Says only what is actually known — that these subjects recur — rather
+    # than inferring a preference, a project or a tool choice from them.
+    "topic_interest": (
+        "Subjects that come up often in the user's notes: {topics}."
+    ),
     "decision_history": (
         "Recent key decisions: {decisions}. "
         "These reflect the user's current direction."
@@ -75,6 +80,7 @@ CATEGORY_PRIORITY_ORDER: list[str] = [
     "behavioral",  # v3.4.7: behavioral assertions after communication style
     "workflow_pattern",
     "project_context",
+    "topic_interest",
     "decision_history",
     "avoidance",
 ]
@@ -105,6 +111,82 @@ class SoftPromptTemplate:
 # SoftPromptGenerator class
 # ---------------------------------------------------------------------------
 
+def _empty_words() -> frozenset[str]:
+    """Words that say nothing about a person when listed as a preference.
+
+    Read from the list the miner already filters on, so there is one definition
+    to extend rather than two that drift.
+    """
+    try:
+        from superlocalmemory.learning.pattern_miner_constants import STOPWORDS
+
+        return frozenset(STOPWORDS)
+    except Exception:  # pragma: no cover — the check degrades to "keep it"
+        return frozenset()
+
+
+_EMPTY_WORDS = _empty_words()
+
+
+def _is_substantive(category: str, values: dict[str, str]) -> bool:
+    """Whether a rendered prompt says anything at all about the user.
+
+    Deliberately weak, and it got that way by being wrong in the other
+    direction first. The original version required a ``tech_preference`` claim to
+    name something from a fixed vocabulary of technologies — which discarded
+    ``Node.js``, ``Git``, ``pip``, ``npm``, ``zig`` and every stack the list did
+    not happen to enumerate. Those were the GENUINE rows on a live store. A
+    filter that silently drops real preferences to catch fake ones is a worse
+    failure than the one it was added for, because nothing reports it.
+
+    What it was actually added for no longer arrives here. The live nonsense —
+    "preferred technology stack includes: test, gate, practices, compliance,
+    projects, while, their, processing, data" — came from word-frequency topics
+    being mapped onto this category, and they are now their own category, where
+    the same words form a true statement. This is the remaining floor: a prompt
+    built entirely out of words that appear in most English sentences says
+    nothing, whatever category it lands in.
+
+    Length is checked per TERM and only against that word list, never as a
+    minimum: "CTO", "AWS", "npm" and "R" are all shorter than a threshold would
+    allow and all mean something.
+    """
+    filled = [
+        v.strip() for v in values.values()
+        if isinstance(v, str) and v.strip()
+    ]
+    if not filled:
+        return False
+    terms = [
+        t.strip().lower()
+        for value in filled
+        for t in value.replace(";", ",").split(",")
+        if t.strip()
+    ]
+    if not terms:
+        return False
+    return any(term not in _EMPTY_WORDS for term in terms)
+
+
+def _fix_stutter(content: str) -> str:
+    """Remove the duplicated conjunction where a template meets its value.
+
+    ``"The user typically {workflow_description}"`` was rendering as "The user
+    typically When when using X" — the template supplies the lead-in and the
+    value already starts with its own. Observed on 19 of 34 stored prompts.
+    """
+    import re as _re
+
+    for word in ("when", "typically", "prefers", "often", "usually"):
+        content = _re.sub(
+            rf"\b({word})\s+{word}\b", r"\1", content, flags=_re.IGNORECASE,
+        )
+    # "typically When when" collapses to "typically When"; then the lead-in and
+    # the value's own opener are adjacent duplicates of different case.
+    content = _re.sub(r"\btypically\s+When\b", "typically, when", content)
+    return content
+
+
 class SoftPromptGenerator:
     """Convert extracted pattern assertions into natural language soft prompts.
 
@@ -243,12 +325,25 @@ class SoftPromptGenerator:
 
         # Clean up
         content = self._clean_content(content)
+        content = _fix_stutter(content)
 
         # Filter PII
         content = self._pii_filter.filter_text(content)
         if not content.strip():
             return None
 
+        # A prompt that says nothing must not be injected. These go into the
+        # model's context on every turn, so an empty claim is not neutral — it
+        # spends the budget and asserts something false. Measured on a live
+        # store: 15 of 34 stored prompts read "the user's preferred technology
+        # stack includes: data, processing, their, projects, test", built from
+        # common words that happened to appear near a technology keyword.
+        if not _is_substantive(category, values):
+            logger.debug(
+                "soft prompt for %r dropped: no substantive values", category,
+            )
+            return None
+
         # Trim to 100 tokens per category
         content = self._trim_to_tokens(content, 100)
 
@@ -305,6 +400,9 @@ class SoftPromptGenerator:
         elif category == "workflow_pattern":
             values["workflow_description"] = "; ".join(pat_values)
 
+        elif category == "topic_interest":
+            values["topics"] = ", ".join(pat_values)
+
         elif category == "project_context":
             values["project_name"] = pat_values[0] if pat_values else ""
             values["context_summary"] = ", ".join(pat_values[1:])

package/src/superlocalmemory/retrieval/bm25_channel.py

@@ -54,6 +54,65 @@ def tokenize(text: str) -> list[str]:
     return [t for t in tokens if t not in _STOPWORDS]
 
 
+#: Saturation constant for the BM25 -> [0,1) transform. Chosen from measurement,
+#: not taste: raw scores on a live store run ~2.5 to ~15 across query
+#: lengths, so k = 5 puts an ordinary match near 0.4 and a strong one near 0.7,
+#: leaving headroom at both ends rather than pinning everything to one corner.
+_BM25_SATURATION = 5.0
+
+
+def _to_unit_scale(scored: list[tuple[str, float]]) -> list[tuple[str, float]]:
+    """Map BM25 scores into [0, 1) without disturbing order or magnitude.
+
+    WHY ANY OF THIS. ``engine.apply_channel_weights`` re-scores a candidate as
+    ``sum(channel_scores[ch] * weights[ch])`` — a SUM of raw channel scores.
+    Every other channel is bounded: semantic cosine and Fisher-Rao are [0, 1],
+    the temporal proximity score is Gaussian on [0, 1]. BM25 is not. Measured on
+    a live store, one query at a time::
+
+        "slm release"                                    max  2.845
+        "memory"                                         max  3.865
+        "the release ships once both audits are clean"    max 10.150
+
+    So the sum was decided by a scale rather than by evidence, and any weight
+    the bandit converged on was a correction for that scale — wrong the moment
+    the query length changed.
+
+    WHY NOT DIVIDE BY THE BATCH MAXIMUM. That was the first implementation here
+    and it is wrong, which an existing test caught before it shipped:
+    ``test_real_fts5_exact_hit_keeps_bounded_slot`` exists to prove *"a real
+    sub-1.0 FTS5 hit remains visible under semantic pressure"*. Dividing by the
+    batch maximum makes the best result exactly 1.0 **whatever it scored**, so a
+    query with one weak lexical match reports full confidence and outranks a
+    semantic channel it should lose to. Batch-relative scaling manufactures
+    confidence out of an empty batch, and it also makes a fact's score depend on
+    which other facts happened to come back — the same query returning a
+    different number on a different day, which HARD-RULES RULE 6 puts above
+    speed.
+
+    A saturating transform has neither problem: ``s / (s + k)`` is strictly
+    increasing, so order is untouched; it is bounded below 1.0, so nothing is
+    ever certain; and it depends only on the score itself, so it is repeatable.
+    Applied to the measurements above: 2.676 -> 0.35, 2.845 -> 0.36,
+    3.865 -> 0.44, 10.150 -> 0.67.
+
+    FUSION IS UNAFFECTED, verified by reading ``fusion.weighted_rrf`` rather
+    than assuming: it computes ``fused += w / (k + rank)`` and keeps the score
+    only for reporting. Rescaling a value nothing divides by cannot move a
+    fused rank.
+
+    Non-positive scores map to 0.0. FTS5's ``bm25()`` is <= 0 and is negated
+    here, so a value at or below zero means "no lexical evidence", and that is
+    what it should contribute to a sum.
+    """
+    if not scored:
+        return scored
+    return [
+        (fid, (s / (s + _BM25_SATURATION)) if s > 0.0 else 0.0)
+        for fid, s in scored
+    ]
+
+
 class BM25Channel:
     """Persistent BM25Plus index for keyword retrieval.
 
@@ -221,14 +280,10 @@ class BM25Channel:
             include_shared=include_shared,
             prefix="af",
         )
-        # Archived facts are not live; never surface them in keyword recall.
-        # Guarded on column presence: the archive column is added by a deferred
-        # migration and may be absent on an unmigrated database.
-        archive_clause = (
-            " AND COALESCE(af.archive_status, 'live') != 'archived'"
-            if self._db._has_archive_status()
-            else ""
-        )
+        # Soft-deleted and withheld rows are not live. Filtered HERE rather
+        # than only at hydration so neither spends one of this channel's top_k
+        # slots; the shared clause keeps the definition in one place.
+        archive_clause = self._db.visible_fact_clause("af")
         sql = (
             "SELECT af.fact_id AS fact_id, bm25(atomic_facts_fts) AS rank "
             "FROM atomic_facts_fts "
@@ -304,10 +359,10 @@ class BM25Channel:
         # Falls back to rank_bm25 ONLY if the FTS5 table is genuinely
         # unavailable (raises) — e.g. a pre-FTS legacy DB.
         try:
-            return self._fts5_search(
+            return _to_unit_scale(self._fts5_search(
                 query, profile_id, top_k,
                 include_global=include_global, include_shared=include_shared,
-            )
+            ))
         except Exception as exc:  # pragma: no cover — legacy/missing FTS table
             logger.debug(
                 "BM25 FTS5 path unavailable, using rank_bm25 fallback: %s", exc,
@@ -342,7 +397,9 @@ class BM25Channel:
                 scored.append((self._fact_ids[i], bonus))
 
         scored.sort(key=lambda x: (-x[1], x[0]))
-        return scored[:top_k]
+        # Same rescale as the FTS5 path. This fallback applies a 1.5x exact
+        # phrase bonus, so its raw ceiling is higher still.
+        return _to_unit_scale(scored[:top_k])
 
     def update_fact(self, fact_id: str, new_content: str, profile_id: str) -> None:
         """Replace a fact's representation in the live index and persist new tokens.