superlocalmemory 3.4.19 → 3.4.21

package/src/superlocalmemory/mcp/tools_context.py

@@ -0,0 +1,183 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-05 §7
+
+"""MCP proactive-context tool — ``prestage_context``.
+
+LLD-05 §7. Exposes a single MCP tool that returns top-K redacted memories
+for a given query. Guardrails:
+  - Rate limit 30 calls / minute (token bucket; A11).
+  - Every returned text passes through ``redact_secrets`` (A9).
+  - JSON response size bound ≤ 16 KB.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from threading import Lock
+from typing import Callable
+
+from superlocalmemory.core.security_primitives import redact_secrets
+
+logger = logging.getLogger(__name__)
+
+MAX_CALLS_PER_MINUTE = 30
+MAX_RESPONSE_BYTES = 16 * 1024  # 16 KB
+WINDOW_SECONDS = 60.0
+
+
+@dataclass
+class _RateLimiter:
+    """Simple fixed-window rate limiter. Thread-safe.
+
+    Keyed by session id. Clock is injectable for deterministic tests.
+    """
+    max_calls: int = MAX_CALLS_PER_MINUTE
+    window: float = WINDOW_SECONDS
+    now_fn: Callable[[], float] = time.monotonic
+    _buckets: dict[str, tuple[float, int]] = field(default_factory=dict)
+    _lock: Lock = field(default_factory=Lock)
+
+    def allow(self, key: str) -> bool:
+        with self._lock:
+            now = self.now_fn()
+            start, count = self._buckets.get(key, (now, 0))
+            if now - start >= self.window:
+                # Reset window.
+                self._buckets[key] = (now, 1)
+                return True
+            if count >= self.max_calls:
+                return False
+            self._buckets[key] = (start, count + 1)
+            return True
+
+    def reset(self) -> None:
+        with self._lock:
+            self._buckets.clear()
+
+
+_DEFAULT_LIMITER = _RateLimiter()
+
+
+# RecallFn for the tool. Callers inject a real recall engine; tests inject fakes.
+PrestageRecallFn = Callable[[str, int, str], list[dict]]
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _cap_memory(memory: dict, *, max_text_bytes: int = 2048) -> dict:
+    """Ensure each memory is bounded and redacted."""
+    text = memory.get("text", "")
+    if not isinstance(text, str):
+        text = str(text)
+    text = redact_secrets(text)
+    if len(text.encode("utf-8")) > max_text_bytes:
+        text = text.encode("utf-8")[:max_text_bytes].decode("utf-8", "ignore")
+    score = float(memory.get("score", 0.0) or 0.0)
+    return {
+        "id": str(memory.get("id", "")),
+        "text": text,
+        "score": score,
+        "source": str(memory.get("source", "recall")),
+    }
+
+
+def prestage_context(
+    query: str,
+    *,
+    limit: int = 5,
+    profile_id: str = "default",
+    session_id: str = "default",
+    recall_fn: PrestageRecallFn,
+    limiter: _RateLimiter | None = None,
+) -> dict:
+    """Proactive-context tool body.
+
+    Pure function: takes an injected recall_fn + limiter. The MCP server
+    wrapper in the session process wires the real engine and shares a
+    single limiter instance.
+    """
+    _limiter = limiter or _DEFAULT_LIMITER
+    if not _limiter.allow(session_id):
+        return {
+            "error": "rate_limit_exceeded",
+            "memories": [],
+            "generated_at": _iso_now(),
+            "limit": limit,
+            "truncated_count": 0,
+        }
+
+    if not isinstance(query, str) or not query.strip():
+        return {
+            "error": "empty_query",
+            "memories": [],
+            "generated_at": _iso_now(),
+            "limit": limit,
+            "truncated_count": 0,
+        }
+    limit = max(1, min(int(limit), 50))
+
+    try:
+        raw = recall_fn(query, limit, profile_id) or []
+    except Exception as exc:
+        logger.warning("prestage_context recall failed: %s", exc)
+        return {
+            "error": "recall_error",
+            "memories": [],
+            "generated_at": _iso_now(),
+            "limit": limit,
+            "truncated_count": 0,
+        }
+
+    capped = [_cap_memory(m) for m in raw if isinstance(m, dict)]
+    capped = capped[:limit]
+
+    # Enforce total response size cap (A11/16 KB).
+    response = {
+        "memories": capped,
+        "generated_at": _iso_now(),
+        "limit": limit,
+        "truncated_count": 0,
+    }
+    encoded = json.dumps(response).encode("utf-8")
+    truncated = 0
+    while len(encoded) > MAX_RESPONSE_BYTES and response["memories"]:
+        response["memories"].pop()
+        truncated += 1
+        response["truncated_count"] = truncated
+        encoded = json.dumps(response).encode("utf-8")
+    return response
+
+
+def register_prestage_tool(server, recall_fn: PrestageRecallFn,
+                           *, session_id_fn: Callable[[], str] | None = None
+                           ) -> None:
+    """Register the ``prestage_context`` tool on an MCP server."""
+    limiter = _RateLimiter()
+
+    @server.tool()
+    async def prestage_context_tool(  # pragma: no cover — MCP wiring
+        query: str,
+        limit: int = 5,
+        profile_id: str = "default",
+    ) -> dict:
+        """Proactively return top-K memories for a query."""
+        session_id = session_id_fn() if session_id_fn else "default"
+        return prestage_context(
+            query, limit=limit, profile_id=profile_id,
+            session_id=session_id, recall_fn=recall_fn, limiter=limiter,
+        )
+
+
+__all__ = (
+    "MAX_CALLS_PER_MINUTE",
+    "MAX_RESPONSE_BYTES",
+    "prestage_context",
+    "register_prestage_tool",
+)

package/src/superlocalmemory/mcp/tools_core.py

@@ -35,45 +35,59 @@ def _emit_event(event_type: str, payload: dict | None = None,
         pass
 
 
-def _record_recall_hits(get_engine: Callable, query: str, results: list[dict]) -> None:
-    """Record implicit feedback + learning signals for each recall.
-
-    Non-blocking, non-critical — failures silently ignored.
-    Feeds: FeedbackCollector + Co-Retrieval + Confidence Boost.
+def _record_recall_hits(
+    get_engine: Callable,
+    query: str,
+    results: list[dict],
+    *,
+    query_id: str = "",
+    fact_ids_candidates: list[str] | None = None,
+) -> None:
+    """Record honest shown-state signals (LLD-02 §4.9).
+
+    v3.4.21: No more fake positives. For every candidate we enqueue a
+    ``shown`` / ``not_shown`` flip based on whether it was returned in the
+    top-K presented to the user. Outcome/reward arrives in v3.4.21 via the
+    action-outcomes pipeline.
+
+    Non-blocking: all work funnels through ``signals.enqueue_shown_flip``
+    (module-level queue + background drain). Failures are swallowed —
+    signal quality is never load-bearing on recall correctness.
     """
     try:
         from pathlib import Path
