lean-memory 0.1.0__py3-none-any.whl

lean_memory/extract/router.py

@@ -0,0 +1,418 @@
+"""Pass 3 — the recall-biased router (design-spec §5, Pass 3).
+
+After Pass 1 (rules) and Pass 2 (GLiNER2) over-generate high-recall candidates, the
+vast majority are *trivially explicit, high-confidence, intra-utterance* facts that a
+local LLM would only rubber-stamp at a cost. The router's job is to spend the LLM
+budget only where deterministic extraction is known to fail (BET 2, corrected 2026-06:
+GLiNER2-class relation typing is weak — ~17.8% zero-shot Micro-F1 — and inferential /
+cross-turn edges are exactly the residual the LLM must own).
+
+A candidate is ESCALATED to the Pass-4 LLM-typing batch if ANY of:
+  1. GLiNER2 confidence below `conf_threshold`          — the parser is unsure;
+  2. coreference / ellipsis / zero-pronoun detected      — the span isn't self-contained;
+  3. it is a possible `derives` (inferential) edge        — only the LLM may emit `is_inference=1`.
+Everything else is routed `direct` (skips the LLM) and gets the cheap `asserts`/slot path.
+
+RETIRED (Task 6, 2026-07): a former criterion escalated any candidate touching a
+*previously-seen* entity (`known_entities`). It fired on 52.8% of real conversational
+candidates (subject re-mention is normal discourse, not a hard cross-turn case) and was
+the last confidence-independent floor over the <20% gate. Entity linking is deterministic
+by name (`upsert_entity`); genuinely ambiguous references still escalate via coref, and
+inferential edges via derives. `known_entities` is still accepted (the typer uses the
+names as context) but no longer drives escalation.
+
+WHY this is its own deterministic pass (no model): the router IS the cost story. The
+spec gates the whole BET-2 design on escalation rate staying < 20%; if it trends to
+100% the hybrid is no cheaper than 100%-LLM and we revisit. So the router must be pure
+stdlib, fully reproducible, and — critically — must surface its escalation rate as a
+first-class, inspectable metric (`last_stats`) that the BET-2 ablation harness reads.
+
+Like FakeEmbedder / IdentityReranker in Phase 0, this is the always-offline default:
+zero downloads, zero servers, deterministic. The real GLiNER2 (Pass 2) and Ollama LLM
+(Pass 4) sit behind their own interfaces with their own stubs; the router never calls
+either — it only *decides* who gets escalated, from the candidate metadata alone.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Iterable, Optional
+
+# `Candidate` is the Pass-2 output contract, owned by the sibling taxonomy module.
+# We import the symbol for type-hinting (the load-bearing module boundary), but read
+# its fields through defensive accessors below so a parallel-built `Candidate` whose
+# exact attribute names differ slightly still routes correctly rather than crashing.
+from .taxonomy import Candidate
+
+# ── escalation reason codes (stable strings → cheap to assert on / aggregate) ──
+REASON_LOW_CONF = "low_confidence"
+REASON_COREF = "coreference"
+# DEPRECATED (Task 6, 2026-07): `prior_entity` was retired as an escalation trigger
+# (subject re-mention fired on 52.8% of real candidates — normal discourse, not a hard
+# case; entity linking is deterministic by name, ambiguous refs escalate via coref).
+# The constant is kept because historical probe/telemetry JSONs reference the string;
+# the router never emits it anymore. See _reasons() and the calibration README.
+REASON_PRIOR_ENTITY = "prior_entity"
+REASON_DERIVES = "derives"
+REASON_PRE_FLAGGED = "pre_flagged"  # Pass-2 `needs_typing` already requested typing
+
+# The relation taxonomy. `derives` is LLM-only (is_inference=1); the deterministic
+# passes may only ever propose the structural three. An unknown/empty predicate is
+# itself a signal that typing is needed, so it escalates.
+_STRUCTURAL_RELATIONS = frozenset({"asserts", "supersedes", "extends"})
+_KNOWN_PREDICATES = frozenset(
+    {
+        # The full slot lexicon emitted by Pass 1 (rules) AND Pass 2 (gliner_extractor
+        # DEFAULT_RELATION_TYPES + _VERB_RELATIONS). Must stay a SUPERSET of both, else
+        # a confidently-typed predicate gets mis-escalated as "possible derives" and the
+        # escalation rate blows past the BET-2 <20% target on the offline default.
+        "works_at",
+        "lives_in",
+        "located_in",
+        "likes",
+        "dislikes",
+        "is_a",
+        "has",
+        "uses",
+        "knows",
+        # gliner_extractor DEFAULT_RELATION_TYPES extras not in the original list:
+        "owns",
+        "member_of",
+        # common predicates the typer and gold set exercise (commutes_by, speaks, etc.
+        # are *inferential* slots — they stay out; the ones below are explicit):
+        "drives",
+        "speaks",
+        "plays",
+        "skilled_in",
+        "interested_in",
+        "works_in",
+        "commutes_by",
+    }
+) | _STRUCTURAL_RELATIONS
+
+# ── coreference / ellipsis heuristics ──
+# Endpoint-level pronouns/demonstratives: a candidate whose OWN subject or object
+# is one of these is not self-contained. This replaces the old whole-text scan,
+# which fired on conversational filler ("that", "it", "there") in 65.6% of real
+# turns (2026-07 baseline probe) and put a hard floor over the <20% target.
+_ENDPOINT_PRONOUNS = frozenset({
+    "he", "him", "his", "she", "her", "hers", "they", "them", "their", "theirs",
+    "it", "its", "this", "that", "these", "those",
+    "the former", "the latter", "the same",
+})
+
+# Inferential cue words → a candidate that *might* be a `derives` edge. The router only
+# flags it for the LLM to confirm; the router itself NEVER assigns `derives`.
+_INFERENCE_CUES = re.compile(
+    r"\b("
+    r"so|therefore|thus|hence|because|since|"
+    r"must|probably|likely|presumably|implies|imply|implied|"
+    r"means|suggests?|consequently|as\s+a\s+result"
+    r")\b",
+    re.I,
+)
+
+# A leading conjunction / verb with no overt subject ⇒ likely an elided (zero-pronoun)
+# subject carried from the prior clause/turn ("...and moved to Berlin", "Then joined X").
+_ELLIPSIS_LEAD = re.compile(r"^\s*(and|but|then|also|plus|so)\b", re.I)
+_LEADING_VERB = re.compile(
+    r"^\s*(works?|lives?|moved|joined|left|likes?|loves?|hates?|uses?|has|had|is|are|was|were)\b",
+    re.I,
+)
+
+
+@dataclass
+class RouteStats:
+    """Escalation-rate metrics — the router's first-class, inspectable output.
+
+    `rate` is escalated/seen (0.0 when nothing was seen). The BET-2 ablation harness
+    reads this to assert the < 20% target and to log tokens-saved vs 100%-LLM.
+    `by_reason` breaks the escalations down so we can see *why* the budget is spent.
+    """
+
+    seen: int = 0
+    escalated: int = 0
+    by_reason: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def rate(self) -> float:
+        return (self.escalated / self.seen) if self.seen else 0.0
+
+    def as_dict(self) -> dict:
+        # Matches the spec's required {seen, escalated, rate} shape, plus the breakdown.
+        return {
+            "seen": self.seen,
+            "escalated": self.escalated,
+            "rate": self.rate,
+            "by_reason": dict(self.by_reason),
+        }
+
+
+# ── candidate-field accessors (defensive: tolerate sibling-module naming drift) ──
+def _cand_confidence(c: Candidate) -> float:
+    """GLiNER2 (or rules) confidence in [0,1]. Missing ⇒ 0.0 ⇒ escalate (recall-biased).
+
+    Reads `confidence` (taxonomy/gliner contract) and falls back to `gliner_confidence`
+    so a Candidate carrying only the typer-side confidence name still routes correctly.
+    """
+    for attr in ("confidence", "gliner_confidence"):
+        val = getattr(c, attr, None)
+        if val is not None:
+            try:
+                return float(val)
+            except (TypeError, ValueError):
+                return 0.0
+    return 0.0
+
+
+def _cand_pre_flagged(c: Candidate) -> bool:
+    """The upstream `needs_typing` pre-flag (Pass 2 sets it for low-confidence spans).
+
+    The GLiNER2 generator already marks borderline candidates; the router ORs that flag
+    with its own coref/ellipsis/cross-turn/derives triggers so a pre-flagged span is
+    never accidentally routed `direct`. Absent ⇒ False (no pre-flag, decide on triggers).
+    """
+    return bool(getattr(c, "needs_typing", False))
+
+
+def _cand_text(c: Candidate) -> str:
+    """The standalone span text the coref/ellipsis/inference heuristics run over."""
+    for attr in ("fact_text", "text", "sentence"):
+        val = getattr(c, attr, None)
+        if isinstance(val, str) and val:
+            return val
+    return ""
+
+
+def _cand_predicate(c: Candidate) -> str:
+    val = getattr(c, "predicate", None)
+    return val if isinstance(val, str) else ""
+
+
+def _cand_subject_name(c: Candidate) -> Optional[str]:
+    for attr in ("subject_name", "subject", "head", "head_text"):
+        val = getattr(c, attr, None)
+        if isinstance(val, str) and val:
+            return val
+    return None
+
+
+def _cand_object_name(c: Candidate) -> Optional[str]:
+    for attr in ("object_name", "object_literal", "object_text", "object", "tail", "tail_text"):
+        val = getattr(c, attr, None)
+        if isinstance(val, str) and val:
+            return val
+    return None
+
+
+def _cand_introduced_here(c: Candidate) -> Optional[set[str]]:
+    """The entity names Pass 2 says were FIRST introduced in *this* episode, if it told us.
+
+    When the candidate carries this set we trust it; otherwise we return None and the
+    caller falls back to plain `known_entities` membership (still recall-biased). This is
+    optional metadata — the real Pass-2 `Candidate` may not populate it, which is fine."""
+    val = getattr(c, "introduced_here", None)
+    if isinstance(val, (set, frozenset)):
+        return {str(x) for x in val}
+    if isinstance(val, (list, tuple)):
+        return {str(x) for x in val}
+    return None
+
+
+def _norm(name: Optional[str]) -> str:
+    """Case/space-insensitive entity-name key so 'Tim Cook' == 'tim cook'."""
+    return re.sub(r"\s+", " ", name.strip().lower()) if name else ""
+
+
+def _record_reasons(c: Candidate, reasons: list[str]) -> None:
+    """Best-effort: stamp WHY a candidate escalated onto its `escalation_reasons` field.
+
+    Both the taxonomy `Candidate` and the typer's `Candidate` declare this field so
+    Pass 4 / the ablation harness can attribute each escalation. Purely informational —
+    if the candidate is frozen/slotted and won't accept the assignment we silently skip
+    it (the authoritative record is always the router's own `by_reason` stats)."""
+    if not hasattr(c, "escalation_reasons"):
+        return
+    try:
+        c.escalation_reasons = tuple(reasons)  # type: ignore[attr-defined]
+    except (AttributeError, TypeError):
+        pass
+
+
+class RecallBiasedRouter:
+    """Decide which Pass-2 candidates need Pass-4 LLM typing — and audit how often.
+
+    Deterministic and model-free. `route()` partitions candidates into
+    (to_type, direct) and updates the running escalation metrics; `last_stats`
+    exposes the most recent call's {seen, escalated, rate, by_reason}, and
+    `cumulative_stats` aggregates across every call on this instance.
+    """
+
+    def __init__(self, conf_threshold: float = 0.4) -> None:
+        # The recall knob. Anything the parser was less-than-`conf_threshold` sure of is
+        # sent to the LLM. Frozen 2026-07 to 0.4 (was 0.5) — the chosen escalation operating
+        # point from the real-turn calibration after the coref (Task 4) + prior_entity-drop
+        # (Task 6) fixes: at (typing=0.4, conf=0.4) the post-drop probe escalates 14.6%
+        # (103/704, derives-dominated), the highest (typing, conf) pair with probe rate < 0.15.
+        # See bench/results/calibration/2026-07-escalation-postdrop-p1.json + the calibration
+        # README. Tunable so the ablation harness can still sweep it.
+        self.conf_threshold = float(conf_threshold)
+        self._last = RouteStats()
+        self._cum = RouteStats()
+
+    # ── public API ──
+    def route(
+        self,
+        candidates: Iterable[Candidate],
+        known_entities: Optional[Iterable[str]] = None,
+        self_entity: Optional[str] = "user",
+    ) -> tuple[list[Candidate], list[Candidate]]:
+        """Partition `candidates` into (to_type, direct).
+
+        `to_type`  → escalated to the Pass-4 LLM-typing batch (hard spans).
+        `direct`   → skip the LLM; cheap deterministic `asserts`/slot path.
+
+        `known_entities` is the set of entity names already seen in PRIOR turns/sessions
+        of this namespace. As of Task 6 (2026-07) it NO LONGER drives escalation — the
+        `prior_entity` trigger was retired (it fired on 52.8% of real candidates without
+        recall benefit; entity linking is deterministic by name). The parameter is kept
+        for API stability and because the Pass-4 typer uses these names as context.
+
+        `self_entity` is the namespace-owner / first-person persona name (default "user").
+        It was the exemption for the retired `prior_entity` trigger and is likewise no
+        longer consulted for escalation; kept for API stability.
+        """
+        known = {_norm(e) for e in known_entities} if known_entities else set()
+        self_key = _norm(self_entity) if self_entity else ""
+
+        to_type: list[Candidate] = []
+        direct: list[Candidate] = []
+        stats = RouteStats()
+
+        for cand in candidates:
+            stats.seen += 1
+            reasons = self._reasons(cand, known, self_key)
+            if reasons:
+                stats.escalated += 1
+                for r in reasons:
+                    stats.by_reason[r] = stats.by_reason.get(r, 0) + 1
+                _record_reasons(cand, reasons)
+                to_type.append(cand)
+            else:
+                direct.append(cand)
+
+        self._last = stats
+        self._accumulate(stats)
+        return to_type, direct
+
+    def should_escalate(
+        self,
+        candidate: Candidate,
+        known_entities: Optional[Iterable[str]] = None,
+        self_entity: Optional[str] = "user",
+    ) -> bool:
+        """Single-candidate convenience (does NOT touch the running metrics)."""
+        known = {_norm(e) for e in known_entities} if known_entities else set()
+        self_key = _norm(self_entity) if self_entity else ""
+        return bool(self._reasons(candidate, known, self_key))
+
+    # ── metrics surface (first-class, per spec) ──
+    @property
+    def last_stats(self) -> dict:
+        """{seen, escalated, rate, by_reason} for the most recent route() call."""
+        return self._last.as_dict()
+
+    @property
+    def cumulative_stats(self) -> dict:
+        """Aggregate {seen, escalated, rate, by_reason} across all route() calls."""
+        return self._cum.as_dict()
+
+    @property
+    def escalation_rate(self) -> float:
+        """Cumulative escalated/seen — the < 20% BET-2 target metric."""
+        return self._cum.rate
+
+    def reset_stats(self) -> None:
+        self._last = RouteStats()
+        self._cum = RouteStats()
+
+    # ── escalation logic ──
+    def _reasons(self, cand: Candidate, known: set[str], self_key: str = "") -> list[str]:
+        """Collect every reason this candidate must be escalated (order = check order).
+
+        Returns [] ⇒ route direct. Multiple reasons are kept so `by_reason` reflects the
+        true distribution of *why* spans escalate (a span can be both low-conf and coref)."""
+        reasons: list[str] = []
+        text = _cand_text(cand)
+
+        # 0. Upstream pre-flag: Pass 2 already decided this span needs typing. OR it in
+        #    so a pre-flagged candidate is never routed direct (gliner_extractor relies
+        #    on the router honoring `needs_typing`).
+        if _cand_pre_flagged(cand):
+            reasons.append(REASON_PRE_FLAGGED)
+
+        # 1. Low parser confidence — recall-biased: unsure ⇒ escalate.
+        if _cand_confidence(cand) < self.conf_threshold:
+            reasons.append(REASON_LOW_CONF)
+
+        # 2. Coreference / ellipsis / zero-pronoun: the candidate itself is not
+        #    self-contained (endpoint-scoped — see _coref_or_ellipsis).
+        if self._coref_or_ellipsis(cand, text, self_key):
+            reasons.append(REASON_COREF)
+
+        # 3. Possible `derives` (inferential) edge — LLM-only relation.
+        if self._is_possible_derives(cand, text):
+            reasons.append(REASON_DERIVES)
+
+        # NOTE (Task 6, 2026-07): a former criterion here escalated any candidate
+        # touching a `known_entities` member. Retired — it fired on 52.8% of real
+        # candidates (subject re-mention is normal discourse) and blocked the <20%
+        # gate. `known` / `self_key` are still threaded through for API stability but
+        # no longer consulted. See REASON_PRIOR_ENTITY (deprecated) and the docstring.
+
+        return reasons
+
+    def _coref_or_ellipsis(self, cand: Candidate, text: str, self_key: str) -> bool:
+        """Endpoint-scoped coref: escalate iff the candidate's OWN endpoints are
+        unresolvable — a pronoun endpoint, or no grounded subject on a clause that
+        leads like a subject-dropped continuation. A pronoun elsewhere in the
+        sentence is conversational filler, not a resolution problem."""
+        for endpoint in (_cand_subject_name(cand), _cand_object_name(cand)):
+            if _norm(endpoint) in _ENDPOINT_PRONOUNS:
+                return True
+        subject_key = _norm(_cand_subject_name(cand))
+        grounded = (
+            getattr(cand, "subject_span", None) is not None
+            or (bool(subject_key) and subject_key == self_key)
+        )
+        if not grounded and text and (_ELLIPSIS_LEAD.match(text) or _LEADING_VERB.match(text)):
+            return True
+        return False
+
+    # NOTE (Task 6, 2026-07): `_references_prior_entity` was deleted here. It escalated
+    # any candidate whose subject was a previously-seen entity; on real dialogs subject
+    # re-mention is normal discourse (52.8% of candidates), so it blocked the <20% gate
+    # with no recall benefit (entity linking is deterministic by name). Ambiguous
+    # references still escalate via `_coref_or_ellipsis`, inferential edges via
+    # `_is_possible_derives`. `_cand_introduced_here` is now unused by the router but
+    # kept as a public helper; `known_entities` remains a `route()` parameter for the
+    # typer's context (see route()'s docstring).
+
+    @staticmethod
+    def _is_possible_derives(cand: Candidate, text: str) -> bool:
+        """Heuristic for an inferential edge: an inference cue word, OR a predicate that
+        isn't in our confidently-typeable set (unknown/empty ⇒ the LLM must type it)."""
+        predicate = _cand_predicate(cand)
+        if not predicate or predicate not in _KNOWN_PREDICATES:
+            return True
+        if text and _INFERENCE_CUES.search(text):
+            return True
+        return False
+
+    # ── internals ──
+    def _accumulate(self, stats: RouteStats) -> None:
+        self._cum.seen += stats.seen
+        self._cum.escalated += stats.escalated
+        for reason, n in stats.by_reason.items():
+            self._cum.by_reason[reason] = self._cum.by_reason.get(reason, 0) + n

lean_memory/extract/rules.py

@@ -0,0 +1,130 @@
+"""Phase 0 extractor: rules only (regex + dateparser). No GLiNER2, no LLM.
+
+The spec defers GLiNER2 to Phase 1 and the LLM-typing residual to Phase 1+. Phase 0
+proves the spine end-to-end, so this extractor is deliberately simple and fully
+deterministic: it turns an episode into one-or-more atomic facts with a parsed
+`valid_at`, a coarse subject/predicate, and the standalone sentence as `fact_text`.
+
+It is NOT meant to be good extraction — it is the reproducible candidate-generation
+stub that the Phase 1 hybrid pipeline replaces. Each emitted fact is a standalone
+sentence (matching supermemory's "atomic, standalone" rule), keyed off simple
+subject-verb-object heuristics.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from dateutil import parser as dateparser
+
+from ..types import Episode, Fact, new_id, now_ms
+
+# Very small relation lexicon → normalized predicate slot. Phase 1 replaces this
+# with GLiNER2 schema relations + LLM typing.
+_PREDICATE_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"\b(works?|working)\s+(at|for)\b", re.I), "works_at"),
+    (re.compile(r"\b(lives?|living|based)\s+in\b", re.I), "lives_in"),
+    (re.compile(r"\b(likes?|loves?|enjoys?|prefers?)\b", re.I), "likes"),
+    (re.compile(r"\b(dislikes?|hates?)\b", re.I), "dislikes"),
+    (re.compile(r"\b(is|am|are)\s+(a|an)\b", re.I), "is_a"),
+    (re.compile(r"\b(has|have|owns?)\b", re.I), "has"),
+    (re.compile(r"\b(uses?|using)\b", re.I), "uses"),
+]
+
+_FIRST_PERSON = re.compile(r"\b(I|I'm|I am|my|me|mine)\b", re.I)
+_SENT_SPLIT = re.compile(r"(?<=[.!?])\s+")
+
+
+@dataclass
+class ExtractedFact:
+    """An extractor's pre-persistence candidate (before entity resolution)."""
+
+    subject_name: str
+    predicate: str
+    fact_text: str
+    valid_at: int
+    object_literal: Optional[str] = None
+    confidence: float = 0.6  # rules-only → modest confidence; LLM typing would lift this
+
+
+class RulesExtractor:
+    def __init__(self, default_subject: str = "user") -> None:
+        self.default_subject = default_subject
+
+    def extract(self, episode: Episode) -> list[ExtractedFact]:
+        out: list[ExtractedFact] = []
+        for sentence in _split_sentences(episode.raw):
+            valid_at = self._resolve_time(sentence, episode.t_ref)
+            predicate = self._match_predicate(sentence)
+            if predicate is None:
+                continue
+            subject = self.default_subject if _FIRST_PERSON.search(sentence) else _lead_noun(sentence)
+            out.append(
+                ExtractedFact(
+                    subject_name=subject,
+                    predicate=predicate,
+                    fact_text=sentence.strip(),
+                    valid_at=valid_at,
+                )
+            )
+        return out
+
+    def _match_predicate(self, sentence: str) -> Optional[str]:
+        for pat, slot in _PREDICATE_PATTERNS:
+            if pat.search(sentence):
+                return slot
+        return None
+
+    def _resolve_time(self, sentence: str, t_ref: int) -> int:
+        """Parse an explicit date in the sentence; else fall back to the episode t_ref.
+        Deterministic: dateparser with a fixed default anchored at t_ref."""
+        try:
+            default = _ms_to_dt(t_ref)
+            dt = dateparser.parse(sentence, fuzzy=True, default=default)
+            if dt is not None:
+                return int(dt.timestamp() * 1000)
+        except (ValueError, OverflowError, TypeError):
+            pass
+        return t_ref
+
+
+def to_fact(ef: ExtractedFact, *, namespace: str, subject_id: str, episode_id: str) -> Fact:
+    """Bind an ExtractedFact to resolved ids → a persistable Fact."""
+    ts = now_ms()
+    return Fact(
+        id=new_id(),
+        namespace=namespace,
+        subject_id=subject_id,
+        predicate=ef.predicate,
+        object_literal=ef.object_literal,
+        fact_text=ef.fact_text,
+        valid_at=ef.valid_at,
+        episode_id=episode_id,
+        confidence=ef.confidence,
+        ingested_at=ts,
+        created_at=ts,
+    )
+
+
+# ── helpers ──
+def _split_sentences(text: str) -> list[str]:
+    return [s for s in _SENT_SPLIT.split(text.strip()) if s.strip()]
+
+
+def _lead_noun(sentence: str) -> str:
+    """Crude subject guess: first capitalized token, else the first token. Phase 1's
+    GLiNER2 NER replaces this."""
+    for tok in sentence.split():
+        clean = tok.strip(".,!?;:'\"")
+        if clean and clean[0].isupper():
+            return clean
+    first = sentence.split()
+    return first[0].strip(".,!?;:'\"") if first else "unknown"
+
+
+def _ms_to_dt(ms: int):
+    from datetime import datetime, timezone
+
+    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc)

