superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/mcp/server.py

@@ -1,480 +0,0 @@
-# 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
-
-"""SuperLocalMemory V4 — MCP Server.
-
-Clean MCP server calling V3 MemoryEngine. Supports all MCP-compatible IDEs.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-# CRITICAL: Set BEFORE any torch/transformers import to prevent Metal/MPS
-# GPU memory reservation on Apple Silicon.
-import os as _os
-_os.environ.setdefault('PYTORCH_MPS_HIGH_WATERMARK_RATIO', '0.0')
-_os.environ.setdefault('PYTORCH_MPS_MEM_LIMIT', '0')
-_os.environ.setdefault('PYTORCH_ENABLE_MPS_FALLBACK', '1')
-_os.environ.setdefault('TOKENIZERS_PARALLELISM', 'false')
-_os.environ.setdefault('TORCH_DEVICE', 'cpu')
-# LIGHT engine contract: suppress the top-level dep check in __init__.py
-# that unconditionally imports onnxruntime. MCP runs LIGHT-only — ONNX
-# must never load in this process.
-_os.environ.setdefault('SLM_SKIP_DEP_CHECK', '1')
-
-import logging
-import sys
-
-from superlocalmemory import __version__ as _slm_version
-from superlocalmemory.mcp.http_transport import SLMFastMCP
-
-logger = logging.getLogger(__name__)
-
-# mcp 2.0.0: MCPServer takes version= directly (no private _mcp_server poke).
-server = SLMFastMCP("SuperLocalMemory V4", version=_slm_version)
-
-# Lazy engine singleton -------------------------------------------------------
-
-import threading as _threading
-_engine = None
-_engine_lock = _threading.Lock()
-
-
-def get_engine():
-    """Return (or create) the singleton LIGHT MemoryEngine.
-
-    FastMCP may call tools concurrently from multiple threads. The
-    double-checked lock keeps construction single-shot even if two
-    tool invocations race on a cold process — without it we would
-    double-run the schema migrations and build two ``AdaptiveLearner``
-    instances over the same DB file.
-    """
-    global _engine
-    if _engine is not None:
-        return _engine
-    with _engine_lock:
-        if _engine is not None:
-            return _engine
-        from superlocalmemory.core.config import SLMConfig
-        from superlocalmemory.core.engine import MemoryEngine
-        from superlocalmemory.core.engine_capabilities import Capabilities
-
-        config = SLMConfig.load()
-        new_engine = MemoryEngine(config, capabilities=Capabilities.LIGHT)
-        new_engine.initialize()
-        _engine = new_engine
-    return _engine
-
-
-def reset_engine():
-    """Reset engine singleton (for testing or mode switch)."""
-    global _engine
-    with _engine_lock:
-        _engine = None
-
-
-# Register tools and resources -------------------------------------------------
-#
-# Essential-only default: 41 base tools + 8 mesh tools = 49 registered.
-# when mesh is enabled. Set ``SLM_MCP_ALL_TOOLS=1`` to expose the full
-# toolset. Rationale: IDEs cap at 50-100 tools total (Cursor,
-# Antigravity, Windsurf) and a maximal SLM registration crowds out
-# other MCP servers the user may have installed.
-# Admin/diagnostics tools remain available via CLI (`slm <command>`).
-# Set SLM_MCP_ALL_TOOLS=1 to enable all 94 tools (power users).
-
-import os as _os_reg
-
-_ESSENTIAL_TOOLS: set[str] = {
-    # Core memory operations (8)
-    "remember", "recall", "search", "fetch",
-    "list_recent", "delete_memory", "update_memory", "get_status",
-    "switch_profile",
-    # Session lifecycle (3)
-    "session_init", "observe", "close_session",
-    # 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",
-    # v4.0.4: explicit, optional observation from the separately installed
-    # Bounded Loops MCP producer. It never participates in recall/ranking.
-    "observe_bounded_loop_evidence",
-    # Update, review, and list form one core correction lifecycle.
-    "review_correction", "list_corrections",
-    # v4.0.8 (#113): readable summaries. Present here as well as in the named
-    # profiles because this set is the FALLBACK surface — it must mirror
-    # ``full``, and a tool that ships in the smallest profile ("core") cannot be
-    # missing from the fallback without a client silently losing it.
-    "get_memory_summary",
-    # Memory management (2)
-    "forget", "run_maintenance",
-    # NOTE: prestage_context IS registered (see register_prestage_tool below)
-    # but is deliberately absent from the default surface. Brain evidence is
-    # intentionally present: it is the portable contract for installed agents.
-    # Infinite memory + learning (4)
-    "consolidate_cognitive", "get_soft_prompts",
-    "set_mode", "report_outcome",
-    # v3.4.7: Two-way learning (4)
-    "log_tool_event", "get_assertions",
-    "reinforce_assertion", "contradict_assertion",
-    # v3.4.11: Skill evolution (3)
-    "evolve_skill", "skill_health", "skill_lineage",
-    # v3.6.11: Surface B Optimize tools (5)
-    "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
-    # v3.8.0: bounded-loop tools (3) — CLI + /slm-loop command + MCP. Kept in
-    # the default exposure so any MCP client discovers gated loops, not just
-    # profile=code/full/power sessions.
-    "slm_loop_run", "slm_loop_history", "slm_loop_show",
-}
-
-# v3.4.4: Mesh tools — enabled if mesh_enabled in config or SLM_MCP_MESH_TOOLS=1
-_mesh_tools_enabled = _os_reg.environ.get("SLM_MCP_MESH_TOOLS", "").lower() in ("1", "true")
-if not _mesh_tools_enabled:
-    try:
-        from superlocalmemory.core.config import SLMConfig
-        _cfg = SLMConfig.load()
-        _mesh_tools_enabled = getattr(_cfg, "mesh_enabled", True)  # default True in v3.4.3+
-    except Exception:
-        _mesh_tools_enabled = True  # Safe default — mesh broker is always in daemon
-
-if _mesh_tools_enabled:
-    _ESSENTIAL_TOOLS.update({
-        "mesh_summary", "mesh_peers", "mesh_send", "mesh_inbox",
-        "mesh_state", "mesh_lock", "mesh_events", "mesh_status",
-    })
-
-_ESSENTIAL_TOOLS = frozenset(_ESSENTIAL_TOOLS)
-
-_all_tools = _os_reg.environ.get("SLM_MCP_ALL_TOOLS") == "1"
-
-# v3.4.45: Minimal mode — explicit user allowlist via SLM_MCP_TOOLS env var.
-# Format: comma-separated tool names, e.g. "remember,recall,session_init,search"
-# Use case: Claude Code consumer plans with tight context budgets where the
-# 25-tool essential set is still too many. Power users override to expose
-# exactly the tools they invoke. Falls back to _ESSENTIAL_TOOLS when unset.
-_user_allowlist_str = _os_reg.environ.get("SLM_MCP_TOOLS", "").strip()
-
-# ---------------------------------------------------------------------------
-# Named profile definitions (introduced in v3.6.14)
-# Extracted to mcp/profiles.py (v3.8.0) — pure data, no side effects.
-# All names re-exported here for backward compatibility with existing tests
-# and any code that imports them from this module.
-# ---------------------------------------------------------------------------
-
-from superlocalmemory.mcp.profiles import (  # noqa: E402 (after env setups above)
-    _PROFILE_CORE,
-    _PROFILE_CODE,
-    _PROFILE_FULL_MESH,
-    _PROFILE_FULL,
-    _PROFILE_POWER,
-    _PROFILE_MESH,
-    _PROFILE_DEFINITIONS,
-    _PROFILE_ALIASES,
-)
-
-_profile = _os_reg.environ.get("SLM_MCP_PROFILE", "").strip().lower()
-
-
-def _resolve_profile_allowed(
-    profile: str,
-    definitions: dict[str, frozenset[str]],
-    essential: frozenset[str],
-) -> frozenset[str] | None:
-    """Resolve a profile name to its allowed tool frozenset, or None for raw-server routes.
-
-    Returns:
-        None  — for "" (no selection) or "whole" (raw server, all tools).
-        frozenset — the profile's tool set for known profiles.
-
-    Raises:
-        ValueError: if ``profile`` is neither canonical nor an explicitly
-            supported compatibility alias.
-    """
-    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 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}"
-    )
-
-
-class _FilteredServer:
-    """Wraps FastMCP to only register essential tools.
-
-    Non-essential tools are silently skipped (not registered on the MCP
-    server). They remain available via CLI. When SLM_MCP_ALL_TOOLS=1,
-    all tools are registered (bypass filter). When SLM_MCP_TOOLS is set,
-    that user allowlist is used instead of _ESSENTIAL_TOOLS.
-    """
-    __slots__ = ("_server", "_allowed")
-
-    def __init__(self, real_server: SLMFastMCP, allowed: frozenset[str]) -> None:
-        self._server = real_server
-        self._allowed = allowed
-
-    def tool(self, *args, **kwargs):
-        def decorator(func):
-            if func.__name__ in self._allowed:
-                return self._server.tool(*args, **kwargs)(func)
-            return func  # Skip registration — still importable, just not MCP-visible
-        return decorator
-
-    def __getattr__(self, name):
-        return getattr(self._server, name)
-
-
-# Choose registration target (precedence: ALL > user allowlist > profile > essential)
-if _all_tools:
-    _target = server                                                              # tier1 (unchanged)
-elif _user_allowlist_str:
-    _user_allowlist = frozenset(t.strip() for t in _user_allowlist_str.split(",") if t.strip())
-    _target = _FilteredServer(server, _user_allowlist)                           # tier2 (unchanged)
-elif _profile == "whole":
-    _target = server                                                              # NEW raw-server
-elif _profile:
-    _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)
-
-from superlocalmemory.mcp.tools_core import register_core_tools
-from superlocalmemory.mcp.tools_v28 import register_v28_tools
-from superlocalmemory.mcp.tools_v3 import register_v3_tools
-from superlocalmemory.mcp.tools_active import register_active_tools
-from superlocalmemory.mcp.tools_v33 import register_v33_tools
-from superlocalmemory.mcp.resources import register_resources
-from superlocalmemory.mcp.tools_code_graph import register_code_graph_tools
-from superlocalmemory.mcp.tools_mesh import register_mesh_tools
-from superlocalmemory.mcp.tools_learning import register_learning_tools
-from superlocalmemory.mcp.tools_evolution import register_evolution_tools
-
-register_core_tools(_target, get_engine)
-register_v28_tools(_target, get_engine)
-register_v3_tools(_target, get_engine)
-register_active_tools(_target, get_engine)
-register_v33_tools(_target, get_engine)
-register_resources(server, get_engine)  # Resources always registered (not tools)
-register_code_graph_tools(_target, get_engine)  # CodeGraph: filtered like other tools (SLM_MCP_ALL_TOOLS=1 to show all)
-register_mesh_tools(_target, get_engine)  # v3.4.4: Mesh P2P tools — ships with SLM, no separate slm-mesh needed
-register_learning_tools(_target, get_engine)  # v3.4.7: Two-way learning tools
-register_evolution_tools(_target, get_engine)  # v3.4.11: Skill evolution tools
-from superlocalmemory.mcp.tools_optimize import register_optimize_tools
-register_optimize_tools(_target)  # v3.6.11: Surface B Optimize tools (proxy-free)
-from superlocalmemory.mcp.tools_loops import register_loop_tools
-from superlocalmemory.mcp._daemon_proxy import choose_pool as _choose_loop_pool
-register_loop_tools(
-    _target,
-    get_engine,
-    _choose_loop_pool,
-)  # v3.8.0: bounded-loop tools (CLI+command+MCP)
-from superlocalmemory.mcp.tools_ops import register_ops_tools
-register_ops_tools(_target, get_engine)  # 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_summaries import register_summary_tools
-register_summary_tools(_target, get_engine)  # v4.0.8 issue #113 summary reads
-from superlocalmemory.mcp.tools_context import register_prestage_tool
-
-
-def _prestage_recall(query: str, limit: int, profile_id: str, as_of: str | None = None):
-    """Bridge engine.recall → prestage_context recall_fn shape."""
-    engine = get_engine()
-    if hasattr(engine, "profile_id") and profile_id:
-        try:
-            engine.profile_id = profile_id
-        except Exception:
-            pass
-    try:
-        if as_of is not None:
-            results = engine.recall(query, limit=limit, as_of=as_of)
-        else:
-            results = engine.recall(query, limit=limit)
-    except TypeError:
-        results = engine.recall(query, limit=limit)
-    out: list[dict] = []
-    for r in results or []:
-        if isinstance(r, dict):
-            out.append({
-                "id": str(r.get("fact_id") or r.get("id") or ""),
-                "text": str(r.get("content") or r.get("text") or ""),
-                "score": float(r.get("score") or r.get("relevance_score") or 0.0),
-                "source": str(r.get("source") or "recall"),
-            })
-        else:
-            out.append({
-                "id": str(getattr(r, "fact_id", "") or ""),
-                "text": str(getattr(r, "content", "") or ""),
-                "score": float(getattr(r, "score", 0.0) or 0.0),
-                "source": "recall",
-            })
-    return out
-
-
-register_prestage_tool(_target, _prestage_recall)
-
-
-# Keep stdio MCP processes thin until a tool truly needs a local LIGHT engine.
-# Every open IDE/task owns a stdio process; eagerly opening memory.db in all of
-# them multiplied RAM and SQLite writers on machines with many long-lived
-# sessions. The shared daemon owns model warmup and common remember/recall work.
-def _eager_warmup() -> None:
-    """Ensure the shared daemon is running without opening a per-client engine.
-
-    Mesh registration is intentionally lazy: a local stdio session is not a
-    remote peer, and heartbeat writes should begin only after a mesh tool is
-    actually used.
-    """
-    _logger = logging.getLogger(__name__)
-
-    # Measurement / test harnesses set this to skip daemon-start.
-    if _os.environ.get("SLM_DISABLE_WARMUP_SIDE_EFFECTS") == "1":
-        return
-
-    # V3.4.4: Also ensure daemon is running for dashboard/mesh/health features.
-    # This runs in background — doesn't block MCP tool registration.
-    try:
-        from superlocalmemory.cli.daemon import ensure_daemon
-        if ensure_daemon():
-            _logger.info("Daemon auto-started by MCP server")
-    except Exception as exc:
-        _logger.warning("Daemon auto-start failed: %s", exc)
-
-import threading
-
-# v3.6.7: Suppress standalone-process behaviours when the MCP server is
-# imported inside the daemon (SLM_MCP_EMBEDDED=1). Three threads are safe
-# to run in a dedicated `slm mcp` subprocess but harmful inside the daemon:
-#   mcp-warmup      — ensures the shared daemon only; never creates an engine.
-#   parent-watchdog — calls os._exit(0) if its parent IDE quits, which would
-#                     kill the daemon along with it.
-#   stdin-eof-monitor — monitors stdin pipe; meaningless inside the daemon.
-_embedded_in_daemon = _os.environ.get("SLM_MCP_EMBEDDED") == "1"
-
-if not _embedded_in_daemon:
-    _warmup_thread = threading.Thread(target=_eager_warmup, daemon=True, name="mcp-warmup")
-    _warmup_thread.start()
-
-
-# V3.4.57: Parent watchdog — self-terminate when the IDE/Claude session dies.
-# FastMCP relies on stdin EOF to stop, but stdin EOF is NOT guaranteed on
-# crash or force-quit. Without this, every abnormal exit leaves an orphaned
-# slm mcp process consuming ~100-200 MB indefinitely. 22 orphans caused a
-# daemon deadlock on May 30 2026 (241% CPU, session_init timeouts).
-def _parent_watchdog() -> None:
-    """Exit when parent IDE process (Claude Code, Cursor, etc.) dies.
-
-    Polls os.getppid() every 10 seconds. On macOS/Linux, when a parent
-    dies the child is reparented to PID 1 (init) — getppid() returns 1.
-    Also validates the original parent is still alive via os.kill(ppid, 0).
-    Uses os._exit(0) to bypass any atexit handlers that might hang.
-    """
-    import os as _os_wd, time as _time
-    _wlog = logging.getLogger(__name__ + ".watchdog")
-    initial_ppid = _os_wd.getppid()
-    if initial_ppid <= 1:
-        return  # Already reparented at startup — don't self-terminate
-    while True:
-        _time.sleep(10)
-        try:
-            current_ppid = _os_wd.getppid()
-            if current_ppid != initial_ppid or current_ppid <= 1:
-                _wlog.info("Parent PID changed (%d→%d), self-terminating", initial_ppid, current_ppid)
-                _os_wd._exit(0)
-            _os_wd.kill(initial_ppid, 0)  # Raises ProcessLookupError if dead
-        except ProcessLookupError:
-            _wlog.info("Parent PID %d gone, self-terminating", initial_ppid)
-            _os_wd._exit(0)
-        except Exception:
-            pass  # Transient errors — keep watching
-
-
-if not _embedded_in_daemon:
-    _watchdog_thread = threading.Thread(target=_parent_watchdog, daemon=True, name="parent-watchdog")
-    _watchdog_thread.start()
-
-
-# V3.5.9: Stdin EOF monitor — complements the parent watchdog for the case where
-# the IDE starts a new MCP session WITHOUT quitting the app. The old stdio pipe
-# is abandoned (write-end closed) but the parent process stays alive, so the
-# watchdog never fires. Without this, each IDE reconnect adds a zombie process
-# (22 seen in production causing 12 GB swap on the M5 Pro).
-#
-# Uses kqueue(2) KQ_EV_EOF on macOS — fires when the write-end of the stdin pipe
-# closes WITHOUT consuming any bytes, so it cannot race with FastMCP's asyncio
-# stdin reader. On Linux (no kqueue), the watchdog alone provides coverage.
-def _stdin_eof_monitor() -> None:
-    """Exit when the IDE closes our stdin pipe (kqueue — macOS only).
-
-    V3.6.4: kqueue ``EVFILT_READ`` reports ``EV_EOF`` *together with*
-    still-readable bytes (``ev.data > 0``) when the write-end closes while a
-    final request is buffered. Exiting on the EOF flag alone (pre-3.6.4)
-    dropped that in-flight request and self-terminated a session that still
-    had work to deliver — strict MCP hosts (e.g. the Hermes agent) then
-    logged a keepalive failure and respawned the process. We now defer
-    termination until the buffer is genuinely drained (see ``_stdin_guard``).
-    """
-    import select as _sel, os as _os_eof, time as _time
-    from superlocalmemory.mcp._stdin_guard import eof_action
-    _mlog = logging.getLogger(__name__ + ".stdin_monitor")
-    if not hasattr(_sel, "kqueue"):
-        return  # Linux / non-macOS: watchdog covers process death
-    # Bounded grace for the FastMCP reader to drain a buffered final request
-    # before we tear down. ~2 s ceiling (40 × 50 ms): a genuine EOF means the
-    # session is ending regardless, so we never wait indefinitely.
-    _DRAIN_POLL_S = 0.05
-    _DRAIN_MAX_POLLS = 40
-    try:
-        fd = sys.stdin.fileno()
-        kq = _sel.kqueue()
-        ke = _sel.kevent(fd, filter=_sel.KQ_FILTER_READ, flags=_sel.KQ_EV_ADD | _sel.KQ_EV_EOF)
-        kq.control([ke], 0)  # register without waiting
-        while True:
-            evs = kq.control(None, 4, 30.0)  # 30 s poll — low cost
-            for ev in evs:
-                action = eof_action(ev.flags, ev.data, _sel.KQ_EV_EOF)
-                if action == "ignore":
-                    continue
-                if action == "drain":
-                    # Write-end closed but unread bytes remain. Let the
-                    # FastMCP reader consume the final request(s); poll until
-                    # drained or the grace ceiling elapses.
-                    for _ in range(_DRAIN_MAX_POLLS):
-                        _time.sleep(_DRAIN_POLL_S)
-                        recheck = kq.control(None, 4, 0)  # non-blocking
-                        if not recheck:
-                            break
-                        ev = recheck[0]
-                        if eof_action(ev.flags, ev.data, _sel.KQ_EV_EOF) != "drain":
-                            break
-                _mlog.info("stdin write-end closed (kqueue EOF, drained), self-terminating")
-                _os_eof._exit(0)
-    except Exception as exc:
-        _mlog.debug("stdin EOF monitor error: %s — watchdog will cover", exc)
-
-
-if not _embedded_in_daemon:
-    _stdin_monitor_thread = threading.Thread(target=_stdin_eof_monitor, daemon=True, name="stdin-eof-monitor")
-    _stdin_monitor_thread.start()
-
-
-if __name__ == "__main__":
-    server.run(transport="stdio")

package/src/superlocalmemory/mcp/session_binding.py

@@ -1,98 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Work out which session a tool call belongs to, the same way every time.
-
-``recall`` has resolved this through a four-step ladder since S9-DASH-10 — the
-explicit argument, then the environment, then the hook registry, then a stable
-per-agent fallback — so an engagement signal lands on the right pending outcome.
-``remember`` never had it. It took ``session_id: str = ""`` and stored whatever
-it was handed, which for a caller that does not pass one is nothing.
-
-Measured on the author's store: **192 of 3,894 genuine facts carry a session_id
-(4.9%)**, and 4 of the 200 most recent (2%). Every one of the rest was written
-through a path that could have known and did not.
-
-That is not bookkeeping. ``RetrievalEngine`` promotes results so the top of an
-answer spans more than one session (its ``sessions_in_top`` pass), and a fact
-with no session_id can never be promoted by it — so the diversity mechanism was
-running against a corpus where 95% of rows were indistinguishable. It also means
-"what did we discuss in that session" has almost nothing to match on.
-
-One implementation, called by both tools, so the read path and the write path
-cannot disagree about which session they are in.
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-
-logger = logging.getLogger(__name__)
-
-__all__ = ["resolve_session_id", "SESSION_ENV_VARS"]
-
-#: Checked in order. Hosts set one or the other; SLM's own takes precedence so a
-#: user can override a host that sets its variable to something unhelpful.
-#: ``CLAUDE_CODE_SESSION_ID`` is the actual variable Claude Code's MCP
-#: subprocess environment carries — verified on a live daemon 2026-08-24,
-#: this pipeline settled 6013/6039 outcomes at the neutral 0.5 fallback
-#: because the old two-name list never matched it, and every recall fell
-#: through to the synthetic ``mcp:<agent_id>`` id that step 4 deliberately
-#: excludes from matching.
-SESSION_ENV_VARS = ("SLM_SESSION_ID", "CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")
-
-
-def resolve_session_id(
-    explicit: str = "",
-    *,
-    agent_id: str = "unknown",
-    allow_agent_fallback: bool = True,
-) -> str:
-    """Best available session id for this call. Never raises.
-
-    Order, most to least specific:
-
-      1. ``explicit`` — what the caller passed. Always wins.
-      2. ``SLM_SESSION_ID`` / ``CLAUDE_SESSION_ID`` from the environment.
-      3. The hook registry: the session whose parent process is ours, else the
-         most recently active one inside 60 seconds. Parent-PID lookup is
-         collision-free across parallel host sessions, because each MCP
-         server's parent is the editor that spawned it.
-      4. ``mcp:<agent_id>`` — stable per agent, and deliberately NOT matched by
-         the Stop hook, so the reaper settles those outcomes at a neutral 0.5
-         rather than crediting or blaming a session that never existed.
-
-    ``allow_agent_fallback=False`` stops before step 4 and returns "". Use it
-    where a synthetic id would be worse than none: grouping memories under
-    ``mcp:<agent>`` would put every memory an agent ever wrote into one bucket
-    and make session-diversity promotion rank them as a single session, which
-    is the opposite of what it is for.
-    """
-    if explicit and explicit.strip():
-        return explicit.strip()
-
-    for name in SESSION_ENV_VARS:
-        value = os.environ.get(name)
-        if value and value.strip():
-            return value.strip()
-
-    try:
-        from superlocalmemory.hooks.session_registry import (
-            lookup_by_parent,
-            most_recent_active,
-        )
-
-        found = (
-            lookup_by_parent(within_seconds=60)
-            or most_recent_active(agent_type="claude", within_seconds=60)
-            or ""
-        )
-        if found:
-            return found
-    except Exception as exc:  # noqa: BLE001 — a hint must never fail a call
-        logger.debug("session registry lookup unavailable: %s", exc)
-
-    if allow_agent_fallback:
-        return f"mcp:{agent_id}"
-    return ""

package/src/superlocalmemory/mcp/shared.py

@@ -1,112 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3
-
-"""Shared MCP utilities — single source of truth for helpers used
-across tools_core, tools_active, tools_v28, tools_v3, tools_v33.
-
-V3.3.12: Extracted _emit_event to eliminate code duplication.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-from superlocalmemory.infra.data_root import state_path
-
-
-def emit_event(event_type: str, payload: dict | None = None,
-               source_agent: str = "mcp_client") -> None:
-    """Emit an event to the EventBus (best-effort, never raises)."""
-    try:
-        from superlocalmemory.infra.event_bus import EventBus
-        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.
-
-    Phase 1: Routes through the admission registry so enterprise policy applies
-    even when the caller has local trust (trust-hook alone cannot bypass registry).
-    AdmissionDenied propagates to the caller; personal OWNER is always admitted.
-    """
-    if operation not in {"update", "delete"}:
-        raise ValueError("MCP mutations must use update or delete policy")
-
-    from superlocalmemory.core.actor_context import Transport
-    from superlocalmemory.core.admission import (
-        AdmissionDenied,
-        _resolve_deployment,
-        admit,
-        resolve_actor,
-    )
-    from superlocalmemory.core.engine_ingestion import local_trusted_actor_id
-    from superlocalmemory.core.operation_request import OperationKind
-    from superlocalmemory.mcp.agent_context import get_current_agent_id
-
-    deployment = _resolve_deployment()
-    tier = "enterprise" if deployment.is_enterprise else "personal"
-    mode = "company" if deployment.is_enterprise else "local"
-    actor = resolve_actor(Transport.MCP, tier=tier, mode=mode)
-    kind = OperationKind.FORGET if operation == "delete" else OperationKind.CORRECT
-    admit(kind, actor, mode=mode)  # raises AdmissionDenied on deny
-
-    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",
-]