superlocalmemory 2.6.5 → 2.7.0

package/install.sh

@@ -57,18 +57,87 @@ if [ "$NON_INTERACTIVE" = true ]; then
     echo ""
 fi
 
-# Check Python version
+# Check Python version — install if missing (non-tech user friendly)
 echo "Checking Python version..."
+
+install_python() {
+    echo ""
+    echo "Python 3 not found. Attempting automatic installation..."
+    if [ "$(uname)" = "Darwin" ]; then
+        # macOS: try Homebrew first, then Xcode CLI tools
+        if command -v brew &> /dev/null; then
+            echo "Installing Python via Homebrew..."
+            brew install python3 && return 0
+        fi
+        # Try installing Xcode Command Line Tools (includes Python 3)
+        echo "Installing Xcode Command Line Tools (includes Python 3)..."
+        echo "A system dialog may appear — click 'Install' to continue."
+        xcode-select --install 2>/dev/null
+        # Wait for user to complete the install dialog
+        echo "Waiting for Xcode CLI tools installation to complete..."
+        echo "Press Enter after the installation finishes."
+        if [ "$NON_INTERACTIVE" = false ]; then
+            read -r
+        else
+            # In non-interactive mode, wait and retry
+            sleep 30
+        fi
+        if command -v python3 &> /dev/null; then
+            return 0
+        fi
+        # Last resort: direct Python.org installer
+        echo ""
+        echo "Automatic installation could not complete."
+        echo "Please install Python 3.10+ from: https://www.python.org/downloads/"
+        echo "Then re-run this installer."
+        return 1
+    elif [ -f /etc/debian_version ]; then
+        # Debian/Ubuntu
+        echo "Installing Python via apt..."
+        sudo apt-get update -qq && sudo apt-get install -y python3 python3-pip && return 0
+    elif [ -f /etc/redhat-release ]; then
+        # RHEL/CentOS/Fedora
+        echo "Installing Python via dnf..."
+        sudo dnf install -y python3 python3-pip && return 0
+    elif [ -f /etc/arch-release ]; then
+        # Arch Linux
+        sudo pacman -S --noconfirm python python-pip && return 0
+    fi
+    echo "Could not auto-install Python. Please install Python 3.8+ manually."
+    echo "  macOS:  brew install python3"
+    echo "  Ubuntu: sudo apt install python3 python3-pip"
+    echo "  Fedora: sudo dnf install python3 python3-pip"
+    return 1
+}
+
+if ! command -v python3 &> /dev/null; then
+    install_python || exit 1
+fi
+
 PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
 PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
 PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
 
 if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 8 ]); then
-    echo "✗ Error: Python 3.8+ required (found $PYTHON_VERSION)"
-    exit 1
+    echo "Python $PYTHON_VERSION found but 3.8+ required."
+    install_python || exit 1
+    # Re-check after install
+    PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+    PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
+    PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
+    if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 8 ]); then
+        echo "✗ Error: Python 3.8+ still not available after install attempt"
+        exit 1
+    fi
 fi
 echo "✓ Python $PYTHON_VERSION"
 
+# Ensure pip3 is available
+if ! command -v pip3 &> /dev/null; then
+    echo "Installing pip..."
+    python3 -m ensurepip --upgrade 2>/dev/null || python3 -c "import urllib.request; urllib.request.urlretrieve('https://bootstrap.pypa.io/get-pip.py', '/tmp/get-pip.py')" && python3 /tmp/get-pip.py 2>/dev/null || true
+fi
+
 # Create installation directory
 echo ""
 echo "Creating installation directory..."
@@ -88,6 +157,13 @@ echo "Copying source files..."
 cp -r "${REPO_DIR}/src/"* "${INSTALL_DIR}/"
 echo "✓ Source files copied"
 
+# Copy learning modules explicitly (v2.7+ — ensures nested dir is handled)
+if [ -d "${REPO_DIR}/src/learning" ]; then
+    mkdir -p "${INSTALL_DIR}/learning"
+    cp -r "${REPO_DIR}/src/learning/"* "${INSTALL_DIR}/learning/"
+    echo "✓ Learning modules copied"
+fi
+
 # Copy hooks
 echo "Copying hooks..."
 mkdir -p "${INSTALL_DIR}/hooks"
@@ -205,6 +281,22 @@ else
     echo "⚠️  requirements-core.txt not found, skipping dependency installation"
 fi
 
