merge: T78 search_memories docstring SQL-bias note

chat/state/memory.py

@@ -125,6 +125,16 @@ def search_memories(
     so that stronger candidates yield smaller composite scores; the result is
     sorted ascending and truncated to ``k``. The unmodified ``fts_rank`` and a
     debug-friendly ``composite_score`` are kept on each returned dict.
+
+    The result ordering applies TWO independent significance boosts:
+
+    * **SQL-side** — ``ORDER BY (rank - significance * SIGNIFICANCE_RANK_BIAS)``
+      pushes higher-significance memories ahead in the FTS5 candidate set so
+      the over-fetch already prefers them for tied / near-tied BM25 ranks
+      (T57, §11.1).
+    * **Python-side** — a composite re-rank with ``_SIGNIFICANCE_WEIGHT``
+      reinforces the ordering after candidate retrieval, alongside the
+      recency boost above.
     """
     if witness_role not in _VALID_WITNESS_ROLES:
         raise ValueError(