superlocalmemory 3.6.22 → 3.7.0

package/src/superlocalmemory/mcp/shared.py

@@ -10,9 +10,10 @@ V3.3.12: Extracted _emit_event to eliminate code duplication.
 
 from __future__ import annotations
 
-from pathlib import Path
+from dataclasses import dataclass
+from typing import Any
 
-_DB_PATH = Path.home() / ".superlocalmemory" / "memory.db"
+from superlocalmemory.infra.data_root import state_path
 
 
 def emit_event(event_type: str, payload: dict | None = None,
@@ -20,8 +21,73 @@ def emit_event(event_type: str, payload: dict | None = None,
     """Emit an event to the EventBus (best-effort, never raises)."""
     try:
         from superlocalmemory.infra.event_bus import EventBus
-        bus = EventBus.get_instance(_DB_PATH)
+        bus = EventBus.get_instance(state_path("memory.db"))
         bus.emit(event_type, payload=payload, source_agent=source_agent,
                  source_protocol="mcp")
     except Exception:
         pass
+
+
+@dataclass
+class MCPMutationAuthorization:
+    """One capability-owned MCP mutation authorized by engine policy."""
+
+    engine: Any
+    operation: str
+    context: dict[str, str]
+    _completed: bool = False
+
+    @property
+    def actor_id(self) -> str:
+        return self.context["agent_id"]
+
+    def complete(self) -> None:
+        """Emit the matching post hook once the mutation succeeds."""
+        if self._completed:
+            return
+        self.engine._hooks.run_post(self.operation, self.context)
+        self._completed = True
+
+
+def authorize_mcp_mutation(
+    engine: Any,
+    operation: str,
+    *,
+    mutation_source: str,
+    profile_id: str | None = None,
+    fact_id: str = "",
+    content_preview: str = "",
+) -> MCPMutationAuthorization:
+    """Derive local authority and run policy before a direct MCP write.
+
+    MCP URL/env agent identifiers remain audit attribution only.  The trusted
+    principal is derived from the private local install capability, matching
+    the canonical ingestion and recall-worker mutation boundaries.
+    """
+    if operation not in {"update", "delete"}:
+        raise ValueError("MCP mutations must use update or delete policy")
+
+    from superlocalmemory.core.engine_ingestion import local_trusted_actor_id
+    from superlocalmemory.mcp.agent_context import get_current_agent_id
+
+    source_agent_id = get_current_agent_id(env_fallback=True)
+    context = {
+        "operation": operation,
+        "agent_id": local_trusted_actor_id("mcp"),
+        "source_agent_id": source_agent_id,
+        "mutation_source": mutation_source,
+        "profile_id": profile_id or engine.profile_id,
+    }
+    if fact_id:
+        context["fact_id"] = fact_id
+    if content_preview:
+        context["content_preview"] = content_preview[:100]
+    engine._hooks.run_pre(operation, context)
+    return MCPMutationAuthorization(engine, operation, context)
+
+
+__all__ = [
+    "MCPMutationAuthorization",
+    "authorize_mcp_mutation",
+    "emit_event",
+]

package/src/superlocalmemory/mcp/tools_active.py

@@ -19,16 +19,17 @@ from __future__ import annotations
 import asyncio
 import datetime
 import logging
-import os
 import sqlite3
 import uuid
-from pathlib import Path
-from typing import Callable
+from typing import TYPE_CHECKING, Callable
 
-logger = logging.getLogger(__name__)
+from superlocalmemory.infra.data_root import canonical_data_root, state_path
+from superlocalmemory.mcp.shared import authorize_mcp_mutation
+
+if TYPE_CHECKING:
+    from superlocalmemory.mcp._pool_adapter import PoolRecallResponse
 
-MEMORY_DIR = Path.home() / ".superlocalmemory"
-DB_PATH = MEMORY_DIR / "memory.db"
+logger = logging.getLogger(__name__)
 
 
 def _sqlite_emergency_recall(
@@ -48,8 +49,9 @@ def _sqlite_emergency_recall(
     Used ONLY when Tier-1 (full daemon recall) fails completely. Normal
     path is full 6-channel; this is the fire-alarm.
     """
-    from superlocalmemory.mcp._pool_adapter import PoolFact, PoolRecallItem, PoolRecallResponse
     import re
+
+    from superlocalmemory.mcp._pool_adapter import PoolFact, PoolRecallItem, PoolRecallResponse
     try:
         # FTS5 MATCH syntax: tokenize the query, drop special characters
         # that confuse the parser (/, :, ., etc), and join with OR for
@@ -64,7 +66,7 @@ def _sqlite_emergency_recall(
             f"AND f.created_at >= datetime('now', '-{int(max_age_days)} days') "
             if max_age_days > 0 else ""
         )
-        conn = sqlite3.connect(str(DB_PATH), timeout=5.0)
+        conn = sqlite3.connect(str(state_path("memory.db")), timeout=5.0)
         try:
             rows = conn.execute(
                 f"""SELECT f.fact_id, f.content, f.memory_id, f.created_at,
@@ -129,24 +131,26 @@ def _emit_event(event_type: str, payload: dict | None = None,
     resolved_agent = source_agent if source_agent is not None else _get_agent_id()
     try:
         from superlocalmemory.infra.event_bus import EventBus
-        bus = EventBus.get_instance(str(DB_PATH))
+        bus = EventBus.get_instance(str(state_path("memory.db")))
         bus.emit(event_type, payload=payload, source_agent=resolved_agent,
                  source_protocol="mcp")
     except Exception as exc:
         logger.warning("event emit failed: type=%s err=%s", event_type, exc)
 
 
-def _register_agent(agent_id: str, profile_id: str) -> None:
+def _register_agent(agent_id: str, profile_id: str) -> bool:
     """Register an agent in the AgentRegistry (best-effort)."""
     try:
         from superlocalmemory.core.registry import AgentRegistry
-        registry_path = MEMORY_DIR / "agents.json"
+        registry_path = canonical_data_root() / "agents.json"
         registry = AgentRegistry(persist_path=registry_path)
         registry.register_agent(agent_id, profile_id)
+        return True
     except Exception as exc:
         logger.warning(
             "agent registry write failed: agent=%s err=%s", agent_id, exc,
         )
+        return False
 
 
 def register_active_tools(server, get_engine: Callable) -> None:
@@ -194,7 +198,12 @@ def register_active_tools(server, get_engine: Callable) -> None:
             rules = RulesEngine()
 
             if not rules.should_recall("session_start"):
-                return {"success": True, "context": "", "memories": [], "message": "Auto-recall disabled"}
+                return {
+                    "success": True,
+                    "context": "",
+                    "memories": [],
+                    "message": "Auto-recall disabled",
+                }
 
             recall_config = rules.get_recall_config()
             relevance_threshold = recall_config.get("relevance_threshold", 0.3)
@@ -239,7 +248,8 @@ def register_active_tools(server, get_engine: Callable) -> None:
             # Memories older than max_age_days are excluded unless their score
             # exceeds 0.7 (high-relevance architectural decisions always surface).
             # max_age_days=0 disables the gate entirely.
-            from datetime import UTC, datetime as _dt
+            from datetime import UTC
+            from datetime import datetime as _dt
             _now = _dt.now(UTC)
 
             def _age_days(created_at_str: str) -> float:
@@ -272,6 +282,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 clamp_content,
                 is_low_quality,
                 render_context,
+                sanitize_untrusted_content,
             )
 
             pid = engine.profile_id
@@ -282,7 +293,6 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 pinned_facts = engine.db.get_pinned(pid)
             except Exception:
                 pinned_facts = []
-            pinned_ids = {f.fact_id for f in pinned_facts}
             pinned_seen = set()
 
             cfg_inj = getattr(getattr(engine, "config", None), "injection", None)
@@ -304,6 +314,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
                     importance=getattr(pf, "importance", 0.0) or 0.0,
                     access_count=getattr(pf, "access_count", 0) or 0,
                     pinned=True,
+                    source_type="pinned-fact",
                 ))
                 pinned_seen.add(pf.fact_id)
 
@@ -317,17 +328,18 @@ def register_active_tools(server, get_engine: Callable) -> None:
                     fact_id=r.fact.fact_id,
                     importance=getattr(r.fact, "importance", 0.0) or 0.0,
                     access_count=getattr(r.fact, "access_count", 0) or 0,
+                    source_type="recall",
                 ))
 
             mode_str = str(getattr(engine, "mode", "B")).upper()
             try:
