superlocalmemory 2.6.0 → 2.7.0

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.0",
+  "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

package/scripts/verify-v27.sh

@@ -0,0 +1,233 @@
+#!/bin/bash
+# ============================================================================
+# SuperLocalMemory V2.7 — Quick Verification Script
+# Copyright (c) 2026 Varun Pratap Bhardwaj
+# Licensed under MIT License
+# Repository: https://github.com/varun369/SuperLocalMemoryV2
+#
+# Run this after installation to verify everything works:
+#   bash scripts/verify-v27.sh
+# ============================================================================
+
+INSTALL_DIR="${HOME}/.claude-memory"
+PASS=0
+WARN=0
+FAIL=0
+
+echo ""
+echo "SuperLocalMemory v2.7 Verification"
+echo "==================================="
+echo ""
+
+# ── Check 1: Installation directory ──────────────────────────────────────────
+if [ -d "$INSTALL_DIR" ]; then
+    echo "[PASS] Installation directory exists: $INSTALL_DIR"
+    PASS=$((PASS + 1))
+else
+    echo "[FAIL] Installation directory missing. Run install.sh first."
+    FAIL=$((FAIL + 1))
+    echo ""
+    echo "==================================="
+    echo "Result: FAIL — SuperLocalMemory is not installed."
+    echo "Run:  bash install.sh"
+    exit 1
+fi
+
+# ── Check 2: Core modules ────────────────────────────────────────────────────
+echo ""
+echo "Core Modules:"
+for mod in memory_store_v2.py graph_engine.py pattern_learner.py mcp_server.py tree_manager.py; do
+    if [ -f "$INSTALL_DIR/$mod" ]; then
+        echo "  [PASS] $mod"
+        PASS=$((PASS + 1))
+    else
+        echo "  [FAIL] Missing: $mod"
+        FAIL=$((FAIL + 1))
+    fi
+done
+
+# ── Check 3: v2.5 modules ────────────────────────────────────────────────────
+echo ""
+echo "Event System (v2.5):"
+for mod in event_bus.py subscription_manager.py webhook_dispatcher.py agent_registry.py provenance_tracker.py trust_scorer.py db_connection_manager.py; do
+    if [ -f "$INSTALL_DIR/$mod" ]; then
+        echo "  [PASS] $mod"
+        PASS=$((PASS + 1))
+    else
+        echo "  [WARN] Missing: $mod (v2.5 feature)"
+        WARN=$((WARN + 1))
+    fi
+done
+
+# ── Check 4: Learning modules (v2.7) ─────────────────────────────────────────
+echo ""
+echo "Learning System (v2.7):"
+if [ -d "$INSTALL_DIR/learning" ]; then
+    echo "  [PASS] learning/ directory exists"
+    PASS=$((PASS + 1))
+
+    for mod in __init__.py learning_db.py adaptive_ranker.py feedback_collector.py \
+               engagement_tracker.py cross_project_aggregator.py project_context_manager.py \
+               workflow_pattern_miner.py source_quality_scorer.py synthetic_bootstrap.py \
+               feature_extractor.py; do
+        if [ -f "$INSTALL_DIR/learning/$mod" ]; then
+            echo "  [PASS] learning/$mod"
+            PASS=$((PASS + 1))
+        else
+            echo "  [WARN] Missing: learning/$mod"
+            WARN=$((WARN + 1))
+        fi
+    done
+else
+    echo "  [FAIL] learning/ directory missing (v2.7 not fully installed)"
+    FAIL=$((FAIL + 1))
+fi
+
+# ── Check 5: Learning dependencies ───────────────────────────────────────────
+echo ""
+echo "Learning Dependencies:"
+python3 -c "import lightgbm; print(f'  [PASS] LightGBM {lightgbm.__version__}')" 2>/dev/null || {
+    echo "  [INFO] LightGBM not installed (optional — rule-based ranking will be used)"
+    WARN=$((WARN + 1))
+}
+python3 -c "import scipy; print(f'  [PASS] SciPy {scipy.__version__}')" 2>/dev/null || {
+    echo "  [INFO] SciPy not installed (optional — install for full learning features)"
+    WARN=$((WARN + 1))
+}
+
+# ── Check 6: Core dependencies ───────────────────────────────────────────────
+echo ""
+echo "Core Dependencies:"
+python3 -c "import sklearn; print(f'  [PASS] scikit-learn {sklearn.__version__}')" 2>/dev/null || {
+    echo "  [WARN] scikit-learn not installed (needed for knowledge graph)"
+    WARN=$((WARN + 1))
+}
+python3 -c "import numpy; print(f'  [PASS] numpy {numpy.__version__}')" 2>/dev/null || {
+    echo "  [WARN] numpy not installed"
+    WARN=$((WARN + 1))
+}
+python3 -c "import igraph; print(f'  [PASS] python-igraph {igraph.__version__}')" 2>/dev/null || {
+    echo "  [WARN] python-igraph not installed (needed for graph clustering)"
+    WARN=$((WARN + 1))
+}
+
+# ── Check 7: Database ────────────────────────────────────────────────────────
+echo ""
+echo "Databases:"
+if [ -f "$INSTALL_DIR/memory.db" ]; then
+    MEMORY_COUNT=$(sqlite3 "$INSTALL_DIR/memory.db" "SELECT COUNT(*) FROM memories;" 2>/dev/null || echo "0")
+    DB_SIZE=$(du -h "$INSTALL_DIR/memory.db" 2>/dev/null | cut -f1)
+    echo "  [PASS] memory.db exists ($MEMORY_COUNT memories, $DB_SIZE)"
+    PASS=$((PASS + 1))
+else
+    echo "  [INFO] memory.db not yet created (will auto-create on first use)"
+fi
+
+if [ -f "$INSTALL_DIR/learning.db" ]; then
+    FEEDBACK_COUNT=$(sqlite3 "$INSTALL_DIR/learning.db" "SELECT COUNT(*) FROM ranking_feedback;" 2>/dev/null || echo "0")
+    echo "  [PASS] learning.db exists ($FEEDBACK_COUNT feedback signals)"
+    PASS=$((PASS + 1))
+else
+    echo "  [INFO] learning.db not yet created (will auto-create on first recall)"
+fi
+
+# ── Check 8: CLI ──────────────────────────────────────────────────────────────
+echo ""
+echo "CLI:"
+if command -v slm &> /dev/null; then
+    echo "  [PASS] slm command available in PATH"
+    PASS=$((PASS + 1))
+else
+    if [ -f "$INSTALL_DIR/bin/slm" ]; then
+        echo "  [WARN] slm exists at $INSTALL_DIR/bin/slm but not in PATH"
+        echo "         Add to PATH: export PATH=\"\$HOME/.claude-memory/bin:\$PATH\""
+        WARN=$((WARN + 1))
+    else
+        echo "  [FAIL] slm command not found"
+        FAIL=$((FAIL + 1))
+    fi
+fi
+
+# ── Check 9: MCP server ──────────────────────────────────────────────────────
+echo ""
+echo "MCP Server:"
+if [ -f "$INSTALL_DIR/mcp_server.py" ]; then
+    echo "  [PASS] mcp_server.py installed"
+    PASS=$((PASS + 1))
+else
+    echo "  [FAIL] mcp_server.py missing"
+    FAIL=$((FAIL + 1))
+fi
+
+if python3 -c "from mcp.server.fastmcp import FastMCP" 2>/dev/null; then
+    echo "  [PASS] MCP SDK installed"
+    PASS=$((PASS + 1))
+else
+    echo "  [WARN] MCP SDK not installed (install: pip3 install mcp)"
+    WARN=$((WARN + 1))
+fi
+
+# ── Check 10: Import chain verification ───────────────────────────────────────
+echo ""
+echo "Import Chain:"
+IMPORT_RESULT=$(python3 -c "
+import sys
+sys.path.insert(0, '$INSTALL_DIR')
+try:
+    from learning import get_learning_db, get_status, FULL_LEARNING_AVAILABLE, ML_RANKING_AVAILABLE
+    status = get_status()
+    ml = 'yes' if status['ml_ranking_available'] else 'no'
+    full = 'yes' if status['learning_available'] else 'no'
+    print(f'OK ml_ranking={ml} full_learning={full}')
+except ImportError as e:
+    print(f'IMPORT_ERROR {e}')
+except Exception as e:
+    print(f'ERROR {e}')
+" 2>&1)
+
+if [[ "$IMPORT_RESULT" == OK* ]]; then
+    echo "  [PASS] Learning system imports successfully"
+    echo "         $IMPORT_RESULT"
+    PASS=$((PASS + 1))
+elif [[ "$IMPORT_RESULT" == IMPORT_ERROR* ]]; then
+    echo "  [WARN] Learning import failed: ${IMPORT_RESULT#IMPORT_ERROR }"
+    echo "         This may be normal if learning modules are not yet installed."
+    WARN=$((WARN + 1))
+else
+    echo "  [WARN] Learning check: $IMPORT_RESULT"
+    WARN=$((WARN + 1))
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "==================================="
+echo "Verification Summary"
+echo "  Passed:   $PASS"
+echo "  Warnings: $WARN"
+echo "  Failed:   $FAIL"
+echo "==================================="
+echo ""
+
+if [ $FAIL -eq 0 ]; then
+    echo "Status: READY"
+    echo ""
+    echo "Quick start:"
+    echo "  slm remember \"My first memory\""
+    echo "  slm recall \"first\""
+    echo "  slm status"
+    echo ""
+    if [ $WARN -gt 0 ]; then
+        echo "Some optional features may not be available."
+        echo "Install missing dependencies to enable them:"
+        echo "  pip3 install lightgbm scipy        # Learning system"
+        echo "  pip3 install scikit-learn igraph    # Knowledge graph"
+        echo ""
+    fi
+else
+    echo "Status: INCOMPLETE"
+    echo ""
+    echo "Fix the failed checks above, then re-run:"
+    echo "  bash scripts/verify-v27.sh"
+    echo ""
+    exit 1
+fi