superlocalmemory 4.0.9 → 4.1.0

package/src/superlocalmemory/core/working_memory.py

@@ -0,0 +1,288 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""A small, per-session set of memories that biases the next recall.
+
+WHAT THIS IS FOR
+----------------
+Turn 5 of a conversation currently knows nothing about turns 1-4. Every recall
+starts from the query alone, so a memory the user was just discussing competes
+from scratch against every other memory in the store.
+
+``ContextCache`` does not fix this, because it does something different: on a
+hit it answers *instead of* searching, and on a miss it contributes nothing.
+This module biases a search that always runs in full. The distinction is the
+whole point — a cache replaces retrieval, a working set shapes it.
+
+The two are complementary and both stay: the cache short-circuits an exact
+repeat of a query before the daemon is reached, this biases the ranking of
+every query that does reach it.
+
+WHY SO SMALL
+------------
+Seven slots per session, evicting the least-activated when full. Human working
+memory is capacity-limited to a handful of items, and the limit is what makes it
+useful: an unbounded "everything recently seen" set would boost most of the
+store and therefore rank nothing.
+
+Seven is the constant this ships with. It is a starting point, not a derived
+optimum, and ``MAX_SLOTS`` is the single place to change it.
+
+ADMISSION IS BY RANK, NOT BY SCORE
+----------------------------------
+An earlier design admitted a memory when its fused score cleared 0.60. That
+threshold is unreachable, and measurably so: reciprocal-rank fusion of *n*
+channels caps the top score at ``n/(k+1)``, which is 0.31 at ``rrf_k=15`` and
+0.08 at ``rrf_k=60``. Nothing would ever have been admitted, the bias would
+never have fired, and the symptom would have been silence rather than an error.
+(The 0.60 that does exist in retrieval is the evidence floor's semantic cosine —
+a different quantity on a different scale.)
+
+So admission takes the memories that were actually *shown* at the top of an
+answer. Rank survives every rescaling the pipeline applies to scores; an
+absolute threshold does not.
+
+WHY A LOCK, AND NOT "THE GIL IS ENOUGH"
+---------------------------------------
+``admit`` reads the slot list, decides an eviction, and writes it back. That is
+not atomic under the GIL — it spans many bytecodes, and the daemon serves
+recalls from a thread-pool executor, so two recalls in one session genuinely
+interleave. Without the lock, both can pass the capacity check and both append,
+leaving eight slots in a seven-slot set. A lock acquisition costs nanoseconds
+against a recall measured in hundreds of milliseconds.
+
+NEVER PERSISTED
+---------------
+There is no table behind this and there must not be. It is ephemeral by
+definition; persisting it would create an unbounded write per recall for state
+whose entire value is that it is cheap.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+
+__all__ = [
+    "MAX_SLOTS",
+    "WorkingMemory",
+    "discard",
+    "discard_profile",
+    "get_or_create",
+    "registry_size",
+]
+
+#: Slots per session. See "WHY SO SMALL" above.
+MAX_SLOTS = 7
+
+#: How many shown memories a single answer may offer for admission. Matches the
+#: prefix the settlement path records as "what this query showed", so the two
+#: notions of "what the user actually saw" cannot drift apart.
+ADMIT_TOP_N = 5
+
+#: A session untouched for this long is dropped. The daemon runs for weeks.
+SESSION_IDLE_EVICT_SECS = 86_400  # 24 h
+
+#: Hard ceiling on tracked sessions, evicting least-recently-touched first.
+#: Age alone does not bound anything inside the first 24 hours, and a burst of
+#: short-lived session ids is exactly the shape of an agent workload.
+MAX_SESSIONS = 512
+
+#: Activation halves roughly every hour of disuse.
+_RECENCY_HALFLIFE_SECS = 3_600.0
+
+
+@dataclass(frozen=True)
+class _Slot:
+    """One remembered memory. Frozen, so an update is a replacement.
+
+    Immutability is not decoration here: a reader holding this object while a
+    writer updates the same memory sees either the old slot or the new one,
+    never a half-applied mix of the two.
+    """
+
+    fact_id: str
+    hits: int
+    last_seen: float
+
+    def activation(self, now: float) -> float:
+        """How strongly this memory is currently held.
+
+        Repetition raises it, elapsed time lowers it. The decay is a smooth
+        reciprocal rather than a step, so eviction never depends on which side
+        of a boundary a timestamp happened to land.
+        """
+        age = max(0.0, now - self.last_seen)
+        return self.hits / (1.0 + age / _RECENCY_HALFLIFE_SECS)
+
+
+class WorkingMemory:
+    """The working set for one (profile, session) pair."""
+
+    __slots__ = ("_lock", "_slots", "_touched_at")
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._slots: dict[str, _Slot] = {}
+        self._touched_at = time.monotonic()
+
+    # -- mutation ----------------------------------------------------------
+
+    def admit(self, fact_ids: list[str] | tuple[str, ...]) -> None:
+        """Offer the memories an answer just showed, best-ranked first.
+
+        Already-held memories are reinforced rather than duplicated, which is
+        what makes a memory referenced across several turns hard to evict.
+        """
+        if not fact_ids:
+            return
+        now = time.monotonic()
+        with self._lock:
+            self._touched_at = now
+            for fact_id in fact_ids[:ADMIT_TOP_N]:
+                if not fact_id:
+                    continue
+                existing = self._slots.get(fact_id)
+                self._slots[fact_id] = _Slot(
+                    fact_id=fact_id,
+                    hits=(existing.hits + 1) if existing else 1,
+                    last_seen=now,
+                )
+            self._evict_locked(now)
+
+    def touch(self, fact_id: str) -> None:
+        """Reinforce a memory something downstream actually used.
+
+        Stronger evidence than having been displayed, and it arrives later, so
+        it is a separate entry point rather than a flag on ``admit``. A memory
+        that is not held is not admitted by being touched: this reinforces
+        attention, it does not create it.
+        """
+        if not fact_id:
+            return
+        now = time.monotonic()
+        with self._lock:
+            self._touched_at = now
+            existing = self._slots.get(fact_id)
+            if existing is None:
+                return
+            self._slots[fact_id] = _Slot(
+                fact_id=fact_id, hits=existing.hits + 1, last_seen=now,
+            )
+
+    def _evict_locked(self, now: float) -> None:
+        """Drop the least-activated slots. Caller holds the lock."""
+        while len(self._slots) > MAX_SLOTS:
+            weakest = min(
+                self._slots.values(),
+                key=lambda s: (s.activation(now), s.last_seen, s.fact_id),
+            )
+            self._slots.pop(weakest.fact_id, None)
+
+    # -- reads -------------------------------------------------------------
+
+    def boost_set(self) -> frozenset[str]:
+        """The memories currently held. Read by the ranking bias."""
+        with self._lock:
+            return frozenset(self._slots)
+
+    def idle_secs(self, now: float | None = None) -> float:
+        with self._lock:
+            return max(0.0, (now or time.monotonic()) - self._touched_at)
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._slots)
+
+
+# ---------------------------------------------------------------------------
+# Registry
+#
+# Keyed by (profile_id, session_id), never by session_id alone. Two profiles in
+# one daemon can be handed the same session id, and a shared key would let one
+# profile's memories bias the other's answers. It also gives erasure something
+# to erase: ``discard_profile`` can find every set belonging to a profile.
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[tuple[str, str], WorkingMemory] = {}
+_REGISTRY_LOCK = threading.Lock()
+
+
+def get_or_create(profile_id: str, session_id: str) -> WorkingMemory:
+    """The working set for this session, creating it on first use.
+
+    Both arguments are required and neither defaults. A default ``profile_id``
+    is how two profiles end up sharing one set.
+    """
+    key = (profile_id or "", session_id or "")
+    with _REGISTRY_LOCK:
+        _sweep_locked()
+        existing = _REGISTRY.get(key)
+        if existing is not None:
+            return existing
+        created = WorkingMemory()
+        _REGISTRY[key] = created
+        return created
+
+
+def peek(profile_id: str, session_id: str) -> WorkingMemory | None:
+    """The working set if one exists, without creating one.
+
+    Reading must not allocate: a bias that runs on every recall would otherwise
+    register an entry for every session id it ever sees, including those that
+    never admit anything.
+    """
+    with _REGISTRY_LOCK:
+        return _REGISTRY.get((profile_id or "", session_id or ""))
+
+
+def discard(profile_id: str, session_id: str) -> None:
+    """Forget one session. Called when a session closes."""
+    with _REGISTRY_LOCK:
+        _REGISTRY.pop((profile_id or "", session_id or ""), None)
+
+
+def discard_profile(profile_id: str) -> int:
+    """Forget every session belonging to a profile. Returns the count dropped.
+
+    Called from erasure. In-process state is still the erased subject's data:
+    leaving it behind would let a deleted profile's memories bias a later
+    session that reuses its session id, which is the residue defect this
+    project has already paid for once in a search index.
+    """
+    target = profile_id or ""
+    with _REGISTRY_LOCK:
+        doomed = [k for k in _REGISTRY if k[0] == target]
+        for key in doomed:
+            _REGISTRY.pop(key, None)
+        return len(doomed)
+
+
+def registry_size() -> int:
+    with _REGISTRY_LOCK:
+        return len(_REGISTRY)
+
+
+def _sweep_locked() -> None:
+    """Bound the registry by idle time and then by count. Caller holds the lock."""
+    now = time.monotonic()
+    stale = [
+        key for key, wm in _REGISTRY.items()
+        if wm.idle_secs(now) > SESSION_IDLE_EVICT_SECS
+    ]
+    for key in stale:
+        _REGISTRY.pop(key, None)
+    # Trim to one below the ceiling, because the caller is about to insert.
+    # Trimming to the ceiling itself leaves the registry one over after every
+    # insertion, which is a cap that is never actually enforced. Sweeping after
+    # the insert instead would make the new entry — idle for zero seconds, tied
+    # with every other new entry — a candidate for its own eviction.
+    headroom = MAX_SESSIONS - 1
+    if len(_REGISTRY) <= headroom:
+        return
+    by_age = sorted(
+        _REGISTRY.items(), key=lambda kv: (-kv[1].idle_secs(now), kv[0]),
+    )
+    for key, _wm in by_age[: len(_REGISTRY) - headroom]:
+        _REGISTRY.pop(key, None)