-                context = render_context(inj_mems, mode=mode_str, cfg=cfg_inj, wrap=False)
+                context = render_context(
+                    inj_mems, mode=mode_str, cfg=cfg_inj, wrap=True,
+                )
             except Exception:
-                # Fall back to legacy content building on any formatter failure
-                lines = ["# Relevant Memory Context", ""]
-                for m in inj_mems[:max_results]:
-                    lines.append(f"- {m.content[:200]}")
-                context = "\n".join(lines)
+                # Fail closed: never serialize retrieved content through a
+                # weaker ad-hoc path when the mandatory renderer fails.
+                context = ""
 
             # GAP-FIX (v3.4.65 delivery-lead): the memories[] array is part of
             # the MCP response Claude Code ingests — it MUST be bounded too, not
@@ -335,16 +347,43 @@ def register_active_tools(server, get_engine: Callable) -> None:
             # content shipped here (one fact was 131K chars → ~124K-token
             # response, defeating the whole token budget). Clamp each content
             # to per_memory_max_tokens, drop junk, and honour max_results.
-            memories = [
-                {
+            contract_by_id = {
+                r.fact.fact_id: r for r in relevant[:max_results]
+            }
+            memories = []
+            for position, m in enumerate(inj_mems[:max_results], start=1):
+                if is_low_quality(m.content):
+                    continue
+                result_contract = contract_by_id.get(m.fact_id)
+                relevance = (
+                    getattr(result_contract, "relevance_score", m.score)
+                    if result_contract is not None else m.score
+                )
+                memory_confidence = (
+                    getattr(result_contract, "memory_confidence", None)
+                    if result_contract is not None else None
+                )
+                memories.append({
                     "fact_id": m.fact_id,
-                    "content": clamp_content(m.content, cfg_inj),
+                    "content": clamp_content(
+                        sanitize_untrusted_content(m.content), cfg_inj,
+                    ),
                     "score": m.score,
+                    "relevance_score": relevance,
+                    "ranking_score": (
+                        getattr(result_contract, "ranking_score", None)
+                        if result_contract is not None else None
+                    ),
+                    "confidence": memory_confidence,
+                    "memory_confidence": memory_confidence,
+                    "rank_position": (
+                        getattr(result_contract, "rank_position", position)
+                        if result_contract is not None else position
+                    ),
                     "is_core": m.is_core,
-                }
-                for m in inj_mems[:max_results]
-                if not is_low_quality(m.content)
-            ]
+                    "untrusted": True,
+                    "source_type": m.source_type,
+                })
 
             # Get learning status
             feedback_count = 0
