superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/mcp/tools_learning.py

@@ -24,6 +24,8 @@ from typing import Callable
 
 from mcp.types import ToolAnnotations
 
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.mcp.shared import authorize_mcp_mutation
 
 logger = logging.getLogger(__name__)
@@ -35,6 +37,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
     """Register learning MCP tools for two-way intelligence."""
 
     @server.tool()
+    @admits(OperationKind.REMEMBER)
     async def log_tool_event(
         tool_name: str,
         event_type: str = "invoke",
@@ -144,6 +147,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             return {"assertions": [], "count": 0, "error": str(exc)}
 
     @server.tool()
+    @admits(OperationKind.CORRECT)
     async def reinforce_assertion(assertion_id: str) -> dict:
         """Reinforce a behavioral assertion (increase confidence).
 
@@ -164,6 +168,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             )
             result = _update_assertion_confidence(
                 engine._db, assertion_id, reinforce=True,
+                profile_id=engine.profile_id,
             )
             if result.get("success"):
                 authorization.complete()
@@ -172,6 +177,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             return {"success": False, "error": str(exc)}
 
     @server.tool()
+    @admits(OperationKind.FORGET)
     async def contradict_assertion(assertion_id: str) -> dict:
         """Contradict a behavioral assertion (decrease confidence).
 
@@ -192,6 +198,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             )
             result = _update_assertion_confidence(
                 engine._db, assertion_id, reinforce=False,
+                profile_id=engine.profile_id,
             )
             if result.get("success"):
                 authorization.complete()
@@ -200,14 +207,16 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             return {"success": False, "error": str(exc)}
 
 
-def _update_assertion_confidence(db, assertion_id: str, reinforce: bool) -> dict:
-    """Bayesian confidence update for behavioral assertions."""
+def _update_assertion_confidence(
+    db, assertion_id: str, reinforce: bool, profile_id: str,
+) -> dict:
+    """Bayesian confidence update for behavioral assertions, scoped to one profile."""
     now = datetime.now(timezone.utc).isoformat()
     try:
         row = db.execute(
             "SELECT confidence, reinforcement_count, contradiction_count "
-            "FROM behavioral_assertions WHERE id = ?",
-            (assertion_id,),
+            "FROM behavioral_assertions WHERE id = ? AND profile_id = ?",
+            (assertion_id, profile_id),
         )
         rows = list(row)
         if not rows:
