superlocalmemory 4.0.8 → 4.0.9

package/src/superlocalmemory/learning/model_cache.py

@@ -4,8 +4,6 @@
 
 """Active-model cache + integrity verification.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Section 4.4 — every model load goes through here.
 
 Hard rules enforced:
     M1 — ``pickle.loads`` is FORBIDDEN on ``state_bytes``.

package/src/superlocalmemory/learning/ranker.py

@@ -4,8 +4,6 @@
 
 """3-phase adaptive ranker — from heuristic to ML.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Sections 4.4 + 4.5.
 
 Phase 1: cross-encoder score only (cold start)
 Phase 2: heuristic boosts (some data)

package/src/superlocalmemory/learning/reward_archive.py

@@ -34,6 +34,7 @@ from pathlib import Path
 from superlocalmemory.learning.fact_outcome_joins import (
     has_recent_positive_reward,
 )
+from superlocalmemory.storage.embedding_codec import decode_embedding
 from superlocalmemory.storage.write_lock import get_write_lock
 
 logger = logging.getLogger(__name__)
@@ -113,13 +114,17 @@ def run_reward_gated_archive(
                 window_days=REWARD_WINDOW_DAYS,
             ):
                 continue
+            # Decode the embedding to list[float] so json.dumps(payload)
+            # succeeds regardless of whether the row is TEXT or BLOB.
+            # ValueError (corrupt buffer) propagates — a silent None here
+            # would archive a fact with a missing embedding, which loses data.
             to_archive.append({
                 "fid": fid,
                 "content": row["content"],
                 "canonical_entities_json": row["canonical_entities_json"],
                 "importance": row["importance"],
                 "confidence": row["confidence"],
-                "embedding": row["embedding"],
+                "embedding": decode_embedding(row["embedding"], fact_id=fid),
                 "created_at": row["created_at"],
             })
     finally:

package/src/superlocalmemory/learning/reward_proxy.py

@@ -4,8 +4,6 @@
 
 """Proxy settlement for bandit plays (v3.4.22 only).
 
-LLD reference: ``.backup/active-brain/lld/LLD-03-contextual-bandit-and-ensemble.md``
-Section 3.5 and 5.6.
 
 Replaced in v3.4.22 by ``reward_from_outcomes.py`` — DO NOT extend this
 module beyond the proxy window contract.

package/src/superlocalmemory/learning/signal_worker.py

@@ -4,8 +4,6 @@
 
 """Background signal drain worker.
 
-LLD reference: ``.backup/active-brain/lld/LLD-02-signal-pipeline-and-lightgbm.md``
-Section 4.2 — moves signal writes off the recall hot path.
 
 Contract (hard rules, enforced by tests):
     SW1 — Hot path never waits for disk.

package/src/superlocalmemory/math/fisher.py

@@ -19,7 +19,7 @@ Geodesic distance (Atkinson & Mitchell 1981, Pinele et al. 2020):
     Diagonal multivariate (product-manifold decomposition):
         d_FR(p, q) = sqrt( sum_i  d_i^2 )
 
-Bayesian variance update (NEW in Innovation Wave 4):
+Bayesian variance update (added in v3.5):
 
     V1 bug: query always received UNIFORM variance, so Fisher degenerated
     to a monotonic transform of cosine.  FIX: every fact maintains its own

package/src/superlocalmemory/math/hopfield.py

@@ -56,7 +56,10 @@ class HopfieldConfig:
     max_iterations: int = 1
     convergence_epsilon: float = 1e-6
     prefilter_threshold: int = 10_000
-    prefilter_candidates: int = 1000
+    # MUST match HopfieldConfig.prefilter_candidates in core/config.py, where the
+    # reasoning for the value is written. This stage decides final membership, so
+    # this number is a hard limit on which memories can be returned at all.
+    prefilter_candidates: int = 500
     skip_threshold: int = 100_000
     cache_ttl_seconds: float = 60.0
 

package/src/superlocalmemory/math/langevin.py

@@ -26,7 +26,7 @@ Potential function:
     - Old / unused:       gamma term raises potential -> drift to boundary
     - Important memories: delta term lowers potential -> retain near origin
 
-V1 bugs fixed in Innovation Wave 4:
+V1 bugs fixed in v3.5:
     1. Positions were computed per-recall then DISCARDED.  Now ``step()``
        and ``batch_step()`` return new positions for the caller to persist.
     2. Weight range was [0.7, 1.0] --- too narrow to change rankings.

package/src/superlocalmemory/math/sheaf.py

@@ -24,6 +24,8 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
+from superlocalmemory.storage.embedding_codec import decode_embedding
+
 if TYPE_CHECKING:
     from superlocalmemory.storage.database import DatabaseManager
     from superlocalmemory.storage.models import AtomicFact