@@ -366,7 +405,21 @@ def register_active_tools(server, get_engine: Callable) -> None:
 
             # Register agent + emit event (v3.4.39: SLM_AGENT_ID env support)
             agent_id = _get_agent_id()
-            _register_agent(agent_id, pid)
+            if hasattr(engine, "_hooks"):
+                registration_auth = authorize_mcp_mutation(
+                    engine,
+                    "update",
+                    mutation_source="mcp-agent-registration",
+                    profile_id=pid,
+                )
+                if _register_agent(agent_id, pid):
+                    registration_auth.complete()
+            else:
+                # A LIGHT client without the policy registry is read-capable,
+                # but must not fall back to an unauthorised registry write.
+                logger.info(
+                    "agent registration skipped: policy hooks unavailable"
+                )
             _emit_event("agent.connected", {
                 "agent_id": agent_id,
                 "project_path": project_path,
@@ -381,11 +434,29 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 "memory_count": len(memories),
                 "core_memory": [m["content"] for m in memories if m.get("is_core")],
                 "degraded_mode": degraded_mode,
-                "retrieval_mode": "emergency_fts5_bm25" if degraded_mode else "full_6_channel",
+                "retrieval_mode": (
+                    "emergency_fts5_bm25"
+                    if degraded_mode
+                    else "hybrid_candidate_fusion"
+                ),
+                "score_contract_version": getattr(
+                    response, "score_contract_version", "2"
+                ),
+                "calibration_status": getattr(
+                    response, "calibration_status", "uncalibrated"
+                ),
+                "calibration_id": getattr(response, "calibration_id", None),
+                "answer_confidence": getattr(response, "answer_confidence", None),
+                "abstained": getattr(response, "abstained", not bool(relevant)),
+                "abstention_reason": getattr(response, "abstention_reason", None),
                 "learning": {
                     "feedback_signals": feedback_count,
                     "phase": 1 if feedback_count < 50 else (2 if feedback_count < 200 else 3),
-                    "status": "collecting" if feedback_count < 50 else ("learning" if feedback_count < 200 else "trained"),
+                    "status": (
+                        "collecting"
+                        if feedback_count < 50
+                        else "learning" if feedback_count < 200 else "trained"
+                    ),
                 },
             }
         except Exception as exc:
@@ -496,8 +567,22 @@ def register_active_tools(server, get_engine: Callable) -> None:
             pid = engine.profile_id
 
             if feedback not in ("relevant", "irrelevant", "partial"):
-                return {"success": False, "error": f"Invalid feedback: {feedback}. Use relevant/irrelevant/partial"}
+                return {
+                    "success": False,
+                    "error": (
+                        f"Invalid feedback: {feedback}. "
+                        "Use relevant/irrelevant/partial"
+                    ),
+                }
 
+            authorization = authorize_mcp_mutation(
+                engine,
+                "update",
+                mutation_source="mcp-recall-feedback",
+                profile_id=pid,
+                fact_id=fact_id,
+                content_preview=feedback,
+            )
             record = engine._adaptive_learner.record_feedback(
                 query=query,
                 fact_id=fact_id,
@@ -506,6 +591,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
             )
 
             count = engine._adaptive_learner.get_feedback_count(pid)
+            authorization.complete()
 
             _emit_event("pattern.learned", {
                 "fact_id": fact_id,
@@ -562,7 +648,15 @@ def register_active_tools(server, get_engine: Callable) -> None:
                     pass
             if not sid:
                 return {"success": False, "error": "No session_id provided or found"}
+            authorization = authorize_mcp_mutation(
+                engine,
+                "update",
+                mutation_source="mcp-session-close",
+                profile_id=engine.profile_id,
+                content_preview=sid,
+            )
             count = engine.close_session(sid)
+            authorization.complete()
             return {
                 "success": True,
                 "session_id": sid,
@@ -596,13 +690,29 @@ def register_active_tools(server, get_engine: Callable) -> None:
             if action == "pin":
                 if not fact_id:
                     return {"success": False, "error": "fact_id required for pin"}
+                authorization = authorize_mcp_mutation(
+                    engine,
+                    "update",
+                    mutation_source="mcp-core-memory-pin",
+                    profile_id=pid,
+                    fact_id=fact_id,
+                )
                 db.set_pinned(fact_id, True)
+                authorization.complete()
                 return {"success": True, "action": "pin", "fact_id": fact_id}
 
             if action == "unpin":
                 if not fact_id:
                     return {"success": False, "error": "fact_id required for unpin"}
+                authorization = authorize_mcp_mutation(
+                    engine,
+                    "update",
+                    mutation_source="mcp-core-memory-unpin",
+                    profile_id=pid,
+                    fact_id=fact_id,
+                )
                 db.set_pinned(fact_id, False)
+                authorization.complete()
                 return {"success": True, "action": "unpin", "fact_id": fact_id}
 
             if action == "list":