+# Install learning dependencies (v2.7+)
+echo ""
+echo "Installing learning dependencies..."
+echo "  Enables intelligent pattern learning and personalized recall"
+
+if [ -f "${REPO_DIR}/requirements-learning.txt" ]; then
+    if pip3 install $PIP_FLAGS -q -r "${REPO_DIR}/requirements-learning.txt" 2>/dev/null; then
+        echo "✓ Learning dependencies installed (personalized ranking enabled)"
+    else
+        echo "○ Learning dependencies skipped (core features unaffected)"
+        echo "  To install later: pip3 install lightgbm scipy"
+    fi
+else
+    echo "○ requirements-learning.txt not found (learning features will use rule-based ranking)"
+fi
+
 # Initialize knowledge graph and pattern learning
 echo ""
 echo "Initializing advanced features..."
@@ -677,6 +769,10 @@ echo "  slm status"
 echo "  slm remember 'My first memory'"
 echo "  slm recall 'first'"
 echo ""
+echo "Learning System (v2.7+):"
+echo "  slm learning status              - Check learning system"
+echo "  slm engagement                   - View engagement metrics"
+echo ""
 # Optional: Offer to install optional features
 if [ "$NON_INTERACTIVE" = true ]; then
     INSTALL_CHOICE="N"

package/mcp_server.py

@@ -63,6 +63,15 @@ try:
 except ImportError:
     TRUST_AVAILABLE = False
 
+# Learning System (v2.7+)
+try:
+    sys.path.insert(0, str(Path(__file__).parent / "src"))
+    from learning import get_learning_db, get_adaptive_ranker, get_feedback_collector, get_engagement_tracker, get_status as get_learning_status
+    from learning import FULL_LEARNING_AVAILABLE, ML_RANKING_AVAILABLE
+    LEARNING_AVAILABLE = True
+except ImportError:
+    LEARNING_AVAILABLE = False
+
 def _sanitize_error(error: Exception) -> str:
     """Strip internal paths and structure from error messages."""
     msg = str(error)
@@ -165,6 +174,18 @@ def get_trust_scorer():
     return _trust_scorer
 
 
+def get_learning_components():
+    """Get learning system components. Returns None if unavailable."""
+    if not LEARNING_AVAILABLE:
+        return None
+    return {
+        'db': get_learning_db(),
+        'ranker': get_adaptive_ranker(),
+        'feedback': get_feedback_collector(),
+        'engagement': get_engagement_tracker(),
+    }
+
+
 def _register_mcp_agent(agent_name: str = "mcp-client"):
     """Register the calling MCP agent and record activity. Non-blocking."""
     registry = get_agent_registry()
