superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/encoding/prospective_markers.py

@@ -1,262 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Does this sentence describe something that has not happened yet?
-
-A prospective memory is a plan: a deadline, an appointment, a scheduled event,
-something with a date still ahead of it. It is a different kind of memory from
-a record of what happened, and it is meant to be small and precise — the
-handful of things a user is waiting on.
-
-WHY THIS MODULE EXISTS
-
-Two different regexes used to answer this question, one in ``fact_extractor``
-and one in ``type_router``, and they disagreed. Measured on a real 468 MB
-store: 869 facts carried the prospective type and **7** contained any planning
-language at all. The rest were session summaries and records of completed work.
-
-The extractor's pattern contained ``by \\w+``, which matches every passive-voice
-and attribution sentence ever written — "was caused **by a** stale DNS entry" —
-and ``yesterday``, which cannot indicate a plan. The router's contained bare
-``ends?``, so "the service ends at midnight" was a plan.
-
-WHAT REPLACED THEM
-
-Two tiers, because the evidence really is of two strengths:
-
-*Definite* markers point forward on their own. "Tomorrow" is tomorrow whatever
-else the sentence says, and a deadline is a deadline.
-
-*Circumstantial* markers — a weekday, a clock time, "starts", "in three days" —
-are shaped like a plan but read equally well as narration. They count only when
-nothing in the sentence says the thing already happened.
-
-The asymmetry is deliberate. A plan wrongly filed as an ordinary memory is
-still found by every other channel and costs a user nothing. An ordinary
-memory wrongly filed as a plan pollutes the one list a user checks to see what
-is coming up. **When in doubt, it is not a plan.**
-"""
-
-from __future__ import annotations
-
-import re
-
-__all__ = [
-    "ANCHORED_FUTURE",
-    "PLANNING_LANGUAGE",
-    "CIRCUMSTANTIAL_FUTURE",
-    "RECURRING",
-    "ALREADY_HAPPENED",
-    "CALLED_OFF",
-    "PLACEMENT",
-    "RESCHEDULING",
-    "DEFINITE_FUTURE",
-    "looks_prospective",
-]
-
-_WEEKDAY = r"(?:mon|tues?|wednes|thurs?|fri|satur|sun)day"
-_MONTH = (
-    r"(?:january|february|march|april|may|june|july|august|september|"
-    r"october|november|december|jan|feb|mar|apr|jun|jul|aug|sep|sept|oct|nov|dec)"
-)
-
-#: Points forward on its own, whatever else the sentence says. Every member
-#: carries an explicit forward time anchor, so "rescheduled to next Friday" is
-#: still a plan even though "rescheduled" reads as past.
-ANCHORED_FUTURE = re.compile(
-    r"\b(?:"
-    r"tomorrow|"
-    r"next\s+(?:week|weekend|month|year|quarter|sprint|release|" + _WEEKDAY + r")|"
-    r"this\s+(?:coming|weekend)|"
-    r"upcoming\s+(?:release|meeting|week|month|sprint|deadline|event|launch|"
-    r"call|review|milestone)|"
-    r"by\s+(?:end\s+of|eod|eow|cob|" + _WEEKDAY + r"|" + _MONTH + r"|\d{4}-\d{2}-\d{2})|"
-    r"due\s+(?:date|by|on|" + _WEEKDAY + r"|" + _MONTH + r")"
-    r")\b",
-    re.IGNORECASE,
-)
-
-#: The vocabulary of planning. These words are ABOUT something being planned,
-#: and they read exactly as well in the past: a deadline can be missed, an
-#: appointment cancelled, a launch date long gone. They count only when nothing
-#: says the thing already happened.
-#:
-#: Treating them as definite is what re-polluted the list this module exists to
-#: clean — "the appointment was cancelled yesterday" was filed as something to
-#: look forward to.
-PLANNING_LANGUAGE = re.compile(
-    r"\b(?:"
-    r"deadline|"
-    r"appointment|"
-    r"before\s+(?:" + _WEEKDAY + r"|" + _MONTH + r"|\d{4}-\d{2}-\d{2})|"
-    r"expir(?:es|ing|e)\s+(?:on|at)\s+(?:" + _WEEKDAY + r"|" + _MONTH + r"|\d)|"
-    r"expir(?:y|ation)\s+date|"
-    r"scheduled?\s+(?:for|on|at|to)|reschedul(?:e|ed|ing)|"
-    r"plans?\s+to|planning\s+to|"
-    r"go[-\s]?live|cut[-\s]?over|launch\s+date|"
-    r"will\s+(?:happen|start|begin|expire|ship|launch|resume|reopen|take\s+place)|"
-    r"will\s+be\s+(?:deleted|removed|released|deployed|held|published|migrated|"
-    r"archived|retired|rotated|decommissioned|shut\s+down)|"
-    r"going\s+to\s+(?:happen|ship|start|launch|begin)"
-    r")\b",
-    re.IGNORECASE,
-)
-
-#: Kept for callers that imported the old name; the two tiers together are what
-#: it used to mean.
-DEFINITE_FUTURE = ANCHORED_FUTURE
-
-#: Shaped like a plan, but reads equally well as narration.
-CIRCUMSTANTIAL_FUTURE = re.compile(
-    r"\b(?:"
-    r"on\s+" + _WEEKDAY + r"|"
-    r"(?:is|are)\s+(?:this\s+)?" + _WEEKDAY + r"|"
-    r"this\s+(?:week|" + _WEEKDAY + r")|"
-    r"at\s+\d{1,2}:\d{2}|"
-    r"in\s+\d+\s+(?:days?|weeks?|months?|years?)|"
-    r"(?:starts?|begins?|resumes?|reopens?)\s+(?:on|at)|"
-    r"(?:on|at)\s+\d{4}-\d{2}-\d{2}|"
-    r"meeting\s+(?:on|at)"
-    r")\b",
-    re.IGNORECASE,
-)
-
-#: A thing that happens on a cycle is not a thing that is coming up. "Standup at
-#: 09:30 every day" belongs in nobody's list of what to expect this week.
-RECURRING = re.compile(
-    r"\b(?:every|each)\s+(?:day|week|month|morning|afternoon|evening|night|"
-    r"sprint|release|" + _WEEKDAY + r")|\b(?:daily|weekly|monthly|nightly|"
-    r"hourly|per\s+request|recurring)\b",
-    re.IGNORECASE,
-)
-
-#: Verbs that PUT an event on a date, rather than report on one. "Rescheduled
-#: to next Friday" and "was scheduled for next Monday" are both still plans;
-#: "discussed the deadline for next month" is a record of a conversation. All
-#: three are past-tense sentences containing a forward date, and only the first
-#: two are something to look forward to — so a forward anchor overrides the past
-#: only when one of these is what made the sentence past.
-#:
-#: The passive forms matter more than they look: people write notes that way
-#: ("the appointment was booked for Tuesday"), and leaving them out missed a
-#: whole class of ordinary phrasing.
-PLACEMENT = re.compile(
-    r"\b(?:reschedul(?:e|ed|ing)|mov(?:e|ed|ing)\s+to|postpon(?:e|ed|ing)|"
-    r"push(?:ed)?\s+(?:to|back)|shift(?:ed)?\s+to|defer(?:red)?\s+to|"
-    r"brought\s+forward|pull(?:ed)?\s+forward|bumped\s+to|"
-    r"(?:scheduled?|booked|planned|slated|arranged|set|pencilled|penciled)\s+"
-    r"(?:for|on|at|to)|"
-    r"extend(?:ed)?\s+to|mov(?:e|ed)\s+forward\s+to|"
-    r"chang(?:e|ed)\s+(?:the\s+)?(?:\w+\s+)?"
-    r"(?:date|deadline|time|schedule|window)\s+to)\b",
-    re.IGNORECASE,
-)
-
-#: The old name, kept because it reads in the one place it is used.
-RESCHEDULING = PLACEMENT
-
-#: Says the thing has already happened. Vetoes anything but an anchored future
-#: that was anchored BY a rescheduling.
-ALREADY_HAPPENED = re.compile(
-    r"\b(?:"
-    r"yesterday|"
-    r"last\s+(?:night|week|month|year|" + _WEEKDAY + r")|"
-    r"\d+\s+(?:days?|weeks?|months?|years?)\s+ago|ago|"
-    r"already|"
-    r"was|were|had\s+been|has\s+been|have\s+been|"
-    r"did|done|"
-    r"complet(?:e|ed)|finish(?:ed)?|"
-    r"shipped|released|landed|merged|deployed|"
-    r"fixed|resolved|closed|cancelled|canceled|missed|happened|expired|"
-    r"turned\s+out|ended|began|begun|started|"
-    r"produced|caused|created|caught|found|"
-    r"updated|changed|edited|modified|renamed|bumped|committed|"
-    r"restarted|configured|installed|"
-    r"had|met|arrived|attended|ate|spoke|talked|visited|saw|"
-    # deleted / removed / added are deliberately absent: each is both a simple
-    # past AND the participle in a future passive, and "the worktrees will be
-    # deleted" is a plan. The future-passive list in PLANNING_LANGUAGE is the
-    # narrower half of that ambiguity and it is the half worth keeping.
-    r"decided|agreed|discussed|reviewed|reported|"
-    r"ran|wrote|built|took|made|went|came|said|led|"
-    r"failed|passed|broke|resulted"
-    r")\b",
-    re.IGNORECASE,
-)
-
-
-#: The event is off. This outranks everything, including a present-tense clause
-#: saying when it was going to be.
-CALLED_OFF = re.compile(
-    r"\b(?:cancel(?:led|ed|s)?|called\s+off|scrapped|abandoned|"
-    r"dropped|shelved|withdrawn|no\s+longer\s+(?:happening|planned|scheduled))\b",
-    re.IGNORECASE,
-)
-
-
-#: A present-tense statement that something is on a future date: "the launch is
-#: next Friday", "the freeze starts Monday", "the review is this Tuesday".
-#: Present tense about a forward date is a plan whatever else the surrounding
-#: sentence reports having done.
-#:
-#: Every part of this is bounded on both sides. A first attempt was not, and it
-#: matched "is dec" inside "is decision", "are mar" inside "are marked", and
-#: "this a" inside "is this a" — turning 14 memories into 72 on a real store.
-#: An unbounded month abbreviation is a trap in any prose.
-_FUTURE_FACT = re.compile(
-    r"\b(?:is|are|starts?|begins?|opens?|closes?|resumes?|reopens?|runs?|"
-    r"lands?|ships?|goes\s+live|kicks\s+off)\s+"
-    r"(?:on\s+|at\s+)?"
-    r"(?:"
-    r"tomorrow"
-    r"|next\s+(?:week|weekend|month|year|quarter|sprint|release|" + _WEEKDAY + r")"
-    r"|this\s+(?:coming\s+)?(?:week|weekend|" + _WEEKDAY + r")"
-    r"|" + _WEEKDAY +
-    r"|\d{4}-\d{2}-\d{2}"
-    r")\b",
-    re.IGNORECASE,
-)
-
-
-def _states_a_future_fact(text: str) -> bool:
-    """Present tense about a forward date, inside any sentence."""
-    return bool(_FUTURE_FACT.search(text))
-
-
-def looks_prospective(text: str) -> bool:
-    """True when the text describes something still ahead.
-
-    Three tiers, because the evidence really is of three strengths. An anchored
-    future — "next Tuesday", "by Friday", "on 2026-09-04" — points forward
-    whatever else the sentence says. Planning vocabulary and circumstantial
-    wording both read equally well in the past, so they count only when nothing
-    says the thing already happened. Anything on a cycle is not a plan at all.
-    """
-    if not text:
-        return False
-    behind = ALREADY_HAPPENED.search(text)
-    if CALLED_OFF.search(text):
-        # "The deadline is next Friday but was cancelled yesterday" reads as a
-        # future fact and is not one. Cancelling is the one thing that beats a
-        # present-tense statement about a forward date.
-        return False
-    if _states_a_future_fact(text):
-        # "I updated the timeline so the launch IS next Friday" — the past-tense
-        # verb is about the note, and the clause with the date is in the present
-        # about something ahead. A veto that scans the whole sentence cannot see
-        # that difference and drops a real deadline.
-        return True
-    if ANCHORED_FUTURE.search(text):
-        # Checked BEFORE the recurring veto. "The weekly review is next Tuesday"
-        # names one dated occurrence of a recurring thing, and that occurrence
-        # is coming up; "weekly" describes the series, not this instance.
-        # A forward anchor beats the past only when the past word is what moved
-        # the event. "Rescheduled to next Friday" is a plan; "discussed the
-        # deadline for next month" is a record of a conversation.
-        return not behind or bool(RESCHEDULING.search(text))
-    if RECURRING.search(text):
-        return False
-    if PLANNING_LANGUAGE.search(text) or CIRCUMSTANTIAL_FUTURE.search(text):
-        return not behind
-    return False

package/src/superlocalmemory/encoding/scene_builder.py

@@ -1,410 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""SuperLocalMemory V3 — Scene Builder (Memory Clustering).
-
-Groups related facts into thematic scenes (EverMemOS MemScene pattern).
-Scenes provide contextual retrieval — related facts come together.
-
-V1 had this module but NEVER CALLED it. Now wired into the encoding pipeline.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import json
-
-from superlocalmemory.storage.embedding_codec import decode_embedding
-import logging
-from datetime import UTC, datetime
-
-from superlocalmemory.storage.models import AtomicFact, MemoryScene
-
-logger = logging.getLogger(__name__)
-
-# Similarity threshold for assigning fact to existing scene
-_ASSIGN_THRESHOLD = 0.6
-_MAX_ASSIGNMENT_CANDIDATES = 256
-
-
-class SceneBuilder:
-    """Cluster related facts into thematic scenes.
-
-    When a new fact arrives:
-    1. Compute similarity to existing scenes (via scene theme embedding)
-    2. If above threshold: assign to nearest scene, update scene
-    3. If below threshold: create new scene
-    """
-
-    def __init__(self, db, embedder=None, vector_store=None) -> None:
-        self._db = db
-        self._embedder = embedder
-        self._vector_store = vector_store
-        # Key by scene ID, never theme. Themes are deliberately non-unique,
-        # while eligibility and durable anchor membership are scene-specific.
-        self._scene_embeddings_cache: dict[str, list[float]] = {}
-
-    def assign_to_scene(
-        self,
-        new_fact: AtomicFact,
-        profile_id: str,
-    ) -> MemoryScene:
-        """Assign a fact to an existing scene or create a new one.
-
-        Always embeds the incoming fact content (when embedder is available)
-        so that the embedding is ready for comparison against existing scenes.
-        """
-        if self._embedder is None:
-            return self._create_scene(new_fact, profile_id)
-
-        # Canonical ingestion already embeds the fact before scene assignment.
-        # Reuse that vector so scene clustering does not issue a duplicate model
-        # request for every remembered fact.
-        fact_emb = new_fact.embedding
-        if fact_emb is None:
-            fact_emb = self._embedder.embed(new_fact.content)
-
-        # v3.4.38: Defensive None guard. embedder.embed() returns None when
-        # the embedding worker is unavailable (timeout, crash). Without this
-        # guard, _cosine(None, theme_emb) → zip(None, ...) → 'NoneType'
-        # object is not iterable, propagating up to engine.store() and
-        # causing the entire memory to be lost. Better to skip scene
-        # assignment than lose the memory.
-        if fact_emb is None:
-            return self._create_scene(new_fact, profile_id)
-
-        scenes = self._get_assignment_scenes(profile_id, fact_emb)
-        if not scenes:
-            return self._create_scene(new_fact, profile_id)
-
-        live_scene_embeddings = self._load_live_scene_embeddings(
-            profile_id,
-            tuple(scene.scene_id for scene in scenes),
-        )
-        live_scene_ids = set(live_scene_embeddings)
-        self._scene_embeddings_cache.update({
-            scene_id: embedding
-            for scene_id, embedding in live_scene_embeddings.items()
-            if embedding is not None
-        })
-        # Old consolidation/deletion paths left scene rows whose fact IDs no
-        # longer exist. They are not evidence and must not trigger thousands of
-        # replacement model calls after restart. A cache hit cannot prove that
-        # a scene still has a surviving fact, so eligibility is always derived
-        # from the current database state.
-        scenes = [
-            scene for scene in scenes if scene.scene_id in live_scene_ids
-        ]
-        if not scenes:
-            return self._create_scene(new_fact, profile_id)
-
-        # Find best matching scene
-        best_scene: MemoryScene | None = None
-        best_sim = -1.0
-
-        # A scene's theme is derived from its first (anchor) fact. On daemon
-        # restart the in-memory cache is empty, but the anchor embeddings remain
-        # durable in atomic_facts. Prime from those vectors before calling the
-        # model; otherwise a mature database re-embeds thousands of themes and
-        # repeatedly recycles the shared foreground worker.
-        # V3.3.27: Batch-embed all still-uncached scene themes in ONE call.
-        # Previously: 200+ individual embed() calls per fact (30s on Mode B).
-        # Now: 1 batch call for all uncached themes, then cache hits for the rest.
-        uncached_scenes = [
-            scene for scene in scenes
-            if scene.scene_id not in self._scene_embeddings_cache
-        ]
-        if uncached_scenes and hasattr(self._embedder, 'embed_batch'):
-            try:
-                batch_embs = self._embedder.embed_batch(
-                    [scene.theme for scene in uncached_scenes]
-                )
-                for scene, emb in zip(uncached_scenes, batch_embs):
-                    if emb is not None:
-                        self._scene_embeddings_cache[scene.scene_id] = emb
-            except Exception:
-                pass  # Fall through to individual embeds below
-
-        for scene in scenes:
-            if scene.scene_id in self._scene_embeddings_cache:
-                theme_emb = self._scene_embeddings_cache[scene.scene_id]
-            else:
-                theme_emb = self._embedder.embed(scene.theme)
-                if theme_emb is not None:
-                    self._scene_embeddings_cache[scene.scene_id] = theme_emb
-            if theme_emb is None:
-                continue
-            sim = _cosine(fact_emb, theme_emb)
-            if sim > best_sim:
-                best_sim = sim
-                best_scene = scene
-
-        if best_scene is not None and best_sim >= _ASSIGN_THRESHOLD:
-            return self._add_to_scene(best_scene, new_fact, profile_id)
-
-        return self._create_scene(new_fact, profile_id)
-
-    def get_scene_for_fact(self, fact_id: str, profile_id: str) -> MemoryScene | None:
-        """Get the scene containing a specific fact."""
-        rows = self._db.execute(
-            "SELECT * FROM memory_scenes WHERE profile_id = ?", (profile_id,)
-        )
-        for row in rows:
-            d = dict(row)
-            fids = json.loads(d.get("fact_ids_json", "[]"))
-            if fact_id in fids:
-                return self._row_to_scene(d)
-        return None
-
-    def get_all_scenes(self, profile_id: str) -> list[MemoryScene]:
-        """Get all scenes for a profile."""
-        return self._get_scenes(profile_id)
-
-    # -- Internal ----------------------------------------------------------
-
-    def _create_scene(self, fact: AtomicFact, profile_id: str) -> MemoryScene:
-        """Create a new scene from a single fact.
-
-        Pre-computes and caches the theme embedding for efficient later
-        comparisons in assign_to_scene.
-        """
-        theme = fact.content[:200]
-        scene = MemoryScene(
-            profile_id=profile_id,
-            theme=theme,
-            fact_ids=[fact.fact_id],
-            entity_ids=list(fact.canonical_entities),
-            created_at=datetime.now(UTC).isoformat(),
-            last_updated=datetime.now(UTC).isoformat(),
-        )
-        # Pre-compute theme embedding for future comparisons. The canonical fact
-        # vector represents this exact theme and avoids a duplicate model call.
-        if self._embedder is not None:
-            theme_embedding = fact.embedding
-            if theme_embedding is None:
-                theme_embedding = self._embedder.embed(theme)
-            if theme_embedding is not None:
-                self._scene_embeddings_cache[scene.scene_id] = theme_embedding
-        self._save_scene(scene)
-        return scene
-
-    def _add_to_scene(
-        self, scene: MemoryScene, fact: AtomicFact, profile_id: str
-    ) -> MemoryScene:
-        """Add a fact to an existing scene."""
-        new_fact_ids = [*scene.fact_ids, fact.fact_id]
-        new_entity_ids = list(set(scene.entity_ids) | set(fact.canonical_entities))
-        updated = MemoryScene(
-            scene_id=scene.scene_id,
-            profile_id=profile_id,
-            theme=scene.theme,
-            fact_ids=new_fact_ids,
-            entity_ids=new_entity_ids,
-            created_at=scene.created_at,
-            last_updated=datetime.now(UTC).isoformat(),
-        )
-        self._save_scene(updated)
-        return updated
-
-    def _get_scenes(self, profile_id: str) -> list[MemoryScene]:
-        """Load all scenes from DB."""
-        rows = self._db.execute(
-            "SELECT * FROM memory_scenes WHERE profile_id = ? ORDER BY last_updated DESC",
-            (profile_id,),
-        )
-        return [self._row_to_scene(dict(r)) for r in rows]
-
-    def _get_assignment_scenes(
-        self,
-        profile_id: str,
-        fact_embedding: list[float],
-    ) -> list[MemoryScene]:
-        """Load bounded semantic candidates with a recency fallback.
-
-        Mature stores must not compare every new fact with every historical
-        scene. The fact vector index finds nearby members in bounded time; the
-        normalized membership projection maps them back to scenes. Recent
-        scenes remain a fail-soft fallback for fresh or unavailable indexes.
-        Semantic candidates are ordered first so an old relevant scene cannot
-        be displaced by the recency cap.
-        """
-        recent_rows = self._db.execute(
-            "SELECT ms.* FROM memory_scenes AS ms WHERE ms.profile_id = ? "
-            "AND EXISTS (SELECT 1 FROM scene_fact_members AS live_member "
-            "WHERE live_member.scene_id = ms.scene_id "
-            "AND live_member.profile_id = ms.profile_id) "
-            "ORDER BY ms.last_updated DESC LIMIT ?",
-            (profile_id, _MAX_ASSIGNMENT_CANDIDATES),
-        )
-        recent = [self._row_to_scene(dict(row)) for row in recent_rows]
-
-        nearest_fact_ids: list[str] = []
-        if self._vector_store is not None:
-            try:
-                nearest_fact_ids = [
-                    fact_id
-                    for fact_id, _score in self._vector_store.search(
-                        fact_embedding,
-                        top_k=_MAX_ASSIGNMENT_CANDIDATES,
-                        profile_id=profile_id,
-                    )
-                ]
-            except Exception:
-                nearest_fact_ids = []
-
-        semantic: list[MemoryScene] = []
-        if nearest_fact_ids:
-            placeholders = ",".join("?" for _ in nearest_fact_ids)
-            try:
-                semantic_rows = self._db.execute(
-                    f"""
-                    SELECT ms.*, member.fact_id AS matched_fact_id
-                    FROM scene_fact_members AS member
-                    JOIN memory_scenes AS ms
-                      ON ms.scene_id = member.scene_id
-                     AND ms.profile_id = member.profile_id
-                    WHERE member.profile_id = ?
-                      AND member.fact_id IN ({placeholders})
-                    """,
-                    (profile_id, *nearest_fact_ids),
-                )
-                hit_rank = {
-                    fact_id: rank
-                    for rank, fact_id in enumerate(nearest_fact_ids)
-                }
-                ranked_scenes: dict[str, tuple[int, MemoryScene]] = {}
-                for row in semantic_rows:
-                    data = dict(row)
-                    rank = hit_rank.get(
-                        str(data.pop("matched_fact_id", "")),
-                        len(hit_rank),
-                    )
-                    scene = self._row_to_scene(data)
-                    previous = ranked_scenes.get(scene.scene_id)
-                    if previous is None or rank < previous[0]:
-                        ranked_scenes[scene.scene_id] = (rank, scene)
-                semantic = [
-                    scene
-                    for _rank, scene in sorted(
-                        ranked_scenes.values(), key=lambda item: item[0]
-                    )
-                ]
-            except Exception:
-                # Migration failure or a disabled vector projection must not
-                # make remember fail. The bounded recent set remains valid.
-                semantic = []
-
-        candidates: list[MemoryScene] = []
-        seen: set[str] = set()
-        for scene in (*semantic, *recent):
-            if scene.scene_id in seen:
-                continue
-            seen.add(scene.scene_id)
-            candidates.append(scene)
-            if len(candidates) >= _MAX_ASSIGNMENT_CANDIDATES:
-                break
-        return candidates
-
-    def _load_live_scene_embeddings(
-        self,
-        profile_id: str,
-        scene_ids: tuple[str, ...],
-    ) -> dict[str, list[float] | None]:
-        """Load one durable anchor embedding for every live scene.
-
-        The normalized membership projection resolves the first still-existing
-        fact in each scene without expanding every scene's JSON array. Scenes
-        whose original anchor was consolidated away can still reuse a surviving
-        member. Fully stale scene rows are ignored instead of being re-embedded.
-        """
-        if not scene_ids:
-            return {}
-        placeholders = ",".join("?" for _ in scene_ids)
-        try:
-            rows = self._db.execute(
-                f"""
-                WITH live_scene_facts AS (
-                    SELECT
-                        ms.scene_id,
-                        af.embedding,
-                        ROW_NUMBER() OVER (
-                            PARTITION BY ms.scene_id
-                            ORDER BY member.position
-                        ) AS member_rank
-                    FROM memory_scenes AS ms
-                    JOIN scene_fact_members AS member
-                      ON member.scene_id = ms.scene_id
-                     AND member.profile_id = ms.profile_id
-                    JOIN atomic_facts AS af
-                      ON af.fact_id = member.fact_id
-                     AND af.profile_id = ms.profile_id
-                    WHERE ms.profile_id = ?
-                      AND ms.scene_id IN ({placeholders})
-                )
-                SELECT scene_id, embedding
-                FROM live_scene_facts
-                WHERE member_rank = 1
-                """,
-                (profile_id, *scene_ids),
-            )
-        except Exception:
-            return {}
-
-        result: dict[str, list[float] | None] = {}
-        for row in rows:
-            data = dict(row)
-            raw_embedding = data.get("embedding")
-            embedding = None
-            if raw_embedding:
-                try:
-                    embedding = decode_embedding(
-                        raw_embedding, fact_id=str(data.get("scene_id", "<scene>")),
-                    )
-                except ValueError:
-                    # A malformed stored value, not an absent one. Scenes are an
-                    # optimisation, so one bad row must not sink the batch.
-                    embedding = None
-            result[str(data["scene_id"])] = embedding
-        return result
-
-    def _save_scene(self, scene: MemoryScene) -> None:
-        """Upsert scene to DB."""
-        self._db.execute(
-            """INSERT OR REPLACE INTO memory_scenes
-               (scene_id, profile_id, theme, fact_ids_json, entity_ids_json,
-                created_at, last_updated)
-               VALUES (?, ?, ?, ?, ?, ?, ?)""",
-            (
-                scene.scene_id, scene.profile_id, scene.theme,
-                json.dumps(scene.fact_ids), json.dumps(scene.entity_ids),
-                scene.created_at, scene.last_updated,
-            ),
-        )
-
-    @staticmethod
-    def _row_to_scene(d: dict) -> MemoryScene:
-        return MemoryScene(
-            scene_id=d["scene_id"],
-            profile_id=d["profile_id"],
-            theme=d.get("theme", ""),
-            fact_ids=json.loads(d.get("fact_ids_json", "[]")),
-            entity_ids=json.loads(d.get("entity_ids_json", "[]")),
-            created_at=d.get("created_at", ""),
-            last_updated=d.get("last_updated", ""),
-        )
-
-
-def _cosine(a: list[float] | None, b: list[float] | None) -> float:
-    # v3.4.38: Defensive None guard — embedder can return None on worker
-    # unavailability. Returning 0.0 is correct: zero similarity means no
-    # match, which falls back to creating a new scene.
-    if a is None or b is None:
-        return 0.0
-    dot = sum(x * y for x, y in zip(a, b))
-    na = sum(x * x for x in a) ** 0.5
-    nb = sum(x * x for x in b) ** 0.5
-    if na == 0 or nb == 0:
-        return 0.0
-    return dot / (na * nb)