superlocalmemory 2.7.2 → 2.7.4

package/mcp_server.py

@@ -25,14 +25,16 @@ Usage:
     python3 mcp_server.py --transport http --port 8001
 """
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp import FastMCP, Context
 from mcp.types import ToolAnnotations
 import sys
 import os
 import json
 import re
+import time
+import threading
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Dict, List, Any
 
 # Add src directory to path (use existing code!)
 MEMORY_DIR = Path.home() / ".claude-memory"
@@ -72,6 +74,70 @@ try:
 except ImportError:
     LEARNING_AVAILABLE = False
 
+# ============================================================================
+# Synthetic Bootstrap Auto-Trigger (v2.7 — P1-12)
+# Runs ONCE on first recall if: memory count > 50, no model, LightGBM available.
+# Spawns in background thread — never blocks recall. All errors swallowed.
+# ============================================================================
+
+_bootstrap_checked = False
+
+
+def _maybe_bootstrap():
+    """Check if synthetic bootstrap is needed and run it in a background thread.
+
+    Called once from the first recall invocation. Sets _bootstrap_checked = True
+    immediately to prevent re-entry. The actual bootstrap runs in a daemon thread
+    so it never blocks the recall response.
+
+    Conditions for bootstrap:
+        1. LEARNING_AVAILABLE and ML_RANKING_AVAILABLE flags are True
+        2. SyntheticBootstrapper.should_bootstrap() returns True (checks:
+           - LightGBM + NumPy installed
+           - No existing model file at ~/.claude-memory/models/ranker.txt
+           - Memory count > 50)
+
+    CRITICAL: This function wraps everything in try/except. Bootstrap failure
+    must NEVER break recall. It is purely an optimization — first-time ML
+    model creation so users don't have to wait 200+ recalls for personalization.
+    """
+    global _bootstrap_checked
+    _bootstrap_checked = True  # Set immediately to prevent re-entry
+
+    try:
+        if not LEARNING_AVAILABLE:
+            return
+        if not ML_RANKING_AVAILABLE:
+            return
+
+        from learning.synthetic_bootstrap import SyntheticBootstrapper
+        bootstrapper = SyntheticBootstrapper(memory_db_path=DB_PATH)
+
+        if not bootstrapper.should_bootstrap():
+            return
+
+        # Run bootstrap in background thread — never block recall
+        import threading
+
+        def _run_bootstrap():
+            try:
+                result = bootstrapper.bootstrap_model()
+                if result:
+                    import logging
+                    logging.getLogger("superlocalmemory.mcp").info(
+                        "Synthetic bootstrap complete: %d samples",
+                        result.get('training_samples', 0)
+                    )
+            except Exception:
+                pass  # Bootstrap failure is never critical
+
+        thread = threading.Thread(target=_run_bootstrap, daemon=True)
+        thread.start()
+
+    except Exception:
+        pass  # Any failure in bootstrap setup is swallowed silently
+
+
 def _sanitize_error(error: Exception) -> str:
     """Strip internal paths and structure from error messages."""
     msg = str(error)
@@ -186,8 +252,48 @@ def get_learning_components():
     }
 
 
-def _register_mcp_agent(agent_name: str = "mcp-client"):
-    """Register the calling MCP agent and record activity. Non-blocking."""
+def _get_client_name(ctx: Optional[Context] = None) -> str:
+    """Extract client name from MCP context, or return default.
+
+    Reads clientInfo.name from the MCP initialize handshake via
+    ctx.session.client_params. This identifies Perplexity, Codex,
+    Claude Desktop, etc. as distinct agents.
+    """
+    if ctx:
+        try:
+            # Primary: session.client_params.clientInfo.name (from initialize handshake)
+            session = getattr(ctx, 'session', None)
+            if session:
+                params = getattr(session, 'client_params', None)
+                if params:
+                    client_info = getattr(params, 'clientInfo', None)
+                    if client_info:
+                        name = getattr(client_info, 'name', None)
+                        if name:
+                            return str(name)
+        except Exception:
+            pass
+        try:
+            # Fallback: ctx.client_id (per-request, may be null)
+            client_id = ctx.client_id
+            if client_id:
+                return str(client_id)
+        except Exception:
+            pass
+    return "mcp-client"
+
+
+def _register_mcp_agent(agent_name: str = "mcp-client", ctx: Optional[Context] = None):
+    """Register the calling MCP agent and record activity. Non-blocking.
+
+    v2.7.4: Extracts real client name from MCP context when available,
+    so Perplexity, Codex, Claude Desktop show as distinct agents.
+    """
+    if ctx:
+        detected = _get_client_name(ctx)
+        if detected != "mcp-client":
+            agent_name = detected
+
     registry = get_agent_registry()
     if registry:
         try:
@@ -200,6 +306,264 @@ def _register_mcp_agent(agent_name: str = "mcp-client"):
             pass
 
 
+# ============================================================================
+# RECALL BUFFER & SIGNAL INFERENCE ENGINE (v2.7.4 — Silent Learning)
+# ============================================================================
+# Tracks recall operations and infers implicit feedback signals from user
+# behavior patterns. Zero user effort — all signals auto-collected.
+#
+# Signal Types:
+#   implicit_positive_timegap   — long pause (>5min) after recall = satisfied
+#   implicit_negative_requick   — quick re-query (<30s) = dissatisfied
+#   implicit_positive_reaccess  — same memory in consecutive recalls
+#   implicit_positive_cross_tool — same memory recalled by different agents
+#   implicit_positive_post_update — memory updated after being recalled
+#   implicit_negative_post_delete — memory deleted after being recalled
+#
+# Research: Hu et al. 2008 (implicit feedback), BPR Rendle 2009 (pairwise)
+# ============================================================================
+
+class _RecallBuffer:
+    """Thread-safe buffer tracking recent recall operations for signal inference.
+
+    Stores the last recall per agent_id so we can compare consecutive recalls
+    and infer whether the user found results useful.
+
+    Rate limiting: max 5 implicit signals per agent per minute to prevent gaming.
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        # {agent_id: {query, result_ids, timestamp, result_id_set}}
+        self._last_recall: Dict[str, Dict[str, Any]] = {}
+        # Global last recall (for cross-agent comparison)
+        self._global_last: Optional[Dict[str, Any]] = None
+        # Rate limiter: {agent_id: [timestamp, timestamp, ...]}
+        self._signal_timestamps: Dict[str, List[float]] = {}
+        # Set of memory_ids from the most recent recall (for post-action tracking)
+        self._recent_result_ids: set = set()
+        # Recall counter for passive decay auto-trigger
+        self._recall_count: int = 0
+        # Adaptive threshold: starts at 300s (5min), adjusts based on user patterns
+        self._positive_threshold: float = 300.0
+        self._inter_recall_times: List[float] = []
+
+    def record_recall(
+        self,
+        query: str,
+        result_ids: List[int],
+        agent_id: str = "mcp-client",
+    ) -> List[Dict[str, Any]]:
+        """Record a recall and infer signals from previous recall comparison.
+
+        Returns a list of inferred signal dicts: [{memory_id, signal_type, query}]
+        """
+        now = time.time()
+        signals: List[Dict[str, Any]] = []
+
+        with self._lock:
+            self._recall_count += 1
+            result_id_set = set(result_ids)
+            self._recent_result_ids = result_id_set
+
+            current = {
+                "query": query,
+                "result_ids": result_ids,
+                "result_id_set": result_id_set,
+                "timestamp": now,
+                "agent_id": agent_id,
+            }
+
+            # --- Compare with previous recall from SAME agent ---
+            prev = self._last_recall.get(agent_id)
+            if prev:
+                time_gap = now - prev["timestamp"]
+
+                # Track inter-recall times for adaptive threshold
+                self._inter_recall_times.append(time_gap)
+                if len(self._inter_recall_times) > 100:
+                    self._inter_recall_times = self._inter_recall_times[-100:]
+
+                # Update adaptive threshold (median of recent times, min 60s, max 1800s)
+                if len(self._inter_recall_times) >= 10:
+                    sorted_times = sorted(self._inter_recall_times)
+                    median = sorted_times[len(sorted_times) // 2]
+                    self._positive_threshold = max(60.0, min(median * 0.8, 1800.0))
+
+                # Signal: Quick re-query with different query = negative
+                if time_gap < 30.0 and query != prev["query"]:
+                    for mid in prev["result_ids"][:5]:  # Top 5 only
+                        signals.append({
+                            "memory_id": mid,
+                            "signal_type": "implicit_negative_requick",
+                            "query": prev["query"],
+                            "rank_position": prev["result_ids"].index(mid) + 1,
+                        })
+
+                # Signal: Long pause = positive for previous results
+                elif time_gap > self._positive_threshold:
+                    for mid in prev["result_ids"][:3]:  # Top 3 only
+                        signals.append({
+                            "memory_id": mid,
+                            "signal_type": "implicit_positive_timegap",
+                            "query": prev["query"],
+                            "rank_position": prev["result_ids"].index(mid) + 1,
+                        })
+
+                # Signal: Same memory re-accessed = positive
+                overlap = result_id_set & prev["result_id_set"]
+                for mid in overlap:
+                    signals.append({
+                        "memory_id": mid,
+                        "signal_type": "implicit_positive_reaccess",
+                        "query": query,
+                    })
+
+            # --- Compare with previous recall from DIFFERENT agent (cross-tool) ---
+            global_prev = self._global_last
+            if global_prev and global_prev["agent_id"] != agent_id:
+                cross_overlap = result_id_set & global_prev["result_id_set"]
+                for mid in cross_overlap:
+                    signals.append({
+                        "memory_id": mid,
+                        "signal_type": "implicit_positive_cross_tool",
+                        "query": query,
+                    })
+
+            # Update buffers
+            self._last_recall[agent_id] = current
+            self._global_last = current
+
+        return signals
+
+    def check_post_action(self, memory_id: int, action: str) -> Optional[Dict[str, Any]]:
+        """Check if a memory action (update/delete) follows a recent recall.
+
+        Returns signal dict if the memory was in recent results, else None.
+        """
+        with self._lock:
+            if memory_id not in self._recent_result_ids:
+                return None
+
+            if action == "update":
+                return {
+                    "memory_id": memory_id,
+                    "signal_type": "implicit_positive_post_update",
+                    "query": self._global_last["query"] if self._global_last else "",
+                }
+            elif action == "delete":
+                return {
+                    "memory_id": memory_id,
+                    "signal_type": "implicit_negative_post_delete",
+                    "query": self._global_last["query"] if self._global_last else "",
+                }
+        return None
+
+    def check_rate_limit(self, agent_id: str, max_per_minute: int = 5) -> bool:
+        """Return True if agent is within rate limit, False if exceeded."""
+        now = time.time()
+        with self._lock:
+            if agent_id not in self._signal_timestamps:
+                self._signal_timestamps[agent_id] = []
+
+            # Clean old timestamps (older than 60s)
+            self._signal_timestamps[agent_id] = [
+                ts for ts in self._signal_timestamps[agent_id]
+                if now - ts < 60.0
+            ]
+
+            if len(self._signal_timestamps[agent_id]) >= max_per_minute:
+                return False
+
+            self._signal_timestamps[agent_id].append(now)
+            return True
+
+    def get_recall_count(self) -> int:
+        """Get total recall count (for passive decay trigger)."""
+        with self._lock:
+            return self._recall_count
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get buffer statistics for diagnostics."""
+        with self._lock:
+            return {
+                "recall_count": self._recall_count,
+                "tracked_agents": len(self._last_recall),
+                "positive_threshold_s": round(self._positive_threshold, 1),
+                "recent_results_count": len(self._recent_result_ids),
+            }
+
+
+# Module-level singleton
+_recall_buffer = _RecallBuffer()
+
+
+def _emit_implicit_signals(signals: List[Dict[str, Any]], agent_id: str = "mcp-client") -> int:
+    """Emit inferred implicit signals to the feedback collector.
+
+    Rate-limited: max 5 signals per agent per minute.
+    All errors swallowed — signal collection must NEVER break operations.
+
+    Returns number of signals actually stored.
+    """
+    if not LEARNING_AVAILABLE or not signals:
+        return 0
+
+    stored = 0
+    try:
+        feedback = get_feedback_collector()
+        if not feedback:
+            return 0
+
+        for sig in signals:
+            if not _recall_buffer.check_rate_limit(agent_id):
+                break  # Rate limit exceeded for this agent
+            try:
+                feedback.record_implicit_signal(
+                    memory_id=sig["memory_id"],
+                    query=sig.get("query", ""),
+                    signal_type=sig["signal_type"],
+                    source_tool=agent_id,
+                    rank_position=sig.get("rank_position"),
+                )
+                stored += 1
+            except Exception:
+                pass  # Individual signal failure is fine
+    except Exception:
+        pass  # Never break the caller
+
+    return stored
+
+
+def _maybe_passive_decay() -> None:
+    """Auto-trigger passive decay every 10 recalls in a background thread."""
+    try:
+        if not LEARNING_AVAILABLE:
+            return
+        if _recall_buffer.get_recall_count() % 10 != 0:
+            return
+
+        feedback = get_feedback_collector()
+        if not feedback:
+            return
+
+        def _run_decay():
+            try:
+                count = feedback.compute_passive_decay(threshold=5)
+                if count > 0:
+                    import logging
+                    logging.getLogger("superlocalmemory.mcp").info(
+                        "Passive decay: %d signals emitted", count
+                    )
+            except Exception:
+                pass
+
+        thread = threading.Thread(target=_run_decay, daemon=True)
+        thread.start()
+    except Exception:
+        pass
+
+
 # ============================================================================
 # MCP TOOLS (Functions callable by AI)
 # ============================================================================
@@ -213,7 +577,8 @@ async def remember(
     content: str,
     tags: str = "",
     project: str = "",
-    importance: int = 5
+    importance: int = 5,
+    ctx: Context = None,
 ) -> dict:
     """
     Save content to SuperLocalMemory with intelligent indexing.
@@ -240,8 +605,8 @@ async def remember(
         remember("JWT auth with refresh tokens", tags="security,auth", importance=8)
     """
     try:
-        # Register MCP agent (v2.5 — agent tracking)
-        _register_mcp_agent()
+        # Register MCP agent (v2.5 — agent tracking, v2.7.4 — client detection)
+        _register_mcp_agent(ctx=ctx)
 
         # Trust enforcement (v2.6) — block untrusted agents from writing
         try:
@@ -308,12 +673,16 @@ async def remember(
 async def recall(
     query: str,
     limit: int = 10,
-    min_score: float = 0.3
+    min_score: float = 0.3,
+    ctx: Context = None,
 ) -> dict:
     """
     Search memories using semantic similarity and knowledge graph.
+    Results are personalized based on your usage patterns — the more you
+    use SuperLocalMemory, the better results get. All learning is local.
 
-    This calls the SAME backend as /superlocalmemoryv2:recall skill.
+    After using results, call memory_used(memory_id) for memories you
+    referenced to help improve future recall quality.
 
     Args:
         query: Search query (required)
@@ -341,6 +710,18 @@ async def recall(
         recall("FastAPI", limit=5, min_score=0.5)
     """
     try:
+        # Register MCP agent (v2.7.4 — client detection for agent tab)
+        _register_mcp_agent(ctx=ctx)
+
+        # Track recall in agent registry
+        registry = get_agent_registry()
+        if registry:
+            try:
+                agent_name = _get_client_name(ctx)
+                registry.record_recall(f"mcp:{agent_name}")
+            except Exception:
+                pass
+
         # Use existing MemoryStoreV2 class
         store = get_store()
 
@@ -356,6 +737,10 @@ async def recall(
         else:
             results = store.search(query, limit=limit)
 
+        # v2.7: Auto-trigger synthetic bootstrap on first recall (P1-12)
+        if not _bootstrap_checked:
+            _maybe_bootstrap()
+
         # v2.7: Learning-based re-ranking (optional, graceful fallback)
         if LEARNING_AVAILABLE:
             try:
@@ -377,6 +762,17 @@ async def recall(
             except Exception:
                 pass  # Tracking failure must never break recall
 
+        # v2.7.4: Implicit signal inference from recall patterns
+        try:
+            result_ids = [r.get('id') for r in results if r.get('id')]
+            signals = _recall_buffer.record_recall(query, result_ids)
+            if signals:
+                _emit_implicit_signals(signals)
+            # Auto-trigger passive decay every 10 recalls
+            _maybe_passive_decay()
+        except Exception:
+            pass  # Signal inference must NEVER break recall
+
         # Filter by minimum score
         filtered_results = [
             r for r in results
@@ -640,7 +1036,7 @@ async def backup_status() -> dict:
 @mcp.tool(annotations=ToolAnnotations(
     readOnlyHint=False,
     destructiveHint=False,
-    openWorldHint=False,
+    openWorldHint=True,
 ))
 async def memory_used(
     memory_id: int,
@@ -648,15 +1044,18 @@ async def memory_used(
     usefulness: str = "high"
 ) -> dict:
     """
-    Signal that a recalled memory was useful. Call this when you reference
-    or apply a memory from recall results in your response.
+    Call this tool whenever you use information from a recalled memory in
+    your response. This is the most important feedback signal — it teaches
+    SuperLocalMemory which memories are truly useful and dramatically
+    improves future recall quality. All data stays 100% local.
 
-    This helps SuperLocalMemory learn which memories are most relevant
-    and improves future recall results.
+    Best practice: After using recall() results, call memory_used() for
+    each memory ID you referenced. This takes <1ms and helps the system
+    learn your preferences.
 
     Args:
-        memory_id: ID of the useful memory
-        query: The recall query that found it (optional)
+        memory_id: ID of the useful memory (from recall results)
+        query: The recall query that found it (optional but recommended)
         usefulness: How useful - "high", "medium", or "low" (default "high")
 
     Returns:
@@ -868,6 +1267,15 @@ async def search(query: str) -> dict:
         store = get_store()
         raw_results = store.search(query, limit=20)
 
+        # v2.7: Learning-based re-ranking (optional, graceful fallback)
+        if LEARNING_AVAILABLE:
+            try:
+                ranker = get_adaptive_ranker()
+                if ranker:
+                    raw_results = ranker.rerank(raw_results, query)
+            except Exception:
+                pass  # Re-ranking failure must never break search
+
         results = []
         for r in raw_results:
             if r.get('score', 0) < 0.2:
@@ -1150,7 +1558,7 @@ if __name__ == "__main__":
     # Print startup message to stderr (stdout is used for MCP protocol)
     print("=" * 60, file=sys.stderr)
     print("SuperLocalMemory V2 - MCP Server", file=sys.stderr)
-    print("Version: 2.7.0", file=sys.stderr)
+    print("Version: 2.7.4", file=sys.stderr)
     print("=" * 60, file=sys.stderr)
     print("Created by: Varun Pratap Bhardwaj (Solution Architect)", file=sys.stderr)
     print("Repository: https://github.com/varun369/SuperLocalMemoryV2", file=sys.stderr)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "2.7.2",
+  "version": "2.7.4",
   "description": "Your AI Finally Remembers You - Local-first intelligent memory system for AI assistants. Works with Claude, Cursor, Windsurf, VS Code/Copilot, Codex, and 17+ AI tools. 100% local, zero cloud dependencies.",
   "keywords": [
     "ai-memory",

package/skills/slm-recall/SKILL.md

@@ -142,6 +142,7 @@ Finds: Exact mentions of "PostgreSQL 15"
 - Graph distance
 - Recency (newer = slight boost)
 - Importance level
+- Your usage patterns (results improve automatically over time)
 
 ## Advanced Usage
 

package/src/agent_registry.py

@@ -98,7 +98,7 @@ class AgentRegistry:
                         last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                         memories_written INTEGER DEFAULT 0,
                         memories_recalled INTEGER DEFAULT 0,
-                        trust_score REAL DEFAULT 1.0,
+                        trust_score REAL DEFAULT 0.667,
                         metadata TEXT DEFAULT '{}'
                     )
                 ''')
@@ -126,7 +126,7 @@ class AgentRegistry:
                     last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                     memories_written INTEGER DEFAULT 0,
                     memories_recalled INTEGER DEFAULT 0,
-                    trust_score REAL DEFAULT 1.0,
+                    trust_score REAL DEFAULT 0.667,
                     metadata TEXT DEFAULT '{}'
                 )
             ''')
@@ -150,7 +150,7 @@ class AgentRegistry:
         Register or update an agent in the registry.
 
         If the agent already exists, updates last_seen and metadata.
-        If new, creates the entry with trust_score=1.0.
+        If new, creates the entry with trust_score=0.667 (Beta(2,1) prior).
 
         Args:
             agent_id: Unique identifier (e.g., "mcp:claude-desktop")