superlocalmemory 3.4.1 → 3.4.4

package/src/superlocalmemory/mcp/tools_mesh.py

@@ -0,0 +1,249 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the Elastic License 2.0 - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SLM Mesh MCP Tools — P2P agent communication via the unified daemon.
+
+v3.4.4: These tools ship WITH SuperLocalMemory, no separate slm-mesh install needed.
+End users get full mesh functionality from `pip install superlocalmemory`.
+
+All tools communicate with the daemon's Python mesh broker on port 8765.
+Auto-heartbeat keeps the session alive as long as the MCP server is running.
+
+8 tools: mesh_summary, mesh_peers, mesh_send, mesh_inbox,
+         mesh_state, mesh_lock, mesh_events, mesh_status
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+# Unique peer ID for this MCP server session
+_PEER_ID = str(uuid.uuid4())[:12]
+_SESSION_SUMMARY = ""
+_HEARTBEAT_INTERVAL = 25  # seconds (broker marks stale at 30s, dead at 60s)
+_HEARTBEAT_THREAD: threading.Thread | None = None
+_REGISTERED = False
+
+
+def _daemon_url() -> str:
+    """Get the daemon base URL."""
+    port = 8765
+    try:
+        port_file = os.path.join(os.path.expanduser("~"), ".superlocalmemory", "daemon.port")
+        if os.path.exists(port_file):
+            port = int(open(port_file).read().strip())
+    except Exception:
+        pass
+    return f"http://127.0.0.1:{port}"
+
+
+def _mesh_request(method: str, path: str, body: dict | None = None) -> dict | None:
+    """Send request to daemon mesh broker."""
+    import urllib.request
+    url = f"{_daemon_url()}/mesh{path}"
+    try:
+        data = json.dumps(body).encode() if body else None
+        headers = {"Content-Type": "application/json"} if data else {}
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        resp = urllib.request.urlopen(req, timeout=10)
+        return json.loads(resp.read().decode())
+    except Exception as exc:
+        logger.debug("Mesh request failed: %s %s — %s", method, path, exc)
+        return None
+
+
+def _ensure_registered() -> None:
+    """Register this session with the mesh broker if not already."""
+    global _REGISTERED
+    if _REGISTERED:
+        return
+
+    result = _mesh_request("POST", "/register", {
+        "peer_id": _PEER_ID,
+        "session_id": os.environ.get("CLAUDE_SESSION_ID", _PEER_ID),
+        "summary": _SESSION_SUMMARY or "SLM MCP session",
+    })
+    if result:
+        _REGISTERED = True
+        _start_heartbeat()
+
+
+def _start_heartbeat() -> None:
+    """Background thread that sends heartbeat to keep session alive."""
+    global _HEARTBEAT_THREAD
+    if _HEARTBEAT_THREAD is not None:
+        return
+
+    def heartbeat_loop():
+        while True:
+            time.sleep(_HEARTBEAT_INTERVAL)
+            try:
+                _mesh_request("POST", "/heartbeat", {"peer_id": _PEER_ID})
+            except Exception:
+                pass
+
+    _HEARTBEAT_THREAD = threading.Thread(target=heartbeat_loop, daemon=True, name="mesh-heartbeat")
+    _HEARTBEAT_THREAD.start()
+    logger.info("Mesh heartbeat started (peer_id=%s, interval=%ds)", _PEER_ID, _HEARTBEAT_INTERVAL)
+
+
+def register_mesh_tools(server, get_engine: Callable) -> None:
+    """Register all 8 mesh MCP tools."""
+
+    @server.tool()
+    async def mesh_summary(summary: str = "") -> dict:
+        """Register this session and describe what you're working on.
+
+        Call this at the start of every session. Other agents can see your summary
+        and send you messages. The session stays alive via automatic heartbeat.
+
+        Args:
+            summary: What this session is working on (e.g. "Fixing auth bug in api.py")
+        """
+        global _SESSION_SUMMARY
+        _SESSION_SUMMARY = summary or "Active session"
+
+        _ensure_registered()
+
+        # Update summary
+        result = _mesh_request("POST", "/summary", {
+            "peer_id": _PEER_ID,
+            "summary": _SESSION_SUMMARY,
+        })
+
+        return {
+            "peer_id": _PEER_ID,
+            "summary": _SESSION_SUMMARY,
+            "registered": True,
+            "heartbeat_active": _HEARTBEAT_THREAD is not None,
+            "broker_response": result,
+        }
+
+    @server.tool()
+    async def mesh_peers() -> dict:
+        """List all active peer sessions on this machine.
+
+        Shows other Claude Code, Cursor, or AI agent sessions that are
+        connected to the same SLM mesh network.
+        """
+        _ensure_registered()
+        result = _mesh_request("GET", "/peers")
+        peers = (result or {}).get("peers", [])
+        return {
+            "peers": peers,
+            "count": len(peers),
+            "my_peer_id": _PEER_ID,
+        }
+
+    @server.tool()
+    async def mesh_send(to: str, message: str) -> dict:
+        """Send a message to another peer session.
+
+        Args:
+            to: The peer_id of the recipient (from mesh_peers)
+            message: The message content to send
+        """
+        _ensure_registered()
+        result = _mesh_request("POST", "/send", {
+            "from_peer": _PEER_ID,
+            "to_peer": to,
+            "content": message,
+        })
+        return result or {"error": "Failed to send message"}
+
+    @server.tool()
+    async def mesh_inbox() -> dict:
+        """Read messages sent to this session.
+
+        Returns unread messages from other peer sessions.
+        Messages are marked as read after retrieval.
+        """
+        _ensure_registered()
+        messages = _mesh_request("GET", f"/inbox/{_PEER_ID}")
+        if messages:
+            # Mark as read
+            _mesh_request("POST", f"/inbox/{_PEER_ID}/read")
+        return messages or {"messages": [], "count": 0}
+
+    @server.tool()
+    async def mesh_state(key: str = "", value: str = "", action: str = "get") -> dict:
+        """Get or set shared state across all sessions.
+
+        Shared state is visible to all peers. Use for coordinating work:
+        server IPs, API keys, feature flags, task assignments.
+
+        Args:
+            key: State key name
+            value: Value to set (only for action="set")
+            action: "get" (read all or one key), "set" (write a key)
+        """
+        _ensure_registered()
+
+        if action == "set" and key:
+            result = _mesh_request("POST", "/state", {
+                "key": key,
+                "value": value,
+                "set_by": _PEER_ID,
+            })
+            return result or {"error": "Failed to set state"}
+
+        if key:
+            result = _mesh_request("GET", f"/state/{key}")
+            return result or {"key": key, "value": None}
+
+        result = _mesh_request("GET", "/state")
+        return result or {"state": {}}
+
+    @server.tool()
+    async def mesh_lock(
+        file_path: str,
+        action: str = "query",
+    ) -> dict:
+        """Manage file locks across sessions.
+
+        Before editing a shared file, check if another session has it locked.
+
+        Args:
+            file_path: Path to the file
+            action: "query" (check lock), "acquire" (lock file), "release" (unlock)
+        """
+        _ensure_registered()
+        result = _mesh_request("POST", "/lock", {
+            "file_path": file_path,
+            "action": action,
+            "locked_by": _PEER_ID,
+        })
+        return result or {"error": "Lock operation failed"}
+
+    @server.tool()
+    async def mesh_events() -> dict:
+        """Get recent mesh events (peer joins, leaves, messages, state changes).
+
+        Shows the activity log of the mesh network.
+        """
+        result = _mesh_request("GET", "/events")
+        return result or {"events": []}
+
+    @server.tool()
+    async def mesh_status() -> dict:
+        """Get mesh broker health and statistics.
+
+        Shows broker uptime, peer count, and connection status.
+        """
+        result = _mesh_request("GET", "/status")
+        if result:
+            result["my_peer_id"] = _PEER_ID
+            result["heartbeat_active"] = _HEARTBEAT_THREAD is not None
+        return result or {
+            "broker_up": False,
+            "error": "Cannot reach mesh broker. Is the daemon running? (slm serve start)",
+        }

