superlocalmemory 3.4.45 → 3.4.48

package/CHANGELOG.md

@@ -5,7 +5,67 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-### [Unreleased]
+## [3.4.48] - 2026-05-21
+
+**Multi-Machine Mesh Coordination — M4 & M5 now work as one.**
+
+### Added
+- **`RemoteSyncClient` — cross-machine peer sync** (NEW in v3.4.48)
+  - HTTP-based sync with remote SLM instances
+  - Populates `broker._remote_peers` from remote `/mesh/peers` endpoint every 30s
+  - Environment variables:
+    - `SLM_MESH_PEER_URL`: Full URL of remote SLM (e.g. `http://192.168.1.100:8765`)
+    - `SLM_MESH_SHARED_SECRET`: Shared auth secret (required for remote mode)
+    - `SLM_MESH_DISCOVERY`: `'on'` (default) or `'off'` for mDNS discovery
+  - **mDNS discovery (optional)**: Auto-discovers remote SLM on LAN via `_slm-mesh._tcp` service
+  - **Message proxying**: `broker.send_message()` now proxies direct messages to remote peers
+  - **Graceful fallback**: Network errors logged but don't crash; optional `zeroconf` dependency
+  - Uses `httpx` (already in core deps) + `zeroconf>=0.140` (new, pure Python, cross-platform)
+
+- **Auth guard on `/mesh/peers`** — Remote queries must include `Authorization: Bearer {SLM_MESH_SHARED_SECRET}`
+
+### Changed
+- `MeshBroker` now instantiates `RemoteSyncClient` when `SLM_MESH_PEER_URL` is set or in remote mode
+- `broker.send_message()` checks `to_peer in broker._remote_peers` before DB lookup
+  - If remote, proxies via `sync_client.send_to_remote()`
+  - If local or not found, uses existing DB logic
+- `broker.list_all_peers()` returns local + remote peers merged
+
+### Tests
+- 13 new tests in `tests/integration/test_remote_sync.py`
+  - Init, peer sync, stale peer removal, send proxy, error handling
+  - mDNS discovery callback stubs
+  - Integration: broker routes sends to remote peers
+
+All existing tests pass. No breaking changes.
+
+---
+
+## [3.4.46] - 2026-05-18
+
+### Added
+- **`SLM_MCP_TOOLS` env var** — Fine-grained MCP tool allowlist. Users can now
+  set `SLM_MCP_TOOLS=remember,recall,search,session_init` to expose exactly
+  the tools they need, reducing MCP context budget. Falls back to 25-tool
+  essential set when unset; `SLM_MCP_ALL_TOOLS=1` still wins for power users.
+- **`KMP_DUPLICATE_LIB_OK=TRUE`** — Set at package init to prevent OpenMP
+  multi-library crashes when PyTorch, ONNX Runtime, and NumPy-MKL all load
+  their own runtimes simultaneously.
+
+### Fixed
+- **WAL busy_timeout ordering** (PR #24, @kenyonxu) — `_enable_wal()` now
+  sets `busy_timeout` before `journal_mode=WAL`, ensuring the 10s configured
+  timeout is used instead of SQLite's default 5s during WAL initialization.
+- **Engine init traceback logging** (PR #25, @kenyonxu) — `logger.exception()`
+  replaces `logger.warning()` on daemon engine init failure, capturing the
+  full traceback for root-cause diagnosis.
+- **MCP `fast` recall wiring** (PR #22, @VikingOwl91) — `fast=True` recall
+  parameter now threads through the full MCP→daemon→worker stack.
+  `session_init` performs one `pool_recall(fast=True)` instead of two
+  redundant recalls. Tools switch from `WorkerPool.shared()` to `choose_pool()`
+  for daemon-first routing (avoids N×1.6 GB ONNX duplication across IDEs).
+- **FTS trigger idempotency** — `CREATE TRIGGER IF NOT EXISTS` prevents race
+  crashes on repeated schema init.
 
 ---
 

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">SuperLocalMemory V3.4</h1>
 <p align="center"><strong>Every other AI forgets. Yours won't.</strong><br/><em>Infinite memory for Claude Code, Cursor, Windsurf, and any MCP-compatible AI client.</em></p>
-<p align="center"><code>v3.4.25</code> — Install once. Every session remembers the last. Automatically.</p>
+<p align="center"><code>v3.4.48</code> — Install once. Every session remembers the last. Automatically.<br><strong>Now with multi-machine agent mesh — M4 and M5 coordinate as one.</strong></p>
 <p align="center"><strong>Backed by 3 published research papers</strong> (arXiv preprints + Zenodo-archived) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 
 <p align="center">
@@ -416,6 +416,67 @@ Auto-capture hooks: `slm hooks install` + `slm observe` + `slm session-context`.
 
 ---
 
+## Multi-Machine Mesh Coordination (New in v3.4.48)
+
+Run SLM on multiple machines (M4 + M5) and have your agents coordinate as one team without any disruption.
+
+### Setup
+
+**M4 (broker):**
+```bash
+export SLM_MESH_HOST=192.168.1.100
+export SLM_MESH_SHARED_SECRET=my-secret-key
+slm init  # Starts SLM at http://192.168.1.100:8765
+```
+
+**M5 (client):**
+```bash
+export SLM_MESH_PEER_URL=http://192.168.1.100:8765
+export SLM_MESH_SHARED_SECRET=my-secret-key
+slm init  # Syncs M4's agents every 30s, proxies messages to M4
+```
+
+### How It Works
+
+- **HTTP-based sync** — M5 queries M4's `/mesh/peers` endpoint every 30 seconds
+- **Message proxying** — When M5's agent sends a message to an M4 agent, it's routed automatically
+- **mDNS discovery (optional)** — M5 can auto-discover M4 on the LAN via `_slm-mesh._tcp` (enable with `SLM_MESH_DISCOVERY=on`, default)
+- **Graceful fallback** — Network errors logged but don't crash; offline agents queue messages for delivery
+- **Shared secret** — `SLM_MESH_SHARED_SECRET` gates remote peer discovery (required for remote mode)
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|:---------|:--------|:--------|
+| `SLM_MESH_HOST` | `127.0.0.1` | Host this SLM listens on (set to IP for remote) |
+| `SLM_MESH_PEER_URL` | unset | Full URL of remote SLM (e.g., `http://192.168.1.100:8765`) |
+| `SLM_MESH_SHARED_SECRET` | unset | Auth secret (required when remote) |
+| `SLM_MESH_DISCOVERY` | `on` | mDNS discovery (`on`/`off`) |
+| `SLM_MESH_WS_PORT` | `7900` | WebSocket port for mesh (internal use) |
+
+### Dependencies
+
+- `zeroconf>=0.140` (new in v3.4.48, optional, pure Python, auto-installed)
+- `httpx==0.28.1` (already in core deps)
+- No Docker. No external broker. Works on WiFi + LAN.
+
+### MCP Tools
+
+All 8 mesh tools work seamlessly across machines:
+
+| Tool | Description |
+|:-----|:------------|
+| `mesh_peers` | List local + remote peers merged |
+| `mesh_send` | Send message to any peer (local or remote) |
+| `mesh_broadcast` | Send to all agents (across machines) |
+| `mesh_project` | Send to all agents in a project (across machines) |
+| `mesh_inbox` | Get messages for this agent |
+| `mesh_pending` | Get offline messages (broadcast/project) |
+| `mesh_state` | Get/set shared state (replicated) |
+| `mesh_lock` | Acquire/release distributed file locks |
+
+---
+
 ## Features
 
 ### Retrieval

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.45",
+  "version": "3.4.48",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.4.45"
+version = "3.4.48"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}
@@ -45,6 +45,7 @@ dependencies = [
     "fastapi[all]==0.136.1",
     "uvicorn==0.46.0",
     "websockets==16.0",
+    "zeroconf>=0.140",
     "lightgbm==4.6.0",
     "orjson==3.11.9",
     "tree-sitter==0.25.2",

package/src/superlocalmemory/__init__.py

@@ -1,6 +1,9 @@
 """SuperLocalMemory — information-geometric agent memory."""
 
-__version__ = "3.4.45"
+import os
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+__version__ = "3.4.46"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",
@@ -26,4 +29,12 @@ def _check_critical_deps() -> None:
             pass
 
 
-_check_critical_deps()
+# Only run the dep check when a full (non-LIGHT) engine is in use.
+# The MCP server runs in LIGHT mode — importing onnxruntime here
+# breaks the LIGHT engine contract (ONNX_LOADED must stay False).
+# Skip when SLM_SKIP_DEP_CHECK=1 or SLM_DISABLE_WARMUP_SIDE_EFFECTS=1.
+if not (
+    os.environ.get("SLM_SKIP_DEP_CHECK") == "1"
+    or os.environ.get("SLM_DISABLE_WARMUP_SIDE_EFFECTS") == "1"
+):
+    _check_critical_deps()

package/src/superlocalmemory/core/recall_worker.py

@@ -59,10 +59,12 @@ def _get_engine():
     return _engine
 
 
-def _handle_recall(query: str, limit: int, session_id: str = "") -> dict:
+def _handle_recall(
+    query: str, limit: int, session_id: str = "", fast: bool = False,
+) -> dict:
     engine = _get_engine()
     response = engine.recall(
-        query, limit=limit, session_id=session_id or None,
+        query, limit=limit, session_id=session_id or None, fast=bool(fast),
     )
 
     # Batch-fetch original memory text for all results
@@ -290,7 +292,7 @@ def _worker_main() -> None:
             if cmd == "recall":
                 result = _handle_recall(
                     req.get("query", ""), req.get("limit", 10),
-                    req.get("session_id", ""),
+                    req.get("session_id", ""), bool(req.get("fast", False)),
                 )
                 _respond(result)
             elif cmd == "store":

package/src/superlocalmemory/core/worker_pool.py

@@ -67,6 +67,7 @@ class WorkerPool:
 
     def recall(
         self, query: str, limit: int = 10, session_id: str = "",
+        fast: bool = False,
     ) -> dict:
         """Run recall in worker subprocess. Returns result dict.
 
@@ -77,7 +78,7 @@ class WorkerPool:
         """
         return self._send({
             "cmd": "recall", "query": query, "limit": limit,
-            "session_id": session_id or "",
+            "session_id": session_id or "", "fast": bool(fast),
         })
 
     def store(self, content: str, metadata: dict | None = None) -> dict:

package/src/superlocalmemory/llm/backbone.py

@@ -273,6 +273,10 @@ class LLMBackbone:
         headers = {
             "x-api-key": self._api_key,
             "anthropic-version": _ANTHROPIC_API_VERSION,
+            # Enable prompt caching — system prompt cached as ephemeral block.
+            # Requires ≥1024 tokens in the cached block to activate.
+            # Savings: ~90% cost reduction on cached input tokens.
+            "anthropic-beta": "prompt-caching-2024-07-31",
             "Content-Type": "application/json",
         }
         payload: dict[str, Any] = {
@@ -282,7 +286,14 @@ class LLMBackbone:
             "messages": [{"role": "user", "content": prompt}],
         }
         if system:
-            payload["system"] = system
+            # Structured block with cache_control — plain string disables caching.
+            payload["system"] = [
+                {
+                    "type": "text",
+                    "text": system,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ]
         return _ANTHROPIC_URL, headers, payload
 
     def _build_azure(

package/src/superlocalmemory/mcp/_daemon_proxy.py

@@ -45,10 +45,14 @@ class DaemonPoolProxy:
 
     def recall(
         self, query: str, limit: int = 10, session_id: str = "",
+        fast: bool = False,
     ) -> dict[str, Any]:
-        params = urllib.parse.urlencode(
-            {"q": query, "limit": limit, "session_id": session_id or ""}
-        )
+        params = urllib.parse.urlencode({
+            "q": query,
+            "limit": limit,
+            "session_id": session_id or "",
+            "fast": "true" if fast else "false",
+        })
         try:
             with urllib.request.urlopen(
                 self._url(f"/recall?{params}"), timeout=self._timeout,

package/src/superlocalmemory/mcp/_pool_adapter.py

@@ -74,12 +74,17 @@ def _unwrap_error(raw: Any, op: str) -> None:
         raise PoolError(f"pool.{op} failed: {reason}")
 
 
-def pool_recall(query: str, limit: int = 10, **_: Any) -> PoolRecallResponse:
+def pool_recall(query: str, limit: int = 10, **kwargs: Any) -> PoolRecallResponse:
     """Call pool.recall and reshape its dict into a typed response.
 
     Raises :class:`PoolError` on worker death or any non-ok envelope.
     """
-    raw = _pool().recall(query=query, limit=limit)
+    raw = _pool().recall(
+        query=query,
+        limit=limit,
+        session_id=str(kwargs.get("session_id") or ""),
+        fast=bool(kwargs.get("fast", False)),
+    )
     _unwrap_error(raw, "recall")
     items = raw.get("results", []) if isinstance(raw, dict) else []
     results = [

package/src/superlocalmemory/mcp/server.py

@@ -19,6 +19,10 @@ _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
@@ -122,13 +126,21 @@ _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()
+
 
 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).
+    all tools are registered (bypass filter). When SLM_MCP_TOOLS is set,
+    that user allowlist is used instead of _ESSENTIAL_TOOLS.
     """
     __slots__ = ("_server", "_allowed")
 
@@ -147,8 +159,14 @@ class _FilteredServer:
         return getattr(self._server, name)
 
 
-# Choose full or filtered registration target
-_target = server if _all_tools else _FilteredServer(server, _ESSENTIAL_TOOLS)
+# Choose registration target (precedence: ALL > user allowlist > essential)
+if _all_tools:
+    _target = server
+elif _user_allowlist_str:
+    _user_allowlist = frozenset(t.strip() for t in _user_allowlist_str.split(",") if t.strip())
+    _target = _FilteredServer(server, _user_allowlist)
+else:
+    _target = _FilteredServer(server, _ESSENTIAL_TOOLS)
 
 from superlocalmemory.mcp.tools_core import register_core_tools
 from superlocalmemory.mcp.tools_v28 import register_v28_tools

package/src/superlocalmemory/mcp/tools_active.py

@@ -93,7 +93,6 @@ def register_active_tools(server, get_engine: Callable) -> None:
         The AI should call this automatically before any other work.
         """
         try:
-            from superlocalmemory.hooks.auto_recall import AutoRecall
             from superlocalmemory.hooks.rules_engine import RulesEngine
             from superlocalmemory.mcp._pool_adapter import pool_recall
 
@@ -104,21 +103,37 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 return {"success": True, "context": "", "memories": [], "message": "Auto-recall disabled"}
 
             recall_config = rules.get_recall_config()
-            auto = AutoRecall(
-                recall_fn=pool_recall,
-                config={
-                    "enabled": True,
-                    "max_memories_injected": max_results,
-                    "relevance_threshold": recall_config.get("relevance_threshold", 0.3),
-                },
-            )
-
-            # Get formatted context for system prompt injection
-            context = auto.get_session_context(project_path=project_path, query=query)
-
-            # Get structured results for tool response
-            search_query = query or f"project context {project_path}" if project_path else "recent important decisions"
-            memories = auto.get_query_context(search_query)
+            relevance_threshold = recall_config.get("relevance_threshold", 0.3)
+            if query:
+                search_query = query
+            elif project_path:
+                search_query = f"project context {project_path}"
+            else:
+                search_query = "recent important decisions"
+
+            response = pool_recall(search_query, limit=max_results, fast=True)
+            relevant = [
+                r for r in response.results
+                if r.score >= relevance_threshold
+            ]
+
+            # Build both return shapes from one recall. Calling recall twice
+            # doubles session startup latency and can return duplicate snippets.
+            context = ""
+            if relevant:
+                lines = ["# Relevant Memory Context", ""]
+                for r in relevant[:max_results]:
+                    lines.append(f"- {r.fact.content[:200]}")
+                context = "\n".join(lines)
+
+            memories = [
+                {
+                    "fact_id": r.fact.fact_id,
+                    "content": r.fact.content[:300],
+                    "score": round(r.score, 3),
+                }
+                for r in relevant[:max_results]
+            ]
 
             # Get learning status
             pid = engine.profile_id
@@ -184,7 +199,6 @@ def register_active_tools(server, get_engine: Callable) -> None:
             from superlocalmemory.hooks.rules_engine import RulesEngine
             from superlocalmemory.mcp._pool_adapter import pool_store
 
-            engine = get_engine()
             rules = RulesEngine()
 
             auto = AutoCapture(
@@ -305,7 +319,6 @@ def register_active_tools(server, get_engine: Callable) -> None:
         """
         try:
             engine = get_engine()
-            pid = engine.profile_id
             sid = session_id or getattr(engine, '_last_session_id', '')
             if not sid:
                 return {"success": False, "error": "No session_id provided"}

package/src/superlocalmemory/mcp/tools_core.py

@@ -13,10 +13,9 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
-import json
 import logging
 from pathlib import Path
-from typing import Any, Callable
+from typing import Callable
 
 from mcp.types import ToolAnnotations
 
@@ -111,7 +110,6 @@ def register_core_tools(server, get_engine: Callable) -> None:
         Extracts atomic facts, resolves entities, builds graph edges,
         and indexes for 4-channel retrieval.
         """
-        import asyncio
         try:
             # v3.4.32: Store-first pattern. Write to pending.db and return
             # immediately. The daemon's pending-materializer thread drains
@@ -141,7 +139,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def recall(
         query: str, limit: int = 10, agent_id: str = "mcp_client",
-        session_id: str = "",
+        session_id: str = "", fast: bool = False,
     ) -> dict:
         """Search memories by semantic query with 4-channel retrieval, RRF fusion, and reranking.
 
@@ -153,8 +151,8 @@ def register_core_tools(server, get_engine: Callable) -> None:
         """
         import asyncio
         try:
-            from superlocalmemory.core.worker_pool import WorkerPool
-            pool = WorkerPool.shared()
+            from superlocalmemory.mcp._daemon_proxy import choose_pool
+            pool = choose_pool()
             # S9-DASH-10: priority for session_id, so engagement
             # signals land on the right pending_outcome:
             #   1. Explicit ``session_id`` tool-call argument.
@@ -199,6 +197,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             # block behind a single threading.Lock. See worker_pool.py.
             result = await asyncio.to_thread(
                 pool.recall, query, limit=limit, session_id=effective_sid,
+                fast=bool(fast),
             )
             if result.get("ok"):
                 # Record implicit feedback: every returned result is a recall_hit

package/src/superlocalmemory/mcp/tools_v3.py

@@ -285,8 +285,8 @@ def register_v3_tools(server, get_engine: Callable) -> None:
             limit: Maximum results (default 10).
         """
         try:
-            from superlocalmemory.core.worker_pool import WorkerPool
-            raw = WorkerPool.shared().recall(query=query, limit=limit)
+            from superlocalmemory.mcp._daemon_proxy import choose_pool
+            raw = choose_pool().recall(query=query, limit=limit)
             items = raw.get("results", []) if isinstance(raw, dict) else []
             results = []
             for item in items[:limit]:

package/src/superlocalmemory/mesh/broker.py

@@ -19,8 +19,19 @@ import time
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 
 logger = logging.getLogger("superlocalmemory.mesh")
+import os as _os
+
+# Remote sync support (optional, try/except to avoid import issues)
+try:
+    from .remote_sync import RemoteSyncClient
+except ImportError:
+    RemoteSyncClient = None  # type: ignore
+
+LOCAL_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
+
 
 
 MAX_MESSAGE_SIZE = 4096  # 4KB cap — mesh messages are notifications, not data dumps
@@ -42,6 +53,39 @@ class MeshBroker:
         self._started_at = time.monotonic()
         self._cleanup_thread: threading.Thread | None = None
         self._stop_event = threading.Event()
+        self._host = _os.environ.get("SLM_MESH_HOST", "127.0.0.1")
+        self._shared_secret = _os.environ.get("SLM_MESH_SHARED_SECRET", "") or None
+        self._is_remote = self._host not in LOCAL_HOSTS
+        self._ws_port = int(_os.environ.get("SLM_MESH_WS_PORT", "7900"))
+        self._discovery_enabled = self._is_remote and _os.environ.get("SLM_MESH_DISCOVERY", "on") != "off"
+        self._remote_peers: dict[str, dict] = {}
+        self._peer_url: str | None = _os.environ.get("SLM_MESH_PEER_URL", "") or None
+        self._sync_client: Any = None
+        if self._is_remote and not self._shared_secret:
+            raise RuntimeError(
+                "SLM_MESH_SHARED_SECRET is required when SLM_MESH_HOST is not localhost"
+            )
+
+
+    # -- Remote / Multi-Machine support (v3.4.47) --
+
+    def get_remote_peers(self) -> list[dict]:
+        """Return peers from discovered remote brokers."""
+        return list(self._remote_peers.values())
+
+    def add_remote_peer(self, peer_id: str, info: dict) -> None:
+        """Register a peer from a remote broker."""
+        self._remote_peers[peer_id] = info
+
+    def remove_remote_peer(self, peer_id: str) -> None:
+        """Remove a remote peer."""
+        self._remote_peers.pop(peer_id, None)
+
+    def list_all_peers(self) -> list[dict]:
+        """Return local + remote peers merged."""
+        local = self.list_peers()
+        remote = self.get_remote_peers()
+        return local + remote
 
     def start_cleanup(self) -> None:
         """Start background cleanup thread for stale peers/messages."""
@@ -50,8 +94,17 @@ class MeshBroker:
         )
         self._cleanup_thread.start()
 
+        # Start remote sync client if peer URL configured or remote mode
+        if RemoteSyncClient and (
+            self._peer_url or (self._is_remote and self._host not in LOCAL_HOSTS)
+        ):
+            self._sync_client = RemoteSyncClient(self)
+            self._sync_client.start()
+
     def stop(self) -> None:
         self._stop_event.set()
+        if self._sync_client:
+            self._sync_client.stop()
 
     # -- Connection helper --
 
@@ -65,11 +118,13 @@ class MeshBroker:
     # -- Peers --
 
     def register_peer(self, session_id: str, summary: str = "",
-                      host: str = "127.0.0.1", port: int = 0,
+                      host: str = "", port: int = 0,
                       project_path: str = "", agent_type: str = "unknown") -> dict:
         conn = self._conn()
         try:
             now = datetime.now(timezone.utc).isoformat()
+            if not host:
+                host = self._host
             # Idempotent: update if same session_id exists
             existing = conn.execute(
                 "SELECT peer_id FROM mesh_peers WHERE session_id = ?",
@@ -178,6 +233,14 @@ class MeshBroker:
                 to_peer = "project"
             else:
                 target_type = "peer"
+                # Check if this is a remote peer — proxy to remote SLM
+                if to_peer in self._remote_peers and self._sync_client:
+                    return self._sync_client.send_to_remote(to_peer, {
+                        "from_peer": from_peer,
+                        "to": to_peer,
+                        "content": content,
+                        "type": msg_type,
+                    })
                 # Verify recipient exists for direct messages
                 if not conn.execute("SELECT 1 FROM mesh_peers WHERE peer_id=?", (to_peer,)).fetchone():
                     return {"ok": False, "error": "recipient peer not found"}