superlocalmemory 4.0.0 → 4.0.2

package/src/superlocalmemory/mcp/server.py

@@ -97,6 +97,9 @@ _ESSENTIAL_TOOLS: set[str] = {
     # Feedback / learning signals — reachable Dash-Core path for
     # thumbs-up / pin / drift signals.
     "report_feedback",
+    # v4.0.2 portable Brain evidence: profile-scoped receipt reads/writes.
+    "get_brain_evidence_status", "record_agent_experience",
+    "record_cognitive_turn", "finalize_cognitive_turn",
     # Memory management (2)
     "forget", "run_maintenance",
     # NOTE: prestage_context IS registered (see register_prestage_tool below)
@@ -272,6 +275,8 @@ from superlocalmemory.mcp.tools_loops import register_loop_tools
 register_loop_tools(_target, get_engine)  # v3.8.0: bounded-loop tools (CLI+command+MCP)
 from superlocalmemory.mcp.tools_ops import register_ops_tools
 register_ops_tools(_target, get_engine)  # Wave-3: operational recovery & admin remediation
+from superlocalmemory.mcp.tools_brain import register_brain_tools
+register_brain_tools(_target, get_engine)  # v4.0.2 portable Brain receipts
 from superlocalmemory.mcp.tools_context import register_prestage_tool
 
 

package/src/superlocalmemory/mcp/tools_brain.py

@@ -0,0 +1,132 @@
+"""Portable Agent Experience receipt tools for the SLM Brain.
+
+Receipts are scoped to the MCP engine's active profile.  A host cannot write
+to another profile by supplying a different ``profile_id`` in its payload.
+The receipts are evidence/observability records only: recall and ranking do
+not consume them synchronously, so an unavailable receipt store never slows
+or changes a memory answer.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
+from superlocalmemory.infra.data_root import state_path
+from superlocalmemory.storage.agent_experience import (
+    AgentExperienceConflictError,
+    AgentExperienceStore,
+    CognitiveTurnTransitionError,
+    LearningWriteBusyError,
+    ProfileAdmissionError,
+    get_profile_receipt_summary,
+)
+
+
+def _store_for(engine: Any) -> AgentExperienceStore:
+    active_profile = engine.profile_id
+    return AgentExperienceStore(
+        Path(state_path("learning.db")),
+        is_profile_active=lambda profile_id: profile_id == active_profile,
+    )
+
+
+def _require_active_profile(engine: Any, payload: dict[str, Any]) -> str | None:
+    supplied = payload.get("profile_id")
+    if supplied != engine.profile_id:
+        return "profile_id must equal the active MCP profile"
+    return None
+
+
+def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
+    """Register transport-neutral receipt reads and writes.
+
+    The same tools work through Codex, Claude, Cursor, VS Code, and direct
+    HTTP MCP.  Callers supply contract-shaped JSON; the active-profile check
+    keeps multi-profile data isolated at the public boundary.
+    """
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def get_brain_evidence_status() -> dict[str, Any]:
+        """Get profile-scoped Agent Experience and Cognitive Turn totals."""
+        engine = get_engine()
+        return {
+            "success": True,
+            "profile_id": engine.profile_id,
+            "agent_experience": get_profile_receipt_summary(
+                state_path("learning.db"), engine.profile_id
+            ),
+            "control_plane": "observation_only",
+        }
+
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def record_agent_experience(payload: dict[str, Any]) -> dict[str, Any]:
+        """Record a contract-validated terminal experience receipt.
+
+        Supply only evidence you can substantiate.  SLM records the declared
+        verification authority and does not use this receipt to alter recall,
+        ranking, or model routing automatically.
+        """
+        engine = get_engine()
+        error = _require_active_profile(engine, payload)
+        if error:
+            return {"success": False, "durable": False, "error": error}
+        try:
+            created = _store_for(engine).record_experience(payload)
+        except (AgentExperienceConflictError, ProfileAdmissionError) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}
+        except LearningWriteBusyError as exc:
+            return {"success": False, "durable": False, "retryable": True, "error": str(exc)}
+        except (TypeError, ValueError) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}
+        return {"success": True, "durable": True, "created": created}
+
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def record_cognitive_turn(payload: dict[str, Any]) -> dict[str, Any]:
+        """Open one contract-validated cognitive-turn provenance receipt."""
+        engine = get_engine()
+        error = _require_active_profile(engine, payload)
+        if error:
+            return {"success": False, "durable": False, "error": error}
+        try:
+            created = _store_for(engine).create_cognitive_turn(payload)
+        except (
+            AgentExperienceConflictError,
+            CognitiveTurnTransitionError,
+            ProfileAdmissionError,
+        ) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}
+        except LearningWriteBusyError as exc:
+            return {"success": False, "durable": False, "retryable": True, "error": str(exc)}
+        except (TypeError, ValueError) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}
+        return {"success": True, "durable": True, "created": created}
+
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def finalize_cognitive_turn(
+        receipt_id: str, outcome: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Finalize an active-profile cognitive turn with outcome evidence."""
+        engine = get_engine()
+        try:
+            finalized = _store_for(engine).finalize_cognitive_turn(
+                engine.profile_id, receipt_id, outcome
+            )
+        except (
+            AgentExperienceConflictError,
+            CognitiveTurnTransitionError,
+            ProfileAdmissionError,
+        ) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}
+        except LearningWriteBusyError as exc:
+            return {"success": False, "durable": False, "retryable": True, "error": str(exc)}
+        except (TypeError, ValueError) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}
+        return {"success": True, "durable": True, "finalized": finalized}