@@ -251,7 +253,9 @@ class SheafConsistencyChecker:
         if raw is None or raw == "":
             return None
         try:
-            data = json.loads(raw) if isinstance(raw, str) else raw
-            return np.asarray(data, dtype=np.float64)
-        except (json.JSONDecodeError, TypeError, ValueError):
+            data = decode_embedding(raw, fact_id=str(fact_id))
+        except ValueError:
+            return None
+        if data is None:
             return None
+        return np.asarray(data, dtype=np.float64)

package/src/superlocalmemory/mcp/cli_fallback.py

@@ -1,6 +1,6 @@
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Licensed under AGPL-3.0-or-later - see LICENSE file
-# WP-09: MCP→CLI fallback adapter (ships INERT — DQ-2=B)
+# MCP→CLI fallback adapter (ships inert — disabled by default, no active use yet)
 
 """MCP→CLI fallback adapter for SuperLocalMemory.
 

package/src/superlocalmemory/mcp/profiles.py

@@ -14,7 +14,7 @@ Do NOT import FastMCP, MemoryEngine, or any heavy dependency here.
 from __future__ import annotations
 
 # ---------------------------------------------------------------------------
-# v3.6.14 WP-01: Named profile definitions
+# Named profile definitions (introduced in v3.6.14)
 # ---------------------------------------------------------------------------
 
 _PROFILE_CORE: frozenset[str] = frozenset({  # 17

package/src/superlocalmemory/mcp/server.py

@@ -159,7 +159,7 @@ _all_tools = _os_reg.environ.get("SLM_MCP_ALL_TOOLS") == "1"
 _user_allowlist_str = _os_reg.environ.get("SLM_MCP_TOOLS", "").strip()
 
 # ---------------------------------------------------------------------------
-# v3.6.14 WP-01: Named profile definitions
+# Named profile definitions (introduced in v3.6.14)
 # Extracted to mcp/profiles.py (v3.8.0) — pure data, no side effects.
 # All names re-exported here for backward compatibility with existing tests
 # and any code that imports them from this module.

package/src/superlocalmemory/mcp/tools_active.py

@@ -255,6 +255,56 @@ def _canonical_feedback_count(profile_id: str) -> int | None:
         return None
 
 
+# How far ahead a session looks for scheduled facts, and how many it shows.
+# A session preamble is not a calendar: a long horizon or a large cap turns a
+# useful heads-up into a wall of text nobody reads.
+_SCHEDULED_HORIZON_DAYS = 14
+_SCHEDULED_LIMIT = 5
+
+
+def _upcoming_scheduled_facts(engine, now: datetime.datetime) -> list[dict]:
+    """Facts scheduled from today through the horizon, soonest first.
+
+    Bounded and index-backed, because this runs on every session start. Returns
+    an empty list on any failure: a session must still open when this query
+    cannot answer, so the caller omits the surface entirely rather than showing
+    an empty section that reads like a defect.
+
+    Selects on the stored type of the fact, which is a classification recorded at
+    write time. It is unrelated to the similarly named retrieval channel despite
+    sharing the word.
+    """
+    try:
+        db = getattr(engine, "_db", None) or getattr(engine, "db", None)
+        if db is None or not hasattr(db, "execute"):
+            return []
+        # Both 'YYYY-MM-DD' and full timestamps compare correctly as text,
+        # because ISO-8601 orders lexicographically. The upper bound is
+        # exclusive, so the horizon day itself is included.
+        start = now.date().isoformat()
+        end = (now + datetime.timedelta(days=_SCHEDULED_HORIZON_DAYS + 1)).date().isoformat()
+        rows = db.execute(
+            "SELECT fact_id, content, referenced_date"
+            " FROM atomic_facts"
+            " WHERE profile_id = ?"
+            "   AND fact_type = 'temporal'"
+            "   AND referenced_date IS NOT NULL"
+            "   AND referenced_date >= ?"
+            "   AND referenced_date < ?"
+            " ORDER BY referenced_date ASC"
+            f" LIMIT {_SCHEDULED_LIMIT}",
+            (engine.profile_id, start, end),
+        )
+        return [
+            {"fact_id": r["fact_id"], "content": r["content"],
+             "scheduled_at": r["referenced_date"]}
+            for r in rows
+        ]
+    except Exception as exc:
+        logger.warning("scheduled-fact surface failed: %s", exc)
+        return []
+
+
 def register_active_tools(server, get_engine: Callable) -> None:
     """Register 3 active memory tools on *server*."""
 
@@ -519,6 +569,8 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 f"-{uuid.uuid4().hex[:8]}"
             )
 
+            _upcoming_events = _upcoming_scheduled_facts(engine, _now)
+
             return {
                 "success": True,
                 "session_id": session_id,
@@ -553,6 +605,10 @@ def register_active_tools(server, get_engine: Callable) -> None:
                         else "trained"
                     ),
                 },
+                # Scheduled-event surface: present only when facts exist in the
+                # 14-day window. Absent means the window is empty, not an error.
+                **( {"upcoming_events": _upcoming_events}
+                    if _upcoming_events else {} ),
             }
         except Exception as exc:
             logger.exception("session_init failed")

package/src/superlocalmemory/mcp/tools_core.py

@@ -560,7 +560,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             if db_path.exists():
                 db_size_mb = round(os.path.getsize(db_path) / (1024 * 1024), 2)
 
-            # WP-02 D8: additive canonical key set — provider/base_dir/db_path added.
+            # additive canonical key set — provider/base_dir/db_path added.
             # All pre-existing keys are preserved (zero removals).
             cfg = engine._config
             return {

package/src/superlocalmemory/optimize/cache/manager.py

@@ -223,7 +223,7 @@ class CacheManager:
             tenant_id = _hashlib.sha256(tenant_id.encode()).hexdigest()
 
         if isinstance(req, ProxyRequest) and req.provider == "vertex":
-            # CRIT-2 (WP-11, LOCKED): Vertex bodies have NO model/messages/system.
+            # LOCKED: Vertex bodies have NO model/messages/system.
             # Model is in the PATH; prompts are under 'contents'; system under
             # 'systemInstruction'. Without this branch ALL Vertex requests hash to
             # ONE key → first response poisons every subsequent prompt.
@@ -701,7 +701,7 @@ def json_dumps_bytes(d: dict) -> bytes:
 
 
 # ---------------------------------------------------------------------------
-# Vertex helpers (WP-11 / CRIT-2)
+# Vertex helpers
 # ---------------------------------------------------------------------------
 
 def _vertex_project_location_from_path(path: str) -> tuple[str, str]:

package/src/superlocalmemory/optimize/compress/ccr.py

@@ -99,7 +99,7 @@ class CCRStore:
     def delete(self, ccr_id: str, *, tenant_id: str = "default") -> None:
         """Delete a CCR row by ccr_id scoped to tenant. Idempotent — never raises.
 