lean_memory/extract/salience.py

@@ -0,0 +1,123 @@
+"""Salience (importance) scoring at write time — spec section 6B.
+
+The spec says importance is "rated once at write and cached" and consumed at rank
+time as `importance = salience/10` (see Retriever's salience-decay re-score). The
+*real* Phase >1 plan is an LLM rater that judges how memorable/consequential a fact
+is. Phase 1 keeps it DETERMINISTIC and cheap — no LLM, no network, pure stdlib —
+exactly like RulesExtractor is the deterministic stub for GLiNER2/LLM extraction.
+
+This is a STUB on purpose: `score_salience` is the seam an LLM rater drops into
+later (same signature, same [0, 10] contract). Until then it uses transparent
+heuristics so the value is reproducible in tests and explainable in eval:
+
+  * facts with concrete grounding (dates, numbers, proper nouns) matter more —
+    "moved to Berlin on 2025-03-01" is more consequential than "likes coffee";
+  * directly asserted observations outrank inferred ones — an inference is a
+    derived guess, so it starts lower (the LLM rater would also discount these);
+  * non-user sources (assistant/tool/doc) are background context, so they get a
+    mild discount versus first-party user statements;
+  * very short / filler facts score low; longer specific facts score higher,
+    with diminishing returns so a wall of text can't dominate.
+
+The output is clamped to [0, 10] to match the `salience REAL ... DEFAULT 0.0`
+column and the `importance = salience/10 ∈ [0, 1]` rank-time normalization.
+"""
+
+from __future__ import annotations
+
+import re
+
+# ── tunable weights (kept module-level + named so the heuristic is auditable) ──
+# A neutral baseline so an unremarkable-but-valid fact lands mid-scale, leaving
+# head-room for both boosts and penalties.
+_BASELINE = 4.0
+
+# Signals that a fact is concrete/consequential rather than vague preference talk.
+# Each present signal adds its weight (once), so grounding compounds.
+_DATE = re.compile(
+    r"\b\d{4}-\d{2}-\d{2}\b"  # ISO date
+    r"|\b\d{1,2}[/-]\d{1,2}(?:[/-]\d{2,4})?\b"  # 1/2 or 01/02/2025
+    r"|\b\d{1,2}:\d{2}\b"  # clock time
+    r"|\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+\d{1,2}\b",
+    re.I,
+)
+_NUMBER = re.compile(r"\b\d+(?:[.,]\d+)?\b")  # any standalone number/quantity
+# Proper noun = a capitalized token that is NOT the sentence's first word. We strip
+# the lead token before matching so "I moved" doesn't count "I" as a proper noun.
+_PROPER_NOUN = re.compile(r"(?<!^)\b[A-Z][a-zA-Z]+\b")
+
+_DATE_BOOST = 1.6
+_NUMBER_BOOST = 0.9
+_PROPER_NOUN_BOOST = 1.2
+
+# Penalties.
+# Inferred facts are derived guesses (Fact.is_inference / relation 'derives'); the
+# LLM rater would trust them less, so the deterministic stub mirrors that prior.
+_INFERENCE_PENALTY = 2.0
+# First-party user statements are the primary signal; everything else is context.
+_NON_USER_PENALTY = 1.0
+
+# Length shaping: reward specificity up to a point, then flatten so verbosity alone
+# can't win. Word counts (cheap, locale-free) are good enough for a stub.
+_FILLER_MAX_WORDS = 3  # "ok thanks", "yes" → near-floor importance
+_FILLER_PENALTY = 2.5
+_LEN_BONUS_PER_WORD = 0.18
+_LEN_BONUS_CAP = 1.8  # reached around ~10 content words
+
+# Score bounds match the DB column + importance=salience/10 normalization.
+_MIN, _MAX = 0.0, 10.0
+
+_PROPER_NOUN_LEAD = re.compile(r"^\W*\w+\s*")  # drop leading token for proper-noun test
+
+
+def score_salience(fact_text: str, *, source: str, is_inference: bool) -> float:
+    """Rate how important/memorable a fact is, in [0, 10]. Deterministic stub.
+
+    Cheap, pure-stdlib heuristic computed once at write and cached in
+    `Fact.salience` (the Retriever later reads it as `importance = salience/10`).
+    Replaceable by an LLM rater with this exact signature and range.
+
+    Args:
+        fact_text: the standalone fact sentence (what gets embedded/ranked).
+        source: provenance of the originating episode — 'user'|'assistant'|'tool'|'doc'.
+            User statements are first-party; other sources are discounted slightly.
+        is_inference: True for derived/inferred facts (relation 'derives'); these
+            start lower because they are guesses, not direct observations.
+
+    Returns:
+        A float in [0.0, 10.0]. Empty/whitespace text scores 0.0.
+    """
+    text = (fact_text or "").strip()
+    if not text:
+        # Nothing to weigh — degenerate input shouldn't crash the write path.
+        return _MIN
+
+    score = _BASELINE
+
+    # ── grounding boosts (concrete > vague) ──
+    if _DATE.search(text):
+        score += _DATE_BOOST
+    if _NUMBER.search(text):
+        score += _NUMBER_BOOST
+    # Test proper nouns on the text minus its leading token so a leading capital
+    # (sentence start, "I") doesn't masquerade as a named entity.
+    if _PROPER_NOUN.search(_PROPER_NOUN_LEAD.sub("", text, count=1)):
+        score += _PROPER_NOUN_BOOST
+
+    # ── length / specificity shaping ──
+    n_words = len(text.split())
+    if n_words <= _FILLER_MAX_WORDS:
+        # Short acknowledgements / filler carry little durable information.
+        score -= _FILLER_PENALTY
+    else:
+        # Diminishing reward for elaboration; capped so length alone can't dominate.
+        score += min(_LEN_BONUS_CAP, (n_words - _FILLER_MAX_WORDS) * _LEN_BONUS_PER_WORD)
+
+    # ── provenance / inference penalties ──
+    if is_inference:
+        score -= _INFERENCE_PENALTY
+    if source != "user":
+        score -= _NON_USER_PENALTY
+
+    # Clamp to the cached-salience contract [0, 10].
+    return max(_MIN, min(_MAX, score))