package/src/superlocalmemory/mcp/tools_core.py

@@ -272,6 +272,9 @@ def register_core_tools(server, get_engine: Callable) -> None:
         include_shared: bool | None = None,
         window: str = "",
         as_of: str | None = None,
+        known_as_of: str | None = None,
+        valid_at: str | None = None,
+        include_unknown: bool = False,
     ) -> dict:
         """Search memories through hybrid retrieval, RRF fusion, and reranking.
 
@@ -369,13 +372,26 @@ def register_core_tools(server, get_engine: Callable) -> None:
             # Audit P2: treat empty/whitespace as_of as ABSENT (like HTTP does),
             # not as an invalid value — only a non-blank unparseable string is
             # rejected.
-            if as_of is not None and str(as_of).strip():
+            def _normalize_temporal(value: str | None) -> str | None:
+                if value is None or not str(value).strip():
+                    return None
                 from superlocalmemory.retrieval.temporal_utils import normalize_as_of
-                as_of = normalize_as_of(as_of)
-                if as_of is None:
-                    return {"success": False, "error": "invalid_as_of"}
-            else:
-                as_of = None
+                return normalize_as_of(value)
+
+            raw_as_of, raw_known_as_of, raw_valid_at = as_of, known_as_of, valid_at
+            as_of = _normalize_temporal(raw_as_of)
+            known_as_of = _normalize_temporal(raw_known_as_of)
+            valid_at = _normalize_temporal(raw_valid_at)
+            # Preserve backwards-compatible as_of validation while exposing
+            # named two-clock boundaries. A supplied non-blank invalid value
+            # is rejected rather than silently becoming current recall.
+            for raw, normalized, code in (
+                (raw_as_of, as_of, "invalid_as_of"),
+                (raw_known_as_of, known_as_of, "invalid_known_as_of"),
+                (raw_valid_at, valid_at, "invalid_valid_at"),
+            ):
+                if raw is not None and str(raw).strip() and normalized is None:
+                    return {"success": False, "error": code}
 
             from superlocalmemory.core.admission import enforce_read_scope
             _incl_global, _incl_shared = enforce_read_scope(include_global, include_shared)
@@ -387,6 +403,9 @@ def register_core_tools(server, get_engine: Callable) -> None:
                     fast=fast, include_global=_incl_global,
                     include_shared=_incl_shared, window=window or None,
                     as_of=as_of,
+                    known_as_of=known_as_of,
+                    valid_at=valid_at,
+                    include_unknown=include_unknown,
                 )
 
             result = await asyncio.to_thread(

package/src/superlocalmemory/mcp/tools_v3.py

@@ -286,6 +286,9 @@ def register_v3_tools(server, get_engine: Callable) -> None:
         query: str,
         limit: int = 10,
         as_of: str | None = None,
+        known_as_of: str | None = None,
+        valid_at: str | None = None,
+        include_unknown: bool = False,
     ) -> dict:
         """Recall with per-channel score breakdown.
 