package/src/superlocalmemory/mesh/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the Elastic License 2.0 - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SLM Mesh — Python port of the P2P agent communication broker.
+
+Provides peer registry, message relay, shared state, file locks, and event logging
+for multi-agent coordination. Runs as FastAPI sub-routes inside the unified daemon.
+
+Independent broker — same wire protocol as standalone slm-mesh npm package,
+but separate SQLite tables with mesh_ prefix.
+"""

package/src/superlocalmemory/mesh/broker.py

@@ -0,0 +1,344 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the Elastic License 2.0 - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SLM Mesh Broker — core orchestration for P2P agent communication.
+
+Manages peer lifecycle, scheduled cleanup, and event logging.
+All operations use the shared memory.db via SQLite tables with mesh_ prefix.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger("superlocalmemory.mesh")
+
+
+class MeshBroker:
+    """Lightweight mesh broker for SLM's unified daemon.
+
+    Provides peer management, messaging, state, locks, and events.
+    All methods are synchronous (called from FastAPI via run_in_executor
+    or directly for quick operations).
+    """
+
+    def __init__(self, db_path: str | Path):
+        self._db_path = str(db_path)
+        self._started_at = time.monotonic()
+        self._cleanup_thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+
+    def start_cleanup(self) -> None:
+        """Start background cleanup thread for stale peers/messages."""
+        self._cleanup_thread = threading.Thread(
+            target=self._cleanup_loop, daemon=True, name="mesh-cleanup",
+        )
+        self._cleanup_thread.start()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+
+    # -- Connection helper --
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # -- Peers --
+
+    def register_peer(self, session_id: str, summary: str = "",
+                      host: str = "127.0.0.1", port: int = 0) -> dict:
+        conn = self._conn()
+        try:
+            now = datetime.now(timezone.utc).isoformat()
+            # Idempotent: update if same session_id exists
+            existing = conn.execute(
+                "SELECT peer_id FROM mesh_peers WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            if existing:
+                peer_id = existing["peer_id"]
+                conn.execute(
+                    "UPDATE mesh_peers SET summary=?, host=?, port=?, last_heartbeat=?, status='active' "
+                    "WHERE peer_id=?",
+                    (summary, host, port, now, peer_id),
+                )
+            else:
+                peer_id = str(uuid.uuid4())[:12]
+                conn.execute(
+                    "INSERT INTO mesh_peers (peer_id, session_id, summary, status, host, port, registered_at, last_heartbeat) "
+                    "VALUES (?, ?, ?, 'active', ?, ?, ?, ?)",
+                    (peer_id, session_id, summary, host, port, now, now),
+                )
+            self._log_event(conn, "peer_registered", peer_id, {"session_id": session_id})
+            conn.commit()
+            return {"peer_id": peer_id, "ok": True}
+        finally:
+            conn.close()
+
+    def deregister_peer(self, peer_id: str) -> dict:
+        conn = self._conn()
+        try:
+            row = conn.execute("SELECT 1 FROM mesh_peers WHERE peer_id=?", (peer_id,)).fetchone()
+            if not row:
+                return {"ok": False, "error": "peer not found"}
+            conn.execute("DELETE FROM mesh_peers WHERE peer_id=?", (peer_id,))
+            self._log_event(conn, "peer_deregistered", peer_id)
+            conn.commit()
+            return {"ok": True}
+        finally:
+            conn.close()
+
+    def heartbeat(self, peer_id: str) -> dict:
+        conn = self._conn()
+        try:
+            now = datetime.now(timezone.utc).isoformat()
+            cursor = conn.execute(
+                "UPDATE mesh_peers SET last_heartbeat=?, status='active' WHERE peer_id=?",
+                (now, peer_id),
+            )
+            if cursor.rowcount == 0:
+                return {"ok": False, "error": "peer not found"}
+            conn.commit()
+            return {"ok": True}
+        finally:
+            conn.close()
+
+    def update_summary(self, peer_id: str, summary: str) -> dict:
+        conn = self._conn()
+        try:
+            cursor = conn.execute(
+                "UPDATE mesh_peers SET summary=? WHERE peer_id=?",
+                (summary, peer_id),
+            )
+            if cursor.rowcount == 0:
+                return {"ok": False, "error": "peer not found"}
+            conn.commit()
+            return {"ok": True}
+        finally:
+            conn.close()
+
+    def list_peers(self) -> list[dict]:
+        conn = self._conn()
+        try:
+            rows = conn.execute(
+                "SELECT peer_id, session_id, summary, status, host, port, registered_at, last_heartbeat "
+                "FROM mesh_peers ORDER BY last_heartbeat DESC",
+            ).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
+    # -- Messages --
+
+    def send_message(self, from_peer: str, to_peer: str, content: str,
+                     msg_type: str = "text") -> dict:
+        conn = self._conn()
+        try:
+            # Verify recipient exists
+            if not conn.execute("SELECT 1 FROM mesh_peers WHERE peer_id=?", (to_peer,)).fetchone():
+                return {"ok": False, "error": "recipient peer not found"}
+            now = datetime.now(timezone.utc).isoformat()
+            cursor = conn.execute(
+                "INSERT INTO mesh_messages (from_peer, to_peer, msg_type, content, read, created_at) "
+                "VALUES (?, ?, ?, ?, 0, ?)",
+                (from_peer, to_peer, msg_type, content, now),
+            )
+            self._log_event(conn, "message_sent", from_peer, {"to": to_peer})
+            conn.commit()
+            return {"ok": True, "id": cursor.lastrowid}
+        finally:
+            conn.close()
+
+    def get_inbox(self, peer_id: str) -> list[dict]:
+        conn = self._conn()
+        try:
+            rows = conn.execute(
+                "SELECT id, from_peer, to_peer, msg_type, content, read, created_at "
+                "FROM mesh_messages WHERE to_peer=? ORDER BY created_at DESC LIMIT 100",
+                (peer_id,),
+            ).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
+    def mark_read(self, peer_id: str, message_ids: list[int]) -> dict:
+        conn = self._conn()
+        try:
+            placeholders = ",".join("?" * len(message_ids))
+            conn.execute(
+                f"UPDATE mesh_messages SET read=1 WHERE to_peer=? AND id IN ({placeholders})",
+                [peer_id, *message_ids],
+            )
+            conn.commit()
+            return {"ok": True}
+        finally:
+            conn.close()
+
+    # -- State --
+
+    def get_state(self) -> dict:
+        conn = self._conn()
+        try:
+            rows = conn.execute("SELECT key, value, set_by, updated_at FROM mesh_state").fetchall()
+            return {r["key"]: {"value": r["value"], "set_by": r["set_by"], "updated_at": r["updated_at"]} for r in rows}
+        finally:
+            conn.close()
+
+    def set_state(self, key: str, value: str, set_by: str) -> dict:
+        conn = self._conn()
+        try:
+            now = datetime.now(timezone.utc).isoformat()
+            conn.execute(
+                "INSERT INTO mesh_state (key, value, set_by, updated_at) VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value, set_by=excluded.set_by, updated_at=excluded.updated_at",
+                (key, value, set_by, now),
+            )
+            conn.commit()
+            return {"ok": True}
+        finally:
+            conn.close()
+
+    def get_state_key(self, key: str) -> dict | None:
+        conn = self._conn()
+        try:
+            row = conn.execute(
+                "SELECT key, value, set_by, updated_at FROM mesh_state WHERE key=?", (key,),
+            ).fetchone()
+            return dict(row) if row else None
+        finally:
+            conn.close()
+
+    # -- Locks --
+
+    def lock_action(self, file_path: str, locked_by: str, action: str) -> dict:
+        conn = self._conn()
+        try:
+            now = datetime.now(timezone.utc).isoformat()
+
+            if action == "acquire":
+                existing = conn.execute(
+                    "SELECT locked_by, locked_at FROM mesh_locks WHERE file_path=?",
+                    (file_path,),
+                ).fetchone()
+                if existing and existing["locked_by"] != locked_by:
+                    return {"locked": True, "by": existing["locked_by"], "since": existing["locked_at"]}
+                conn.execute(
+                    "INSERT INTO mesh_locks (file_path, locked_by, locked_at) VALUES (?, ?, ?) "
+                    "ON CONFLICT(file_path) DO UPDATE SET locked_by=excluded.locked_by, locked_at=excluded.locked_at",
+                    (file_path, locked_by, now),
+                )
+                conn.commit()
+                return {"ok": True, "action": "acquired"}
+
+            elif action == "release":
+                conn.execute("DELETE FROM mesh_locks WHERE file_path=? AND locked_by=?",
+                             (file_path, locked_by))
+                conn.commit()
+                return {"ok": True, "action": "released"}
+
+            elif action == "query":
+                row = conn.execute(
+                    "SELECT locked_by, locked_at FROM mesh_locks WHERE file_path=?",
+                    (file_path,),
+                ).fetchone()
+                if row:
+                    return {"locked": True, "by": row["locked_by"], "since": row["locked_at"]}
+                return {"locked": False}
+
+            return {"ok": False, "error": f"unknown action: {action}"}
+        finally:
+            conn.close()
+
+    # -- Events --
+
+    def get_events(self, limit: int = 100) -> list[dict]:
+        conn = self._conn()
+        try:
+            rows = conn.execute(
+                "SELECT id, event_type, payload, emitted_by, created_at "
+                "FROM mesh_events ORDER BY id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
+    def _log_event(self, conn: sqlite3.Connection, event_type: str,
+                   emitted_by: str, payload: dict | None = None) -> None:
+        import json as _json
+        now = datetime.now(timezone.utc).isoformat()
+        conn.execute(
+            "INSERT INTO mesh_events (event_type, payload, emitted_by, created_at) VALUES (?, ?, ?, ?)",
+            (event_type, _json.dumps(payload or {}), emitted_by, now),
+        )
+
+    # -- Status --
+
+    def get_status(self) -> dict:
+        conn = self._conn()
+        try:
+            peer_count = conn.execute("SELECT COUNT(*) FROM mesh_peers WHERE status='active'").fetchone()[0]
+            return {
+                "broker_up": True,
+                "peer_count": peer_count,
+                "uptime_s": round(time.monotonic() - self._started_at),
+            }
+        finally:
+            conn.close()
+
+    # -- Cleanup --
+
+    def _cleanup_loop(self) -> None:
+        """Background cleanup: mark stale peers, delete old messages."""
+        while not self._stop_event.is_set():
+            self._stop_event.wait(300)  # Every 5 min
+            if self._stop_event.is_set():
+                break
+            try:
+                self._run_cleanup()
+            except Exception as exc:
+                logger.debug("Mesh cleanup error: %s", exc)
+
+    def _run_cleanup(self) -> None:
+        conn = self._conn()
+        try:
+            now = datetime.now(timezone.utc)
+            # Mark stale peers (no heartbeat for 5 min)
+            conn.execute(
+                "UPDATE mesh_peers SET status='stale' "
+                "WHERE status='active' AND datetime(last_heartbeat) < datetime(?, '-5 minutes')",
+                (now.isoformat(),),
+            )
+            # Delete dead peers (stale > 30 min)
+            conn.execute(
+                "UPDATE mesh_peers SET status='dead' "
+                "WHERE status='stale' AND datetime(last_heartbeat) < datetime(?, '-30 minutes')",
+                (now.isoformat(),),
+            )
+            conn.execute("DELETE FROM mesh_peers WHERE status='dead'")
+            # Delete read messages > 24hr old
+            conn.execute(
+                "DELETE FROM mesh_messages WHERE read=1 AND datetime(created_at) < datetime(?, '-24 hours')",
+                (now.isoformat(),),
+            )
+            # Delete expired locks
+            conn.execute(
+                "DELETE FROM mesh_locks WHERE datetime(expires_at) < datetime(?)",
+                (now.isoformat(),),
+            )
+            conn.commit()
+        finally:
+            conn.close()

package/src/superlocalmemory/retrieval/entity_channel.py

@@ -282,12 +282,18 @@ class EntityGraphChannel:
                 if use_cache:
                     neighbors = self._adj.get(fid, ())
                     for neighbor, edge_weight in neighbors:
-                        # v3.4.1 P1: Weighted propagation + PageRank bias
-                        weighted = activation[fid] * self._decay * edge_weight
-                        if self._graph_metrics and neighbor in self._graph_metrics:
-                            target_pr = self._graph_metrics[neighbor].get("pagerank_score", 0.0)
-                            pr_boost = min(1.0 + target_pr * 2.0, 2.0)
-                            weighted *= pr_boost
+                        # v3.4.2: Only apply edge_weight and PageRank bias when
+                        # graph metrics are available. Without metrics, edge_weight
+                        # dampens propagation by ~14% with no compensating boost,
+                        # causing retrieval regression (68.4% vs 70.4% on LoCoMo).
+                        if self._graph_metrics:
+                            weighted = activation[fid] * self._decay * edge_weight
+                            if neighbor in self._graph_metrics:
+                                target_pr = self._graph_metrics[neighbor].get("pagerank_score", 0.0)
+                                pr_boost = min(1.0 + target_pr * 2.0, 2.0)
+                                weighted *= pr_boost
+                        else:
+                            weighted = activation[fid] * self._decay
                         if weighted >= self._threshold and weighted > activation.get(neighbor, 0.0):
                             activation[neighbor] = weighted
                             next_frontier.add(neighbor)

package/src/superlocalmemory/server/api.py

@@ -236,16 +236,15 @@ def create_app() -> FastAPI:
     return application
 
 
-app = create_app()
-
-
-# ============================================================================
-# Server Startup
-# ============================================================================
+# v3.4.3: Module-level app removed to prevent duplicate MemoryEngine.
+# The unified daemon (server/unified_daemon.py) imports routes from this
+# module via _register_dashboard_routes(). Do NOT create app here.
+# For standalone use: python -m superlocalmemory.server.api
 
 if __name__ == "__main__":
+    app = create_app()
     print("=" * 60)
-    print("SuperLocalMemory V3 - API Server")
+    print("SuperLocalMemory V3 - API Server (standalone mode)")
     print("=" * 60)
     print(f"Database: {DB_PATH}")
     print(f"UI Directory: {UI_DIR}")