package/src/superlocalmemory/encoding/cognitive_consolidator.py

@@ -187,6 +187,33 @@ def _temporal_midpoint(dates: list[datetime]) -> str:
 # ---------------------------------------------------------------------------
 
 
+def _config_for_this_store() -> "CCQConfig":
+    """The settings this store is actually running under.
+
+    A caller that supplies only a database used to get the bare defaults, which
+    say a language model may be used to summarise. Three of the four places
+    that build this pass only a database, so on a store configured to use no
+    language model at all, the refusal below rested on nobody having handed one
+    in -- true today, and not a property of the mode. Reading the store's own
+    settings makes it a property of the mode.
+
+    Falls back to the defaults if the settings cannot be read, because a
+    consolidation pass that cannot start is worse than one that starts with the
+    documented defaults.
+    """
+    from superlocalmemory.core.config import CCQConfig as _CCQConfig
+
+    try:
+        from superlocalmemory.core.config import SLMConfig
+
+        resolved = getattr(SLMConfig.load(), "ccq", None)
+        if isinstance(resolved, _CCQConfig):
+            return resolved
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("consolidator: using default settings (%s)", exc)
+    return _CCQConfig()
+
+
 class CognitiveConsolidator:
     """CCQ engine: sleep-time consolidation with quantization.
 
@@ -203,12 +230,10 @@ class CognitiveConsolidator:
         llm: LLM | None = None,
         config: CCQConfig | None = None,
     ) -> None:
-        from superlocalmemory.core.config import CCQConfig as _CCQConfig
-
         self._db = db
         self._embedder = embedder
         self._llm = llm
-        self._config = config or _CCQConfig()
+        self._config = config if config is not None else _config_for_this_store()
 
     # ------------------------------------------------------------------
     # Public API
@@ -327,6 +352,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 +530,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),
         )
 
@@ -516,10 +555,15 @@ class CognitiveConsolidator:
                 representative_fact_id="",
             )
 
-        # Try LLM mode (Mode B) if configured
+        # Configuration first, then availability. Mode A sets use_llm_gist=False,
+        # so this refuses because the mode says to — not because an LLM happened
+        # not to be passed in. The previous order tested availability first,
+        # which meant a caller that supplied a model to a Mode A engine would
+        # have got an LLM call on a mode whose whole promise is that nothing
+        # does.
         if (
-            self._llm is not None
-            and self._config.use_llm_gist
+            self._config.use_llm_gist
+            and self._llm is not None
         ):
             try:
                 gist = self._extract_gist_llm(

package/src/superlocalmemory/encoding/context_generator.py

@@ -98,7 +98,7 @@ class ContextGenerator:
             FactType.EPISODIC: "episodic event",
             FactType.SEMANTIC: "semantic knowledge",
             FactType.OPINION: "opinion or preference",
-            FactType.TEMPORAL: "time-bounded event",
+            FactType.PROSPECTIVE: "time-bounded event",
         }
         type_label = type_labels.get(fact.fact_type, "memory")
 

package/src/superlocalmemory/encoding/entity_resolver.py

@@ -223,6 +223,39 @@ def _guess_entity_type(name: str) -> str:
 # Entity Resolver
 # ---------------------------------------------------------------------------
 
+def _unproject_entity(entity_id: str) -> bool:
+    """Remove an entity node from the graph projection, if there is one.
+
+    The projection is a separate storage engine, so deleting the row from
+    SQLite reaches nothing there. An entity node left behind still carries the
+    name it was created with, which is exactly the thing an erasure was asked
+    to remove.
+
+    Returns False when a projection exists and refused, so a caller that
+    reports completeness can report this honestly. No projection at all is not
+    a failure -- there is nothing to remove.
+    """
+    try:
+        from superlocalmemory.core.backend_orchestrator import get_orchestrator
+    except Exception:  # noqa: BLE001
+        return True
+    try:
+        orchestrator = get_orchestrator()
+        graph = orchestrator.get_graph_backend() if orchestrator else None
+        if graph is None:
+            return True
+        remove = getattr(graph, "remove_entity", None)
+        if remove is None:
+            return True
+        remove(entity_id)
+        return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "the graph projection still holds entity %s (%s)", entity_id[:12], exc,
+        )
+        return False
+
+
 class EntityResolver:
     """Resolves raw entity mentions to persisted canonical entities.
 
