superlocalmemory 3.6.23 → 3.7.0

package/src/superlocalmemory/mcp/_pool_adapter.py

@@ -34,6 +34,10 @@ class PoolRecallItem:
     fact: PoolFact = field(default_factory=PoolFact)
     score: float = 0.0
     confidence: float = 0.0
+    relevance_score: float = 0.0
+    ranking_score: float | None = None
+    memory_confidence: float = 0.0
+    rank_position: int = 0
     trust_score: float = 0.0
     channel_scores: dict[str, float] = field(default_factory=dict)
     evidence_chain: list[Any] = field(default_factory=list)
@@ -46,6 +50,12 @@ class PoolRecallResponse:
     retrieval_time_ms: float = 0.0
     channel_weights: dict[str, float] = field(default_factory=dict)
     total_candidates: int = 0
+    score_contract_version: str = "2"
+    calibration_status: str = "uncalibrated"
+    calibration_id: str | None = None
+    answer_confidence: float | None = None
+    abstained: bool = False
+    abstention_reason: str | None = None
 
 
 class PoolError(RuntimeError):
@@ -107,6 +117,15 @@ def pool_recall(query: str, limit: int = 10, **kwargs: Any) -> PoolRecallRespons
             ),
             score=float(item.get("score", 0.0)),
             confidence=float(item.get("confidence", 0.0)),
+            relevance_score=float(item.get("relevance_score", item.get("score", 0.0))),
+            ranking_score=(
+                float(item["ranking_score"])
+                if item.get("ranking_score") is not None else None
+            ),
+            memory_confidence=float(
+                item.get("memory_confidence", item.get("confidence", 0.0))
+            ),
+            rank_position=int(item.get("rank_position", 0)),
             trust_score=float(item.get("trust_score", 0.0)),
             channel_scores=item.get("channel_scores", {}) or {},
             evidence_chain=list(item.get("evidence_chain", []) or []),
@@ -122,6 +141,14 @@ def pool_recall(query: str, limit: int = 10, **kwargs: Any) -> PoolRecallRespons
         if isinstance(raw, dict) else {},
         total_candidates=int(raw.get("total_candidates", 0))
         if isinstance(raw, dict) else 0,
+        score_contract_version=str(raw.get("score_contract_version", "2"))
+        if isinstance(raw, dict) else "2",
+        calibration_status=str(raw.get("calibration_status", "uncalibrated"))
+        if isinstance(raw, dict) else "uncalibrated",
+        calibration_id=raw.get("calibration_id") if isinstance(raw, dict) else None,
+        answer_confidence=raw.get("answer_confidence") if isinstance(raw, dict) else None,
+        abstained=bool(raw.get("abstained", False)) if isinstance(raw, dict) else False,
+        abstention_reason=raw.get("abstention_reason") if isinstance(raw, dict) else None,
     )
 
 