@@ -221,22 +230,24 @@ def _update_assertion_confidence(db, assertion_id: str, reinforce: bool) -> dict
             db.execute(
                 "UPDATE behavioral_assertions SET confidence = ?, "
                 "reinforcement_count = reinforcement_count + 1, "
-                "last_reinforced_at = ?, updated_at = ? WHERE id = ?",
-                (round(new_conf, 4), now, now, assertion_id),
+                "last_reinforced_at = ?, updated_at = ? "
+                "WHERE id = ? AND profile_id = ?",
+                (round(new_conf, 4), now, now, assertion_id, profile_id),
             )
         else:
             new_conf = old_conf * 0.7  # 30% decay
             db.execute(
                 "UPDATE behavioral_assertions SET confidence = ?, "
                 "contradiction_count = contradiction_count + 1, "
-                "last_contradicted_at = ?, updated_at = ? WHERE id = ?",
-                (round(new_conf, 4), now, now, assertion_id),
+                "last_contradicted_at = ?, updated_at = ? "
+                "WHERE id = ? AND profile_id = ?",
+                (round(new_conf, 4), now, now, assertion_id, profile_id),
             )
             # Auto-delete if confidence drops below 0.2
             if new_conf < 0.2:
                 db.execute(
-                    "DELETE FROM behavioral_assertions WHERE id = ?",
-                    (assertion_id,),
+                    "DELETE FROM behavioral_assertions WHERE id = ? AND profile_id = ?",
+                    (assertion_id, profile_id),
                 )
                 return {
                     "success": True, "action": "deleted",

package/src/superlocalmemory/mcp/tools_loops.py

@@ -39,9 +39,12 @@ 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.loops import (
     Bounds,
     LapResult,
+    LedgerEntry,
     Verdict,
     engine_backed_ledger,
     run_bounded_loop,
@@ -66,20 +69,6 @@ _MAX_NAME_CHARS = 128
 _MAX_QUERY_CHARS = 2000
 
 
-def _top_score(resp: Any) -> float:
-    """Highest result score in a RecallResponse (0.0 when there are none)."""
-    best = 0.0
-    for r in getattr(resp, "results", None) or []:
-        s = getattr(r, "score", None)
-        if s is None:
-            s = getattr(r, "relevance_score", 0.0) or 0.0
-        try:
-            best = max(best, float(s))
-        except (TypeError, ValueError):
-            continue
-    return best
-
-
 def register_loop_tools(server, get_engine: Callable) -> None:
     """Register the 3 bounded-loop tools on *server*.
 
@@ -88,6 +77,7 @@ def register_loop_tools(server, get_engine: Callable) -> None:
     """
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    @admits(OperationKind.REMEMBER)
     async def slm_loop_run(
         name: str,
         gate_query: str,
@@ -157,14 +147,35 @@ def register_loop_tools(server, get_engine: Callable) -> None:
 
             def gate(lap: int) -> Verdict:
                 resp = engine.recall(gate_query, limit=3, fast=True)
-                results = getattr(resp, "results", None) or []
+                all_results = getattr(resp, "results", None) or []
+                # Exclude the loop's own audit records from the gate evaluation.
+                # Each lap writes a LedgerEntry (JSON with "run_id" + "lap") into
+                # SLM via store_fast; the FTS5 trigger indexes every such insert.
+                # Without this filter BM25 finds those self-authored records on the
+                # next lap and the gate falsely passes. Only memories written by an
+                # external agent — whose content does not parse as a LedgerEntry —
+                # can satisfy an independent gate.
+                results = [
+                    r for r in all_results
+                    if LedgerEntry.from_json(
+                        getattr(getattr(r, "fact", None), "content", "") or ""
+                    ) is None
+                ]
                 floored = bool(getattr(resp, "no_confident_match", False))
-                top = _top_score(resp)
-                passed = bool(results) and not floored and top >= min_score
+                best: float = 0.0
+                for r in results:
+                    s = getattr(r, "score", None)
+                    if s is None:
+                        s = getattr(r, "relevance_score", 0.0) or 0.0
+                    try:
+                        best = max(best, float(s))
+                    except (TypeError, ValueError):
+                        pass
+                passed = bool(results) and not floored and best >= min_score
                 return Verdict(
                     passed,
                     f"recall '{gate_query[:48]}': hits={len(results)} "
-                    f"top={top:.3f} floor={floored}",
+                    f"top={best:.3f} floor={floored}",
                 )
 
             def runner(lap: int) -> LapResult:

package/src/superlocalmemory/mcp/tools_mesh.py

@@ -26,6 +26,9 @@ from typing import Callable
 
 from mcp.types import ToolAnnotations
 
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
+
 logger = logging.getLogger(__name__)
 
 
@@ -221,6 +224,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
     """Register all 8 mesh MCP tools."""
 
     @server.tool()
+    @admits(OperationKind.MESH_SEND)
     async def mesh_summary(summary: str = "") -> dict:
         """Register this session and describe what you're working on.
 
@@ -269,6 +273,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         }
 
     @server.tool()
+    @admits(OperationKind.MESH_SEND)
     async def mesh_send(to: str, message: str) -> dict:
         """Send a message to another peer session, broadcast, or project.
 
@@ -309,6 +314,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         return result
 
     @server.tool()
+    @admits(OperationKind.MESH_SEND)
     async def mesh_inbox() -> dict:
         """Read messages sent to this session.
 
@@ -341,6 +347,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         }
 
     @server.tool()
+    @admits(OperationKind.MESH_SEND)
     async def mesh_state(key: str = "", value: str = "", action: str = "get") -> dict:
         """Get or set shared state across all sessions.
 
@@ -370,6 +377,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         return result or {"state": {}}
 
     @server.tool()
+    @admits(OperationKind.MESH_LOCK)
     async def mesh_lock(
         file_path: str,
         action: str = "query",

package/src/superlocalmemory/mcp/tools_ops.py

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
+
+"""Wave-3 Operational Recovery & Admin Remediation MCP tools (2 tools).
+
+list_failed_operations — Surface dead-letter, degraded, and exhausted ops.
+resolve_operation      — Admin retry/force-reconcile/cancel for stuck ops.
+
+RBAC: both tools require OWNER or ADMIN role (OPS_INSPECT / OPS_RESOLVE policy).
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
+
+logger = logging.getLogger(__name__)
+
+_VALID_ACTIONS = frozenset({"retry", "force_reconcile", "cancel"})
+
+
+def register_ops_tools(server, get_engine: Callable) -> None:
+    """Register Wave-3 operational-recovery MCP tools on *server*."""
+
+    # ------------------------------------------------------------------
+    # 1. list_failed_operations — surface all stuck/failed/degraded ops
+    # ------------------------------------------------------------------
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    @admits(OperationKind.OPS_INSPECT)
+    async def list_failed_operations(
+        profile_id: str = "",
+    ) -> dict:
+        """List all failed, stuck, or degraded memory operations.
+
+        Returns three categories of troubled operations:
+        - dead_letter: ingestion ops that exhausted all automatic retries.
+        - degraded_manifests: completion records where some projections failed.
+        - exhausted_obligations: graph/projection tasks that could not apply.
+
+        An admin can then call resolve_operation to retry, force-reconcile, or
+        cancel each entry.  Non-technical users see these in the dashboard
+        Operations & Health panel.
+
+        Args:
+            profile_id: Filter to a specific profile (empty = all profiles).
+        """
+        try:
+            engine = get_engine()
+            db_path = getattr(getattr(engine, "_config", None), "db_path", None)
+            if db_path is None:
+                from superlocalmemory.infra.data_root import state_path
+                db_path = state_path("memory.db")
+
+            from superlocalmemory.core.ops_remediation import (
+                list_failed_operations as _list,
+            )
+            result = _list(db_path, profile_id=profile_id or None)
+            return {"success": True, **result}
+        except Exception as exc:
+            logger.exception("list_failed_operations tool failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 2. resolve_operation — admin remediation: retry / force / cancel
+    # ------------------------------------------------------------------
+    @server.tool(annotations=ToolAnnotations(destructiveHint=True))
+    @admits(OperationKind.OPS_RESOLVE)
+    async def resolve_operation(
+        operation_id: str,
+        action: str,
+    ) -> dict:
+        """Resolve a stuck, failed, or degraded operation.
+
+        Performs one of three remediation actions:
+        - retry:            Re-queue the dead-letter entry for ingestion.
+        - force_reconcile:  Force projection obligations to re-apply now.
+        - cancel:           Remove the entry from failure surfaces permanently.
+
+        After a cancel, the entry no longer appears in list_failed_operations.
+        After retry/force_reconcile, results depend on whether the underlying
+        issue (e.g. missing embedding model) is now resolved.
+
+        Args:
+            operation_id: The operation_id string shown in list_failed_operations.
+            action:       One of: retry, force_reconcile, cancel.
+        """
+        if action not in _VALID_ACTIONS:
+            return {
+                "success": False,
+                "error": f"invalid action '{action}': must be one of {sorted(_VALID_ACTIONS)}",
+            }
+        try:
+            engine = get_engine()
+            db_path = getattr(getattr(engine, "_config", None), "db_path", None)
+            if db_path is None:
+                from superlocalmemory.infra.data_root import state_path
+                db_path = state_path("memory.db")
+
+            from superlocalmemory.core.ops_remediation import (
+                resolve_operation as _resolve,
+            )
+            return _resolve(db_path, engine, operation_id, action)
+        except ValueError as exc:
+            return {"success": False, "error": str(exc)}
+        except Exception as exc:
+            logger.exception("resolve_operation tool failed op=%s action=%s", operation_id, action)
+            return {"success": False, "error": str(exc)}

package/src/superlocalmemory/mcp/tools_optimize.py

@@ -24,6 +24,8 @@ import time
 
 from mcp.types import ToolAnnotations
 
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.mcp.agent_context import get_current_agent_id
 from superlocalmemory.optimize.compress.ccr import CCRStore, _UUID4_RE
 from superlocalmemory.optimize.compress.router import CompressRouter
@@ -70,6 +72,7 @@ def register_optimize_tools(server) -> None:
     """
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    @admits(OperationKind.CONSOLIDATE)
     async def slm_compress(
         content: str,
         mode: str = "auto",
@@ -191,6 +194,7 @@ def register_optimize_tools(server) -> None:
             }
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    @admits(OperationKind.REMEMBER)
     async def slm_cache_set(key: str, value: str, ttl_seconds: int = 86400) -> dict:
         """Cache a result you want to reuse (tool output, file read, search result).
 

package/src/superlocalmemory/mcp/tools_v28.py

@@ -15,6 +15,10 @@ from __future__ import annotations
 import logging
 from typing import Callable
 
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.mcp.shared import authorize_mcp_mutation
 
 logger = logging.getLogger(__name__)
@@ -27,6 +31,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
     # 1. report_outcome
     # ------------------------------------------------------------------
     @server.tool()
+    @admits(OperationKind.REMEMBER)
     async def report_outcome(
         memory_ids: str,
         outcome: str,
@@ -91,7 +96,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 2. get_lifecycle_status
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_lifecycle_status(limit: int = 50) -> dict:
         """Get lifecycle state distribution for stored memories.
 
@@ -127,6 +132,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
     # 3. set_retention_policy
     # ------------------------------------------------------------------
     @server.tool()
+    @admits(OperationKind.CONSOLIDATE)
     async def set_retention_policy(
         cold_after_days: int = 30,
         archive_after_days: int = 90,
@@ -163,6 +169,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
     # 4. compact_memories
     # ------------------------------------------------------------------
     @server.tool()
+    @admits(OperationKind.CONSOLIDATE)
     async def compact_memories(dry_run: bool = True) -> dict:
         """Compact memory store by archiving cold/stale facts.
 
@@ -212,7 +219,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 5. get_behavioral_patterns
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_behavioral_patterns(limit: int = 20) -> dict:
         """Get detected behavioral patterns for the active profile.
 
@@ -241,7 +248,7 @@ def register_v28_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 6. audit_trail
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def audit_trail(limit: int = 50) -> dict:
         """Get compliance audit trail for the active profile.
 

package/src/superlocalmemory/mcp/tools_v3.py

@@ -14,6 +14,10 @@ from __future__ import annotations
 import logging
 from typing import Callable
 
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.mcp.shared import authorize_mcp_mutation
 
 logger = logging.getLogger(__name__)
@@ -25,7 +29,7 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 0. get_version (so IDEs can check compatibility)
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_version() -> dict:
         """Get SuperLocalMemory version, Python version, and platform info."""
         try:
@@ -47,12 +51,13 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     # 1. set_mode
     # ------------------------------------------------------------------
     @server.tool()
+    @admits(OperationKind.MODE_CHANGE)
     async def set_mode(mode: str) -> dict:
         """Switch operating mode (a, b, or c).
 
-        Mode A: Local Guardian (zero LLM, EU AI Act full compliance).
-        Mode B: Smart Local (local Ollama LLM, EU AI Act full).
-        Mode C: Full Power (cloud LLM, best accuracy).
+        Mode A: Local Guardian (zero LLM, local embeddings only).
+        Mode B: Smart Local (local Ollama LLM, on-device inference).
+        Mode C: Full Power (configured cloud LLM provider, best accuracy).
 
         Resets the engine to apply the new mode configuration.
 
@@ -106,7 +111,7 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 2. get_mode
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_mode() -> dict:
         """Get current operating mode and its capabilities.
 
@@ -135,7 +140,7 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 3. health
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def health() -> dict:
         """Get system health including math layer status.
 
@@ -219,7 +224,7 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 4. consistency_check
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def consistency_check(limit: int = 100) -> dict:
         """Run sheaf consistency check on stored memories.
 
@@ -276,8 +281,12 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 5. recall_trace
     # ------------------------------------------------------------------
-    @server.tool()
-    async def recall_trace(query: str, limit: int = 10) -> dict:
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def recall_trace(
+        query: str,
+        limit: int = 10,
+        as_of: str | None = None,
+    ) -> dict:
         """Recall with per-channel score breakdown.
 
         Like recall, but returns detailed channel-by-channel scores
@@ -286,14 +295,25 @@ def register_v3_tools(server, get_engine: Callable) -> None:
         Args:
             query: Natural-language search query.
             limit: Maximum results (default 10).
+            as_of: Optional ISO 8601 UTC datetime for point-in-time recall
+                (e.g. "2024-01-01T00:00:00Z"). Omit for current-state recall.
         """
         try:
             import asyncio
             from superlocalmemory.mcp._daemon_proxy import choose_pool
+            from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+
+            # Normalize at MCP boundary before forwarding.
+            _as_of: str | None = None
+            if as_of:
+                _as_of = normalize_as_of(as_of)
+                if _as_of is None:
+                    return {"success": False, "error": "invalid_as_of"}
+
             # 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)
+                lambda: choose_pool().recall(query=query, limit=limit, as_of=_as_of)
             )
             items = raw.get("results", []) if isinstance(raw, dict) else []
             results = []
@@ -341,10 +361,10 @@ def register_v3_tools(server, get_engine: Callable) -> None:
 # -- Helpers ------------------------------------------------------------------
 
 def _mode_description(mode: str) -> str:
-    """Human-readable description for a mode."""
+    """Human-readable capability description for a mode (never a legal claim)."""
     descriptions = {
-        "a": "Local Guardian: zero LLM, full EU AI Act compliance",
-        "b": "Smart Local: local Ollama LLM, full EU AI Act compliance",
-        "c": "Full Power: cloud LLM, best accuracy, partial EU AI Act",
+        "a": "Local Guardian: zero LLM, local embeddings only",
+        "b": "Smart Local: local Ollama LLM, on-device inference",
+        "c": "Full Power: configured cloud LLM provider, best accuracy",
     }
     return descriptions.get(mode, "Unknown mode")