superlocalmemory 4.0.9 → 4.0.10

package/src/superlocalmemory/core/maintenance.py

@@ -31,6 +31,16 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+
+class _ConsolidationDisabled(Exception):
+    """Internal signal: consolidation is switched off, so skip its block.
+
+    A private exception rather than restructuring the surrounding try/except:
+    the block's job is to keep one optional maintenance step from taking the
+    whole pass down with it, and that guarantee should not be weakened to
+    express "deliberately skipped". Caught immediately below, never propagated.
+    """
+
 # Backfill constants
 _BACKFILL_BURN_IN_STEPS = 50
 _LANGEVIN_DIM = 8
@@ -638,9 +648,12 @@ def run_maintenance(
         logger.warning("Entity summary consolidation failed: %s", exc)
 
     # 4. Fact consolidation (v3.8.4 concurrency-safe path via DatabaseManager).
-    # Merges clusters of warm/cold atomic facts about the same entity into a
-    # single consolidated fact, archives the originals (NEVER deletes them),
-    # and records provenance in fact_consolidations.
+    # Groups warm/cold atomic facts that share an entity and writes ONE
+    # DISPLAY summary per cluster into consolidated_summaries, with provenance
+    # in fact_consolidations. It does not write to atomic_facts and does not
+    # archive the source facts — until 4.0.10 it did both, which put 1,195
+    # model-written rows into the retrieval corpus and left 528 genuine
+    # memories archived out of normal recall.
     #
     # Uses the DatabaseManager path so LLM calls happen OUTSIDE the write lock:
     #   - Discover clusters in a short memory_read() (no write lock held).
@@ -652,20 +665,45 @@ def run_maintenance(
     try:
         from superlocalmemory.core.fact_consolidator import consolidate_facts
 
+        # The documented off-switch has to actually switch something off.
+        # ConsolidationConfig.enabled has existed since Phase 5 and this call
+        # site never read it, so a user who ran `slm config` to turn
+        # consolidation off got consolidation anyway — for four months, on
+        # every maintenance pass. -2 is a third distinguishable value, kept
+        # apart from 0 (nothing to merge) and -1 (the step failed), so a
+        # deliberately disabled step is never mistaken for either.
+        _consolidation = getattr(config, "consolidation", None)
+        if _consolidation is not None and not getattr(_consolidation, "enabled", True):
+            counts["facts_consolidated"] = -2
+            logger.debug("Fact consolidation disabled by configuration")
+            raise _ConsolidationDisabled
+
         fc_stats = consolidate_facts(
             db,
             profile_id=profile_id,
-            max_clusters=getattr(config, "max_consolidation_clusters", 20),
+            # Read from ConsolidationConfig, with the old SLMConfig-level name
+            # as the fallback. `getattr(config, "max_consolidation_clusters")`
+            # alone never resolved — SLMConfig has no such attribute — so the
+            # default was the only value this had ever used.
+            max_clusters=int(
+                getattr(_consolidation, "max_consolidation_clusters", None)
+                or getattr(config, "max_consolidation_clusters", None)
+                or 20
+            ),
             dry_run=False,
             config=config,
         )
         counts["facts_consolidated"] = fc_stats.get("consolidated", 0)
         if fc_stats.get("consolidated", 0) > 0:
             logger.info(
-                "Fact consolidation: %d clusters merged, %d facts archived",
+                "Fact consolidation: %d display summaries over %d facts "
+                "(%d clusters refused)",
                 fc_stats.get("consolidated", 0),
-                fc_stats.get("facts_archived", 0),
+                fc_stats.get("facts_summarized", 0),
+                fc_stats.get("rejected", 0),
             )
+    except _ConsolidationDisabled:
+        pass
     except Exception as exc:
         # WARNING, not debug, and a distinguishable count. Leaving this at debug
         # with facts_consolidated=0 made a failing consolidation report exactly

package/src/superlocalmemory/core/memory_health.py

@@ -0,0 +1,266 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Tell the owner, in their own words, whether their memory works.
+
+Until now the only way to learn that 43.7% of a store could not be found by
+asking a question was to write the SQL yourself. One machine sat in exactly
+that state for months while every status line it showed said the system was
+healthy, because nothing measured reachability and nothing reported it.
+
+So this module answers four questions a non-engineer can act on:
+
+  * How many memories do I have?
+  * How many can actually be found by asking a question?
+  * How many were withheld because a model wrote them, not me?
+  * Is anything still being repaired?
+
+Read-only, and every query is bounded. Fail-soft by construction: a missing
+table or column yields ``None`` for that line rather than an exception, because
+a health report that crashes on an old store is worse than one that says "not
+known yet".
+
+Consumed by ``slm doctor``, ``GET /api/v3/memory-health``, and the dashboard.
+One implementation so the three cannot disagree with each other.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["MemoryHealth", "measure", "describe"]
+
+
+@dataclass(frozen=True)
+class MemoryHealth:
+    """A store's answer-ability, counted rather than assumed."""
+
+    #: Memories that recall is allowed to return.
+    live_facts: int = 0
+    #: Of those, how many have a vector projection, i.e. can be found by
+    #: meaning rather than only by matching words.
+    findable_by_meaning: int = 0
+    #: Memories with no vector at all. These are reachable by keyword only.
+    missing_vector: int = 0
+    #: Machine-written summaries withheld from recall and kept for display.
+    withheld_summaries: int = 0
+    #: Summaries preserved in the display table.
+    display_summaries: int = 0
+    #: Memories hidden by the retention system, excluding the withheld ones.
+    hidden_by_forgetting: int = 0
+    #: Rows whose retention zone contradicts their retention score, i.e. hidden
+    #: while the maths says to keep them. Should be zero after repair.
+    inconsistently_hidden: int = 0
+    #: Present only when a table or column was absent.
+    unavailable: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def reachability(self) -> float:
+        """Share of live memories findable by meaning, 0.0-1.0."""
+        if self.live_facts <= 0:
+            return 1.0
+        return self.findable_by_meaning / self.live_facts
+
+    @property
+    def healthy(self) -> bool:
+        """Whether anything here warrants telling the owner about."""
+        return (
+            self.reachability >= 0.99
+            and self.missing_vector == 0
+            and self.inconsistently_hidden == 0
+        )
+
+
+def measure(db_path: str | Path) -> MemoryHealth:
+    """Count the store's answer-ability. Read-only; never raises."""
+    unavailable: list[str] = []
+    try:
+        conn = sqlite3.connect(f"file:{Path(db_path)}?mode=ro", uri=True)
+    except sqlite3.Error as exc:
+        logger.debug("memory health: cannot open %s: %s", db_path, exc)
+        return MemoryHealth(unavailable=("database",))
+
+    try:
+        if not _table_exists(conn, "atomic_facts"):
+            return MemoryHealth(unavailable=("atomic_facts",))
+
+        # Quarantine came in 4.0.10. On an older store every fact is "live",
+        # which is the honest reading of a store that has no withheld rows.
+        has_q = _has_column(conn, "atomic_facts", "quarantined")
+        if not has_q:
+            unavailable.append("quarantined")
+        live_clause = "COALESCE(quarantined, 0) = 0" if has_q else "1=1"
+
+        live = _count(conn, f"SELECT COUNT(*) FROM atomic_facts WHERE {live_clause}")
+        withheld = (
+            _count(conn, "SELECT COUNT(*) FROM atomic_facts WHERE quarantined = 1")
+            if has_q else 0
+        )
+        missing_vec = _count(
+            conn,
+            f"SELECT COUNT(*) FROM atomic_facts "
+            f"WHERE embedding IS NULL AND {live_clause}",
+        )
+
+        if _table_exists(conn, "embedding_metadata"):
+            findable = _count(
+                conn,
+                "SELECT COUNT(*) FROM embedding_metadata em "
+                "JOIN atomic_facts af ON af.fact_id = em.fact_id "
+                f"WHERE {_prefixed(live_clause, 'af')}",
+            )
+        else:
+            unavailable.append("embedding_metadata")
+            findable = 0
+
+        display = (
+            _count(conn, "SELECT COUNT(*) FROM consolidated_summaries")
+            if _table_exists(conn, "consolidated_summaries") else 0
+        )
+        if not _table_exists(conn, "consolidated_summaries"):
+            unavailable.append("consolidated_summaries")
+
+        hidden = inconsistent = 0
+        if _table_exists(conn, "fact_retention"):
+            hidden = _count(
+                conn,
+                "SELECT COUNT(*) FROM fact_retention r "
+                "JOIN atomic_facts af ON af.fact_id = r.fact_id "
+                "WHERE r.lifecycle_zone IN ('archive', 'forgotten') "
+                f"  AND {_prefixed(live_clause, 'af')}",
+            )
+            # The contradiction M043 repairs: hidden, yet scored to keep.
+            inconsistent = _count(
+                conn,
+                "SELECT COUNT(*) FROM fact_retention r "
+                "JOIN atomic_facts af ON af.fact_id = r.fact_id "
+                "WHERE r.lifecycle_zone IN ('archive', 'forgotten') "
+                "  AND r.retention_score > 0.8 "
+                f"  AND {_prefixed(live_clause, 'af')}",
+            )
+        else:
+            unavailable.append("fact_retention")
+
+        return MemoryHealth(
+            live_facts=live,
+            findable_by_meaning=findable,
+            missing_vector=missing_vec,
+            withheld_summaries=withheld,
+            display_summaries=display,
+            hidden_by_forgetting=hidden,
+            inconsistently_hidden=inconsistent,
+            unavailable=tuple(unavailable),
+        )
+    except sqlite3.Error as exc:
+        logger.debug("memory health measurement failed: %s", exc)
+        return MemoryHealth(unavailable=(*unavailable, "query_failed"))
+    finally:
+        conn.close()
+
+
+def describe(health: MemoryHealth) -> list[str]:
+    """Plain-language lines for a reader who does not write SQL.
+
+    No percentages without the counts behind them, and no jargon: "findable by
+    asking a question" rather than "vector coverage", because the person who
+    needs this line is the one who would not know what a vector is.
+    """
+    lines: list[str] = []
+    if "atomic_facts" in health.unavailable or "database" in health.unavailable:
+        return ["Memory store not readable yet."]
+
+    lines.append(f"You have {health.live_facts:,} memories.")
+
+    if "embedding_metadata" in health.unavailable:
+        lines.append(
+            "Whether they can be found by asking a question is not known yet — "
+            "the search index has not been built."
+        )
+    elif health.live_facts:
+        pct = 100.0 * health.reachability
+        if health.findable_by_meaning >= health.live_facts:
+            # "All" only when the counts actually agree. The threshold used to
+            # be reachability >= 0.99, which printed "All of them can be found
+            # by asking a question (5,199 indexed)" on a store of 5,205 — a
+            # claim of all, contradicted by the number beside it. This module
+            # exists to be believed; it cannot round in its own favour.
+            lines.append(
+                f"All {health.live_facts:,} of them can be found by asking a "
+                f"question."
+            )
+        elif health.reachability >= 0.99:
+            gap = health.live_facts - health.findable_by_meaning
+            lines.append(
+                f"{health.findable_by_meaning:,} of them can be found by asking "
+                f"a question. The other {gap:,} can only be found by matching "
+                f"words. That is a small enough share to be normal — a memory "
+                f"written moments ago, or one the model could not read."
+            )
+        else:
+            gap = health.live_facts - health.findable_by_meaning
+            lines.append(
+                f"{health.findable_by_meaning:,} of them ({pct:.0f}%) can be "
+                f"found by asking a question. The other {gap:,} can only be "
+                f"found by matching words, so a question phrased differently "
+                f"will miss them. This repairs itself as the service runs; if "
+                f"it does not, the embedding model is unavailable."
+            )
+
+    if health.withheld_summaries:
+        lines.append(
+            f"{health.withheld_summaries:,} machine-written summaries are kept "
+            f"out of your answers and shown on the dashboard instead. They were "
+            f"written by the summarizer, not by you, and they used to be "
+            f"returned as if they were your own notes."
+        )
+
+    if health.inconsistently_hidden:
+        lines.append(
+            f"{health.inconsistently_hidden:,} memories are hidden even though "
+            f"they are marked worth keeping. This is a fault and it is repaired "
+            f"automatically the next time the service starts."
+        )
+
+    if health.hidden_by_forgetting:
+        lines.append(
+            f"{health.hidden_by_forgetting:,} older memories are set aside by "
+            f"the forgetting curve. They are not deleted and a deep search "
+            f"still reaches them."
+        )
+
+    return lines
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    return conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,),
+    ).fetchone() is not None
+
+
+def _has_column(conn: sqlite3.Connection, table: str, column: str) -> bool:
+    return any(
+        row[1] == column for row in conn.execute(f"PRAGMA table_info({table})")
+    )
+
+
+def _prefixed(clause: str, prefix: str) -> str:
+    """Qualify a bare column reference for use in a joined query.
+
+    Word-bounded, so a future column named ``quarantined_at`` is not silently
+    rewritten to ``af.quarantined_at`` by a substring match. No such column
+    exists today; the point is that the failure would be a wrong count rather
+    than an error, and a wrong count in a health report is the one thing this
+    module must not produce.
+    """
+    return re.sub(r"\bquarantined\b", f"{prefix}.quarantined", clause)
+
+
+def _count(conn: sqlite3.Connection, sql: str) -> int:
+    row = conn.execute(sql).fetchone()
+    return int(row[0]) if row else 0