@@ -301,7 +304,9 @@ def register_v3_tools(server, get_engine: Callable) -> None:
         try:
             import asyncio
             from superlocalmemory.mcp._daemon_proxy import choose_pool
-            from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+            from superlocalmemory.retrieval.temporal_utils import (
+                normalize_as_of, normalize_strict_boundary,
+            )
 
             # Normalize at MCP boundary before forwarding.
             _as_of: str | None = None
@@ -309,11 +314,20 @@ def register_v3_tools(server, get_engine: Callable) -> None:
                 _as_of = normalize_as_of(as_of)
                 if _as_of is None:
                     return {"success": False, "error": "invalid_as_of"}
+            try:
+                _known_as_of = normalize_strict_boundary(known_as_of, "known_as_of")
+                _valid_at = normalize_strict_boundary(valid_at, "valid_at")
+            except ValueError as exc:
+                return {"success": False, "error": str(exc)}
 
             # choose_pool().recall uses blocking urllib; run off the event loop
             # so recall_trace doesn't stall the MCP server for other tools.
             raw = await asyncio.to_thread(
-                lambda: choose_pool().recall(query=query, limit=limit, as_of=_as_of)
+                lambda: choose_pool().recall(
+                    query=query, limit=limit, as_of=_as_of,
+                    known_as_of=_known_as_of, valid_at=_valid_at,
+                    include_unknown=include_unknown,
+                )
             )
             items = raw.get("results", []) if isinstance(raw, dict) else []
             results = []

package/src/superlocalmemory/retrieval/engine.py

@@ -28,6 +28,10 @@ from typing import TYPE_CHECKING, Any, Protocol
 from superlocalmemory.core.config import ChannelWeights, RetrievalConfig
 from superlocalmemory.retrieval.fusion import FusionResult, weighted_rrf
 from superlocalmemory.retrieval.strategy import QueryStrategy, QueryStrategyClassifier
+from superlocalmemory.retrieval.temporal_validity_filter import (
+    admit_correction_candidates,
+    admit_correction_fusion_results,
+)
 from superlocalmemory.retrieval.time_window import (
     in_window,
     infer_window_from_query,
@@ -156,6 +160,9 @@ class RetrievalEngine:
         include_shared: bool = False,
         window: str | tuple[str, str] | None = None,
         as_of: str | None = None,
+        known_as_of: str | None = None,
+        valid_at: str | None = None,
+        include_unknown: bool = False,
     ) -> RecallResponse:
         """Full retrieval pipeline: strategy -> channels -> RRF -> rerank.
 
@@ -172,6 +179,9 @@ class RetrievalEngine:
         not-yet-valid and already-expired facts are demoted. Default ``None``
         leaves all existing behaviour unchanged.
         """
+        from superlocalmemory.retrieval.temporal_utils import normalize_strict_boundary
+        known_as_of = normalize_strict_boundary(known_as_of, "known_as_of")
+        valid_at = normalize_strict_boundary(valid_at, "valid_at")
         t0 = time.monotonic()
         # NOTE: extra_disabled_channels is passed as an explicit local argument
         # to _run_channels() — it is NOT stored on self.  Storing it as a shared
@@ -218,11 +228,20 @@ class RetrievalEngine:
             query, profile_id, strat,
             extra_disabled_channels=extra_disabled_channels,
             include_global=include_global, include_shared=include_shared,
-            as_of=as_of,
+            as_of=as_of, known_as_of=known_as_of, valid_at=valid_at,
+            include_unknown=include_unknown,
         )
         _em("run_channels")
         if profile_hits:
             ch_results["profile"] = profile_hits
+        # The profile shortcut bypasses _run_channels(), so it needs the same
+        # admission before it can influence fusion or seed graph expansion.
+        ch_results = admit_correction_candidates(
+            ch_results, profile_id, self._db, as_of=as_of,
+            known_as_of=known_as_of, valid_at=valid_at,
+            include_unknown=include_unknown,
+            include_global=include_global, include_shared=include_shared,
+        )
         total = sum(len(v) for v in ch_results.values())
 
         # 3. Single-pass RRF fusion