+        from superlocalmemory.learning.signals import (
+            LearningSignals,
+            enqueue_shown_flip,
+        )
+
         engine = get_engine()
         pid = engine.profile_id
         slm_dir = Path.home() / ".superlocalmemory"
-        fact_ids = [r.get("fact_id", "") for r in results[:10] if r.get("fact_id")]
-        if not fact_ids:
+
+        shown_ids = [r.get("fact_id", "") for r in results[:10]
+                     if r.get("fact_id")]
+        candidates = (fact_ids_candidates
+                      if fact_ids_candidates is not None
+                      else shown_ids)
+        if not candidates:
             return
 
-        # 1. Implicit feedback (recall_hit signals for adaptive learner)
-        try:
-            from superlocalmemory.learning.feedback import FeedbackCollector
-            collector = FeedbackCollector(slm_dir / "learning.db")
-            collector.record_implicit(
-                profile_id=pid, query=query,
-                fact_ids_returned=fact_ids, fact_ids_available=fact_ids,
-            )
-        except Exception:
-            pass
+        # Shown-flip enqueue per §4.9. No synthetic positives.
+        shown_set = set(shown_ids)
+        if query_id:
+            for fid in candidates:
+                enqueue_shown_flip(query_id, fid, shown=(fid in shown_set))
 
-        # 2. Co-retrieval signals (strengthen implicit graph edges)
+        # Legacy zero-cost signals — unchanged (co-retrieval + confidence).
         try:
-            from superlocalmemory.learning.signals import LearningSignals
             signals = LearningSignals(slm_dir / "learning.db")
-            signals.record_co_retrieval(pid, fact_ids)
+            signals.record_co_retrieval(pid, shown_ids)
         except Exception:
             pass
-
-        # 3. Confidence boost (accessed facts get +0.02, cap 1.0)
         try:
-            from superlocalmemory.learning.signals import LearningSignals
             mem_db = str(slm_dir / "memory.db")
-            for fid in fact_ids[:5]:
+            for fid in shown_ids[:5]:
                 LearningSignals.boost_confidence(mem_db, fid)
         except Exception:
             pass
@@ -150,14 +164,65 @@ def register_core_tools(server, get_engine: Callable) -> None:
             return {"success": False, "error": str(exc)}
 
     @server.tool()
-    async def recall(query: str, limit: int = 10, agent_id: str = "mcp_client") -> dict:
-        """Search memories by semantic query with 4-channel retrieval, RRF fusion, and reranking."""
+    async def recall(
+        query: str, limit: int = 10, agent_id: str = "mcp_client",
+        session_id: str = "",
+    ) -> dict:
+        """Search memories by semantic query with 4-channel retrieval, RRF fusion, and reranking.
+
+        S9-DASH-02: optional ``session_id`` threads through to the
+        engine's outcome-queue so PostToolUse / Stop hooks can attach
+        engagement signals to this recall. Claude Code should pass its
+        ``CLAUDE_SESSION_ID``. Omitting it degrades to "no closed-loop
+        learning for this recall" — the recall itself always works.
+        """
         import asyncio
         try:
             from superlocalmemory.core.worker_pool import WorkerPool
             pool = WorkerPool.shared()
+            # S9-DASH-10: priority for session_id, so engagement
+            # signals land on the right pending_outcome:
+            #   1. Explicit ``session_id`` tool-call argument.
+            #   2. ``SLM_SESSION_ID`` / ``CLAUDE_SESSION_ID`` env var.
+            #   3. Most-recent-active Claude session from the hook
+            #      registry (last 60s). This catches the common case
+            #      where Claude Code's hooks ran the UserPromptSubmit
+            #      hook right before invoking the MCP tool.
+            #   4. Stable per-agent fallback ``mcp:<agent_id>`` — the
+            #      Stop hook will NOT match this, so the reaper
+            #      settles it at neutral 0.5.
+            effective_sid = session_id
+            if not effective_sid:
+                import os as _os
+                effective_sid = (
+                    _os.environ.get("SLM_SESSION_ID")
+                    or _os.environ.get("CLAUDE_SESSION_ID")
+                    or ""
+                )
+            if not effective_sid:
+                try:
+                    from superlocalmemory.hooks.session_registry import (
+                        lookup_by_parent,
+                        most_recent_active,
+                    )
+                    # Parent-PID lookup is collision-free across multiple
+                    # parallel Claude sessions (each MCP server's parent
+                    # is the IDE that spawned it).
+                    effective_sid = (
+                        lookup_by_parent(within_seconds=60)
+                        or most_recent_active(
+                            agent_type="claude", within_seconds=60,
+                        )
+                        or ""
+                    )
+                except Exception:
+                    pass
+            if not effective_sid:
+                effective_sid = f"mcp:{agent_id}"
             # V3.3.19: Run in thread pool to avoid blocking MCP event loop
-            result = await asyncio.to_thread(pool.recall, query, limit=limit)
+            result = await asyncio.to_thread(
+                pool.recall, query, limit=limit, session_id=effective_sid,
+            )
             if result.get("ok"):
                 # Record implicit feedback: every returned result is a recall_hit
                 try:

package/src/superlocalmemory/parameterization/soft_prompt_generator.py

@@ -123,12 +123,18 @@ class SoftPromptGenerator:
         self,
         patterns: list[PatternAssertion],
         profile_id: str,