package/src/superlocalmemory/core/operation_policy_registry.py

@@ -281,7 +281,7 @@ class OperationPolicyRegistry:
                 allowed_transports=_ALL_TRANSPORTS,
                 audit_level="full",
             ),
-            # Operational recovery & admin remediation (Wave-3 resilience slice)
+            # Operational recovery & admin remediation (resilience slice)
             # OPS_INSPECT: read-only listing of failed/stuck/degraded ops.
             # Allowed over all transports so dashboard, MCP, and CLI all work.
             OperationKind.OPS_INSPECT: OperationPolicy(

package/src/superlocalmemory/core/operation_request.py

@@ -51,7 +51,7 @@ class OperationKind(str, Enum):
     SCHEMA_MIGRATE = "schema_migrate"
     VECTOR_MIGRATE = "vector_migrate"
     EVOLVE_SKILL = "evolve_skill"
-    # Operational recovery & admin remediation (V4 Wave-3 resilience slice)
+    # Operational recovery & admin remediation (V4 resilience slice)
     OPS_INSPECT = "ops_inspect"    # List failed/stuck/degraded operations (OWNER/ADMIN)
     OPS_RESOLVE = "ops_resolve"    # Retry/force-reconcile/cancel an operation (OWNER/ADMIN)
 

package/src/superlocalmemory/core/ops_remediation.py

@@ -1,7 +1,7 @@
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Licensed under AGPL-3.0-or-later - see LICENSE file
 
-"""Operational Recovery & Admin Remediation helpers (Wave-3 resilience slice).
+"""Operational Recovery & Admin Remediation helpers (resilience slice).
 
 Provides two primary functions used by HTTP endpoints, MCP tools, and CLI:
 
@@ -22,7 +22,7 @@ Design constraints (NON-NEGOTIABLE):
     - Additive & backward-compatible — healthy-path unaffected
     - Immutable return dicts; explicit error handling; no silent swallowing
 
-Part of SuperLocalMemory V4 | Wave-3: Operational Recovery
+Part of SuperLocalMemory V4 | Operational Recovery
 """
 
 from __future__ import annotations

package/src/superlocalmemory/core/store_pipeline.py

@@ -118,6 +118,54 @@ def _record_correction_candidate(
         logger.warning("Correction candidate not recorded for %s: %s", successor_fact_id, exc)
 
 
+#: Entity id pattern for the per-profile placeholder a dated fact with no
+#: resolved entity points its temporal event at. Per profile, not shared, so
+#: profile deletion cascades it away with everything else.
+_UNRESOLVED_ENTITY_PREFIX = "__slm_unresolved__:"
+
+
+def _ensure_unresolved_entity(db: Any, profile_id: str) -> str | None:
+    """Return the placeholder entity id for ``profile_id``, creating it once.
+
+    ``temporal_events.entity_id`` is NOT NULL with a foreign key to
+    ``canonical_entities``, so an event for a fact with no recognised entity
+    needs something real to reference. This is that something.
+
+    It is deliberately inert as an entity:
+
+      * Its ``canonical_name`` is empty, and the only query that resolves an
+        entity by name (``retrieval/temporal_channel.py``, the "events for
+        entity X" lookup) is driven by names extracted from the user's
+        question, which are never empty.
+      * Nothing derives entity links from ``temporal_events``. The entity
+        channel builds its map from ``atomic_facts.canonical_entities_json``,
+        which this does not touch — so the placeholder cannot become the kind
+        of entity that links a quarter of the store and flattens entity
+        proximity. That failure mode is real (on the author's store 'State'
+        links 1,388 facts) and this is specifically shaped not to add to it.
+      * ``fact_count`` stays 0. It is a hook for a foreign key, not a concept.
+
+    Returns None if the row cannot be created, in which case the caller skips
+    the temporal event rather than failing the write — a missing temporal row
+    is a degraded memory, an aborted remember is a lost one.
+    """
+    entity_id = f"{_UNRESOLVED_ENTITY_PREFIX}{profile_id}"
+    try:
+        db.execute(
+            "INSERT OR IGNORE INTO canonical_entities "
+            "(entity_id, profile_id, canonical_name, entity_type, fact_count) "
+            "VALUES (?, ?, '', 'unresolved', 0)",
+            (entity_id, profile_id),
+        )
+        return entity_id
+    except Exception as exc:  # noqa: BLE001 — never fail a write over this
+        logger.debug(
+            "temporal placeholder entity unavailable for %s: %s",
+            profile_id, exc,
+        )
+        return None
+
+
 def _record_fact_entity_association(
     db: DatabaseManager,
     *,
@@ -1031,12 +1079,39 @@ def run_store(
         if scene_builder:
             scene_builder.assign_to_scene(fact, profile_id)
 
-        # Populate temporal_events for temporal retrieval
+        # Populate temporal_events for temporal retrieval.
+        #
+        # A DATE IS A DATE WHETHER OR NOT AN ENTITY WAS RESOLVED. This used to
+        # read `if fact.canonical_entities and has_dates`, so a fact carrying a
+        # perfectly good date but no recognised entity got no temporal row at
+        # all. Measured on the author's store: 967 of 3,894 genuine facts have
+        # no canonical entity (24.8%), and 958 of those have no temporal event
+        # either — a quarter of the store that the temporal channel could only
+        # reach through its created_at recency fallback, i.e. by being recent
+        # rather than by being about the right time.
+        #
+        # The date-window query does not need the entity: it joins
+        # temporal_events to atomic_facts and nothing else
+        # (retrieval/temporal_channel.py). Only the "events for entity X"
+        # lookup joins canonical_entities, and that lookup is correctly
+        # uninterested in a fact with no entity.
+        #
+        # temporal_events.entity_id is NOT NULL with an FK to
+        # canonical_entities, so an entity-less event needs a row to point at.
+        # It gets a per-profile sentinel rather than a shared one, and the
+        # sentinel is invisible to ranking: the entity channel builds its map
+        # from atomic_facts.canonical_entities_json, which is untouched here, so
+        # this cannot create the kind of entity that links a quarter of the
+        # store and destroys entity proximity.
         has_dates = (fact.observation_date or fact.referenced_date
                      or fact.interval_start)
-        if fact.canonical_entities and has_dates:
+        if has_dates:
             from superlocalmemory.storage.models import TemporalEvent
-            for eid in fact.canonical_entities:
+            entity_ids = list(fact.canonical_entities)
+            if not entity_ids:
+                sentinel = _ensure_unresolved_entity(db, profile_id)
+                entity_ids = [sentinel] if sentinel else []
+            for eid in entity_ids:
                 event = TemporalEvent(
                     event_id=_ingestion_effect_id(
                         ingestion_operation_id,

package/src/superlocalmemory/encoding/cognitive_consolidator.py

@@ -327,6 +327,17 @@ class CognitiveConsolidator:
               AND r.lifecycle_zone IN ('warm', 'cold')
               AND r.retention_score < ?
               AND f.lifecycle != 'forgotten'
+              -- Withheld rows are not candidates, and this is not tidiness.
+              -- 304 of them remain warm/cold in atomic_facts after 4.0.10
+              -- withholds them, and each still carries its cluster's POOLED
+              -- canonical_entities_json. CCQ clusters on entity overlap, so one
+              -- withheld summary naming ten entities joins a cluster of real
+              -- memories, contributes model prose to the gist, and then this
+              -- pass archives every source in the cluster -- including the real
+              -- memories, at scores M043's restore would not bring back.
+              -- Exactly the damage this release exists to stop, on a path the
+              -- release did not otherwise touch.
+              AND COALESCE(f.quarantined, 0) = 0
               AND f.fact_id NOT IN (
                   SELECT je.value
                   FROM ccq_consolidated_blocks ccb,
@@ -494,7 +505,10 @@ class CognitiveConsolidator:
             f"SELECT fact_id, content, importance, confidence, "
             f"       canonical_entities_json "
             f"FROM atomic_facts "
-            f"WHERE fact_id IN ({placeholders}) AND profile_id = ?",
+            f"WHERE fact_id IN ({placeholders}) AND profile_id = ? "
+            # Belt and braces with the identify query above: a cluster assembled
+            # before a row was withheld must not contribute its text to a gist.
+            f"  AND COALESCE(quarantined, 0) = 0",
             (*cluster.fact_ids, profile_id),
         )
 

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

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