@@ -335,6 +356,27 @@ async def recall(
         else:
             results = store.search(query, limit=limit)
 
+        # v2.7: Learning-based re-ranking (optional, graceful fallback)
+        if LEARNING_AVAILABLE:
+            try:
+                ranker = get_adaptive_ranker()
+                if ranker:
+                    results = ranker.rerank(results, query)
+            except Exception:
+                pass  # Re-ranking failure must never break recall
+
+        # Track recall for passive feedback decay
+        if LEARNING_AVAILABLE:
+            try:
+                feedback = get_feedback_collector()
+                if feedback:
+                    feedback.record_recall_results(query, [r.get('id') for r in results if r.get('id')])
+                tracker = get_engagement_tracker()
+                if tracker:
+                    tracker.record_activity('recall_performed', source='mcp')
+            except Exception:
+                pass  # Tracking failure must never break recall
+
         # Filter by minimum score
         filtered_results = [
             r for r in results
@@ -591,6 +633,212 @@ async def backup_status() -> dict:
         }
 
 
+# ============================================================================
+# LEARNING TOOLS (v2.7 — feedback, transparency, user control)
+# ============================================================================
+
+@mcp.tool(annotations=ToolAnnotations(
+    readOnlyHint=False,
+    destructiveHint=False,
+    openWorldHint=False,
+))
+async def memory_used(
+    memory_id: int,
+    query: str = "",
+    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.
+
+    This helps SuperLocalMemory learn which memories are most relevant
+    and improves future recall results.
+
+    Args:
+        memory_id: ID of the useful memory
+        query: The recall query that found it (optional)
+        usefulness: How useful - "high", "medium", or "low" (default "high")
+
+    Returns:
+        {"success": bool, "message": str}
+    """
+    try:
+        if not LEARNING_AVAILABLE:
+            return {"success": False, "message": "Learning features not available. Install: pip3 install lightgbm scipy"}
+
+        feedback = get_feedback_collector()
+        if feedback is None:
+            return {"success": False, "message": "Feedback collector not initialized"}
+
+        feedback.record_memory_used(
+            memory_id=memory_id,
+            query=query,
+            usefulness=usefulness,
+            source_tool="mcp-client",
+        )
+
+        return {
+            "success": True,
+            "message": f"Feedback recorded for memory #{memory_id} (usefulness: {usefulness})"
+        }
+    except Exception as e:
+        return {"success": False, "error": _sanitize_error(e)}
+
+
+@mcp.tool(annotations=ToolAnnotations(
+    readOnlyHint=True,
+    destructiveHint=False,
+    openWorldHint=False,
+))
+async def get_learned_patterns(
+    min_confidence: float = 0.6,
+    category: str = "all"
+) -> dict:
+    """
+    See what SuperLocalMemory has learned about your preferences,
+    projects, and workflow patterns.
+
+    Args:
+        min_confidence: Minimum confidence threshold 0.0-1.0 (default 0.6)
+        category: Filter by "tech", "workflow", "project", or "all" (default "all")
+
+    Returns:
+        {
+            "success": bool,
+            "patterns": {
+                "tech_preferences": [...],
+                "workflow_patterns": [...],
+            },
+            "ranking_phase": str,
+            "feedback_count": int
+        }
+    """
+    try:
+        if not LEARNING_AVAILABLE:
+            return {"success": False, "message": "Learning features not available. Install: pip3 install lightgbm scipy", "patterns": {}}
+
+        ldb = get_learning_db()
+        if ldb is None:
+            return {"success": False, "message": "Learning database not initialized", "patterns": {}}
+
+        result = {"success": True, "patterns": {}}
+
+        # Tech preferences (Layer 1)
+        if category in ("all", "tech"):
+            patterns = ldb.get_transferable_patterns(min_confidence=min_confidence)
+            result["patterns"]["tech_preferences"] = [
+                {
+                    "id": p["id"],
+                    "type": p["pattern_type"],
+                    "key": p["key"],
+                    "value": p["value"],
+                    "confidence": round(p["confidence"], 2),
+                    "evidence": p["evidence_count"],
+                    "profiles_seen": p["profiles_seen"],
+                }
+                for p in patterns
+            ]
+
+        # Workflow patterns (Layer 3)
+        if category in ("all", "workflow"):
+            workflows = ldb.get_workflow_patterns(min_confidence=min_confidence)
+            result["patterns"]["workflow_patterns"] = [
+                {
+                    "id": p["id"],
+                    "type": p["pattern_type"],
+                    "key": p["pattern_key"],
+                    "value": p["pattern_value"],
+                    "confidence": round(p["confidence"], 2),
+                }
+                for p in workflows
+            ]
+
+        # Ranking phase info
+        ranker = get_adaptive_ranker()
+        if ranker:
+            result["ranking_phase"] = ranker.get_phase()
+            result["feedback_count"] = ldb.get_feedback_count()
+
+        # Learning stats
+        result["stats"] = ldb.get_stats()
+
+        return result
+    except Exception as e:
+        return {"success": False, "error": _sanitize_error(e), "patterns": {}}
+
+
+@mcp.tool(annotations=ToolAnnotations(
+    readOnlyHint=False,
+    destructiveHint=False,
+    openWorldHint=False,
+))
+async def correct_pattern(
+    pattern_id: int,
+    correct_value: str,
+    reason: str = ""
+) -> dict:
+    """
+    Correct a learned pattern that is wrong. Use get_learned_patterns first
+    to see pattern IDs.
+
+    Args:
+        pattern_id: ID of the pattern to correct
+        correct_value: The correct value (e.g., "Vue" instead of "React")
+        reason: Why the correction (optional)
+
+    Returns:
+        {"success": bool, "message": str}
+    """
+    try:
+        if not LEARNING_AVAILABLE:
+            return {"success": False, "message": "Learning features not available"}
+
+        ldb = get_learning_db()
+        if ldb is None:
+            return {"success": False, "message": "Learning database not initialized"}
+
+        # Get existing pattern
+        conn = ldb._get_connection()
+        try:
+            cursor = conn.cursor()
+            cursor.execute('SELECT * FROM transferable_patterns WHERE id = ?', (pattern_id,))
+            pattern = cursor.fetchone()
+            if not pattern:
+                return {"success": False, "message": f"Pattern #{pattern_id} not found"}
+
+            old_value = pattern['value']
+
+            # Update the pattern with correction
+            ldb.upsert_transferable_pattern(
+                pattern_type=pattern['pattern_type'],
+                key=pattern['key'],
+                value=correct_value,
+                confidence=1.0,  # User correction = maximum confidence
+                evidence_count=pattern['evidence_count'] + 1,
+                profiles_seen=pattern['profiles_seen'],
+                contradictions=[f"Corrected from '{old_value}' to '{correct_value}': {reason}"],
+            )
+
+            # Record as negative feedback for the old value
+            feedback = get_feedback_collector()
+            if feedback:
+                feedback.record_memory_used(
+                    memory_id=0,  # No specific memory
+                    query=f"correction:{pattern['key']}",
+                    usefulness="low",
+                    source_tool="mcp-correction",
+                )
+
+            return {
+                "success": True,
+                "message": f"Pattern '{pattern['key']}' corrected: '{old_value}' → '{correct_value}'"
+            }
+        finally:
+            conn.close()
+    except Exception as e:
+        return {"success": False, "error": _sanitize_error(e)}
+
+
 # ============================================================================
 # CHATGPT CONNECTOR TOOLS (search + fetch — required by OpenAI MCP spec)
 # These two tools are required for ChatGPT Connectors and Deep Research.
@@ -758,6 +1006,41 @@ async def get_coding_identity_resource() -> str:
         return json.dumps({"error": _sanitize_error(e)}, indent=2)
 
 
+@mcp.resource("memory://learning/status")
+async def get_learning_status_resource() -> str:
+    """
+    Resource: Get learning system status.
+
+    Usage: memory://learning/status
+    """
+    try:
+        if not LEARNING_AVAILABLE:
+            return json.dumps({"available": False, "message": "Learning deps not installed"}, indent=2)
+        status = get_learning_status()
+        return json.dumps(status, indent=2)
+    except Exception as e:
+        return json.dumps({"error": _sanitize_error(e)}, indent=2)
+
+
+@mcp.resource("memory://engagement")
+async def get_engagement_resource() -> str:
+    """
+    Resource: Get engagement metrics.
+
+    Usage: memory://engagement
+    """
+    try:
+        if not LEARNING_AVAILABLE:
+            return json.dumps({"available": False}, indent=2)
+        tracker = get_engagement_tracker()
+        if tracker:
+            stats = tracker.get_engagement_stats()
+            return json.dumps(stats, indent=2)
+        return json.dumps({"available": False}, indent=2)
+    except Exception as e:
+        return json.dumps({"error": _sanitize_error(e)}, indent=2)
+
+
 # ============================================================================
 # MCP PROMPTS (Template injection)
 # ============================================================================
@@ -867,7 +1150,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.5.0", file=sys.stderr)
+    print("Version: 2.7.0", 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)
@@ -891,12 +1174,19 @@ if __name__ == "__main__":
     print("  - build_graph()", file=sys.stderr)
     print("  - switch_profile(name)", file=sys.stderr)
     print("  - backup_status()        [Auto-Backup]", file=sys.stderr)
+    if LEARNING_AVAILABLE:
+        print("  - memory_used(memory_id, query, usefulness)  [v2.7 Learning]", file=sys.stderr)
+        print("  - get_learned_patterns(min_confidence, category) [v2.7 Learning]", file=sys.stderr)
+        print("  - correct_pattern(pattern_id, correct_value) [v2.7 Learning]", file=sys.stderr)
     print("", file=sys.stderr)
     print("MCP Resources Available:", file=sys.stderr)
     print("  - memory://recent/{limit}", file=sys.stderr)
     print("  - memory://stats", file=sys.stderr)
     print("  - memory://graph/clusters", file=sys.stderr)
     print("  - memory://patterns/identity", file=sys.stderr)
+    if LEARNING_AVAILABLE:
+        print("  - memory://learning/status", file=sys.stderr)
+        print("  - memory://engagement", file=sys.stderr)
     print("", file=sys.stderr)
     print("MCP Prompts Available:", file=sys.stderr)
     print("  - coding_identity_prompt()", file=sys.stderr)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "2.6.5",
+  "version": "2.7.0",
   "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",
@@ -76,6 +76,7 @@
     "docs/",
     "requirements.txt",
     "requirements-core.txt",
+    "requirements-learning.txt",
     "ui/",
     "ui_server.py",
     "api_server.py"

package/requirements-learning.txt

@@ -0,0 +1,12 @@
+# SuperLocalMemory v2.7 - Learning Dependencies
+# ============================================================================
+# Optional but recommended. Enables intelligent pattern learning and
+# personalized recall ranking.
+#
+# If installation fails, core features work normally (v2.6 behavior).
+# To install: pip3 install -r requirements-learning.txt
+#
+# Download size: ~30MB
+# ============================================================================
+lightgbm>=4.0.0
+scipy>=1.9.0