-        WP-10 D6: defensive infra. Deleting a non-existent ccr_id is a no-op.
+        Defensive delete — idempotent: deleting a non-existent ccr_id is a no-op.
         H-02: tenant_id guard prevents cross-tenant deletion.
         """
         try:

package/src/superlocalmemory/optimize/compress/router.py

@@ -411,7 +411,7 @@ class CompressRouter:
             logger.debug("CCR update_compressed failed (non-fatal): %s", exc)
 
     def _ccr_delete(self, ccr_id: str) -> None:
-        """WP-10 D6: Defensive delete — idempotent, never raises.
+        """Defensive delete — idempotent, never raises.
 
         Used to clean up a CCR row if post-store processing fails. In the
         store-after-success D6 path this should never be needed (no orphans

package/src/superlocalmemory/optimize/proxy/_helpers.py

@@ -123,10 +123,10 @@ _OPENAI_FORWARD_HEADERS = frozenset([
 _GEMINI_NATIVE_FORWARD_HEADERS = frozenset([
     "x-goog-api-key",
     "content-type",
-    "authorization",  # WP-11a: Antigravity ADC/OAuth bearer was dropped; add it back
+    "authorization",  # Antigravity ADC/OAuth bearer was previously dropped; explicitly add it back
 ])
 
-# WP-11: Vertex AI forward headers — Authorization passed untouched (AC-2).
+# Vertex AI forward headers — Authorization is passed through untouched.
 # x-goog-user-project required for quota attribution on Vertex calls.
 _VERTEX_FORWARD_HEADERS = frozenset([
     "authorization",

package/src/superlocalmemory/optimize/proxy/server.py

@@ -150,7 +150,7 @@ def build_proxy_router(proxy: ProxyApp) -> APIRouter:
     async def gemini_openai_models_route(request: Request) -> Response:
         return await handle_gemini_openai_compat(proxy, request)
 
-    # WP-11: Vertex AI passthrough — must be registered AFTER exact /v1/* routes
+    # Vertex AI passthrough — must be registered AFTER exact /v1/* routes
     # to avoid shadowing /v1/messages, /v1/chat/completions, /v1/embeddings, etc.
     # FastAPI resolves routes in registration order; the exact routes above are
     # declared before this catch-path, so there is no shadowing.

package/src/superlocalmemory/optimize/proxy/vertex_surface.py

@@ -1,4 +1,4 @@
-"""vertex_surface.py — Vertex AI passthrough proxy surface (WP-11).
+"""vertex_surface.py — Vertex AI passthrough proxy surface.
 
 Transparent passthrough: forward Authorization bearer untouched (AC-2),
 cache by body content never by token (SEC), no SSE — always single JSON.
@@ -14,7 +14,7 @@ Key design decisions (per LLD §5 STAGE-5 RESOLUTIONS):
   SECURITY (AC-3): bearer token structurally excluded from cache key, value,
            logs, and stored ProxyRequest.headers (redacted via _redact_headers).
 
-WP-11a (gemini-native fix) lives in _helpers.py:_GEMINI_NATIVE_FORWARD_HEADERS.
+The gemini-native Authorization-header fix lives in _helpers.py:_GEMINI_NATIVE_FORWARD_HEADERS.
 """
 
 from __future__ import annotations