@@ -444,6 +477,11 @@ class EntityResolver:
             "DELETE FROM canonical_entities WHERE entity_id = ? AND profile_id = ?",
             (entity_id_merge, profile_id),
         )
+        # The merged-away node has its own copy in the graph projection, and
+        # deleting the row above does not reach it. Left there it keeps its own
+        # name and its own edges, so the two halves of a merged entity stay
+        # visible to a graph query as two entities.
+        _unproject_entity(entity_id_merge)
         logger.info(
             "Merged entity %s into %s (profile=%s)",
             entity_id_merge, entity_id_keep, profile_id,

package/src/superlocalmemory/encoding/fact_extractor.py

@@ -17,7 +17,7 @@ the majority of benchmark score differences.
 Key patterns implemented:
   - Conversation chunking (5-10 turns, 2-turn overlap)
   - Three-date temporal model (observation, referenced, interval)
-  - Typed fact classification (episodic / semantic / opinion / temporal)
+  - Typed fact classification (episodic / semantic / opinion / prospective)
   - Importance scoring (entity frequency + emotional markers + recency)
   - Narrative fact extraction in LLM modes (self-contained, context-rich)
 
@@ -34,6 +34,7 @@ import uuid
 from typing import Any, Protocol, runtime_checkable
 
 from superlocalmemory.core.config import EncodingConfig
+from superlocalmemory.encoding.prospective_markers import looks_prospective
 from superlocalmemory.storage.models import AtomicFact, FactType, Mode, SignalType
 
 logger = logging.getLogger(__name__)
@@ -107,13 +108,6 @@ _EXPERIENCE_MARKERS = re.compile(
     re.IGNORECASE,
 )
 
-_TEMPORAL_MARKERS = re.compile(
-    r"\b(?:deadline|due date|expires?|scheduled|appointment|meeting|"
-    r"on \w+day|at \d{1,2}:\d{2}|by \w+|until|before|after|"
-    r"in \d+ (?:days?|weeks?|months?|years?)|"
-    r"next week|next month|this weekend|tomorrow|yesterday)\b",
-    re.IGNORECASE,
-)
 
 _EMOTIONAL_KEYWORDS = frozenset({
     "love", "hate", "amazing", "terrible", "wonderful", "awful", "excited",
@@ -153,7 +147,7 @@ _SYSTEM_PROMPT = (
     "- episodic: personal event or experience (visited, attended, did)\n"
     "- semantic: objective fact about the world (jobs, locations, relations)\n"
     "- opinion: subjective belief or preference (likes, thinks, prefers)\n"
-    "- temporal: time-bound fact with dates or deadlines\n\n"
+    "- prospective: something planned for later, with a date or deadline\n\n"
     "Respond ONLY with a JSON array. Example:\n"
     '[{"text":"Alice works at Google as a software engineer",'
     '"fact_type":"semantic","entities":["Alice","Google"],'
@@ -320,11 +314,18 @@ def _extract_entities(text: str) -> list[str]:
 
 
 def _classify_sentence(sentence: str) -> FactType:
-    """Classify a sentence into a FactType using keyword markers."""
-    if _TEMPORAL_MARKERS.search(sentence):
-        return FactType.TEMPORAL
+    """Classify a sentence into a FactType using keyword markers.
+
+    Opinion is asked first, and the router asks in the same order. They used to
+    differ, so "I think we should ship next week" was a plan on one path and an
+    opinion on the other, for the same sentence. Opinion wins because an opinion
+    about a plan is not a commitment, and the list of what is coming up should
+    hold commitments.
+    """
     if _OPINION_MARKERS.search(sentence):
         return FactType.OPINION
+    if looks_prospective(sentence):
+        return FactType.PROSPECTIVE
     if _EXPERIENCE_MARKERS.search(sentence):
         return FactType.EPISODIC
     return FactType.SEMANTIC
@@ -370,7 +371,7 @@ def _signal_from_fact_type(ft: FactType) -> SignalType:
         FactType.EPISODIC: SignalType.FACTUAL,
         FactType.SEMANTIC: SignalType.FACTUAL,
         FactType.OPINION: SignalType.OPINION,
-        FactType.TEMPORAL: SignalType.TEMPORAL,
+        FactType.PROSPECTIVE: SignalType.TEMPORAL,
     }
     return mapping.get(ft, SignalType.FACTUAL)
 
@@ -770,7 +771,10 @@ class FactExtractor:
             "semantic": FactType.SEMANTIC,
             "world": FactType.SEMANTIC,
             "opinion": FactType.OPINION,
-            "temporal": FactType.TEMPORAL,
+            "prospective": FactType.PROSPECTIVE,
+            # Kept alongside the current word for the reason given in
+            # type_router: an unrecognised type falls through to SEMANTIC.
+            "temporal": FactType.PROSPECTIVE,
         }
         fact_type = type_map.get(raw_type, FactType.SEMANTIC)