@@ -330,6 +349,16 @@ class RetrievalEngine:
             except Exception as exc:
                 logger.warning("Entity graph signal enhancement: %s", exc)
 
+        # Brain Core S402: bridge and scene expansion append candidates after
+        # the channel boundary. Reapply the same hard correction-admission rule
+        # immediately before any candidate can be materialized or reranked.
+        fused = admit_correction_fusion_results(
+            fused, profile_id, self._db, as_of=as_of,
+            known_as_of=known_as_of, valid_at=valid_at,
+            include_unknown=include_unknown,
+            include_global=include_global, include_shared=include_shared,
+        )
+
         _em("expand+entity_enh")
 
         # T-window: prune candidates to the requested event-time range.
@@ -773,6 +802,9 @@ class RetrievalEngine:
         include_global: bool = False,
         include_shared: bool = False,
         as_of: str | None = None,
+        known_as_of: str | None = None,
+        valid_at: str | None = None,
+        include_unknown: bool = False,
     ) -> dict[str, list[tuple[str, float]]]:
         """Run active retrieval channels.
 
@@ -917,6 +949,16 @@ class RetrievalEngine:
                 except Exception as exc:
                     logger.warning("Post-retrieval filter failed: %s", exc)
 
+        # The legacy temporal filter preserves its score-demotion semantics for
+        # compatibility. Admission is separate and hard: no current
+        # system-superseded fact may seed fusion, bridge discovery, or rerank.
+        out = admit_correction_candidates(
+            out, profile_id, self._db, as_of=as_of,
+            known_as_of=known_as_of, valid_at=valid_at,
+            include_unknown=include_unknown,
+            include_global=include_global, include_shared=include_shared,
+        )
+
         return out
 
     def close(self, *, wait: bool = False) -> None:

package/src/superlocalmemory/retrieval/temporal_utils.py

@@ -104,4 +104,19 @@ def normalize_as_of(s: object) -> Optional[str]:
         return None
 
 
-__all__ = ("normalize_as_of",)
+def normalize_strict_boundary(value: object, name: str) -> Optional[str]:
+    """Normalize an optional strict boundary or reject an invalid supplied value.
+
+    Unlike legacy ``as_of`` direct calls, explicit two-clock queries cannot
+    quietly degrade to current recall: doing so would make a malformed history
+    request appear authoritative.
+    """
+    if value is None or (isinstance(value, str) and not value.strip()):
+        return None
+    normalized = normalize_as_of(value)
+    if normalized is None:
+        raise ValueError(f"{name} must be an ISO-8601 timestamp")
+    return normalized
+
+
+__all__ = ("normalize_as_of", "normalize_strict_boundary")

package/src/superlocalmemory/retrieval/temporal_validity_filter.py

@@ -79,6 +79,157 @@ logger = logging.getLogger(__name__)
 _EVENT_TIME_DEMOTION_FACTOR: float = 0.5
 
 
+def _normalized_as_of(as_of: str | None) -> str | None:
+    """Normalize an optional transaction-time boundary at one boundary.
+
+    The MCP/HTTP adapters already reject invalid non-blank values.  Engine
+    callers are also public, however, so an invalid direct value must degrade
+    to current recall rather than turn a read into an exception.
+    """
+    if as_of is None:
+        return None
+    from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+    return normalize_as_of(as_of)
+
+
+def _invalidated_candidate_ids(
+    db: DatabaseManager,
+    fact_ids: set[str],
+    profile_id: str,
+    *,
+    as_of: str | None = None,
+    include_global: bool = False,
+    include_shared: bool = False,
+) -> set[str] | None:
+    """Return admissibility failures, or ``None`` when the lookup is unhealthy.
+
+    ``None`` deliberately preserves the established fail-open availability
+    contract.  It is distinct from an empty set: a bad/mocked return value must
+    not accidentally exclude arbitrary candidates.
+    """
+    if not fact_ids:
+        return set()
+    try:
+        kwargs: dict[str, Any] = {"as_of": _normalized_as_of(as_of)}
+        if include_global:
+            kwargs["include_global"] = True
+        if include_shared:
+            kwargs["include_shared"] = True
+        invalid = db.get_invalidated_fact_ids(list(fact_ids), profile_id, **kwargs)
+    except Exception as exc:
+        logger.warning("Correction admission lookup failed: %s", exc)
+        return None
+    return invalid if isinstance(invalid, set) else None
+
+
+def _strict_temporal_candidate_ids(
+    db: DatabaseManager,
+    fact_ids: set[str],
+    profile_id: str,
+    *,
+    known_as_of: str | None = None,
+    valid_at: str | None = None,
+    include_unknown: bool = False,
+    include_global: bool = False,
+    include_shared: bool = False,
+) -> set[str] | None:
+    """Return strict two-clock admission failures, fail-open on lookup error."""
+    if not fact_ids or (known_as_of is None and valid_at is None):
+        return set()
+    try:
+        invalid = db.get_strict_temporal_inadmissible_fact_ids(
+            list(fact_ids), profile_id,
+            known_as_of=_normalized_as_of(known_as_of),
+            valid_at=_normalized_as_of(valid_at),
+            include_unknown=include_unknown,
+            include_global=include_global,
+            include_shared=include_shared,
+        )
+    except Exception as exc:
+        logger.warning("Strict temporal admission lookup failed: %s", exc)
+        return None
+    return invalid if isinstance(invalid, set) else None
+
+
+def admit_correction_candidates(
+    all_results: dict[str, list[tuple[str, float]]],
+    profile_id: str,
+    db: DatabaseManager,
+    *,
+    as_of: str | None = None,
+    known_as_of: str | None = None,
+    valid_at: str | None = None,
+    include_unknown: bool = False,
+    include_global: bool = False,
+    include_shared: bool = False,
+) -> dict[str, list[tuple[str, float]]]:
+    """Hard-exclude system-superseded facts before candidate fusion.
+
+    This is the SLM 4.0.2 Brain Core admission invariant.  Ranking is unable to
+    enforce a correction because a high-scoring stale fact can still win.  The
+    historical ``as_of`` boundary preserves facts that had not yet been
+    superseded at that point, so current corrections do not rewrite history.
+    """
+    fact_ids = {
+        fact_id
+        for channel_results in all_results.values()
+        for fact_id, _ in channel_results
+    }
+    invalid = _invalidated_candidate_ids(
+        db, fact_ids, profile_id, as_of=as_of,
+        include_global=include_global, include_shared=include_shared,
+    )
+    strict = _strict_temporal_candidate_ids(
+        db, fact_ids, profile_id,
+        known_as_of=known_as_of, valid_at=valid_at,
+        include_unknown=include_unknown,
+        include_global=include_global, include_shared=include_shared,
+    )
+    if strict:
+        invalid = (invalid or set()) | strict
+    if not invalid:
+        return all_results
+    return {
+        channel_name: [
+            (fact_id, score)
+            for fact_id, score in channel_results
+            if fact_id not in invalid
+        ]
+        for channel_name, channel_results in all_results.items()
+    }
+
+
+def admit_correction_fusion_results(
+    fused_results: list[Any],
+    profile_id: str,
+    db: DatabaseManager,
+    *,
+    as_of: str | None = None,
+    known_as_of: str | None = None,
+    valid_at: str | None = None,
+    include_unknown: bool = False,
+    include_global: bool = False,
+    include_shared: bool = False,
+) -> list[Any]:
+    """Re-apply correction admission after graph/scene candidate expansion."""
+    fact_ids = {result.fact_id for result in fused_results}
+    invalid = _invalidated_candidate_ids(
+        db, fact_ids, profile_id, as_of=as_of,
+        include_global=include_global, include_shared=include_shared,
+    )
+    strict = _strict_temporal_candidate_ids(
+        db, fact_ids, profile_id,
+        known_as_of=known_as_of, valid_at=valid_at,
+        include_unknown=include_unknown,
+        include_global=include_global, include_shared=include_shared,
+    )
+    if strict:
+        invalid = (invalid or set()) | strict
+    if not invalid:
+        return fused_results
+    return [result for result in fused_results if result.fact_id not in invalid]
+
+
 class TemporalValidityFilter:
     """Demotes bi-temporally invalid facts in retrieval candidates.