package/src/superlocalmemory/optimize/storage/db.py

@@ -959,7 +959,7 @@ class CacheDB:
     def ccr_delete(self, ccr_id: str, *, tenant_id: str = "default") -> None:
         """Delete a CCR row by ccr_id scoped to tenant. Idempotent — warns on sqlite error, never raises.
 
-        WP-10 D6: defensive infra + sweep parity. Deleting a non-existent row is a no-op.
+        Defensive delete — idempotent: deleting a non-existent row is a no-op.
         H-02: tenant_id guard prevents a tenant from deleting another tenant's CCR.
         """
         try:
@@ -973,7 +973,7 @@ class CacheDB:
     def ccr_count(self) -> int:
         """Return UNFILTERED count of rows in llmcache_ccr_originals.
 
-        WP-10 CRIT-2: Do NOT reuse TTL-filtered count at :646. A fresh no-expiry row
+        Do NOT reuse TTL-filtered count from the query above. A fresh no-expiry row
         has ttl_expires=None, so the TTL filter returns 0 and D6 orphan tests would
         falsely pass. This unfiltered count is test infrastructure only.
         """

package/src/superlocalmemory/retrieval/agentic.py

@@ -163,7 +163,7 @@ class AgenticRetriever:
                 RetrievalRound(2, rq, len(rn), _avg(rn), True),
             )
 
-        merged = sorted(pool.values(), key=lambda x: x[1], reverse=True)
+        merged = sorted(pool.values(), key=lambda x: (-x[1], x[0].fact_id))
         return [f for f, _ in merged[:top_k]]
 
     # -- Sufficiency check ---------------------------------------------------

package/src/superlocalmemory/retrieval/ann_index.py

@@ -178,8 +178,15 @@ class ANNIndex:
             if k <= 0:
                 return []
 
-            top_indices = np.argpartition(scores, -k)[-k:]
-            top_indices = top_indices[np.argsort(scores[top_indices])[::-1]]
+            # Full sort with a secondary key on fact_id so that equal cosine
+            # scores are broken deterministically.  argpartition cannot
+            # guarantee which facts reach the top-k when scores tie at the
+            # boundary — the selection follows array layout (insertion order)
+            # and changes between restarts.  lexsort picks the same k facts
+            # in the same order regardless of how the index was loaded.
+            id_arr = np.array(self._ids, dtype=object)
+            order = np.lexsort((id_arr, -scores))  # primary: -score, secondary: fact_id
+            top_indices = order[:k]
 
             return [
                 (self._ids[i], float(scores[i]))

package/src/superlocalmemory/retrieval/bm25_channel.py

@@ -267,7 +267,7 @@ class BM25Channel:
         except Exception as exc:  # pragma: no cover — legacy/missing expansion FTS
             logger.debug("Expansion FTS search skipped: %s", exc)
 
-        out.sort(key=lambda x: x[1], reverse=True)
+        out.sort(key=lambda x: (-x[1], x[0]))
         return out[:top_k]
 
     def search(
@@ -341,7 +341,7 @@ class BM25Channel:
                         bonus *= 1.5  # 50% boost for exact phrase match
                 scored.append((self._fact_ids[i], bonus))
 
-        scored.sort(key=lambda x: x[1], reverse=True)
+        scored.sort(key=lambda x: (-x[1], x[0]))
         return scored[:top_k]
 
     def update_fact(self, fact_id: str, new_content: str, profile_id: str) -> None:

package/src/superlocalmemory/retrieval/bridge_discovery.py

@@ -160,7 +160,7 @@ class BridgeDiscovery:
             if len(bridges) >= max_bridges:
                 break
 
-        bridges.sort(key=lambda x: x[1], reverse=True)
+        bridges.sort(key=lambda x: (-x[1], x[0]))
         return filter_authorized_results(
             self._db,
             bridges,
@@ -243,7 +243,7 @@ class BridgeDiscovery:
             for fid, score in activations.items()
             if fid not in set(seed_ids) and score > 0.01
         ]
-        results.sort(key=lambda x: x[1], reverse=True)
+        results.sort(key=lambda x: (-x[1], x[0]))
         return filter_authorized_results(
             self._db,
             results,