+        *,
+        high_reward_source_ids: set[str] | None = None,
     ) -> list[SoftPromptTemplate]:
         """Master generation pipeline: filter, group, render, budget-trim.
 
         Args:
             patterns: Extracted pattern assertions.
             profile_id: Target profile.
+            high_reward_source_ids: Optional v3.4.21 (LLD-12 §6) filter —
+                when provided, only patterns whose source_ids intersect
+                this set are considered. When None (default), behaviour
+                matches pre-v3.4.21 and every pattern flows through.
 
         Returns:
             List of SoftPromptTemplate, ordered by category priority,
@@ -140,6 +146,13 @@ class SoftPromptGenerator:
             p for p in patterns if p.category.value in enabled
         ]
 
+        # v3.4.21 (LLD-12 §6): reward-aware filter — opt-in only.
+        if high_reward_source_ids is not None:
+            filtered = [
+                p for p in filtered
+                if set(p.source_ids) & high_reward_source_ids
+            ]
+
         # Group by category
         grouped: dict[str, list[PatternAssertion]] = defaultdict(list)
         for p in filtered:

package/src/superlocalmemory/retrieval/engine.py

@@ -705,3 +705,55 @@ class RetrievalEngine:
                 trust_score=raw_trust,
             ))
         return results
+
+
+# ---------------------------------------------------------------------------
+# apply_channel_weights (LLD-03 §5.5 — module-level pure helper)
+# ---------------------------------------------------------------------------
+
+
+_CHANNEL_KEYS: tuple[str, ...] = (
+    "semantic", "bm25", "entity_graph", "temporal",
+)
+
+
+def apply_channel_weights(
+    candidates: list[RetrievalResult],
+    weights: dict[str, float] | None,
+) -> list[RetrievalResult]:
+    """Re-score candidates under a bandit-chosen weight bundle.
+
+    Multiplies each candidate's ``channel_scores[ch]`` by ``weights[ch]``
+    and applies ``cross_encoder_bias`` to the final score. Preserves order;
+    callers reorder via ensemble_rerank.
+
+    Returns a NEW list with new ``RetrievalResult`` instances — never mutates
+    input. Unknown / missing weights default to 1.0.
+
+    Safe against ``weights=None`` (returns input unchanged) and empty lists.
+    """
+    if not candidates or not weights:
+        return list(candidates)
+
+    ce_bias = float(weights.get("cross_encoder_bias", 1.0))
+    out: list[RetrievalResult] = []
+    for c in candidates:
+        original_cs = c.channel_scores or {}
+        new_cs: dict[str, float] = dict(original_cs)
+        base = 0.0
+        for ch in _CHANNEL_KEYS:
+            raw = float(original_cs.get(ch, 0.0))
+            w = float(weights.get(ch, 1.0))
+            scaled = raw * w
+            new_cs[ch] = scaled
+            base += scaled
+        new_score = (base if base > 0.0 else float(c.score)) * ce_bias
+        out.append(RetrievalResult(
+            fact=c.fact,
+            score=new_score,
+            channel_scores=new_cs,
+            confidence=c.confidence,
+            evidence_chain=c.evidence_chain,
+            trust_score=c.trust_score,
+        ))
+    return out

package/src/superlocalmemory/server/api.py

@@ -219,14 +219,14 @@ def create_app() -> FastAPI:
     @application.get("/health")
     async def health_check():
         """Health check."""
-        from datetime import datetime
+        from datetime import datetime, timezone
         engine = application.state.engine
         return {
             "status": "healthy",
             "version": SLM_VERSION,
             "engine": "initialized" if engine else "unavailable",
             "database": "connected" if DB_PATH.exists() else "missing",
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
         }
 
     @application.on_event("startup")

package/src/superlocalmemory/server/bandit_loops.py

@@ -0,0 +1,140 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-03 §3.5 + §3.6
+
+"""Background schedulers for the v3.4.21 contextual bandit.
+
+Two asyncio tasks, both registered in the daemon lifespan:
+
+  1. Reward-proxy settler — every 60 s (``SLM_BANDIT_REWARD_WINDOW_SEC``),
+     calls ``reward_proxy.settle_stale_plays`` for the configured profile(s).
+  2. Retention sweep — every 24 h
+     (``SLM_BANDIT_PLAYS_RETENTION_INTERVAL_SEC``), calls
+     ``bandit.retention_sweep`` with the configured horizon
+     (``SLM_BANDIT_PLAYS_RETENTION_DAYS``, default 7).
+
+Both honour ``SLM_BANDIT_DISABLED=1`` (caller checks before scheduling).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_REWARD_INTERVAL = float(
+    os.environ.get("SLM_BANDIT_REWARD_WINDOW_SEC", "60"),
+)
+_RETENTION_INTERVAL = float(
+    os.environ.get("SLM_BANDIT_PLAYS_RETENTION_INTERVAL_SEC", "86400"),
+)
+_RETENTION_DAYS = int(
+    os.environ.get("SLM_BANDIT_PLAYS_RETENTION_DAYS", "7"),
+)
+
+
+def _learning_db(config: Any) -> Path:
+    if config is not None:
+        cand = getattr(config, "learning_db_path", None)
+        if cand is not None:
+            return Path(cand)
+    return Path.home() / ".superlocalmemory" / "learning.db"
+
+
+def _memory_db(config: Any) -> Path:
+    if config is not None:
+        cand = getattr(config, "db_path", None)
+        if cand is not None:
+            return Path(cand)
+    return Path.home() / ".superlocalmemory" / "memory.db"
+
+
+def _profile_id(config: Any) -> str:
+    if config is not None:
+        pid = getattr(config, "default_profile", None)
+        if isinstance(pid, str) and pid:
+            return pid
+    return "default"
+
+
+async def _reward_proxy_loop(
+    learning_db: Path, memory_db: Path, profile_id: str,
+    interval_sec: float,
+) -> None:
+    """Run the proxy settler on a steady interval. Never raises."""
+    from superlocalmemory.learning.reward_proxy import settle_stale_plays
+
+    while True:
+        try:
+            await asyncio.sleep(interval_sec)
+            # The settler is synchronous + fast; run in a thread to avoid
+            # blocking the event loop on unusual DB lock stalls.
+            n = await asyncio.to_thread(
+                settle_stale_plays,
+                profile_id, learning_db, memory_db,
+            )
+            if n:
+                logger.debug("bandit.reward_proxy settled=%d", n)
+        except asyncio.CancelledError:  # pragma: no cover — lifecycle
+            raise
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.warning("bandit.reward_proxy loop: %s", exc)
+
+
+async def _retention_loop(
+    learning_db: Path, interval_sec: float, retention_days: int,
+) -> None:
+    """Run retention_sweep on a 24h cadence. Never raises."""
+    from superlocalmemory.learning.bandit import retention_sweep
+
+    while True:
+        try:
+            await asyncio.sleep(interval_sec)
+            deleted = await asyncio.to_thread(
+                retention_sweep, learning_db, retention_days,
+            )
+            logger.info(
+                "bandit_plays_retention_sweep tick: deleted=%d", deleted,
+            )
+        except asyncio.CancelledError:  # pragma: no cover — lifecycle
+            raise
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.warning("bandit.retention loop: %s", exc)
+
+
+def schedule_bandit_loops(application: Any, config: Any) -> None:
+    """Register both background tasks with the FastAPI app state.
+
+    Tasks are stored on ``application.state.bandit_tasks`` so the daemon's
+    shutdown path can cancel them cleanly (if added).
+    """
+    learning = _learning_db(config)
+    memory = _memory_db(config)
+    profile = _profile_id(config)
+
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:  # pragma: no cover — defensive
+        return
+
+    tasks = []
+    tasks.append(loop.create_task(
+        _reward_proxy_loop(learning, memory, profile, _REWARD_INTERVAL),
+    ))
+    tasks.append(loop.create_task(
+        _retention_loop(learning, _RETENTION_INTERVAL, _RETENTION_DAYS),
+    ))
+    if hasattr(application, "state"):
+        application.state.bandit_tasks = tasks
+    logger.info(
+        "bandit loops scheduled: reward=%.0fs, retention=%.0fs, "
+        "retention_days=%d",
+        _REWARD_INTERVAL, _RETENTION_INTERVAL, _RETENTION_DAYS,
+    )
+
+
+__all__ = ("schedule_bandit_loops",)

package/src/superlocalmemory/server/middleware/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-04 §4.2
+
+"""FastAPI middleware — strict security headers for the Brain UI (LLD-04 v2).
+
+The existing ``server/security_middleware.py`` is kept for legacy routes
+that still rely on permissive CSP (``'unsafe-inline'`` + CDNs). The
+middleware in this subpackage enforces the v3.4.21 policy: no inline
+scripts / styles, no nonces, no CDN sources.
+"""