superlocalmemory 3.4.24 → 3.4.30

package/src/superlocalmemory/mcp/tools_core.py

@@ -18,6 +18,8 @@ import logging
 from pathlib import Path
 from typing import Any, Callable
 
+from mcp.types import ToolAnnotations
+
 logger = logging.getLogger(__name__)
 
 _DB_PATH = str(Path.home() / ".superlocalmemory" / "memory.db")
@@ -98,7 +100,7 @@ def _record_recall_hits(
 def register_core_tools(server, get_engine: Callable) -> None:
     """Register the 13 core MCP tools on *server*."""
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(idempotentHint=True))
     async def remember(
         content: str, tags: str = "", project: str = "",
         importance: int = 5, session_id: str = "",
@@ -163,7 +165,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("remember failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def recall(
         query: str, limit: int = 10, agent_id: str = "mcp_client",
         session_id: str = "",
@@ -219,7 +221,9 @@ def register_core_tools(server, get_engine: Callable) -> None:
                     pass
             if not effective_sid:
                 effective_sid = f"mcp:{agent_id}"
-            # V3.3.19: Run in thread pool to avoid blocking MCP event loop
+            # V3.3.19: Run in thread pool to avoid blocking MCP event loop.
+            # V3.4.26: WorkerPool now concurrent — parallel calls no longer
+            # block behind a single threading.Lock. See worker_pool.py.
             result = await asyncio.to_thread(
                 pool.recall, query, limit=limit, session_id=effective_sid,
             )
@@ -248,7 +252,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("recall failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def search(query: str, limit: int = 10, profile_id: str = "") -> dict:
         """Full-text search across memories using FTS5 with BM25 ranking."""
         try:
@@ -269,7 +273,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("search failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def fetch(fact_ids: str) -> dict:
         """Fetch full details for specific fact IDs (comma-separated)."""
         try:
@@ -295,7 +299,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("fetch failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def list_recent(limit: int = 20, profile_id: str = "") -> dict:
         """List most recently stored memories, newest first."""
         try:
@@ -316,7 +320,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("list_recent failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_status() -> dict:
         """Get memory system status: fact count, entity count, mode, profile, db size."""
         try:
@@ -473,7 +477,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("correct_pattern failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(destructiveHint=True))
     async def delete_memory(fact_id: str, agent_id: str = "mcp_client") -> dict:
         """Delete a specific memory by exact fact ID.
 
@@ -505,7 +509,7 @@ def register_core_tools(server, get_engine: Callable) -> None:
             logger.exception("delete_memory failed")
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(idempotentHint=True))
     async def update_memory(
         fact_id: str, content: str, agent_id: str = "mcp_client",
     ) -> dict:

package/src/superlocalmemory/mcp/tools_evolution.py

@@ -21,6 +21,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Callable
 
+from mcp.types import ToolAnnotations
+
 logger = logging.getLogger(__name__)
 
 MEMORY_DB = Path.home() / ".superlocalmemory" / "memory.db"
@@ -125,7 +127,7 @@ def register_evolution_tools(server, get_engine: Callable) -> None:
             logger.debug("evolve_skill failed: %s", exc)
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def skill_health(
         skill_name: str = "",
         include_history: bool = False,
@@ -258,7 +260,7 @@ def register_evolution_tools(server, get_engine: Callable) -> None:
             logger.debug("skill_health failed: %s", exc)
             return {"skills": [], "skill_count": 0, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def skill_lineage(
         skill_name: str = "",
     ) -> dict:

package/src/superlocalmemory/mcp/tools_learning.py

@@ -22,6 +22,8 @@ import uuid
 from datetime import datetime, timezone
 from typing import Callable
 
+from mcp.types import ToolAnnotations
+
 logger = logging.getLogger(__name__)
 
 _MAX_SUMMARY_LEN = 500  # Truncate input/output summaries
@@ -80,7 +82,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             logger.debug("log_tool_event failed: %s", exc)
             return {"success": False, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_assertions(
         min_confidence: float = 0.0,
         category: str = "",
@@ -131,7 +133,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
             logger.debug("get_assertions failed: %s", exc)
             return {"assertions": [], "count": 0, "error": str(exc)}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(idempotentHint=True))
     async def reinforce_assertion(assertion_id: str) -> dict:
         """Reinforce a behavioral assertion (increase confidence).
 
@@ -144,7 +146,7 @@ def register_learning_tools(server, get_engine: Callable) -> None:
         engine = get_engine()
         return _update_assertion_confidence(engine._db, assertion_id, reinforce=True)
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(idempotentHint=True))
     async def contradict_assertion(assertion_id: str) -> dict:
         """Contradict a behavioral assertion (decrease confidence).
 

package/src/superlocalmemory/mcp/tools_mesh.py

@@ -24,6 +24,8 @@ import time
 import uuid
 from typing import Callable
 
+from mcp.types import ToolAnnotations
+
 logger = logging.getLogger(__name__)
 
 # Unique peer ID for this MCP server session
@@ -156,7 +158,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
             "broker_response": result,
         }
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def mesh_peers() -> dict:
         """List all active peer sessions on this machine.
 
@@ -267,7 +269,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         })
         return result or {"error": "Lock operation failed"}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def mesh_events() -> dict:
         """Get recent mesh events (peer joins, leaves, messages, state changes).
 
@@ -276,7 +278,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         result = _mesh_request("GET", "/events")
         return result or {"events": []}
 
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def mesh_status() -> dict:
         """Get mesh broker health and statistics.
 

package/src/superlocalmemory/mcp/tools_v3.py

@@ -273,35 +273,31 @@ def register_v3_tools(server, get_engine: Callable) -> None:
             limit: Maximum results (default 10).
         """
         try:
-            engine = get_engine()
-            response = engine.recall(query, limit=limit)
+            from superlocalmemory.core.worker_pool import WorkerPool
+            raw = WorkerPool.shared().recall(query=query, limit=limit)
+            items = raw.get("results", []) if isinstance(raw, dict) else []
             results = []
-            for r in response.results[:limit]:
+            for item in items[:limit]:
                 results.append({
-                    "fact_id": r.fact.fact_id,
-                    "content": r.fact.content,
-                    "final_score": round(r.score, 4),
-                    "confidence": round(r.confidence, 3),
-                    "trust_score": round(r.trust_score, 3),
-                    "channel_scores": {
-                        k: round(v, 4) for k, v in r.channel_scores.items()
-                    },
-                    "evidence_chain": r.evidence_chain,
-                    "fact_type": r.fact.fact_type.value,
-                    "lifecycle": r.fact.lifecycle.value,
-                    "access_count": r.fact.access_count,
+                    "fact_id": item.get("fact_id", ""),
+                    "content": item.get("content", ""),
+                    "final_score": round(float(item.get("score", 0.0)), 4),
+                    "confidence": round(float(item.get("confidence", 0.0)), 3),
+                    "trust_score": round(float(item.get("trust_score", 0.0)), 3),
+                    "channel_scores": item.get("channel_scores", {}) or {},
+                    "evidence_chain": item.get("evidence_chain", []) or [],
+                    "fact_type": item.get("fact_type", ""),
+                    "lifecycle": item.get("lifecycle", ""),
+                    "access_count": int(item.get("access_count", 0)),
                 })
             return {
                 "success": True,
                 "results": results,
                 "count": len(results),
-                "query_type": response.query_type,
-                "channel_weights": {
-                    k: round(v, 3)
-                    for k, v in response.channel_weights.items()
-                },
-                "total_candidates": response.total_candidates,
-                "retrieval_time_ms": round(response.retrieval_time_ms, 1),
+                "query_type": raw.get("query_type", "") if isinstance(raw, dict) else "",
+                "channel_weights": raw.get("channel_weights", {}) if isinstance(raw, dict) else {},
+                "total_candidates": raw.get("total_candidates", 0) if isinstance(raw, dict) else 0,
+                "retrieval_time_ms": round(float(raw.get("retrieval_time_ms", 0.0)) if isinstance(raw, dict) else 0.0, 1),
             }
         except Exception as exc:
             logger.exception("recall_trace failed")

package/src/superlocalmemory/mcp/tools_v33.py

@@ -20,12 +20,43 @@ import logging
 from pathlib import Path
 from typing import Callable
 
+from mcp.types import ToolAnnotations
+
 logger = logging.getLogger(__name__)
 
 MEMORY_DIR = Path.home() / ".superlocalmemory"
 DB_PATH = MEMORY_DIR / "memory.db"
 
 
+def _try_daemon_post(path: str, body: dict, timeout_s: float = 60.0) -> dict | None:
+    """POST to the daemon, return parsed dict or None if daemon unavailable.
+
+    Keeps heavy imports (CognitiveConsolidator, ForgettingScheduler,
+    ConsolidationWorker) out of the MCP process when a daemon is up.
+    Returns None on any failure so the caller can fall back to local
+    execution.
+    """
+    try:
+        from superlocalmemory.cli.daemon import _get_port, is_daemon_running
+        if not is_daemon_running():
+            return None
+        import json as _json
+        import urllib.request as _urq
+        port = _get_port()
+        req = _urq.Request(
+            f"http://127.0.0.1:{port}{path}",
+            data=_json.dumps(body).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with _urq.urlopen(req, timeout=timeout_s) as resp:
+            raw = resp.read().decode() or "{}"
+        return _json.loads(raw)
+    except Exception as exc:
+        logger.warning("daemon POST %s failed: %s", path, exc)
+        return None
+
+
 def _emit_event(event_type: str, payload: dict | None = None,
                 source_agent: str = "mcp_client") -> None:  # V3.3.12: see also mcp/shared.py
     """Emit an event to the EventBus (best-effort, never raises)."""
@@ -44,7 +75,7 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 1. forget — Ebbinghaus forgetting decay cycle
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(destructiveHint=True))
     async def forget(
         profile_id: str = "",
         dry_run: bool = True,
@@ -188,6 +219,26 @@ def register_v33_tools(server, get_engine: Callable) -> None:
             engine = get_engine()
             pid = profile_id or engine.profile_id
 
+            # v3.4.26: prefer the daemon's /consolidate/cognitive endpoint
+            # so the heavy CognitiveConsolidator import stays out of the
+            # MCP process. Fall back to local import only if no daemon.
+            daemon_result = _try_daemon_post(
+                "/consolidate/cognitive", {"profile_id": pid},
+            )
+            if daemon_result is not None:
+                _emit_event("ccq.consolidation_complete", {
+                    "profile_id": pid,
+                    "clusters_processed": daemon_result.get("clusters_processed", 0),
+                    "blocks_created": daemon_result.get("blocks_created", 0),
+                })
+                return {
+                    "success": True,
+                    "clusters_processed": daemon_result.get("clusters_processed", 0),
+                    "blocks_created": daemon_result.get("blocks_created", 0),
+                    "profile_id": pid,
+                    "via": "daemon",
+                }
+
             from superlocalmemory.encoding.cognitive_consolidator import (
                 CognitiveConsolidator,
             )
@@ -216,7 +267,7 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 4. get_soft_prompts — Retrieve active soft prompts
     # ------------------------------------------------------------------
-    @server.tool()
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_soft_prompts(
         profile_id: str = "",
     ) -> dict:
@@ -379,6 +430,18 @@ def register_v33_tools(server, get_engine: Callable) -> None:
         try:
             engine = get_engine()
             pid = profile_id or engine.profile_id
+
+            # v3.4.26: prefer the daemon so ForgettingScheduler /
+            # ConsolidationWorker / EbbinghausCurve don't load inside
+            # the MCP process.
+            daemon_result = _try_daemon_post(
+                "/maintenance/run", {"profile_id": pid},
+            )
+            if daemon_result is not None:
+                daemon_result.setdefault("success", True)
+                daemon_result["via"] = "daemon"
+                return daemon_result
+
             results = {}
 
             # 1. Langevin dynamics step (lifecycle evolution)

package/src/superlocalmemory/migrations/__init__.py

@@ -0,0 +1,5 @@
+# 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
+
+"""Schema and data migrations."""

package/src/superlocalmemory/migrations/v3_4_25_to_v3_4_26.py

@@ -0,0 +1,144 @@
+# 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
+
+"""Idempotent migration from v3.4.25 to v3.4.26 data layout.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _daemon_running() -> bool:
+    """Return True if an SLM daemon is holding the data dir.
+
+    Defined as a module-level indirection so tests can monkey-patch it
+    without reaching into ``cli.daemon``.
+    """
+    from superlocalmemory.cli.daemon import is_daemon_running
+    return bool(is_daemon_running())
+
+
+def migrate_if_safe(data_dir: Path) -> dict[str, object]:
+    """Run :func:`migrate` only when it's safe to touch the data dir.
+
+    Safety guarantees:
+
+    1. A live daemon means defer — the daemon is the authoritative DB
+       holder and will apply the migration on its next start.
+    2. If the daemon probe itself fails, err on the safe side and defer.
+    3. Concurrent CLI + daemon-start + npm-postinstall invocations on
+       the same data dir serialize through a file lock, so no two
+       processes can race into ``migrate()`` at the same moment.
+
+    Returns a dict with a ``status`` in
+    ``{applied, already_applied, deferred}``.
+    """
+    data_dir = Path(data_dir)
+
+    if is_ready(data_dir):
+        return {"status": "already_applied", "data_dir": str(data_dir)}
+
+    try:
+        daemon_up = _daemon_running()
+    except Exception as exc:
+        logger.warning(
+            "daemon probe failed, deferring migrate_if_safe: %s", exc,
+        )
+        daemon_up = True
+
+    if daemon_up:
+        return {
+            "status": "deferred",
+            "data_dir": str(data_dir),
+            "reason": "daemon is running — migration will apply on next daemon start",
+        }
+
+    # Serialize concurrent CLI / postinstall / daemon-boot callers.
+    data_dir.mkdir(parents=True, exist_ok=True)
+    lock_path = data_dir / ".migrate-v3.4.26.lock"
+    lock_fd = None
+    try:
+        import os
+        lock_fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o600)
+        import sys
+        if sys.platform == "win32":
+            try:
+                import msvcrt
+                msvcrt.locking(lock_fd, msvcrt.LK_LOCK, 1)
+            except (IOError, OSError):
+                # Another process is mid-migrate — they will apply it.
+                return {
+                    "status": "deferred",
+                    "data_dir": str(data_dir),
+                    "reason": "concurrent migrate_if_safe in progress",
+                }
+        else:
+            try:
+                import fcntl
+                fcntl.flock(lock_fd, fcntl.LOCK_EX)
+            except (IOError, OSError):
+                return {
+                    "status": "deferred",
+                    "data_dir": str(data_dir),
+                    "reason": "concurrent migrate_if_safe in progress",
+                }
+
+        # Re-check the sentinel now that we own the lock — another
+        # process may have applied the migration while we waited.
+        if is_ready(data_dir):
+            return {"status": "already_applied", "data_dir": str(data_dir)}
+
+        result = migrate(data_dir)
+        result["status"] = "applied"
+        return result
+    finally:
+        if lock_fd is not None:
+            try:
+                import os as _os
+                _os.close(lock_fd)
+            except OSError:
+                pass
+
+
+def migrate(data_dir: Path) -> dict[str, object]:
+    """Prepare v3.4.26 data directory. Safe to run any number of times.
+
+    memory.db is untouched; the migration only provisions the new
+    recall_queue.db and marks readiness with a sentinel file.
+    """
+    result: dict[str, object] = {
+        "data_dir": str(data_dir),
+        "created": [],
+        "already_present": [],
+    }
+    data_dir = Path(data_dir)
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    from superlocalmemory.core.recall_queue import RecallQueue
+
+    queue_path = data_dir / "recall_queue.db"
+    if queue_path.exists():
+        result["already_present"].append(str(queue_path))
+    else:
+        result["created"].append(str(queue_path))
+    q = RecallQueue(db_path=queue_path)
+    q.close()
+
+    marker = data_dir / ".slm-v3.4.26-ready"
+    if marker.exists():
+        result["already_present"].append(str(marker))
+    else:
+        marker.write_text("3.4.26\n", encoding="utf-8")
+        result["created"].append(str(marker))
+    return result
+
+
+def is_ready(data_dir: Path) -> bool:
+    return (Path(data_dir) / ".slm-v3.4.26-ready").exists()

package/src/superlocalmemory/server/routes/events.py

@@ -44,7 +44,7 @@ def _event_to_sse_bridge(event: dict):
                 q.put_nowait(event)
             except _queue.Full:
                 dead_queues.add(q)
-        _sse_queues -= dead_queues
+        _sse_queues.difference_update(dead_queues)
 
 
 def register_event_listener():

package/src/superlocalmemory/server/routes/v3_api.py

@@ -558,7 +558,6 @@ async def recall_trace(request: Request):
 
 def _record_learning_signals(query: str, results: list) -> None:
     """Record feedback + co-retrieval + confidence boost for any recall."""
-    from pathlib import Path
     from superlocalmemory.core.config import SLMConfig
 
     slm_dir = Path.home() / ".superlocalmemory"