package/src/superlocalmemory/mcp/http_transport.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Resource-safe FastMCP Streamable-HTTP integration.
+
+MCP SDK 1.27.1 passes an AnyIO ``MemoryObjectReceiveStream`` directly to
+``EventSourceResponse`` for every JSON-RPC POST.  The response consumes that
+stream but does not close it after normal iteration, leaving one receive
+endpoint per request for the garbage collector.  The response is the owner of
+that per-request iterator, so SLM closes it at the response boundary.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+from sse_starlette.sse import EventSourceResponse
+from starlette.types import Receive, Scope, Send
+
+
+class ClosingEventSourceResponse(EventSourceResponse):
+    """EventSourceResponse that closes the async iterator it consumes."""
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            await super().__call__(scope, receive, send)
+        finally:
+            close = getattr(self.body_iterator, "aclose", None)
+            if close is not None:
+                await close()
+
+
+def install_streamable_http_resource_guard() -> None:
+    """Install the response owner used by MCP's Streamable-HTTP transport."""
+    from mcp.server import streamable_http
+
+    streamable_http.EventSourceResponse = ClosingEventSourceResponse
+
+
+class SLMFastMCP(FastMCP):
+    """FastMCP with SLM release identity and deterministic SSE cleanup."""
+
+    def __init__(self, *args, product_version: str = "3.7.0", **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        # FastMCP delegates the initialize response to the low-level MCP
+        # server. Without an explicit value it reports the installed ``mcp``
+        # library version, which makes an SLM 3.7 server identify itself as
+        # (for example) 1.27.1 to every IDE client.
+        self._mcp_server.version = product_version
+
+    def streamable_http_app(self):
+        install_streamable_http_resource_guard()
+        return super().streamable_http_app()

package/src/superlocalmemory/mcp/server.py

@@ -27,11 +27,11 @@ _os.environ.setdefault('SLM_SKIP_DEP_CHECK', '1')
 import logging
 import sys
 
-from mcp.server.fastmcp import FastMCP
+from superlocalmemory.mcp.http_transport import SLMFastMCP
 
 logger = logging.getLogger(__name__)
 
-server = FastMCP("SuperLocalMemory V3")
+server = SLMFastMCP("SuperLocalMemory V3")
 
 # Lazy engine singleton -------------------------------------------------------
 
@@ -175,6 +175,18 @@ _PROFILE_DEFINITIONS: dict[str, frozenset[str]] = {
     "mesh": _PROFILE_MESH,
 }  # "whole" intentionally absent — maps to raw server (D-2 LOCKED)
 
+# Compatibility aliases published by the v3.6 README.  Keep these explicit so
+# a stale client configuration has one deterministic meaning and emits a
+# migration warning.  Any other value is a configuration error (fail closed).
+_PROFILE_ALIASES: dict[str, str] = {
+    "core14": "core",
+    "code20": "code",
+    "full38": "full",
+    "power50": "power",
+    "mesh8": "mesh",
+    "whole81": "whole",
+}
+
 _profile = _os_reg.environ.get("SLM_MCP_PROFILE", "").strip().lower()
 
 
@@ -188,19 +200,26 @@ def _resolve_profile_allowed(
     Returns:
         None  — for "" (no selection) or "whole" (raw server, all tools).
         frozenset — the profile's tool set for known profiles.
-        essential — fail-open fallback for unknown non-empty profiles (+ warning).
+
+    Raises:
+        ValueError: if ``profile`` is neither canonical nor an explicitly
+            supported compatibility alias.
     """
-    if not profile or profile == "whole":
+    canonical = _PROFILE_ALIASES.get(profile, profile)
+    if canonical != profile:
+        logger.warning(
+            "SLM_MCP_PROFILE=%r is deprecated; use %r instead.",
+            profile,
+            canonical,
+        )
+    if not canonical or canonical == "whole":
         return None
-    if profile in definitions:
-        return definitions[profile]
-    logger.warning(
-        "SLM_MCP_PROFILE=%r is not a recognised profile "
-        "(valid: %s, whole); falling back to essential tools.",
-        profile,
-        ", ".join(sorted(definitions)),
+    if canonical in definitions:
+        return definitions[canonical]
+    valid = ", ".join((*sorted(definitions), "whole"))
+    raise ValueError(
+        f"SLM_MCP_PROFILE={profile!r} is not recognised; valid profiles: {valid}"
     )
-    return essential
 
 
 class _FilteredServer:
@@ -237,7 +256,14 @@ elif _user_allowlist_str:
 elif _profile == "whole":
     _target = server                                                              # NEW raw-server
 elif _profile:
-    _target = _FilteredServer(server, _resolve_profile_allowed(_profile, _PROFILE_DEFINITIONS, _ESSENTIAL_TOOLS))  # NEW
+    _profile_allowed = _resolve_profile_allowed(
+        _profile, _PROFILE_DEFINITIONS, _ESSENTIAL_TOOLS
+    )
+    _target = (
+        server
+        if _profile_allowed is None
+        else _FilteredServer(server, _profile_allowed)
+    )
 else:
     _target = _FilteredServer(server, _ESSENTIAL_TOOLS)                          # default (unchanged)
 

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":