superlocalmemory 3.0.37 → 3.1.0

package/src/superlocalmemory/mcp/resources.py

@@ -20,7 +20,32 @@ logger = logging.getLogger(__name__)
 
 
 def register_resources(server, get_engine: Callable) -> None:
-    """Register 6 MCP resources on *server*."""
+    """Register 7 MCP resources on *server*."""
+
+    # ------------------------------------------------------------------
+    # 0. slm://context — Active Memory auto-injection
+    # ------------------------------------------------------------------
+    @server.resource("slm://context")
+    async def session_context() -> str:
+        """Active session context — auto-injected on MCP connect.
+
+        Returns the most relevant memories for the current session:
+        recent decisions, active patterns, and project context.
+        AI tools read this automatically on connection to get instant context.
+        """
+        try:
+            from superlocalmemory.hooks.auto_recall import AutoRecall
+            engine = get_engine()
+            auto = AutoRecall(
+                engine=engine,
+                config={"enabled": True, "max_memories_injected": 10, "relevance_threshold": 0.3},
+            )
+            context = auto.get_session_context(query="recent decisions and important context")
+            if not context:
+                return "No session context available yet. Use 'remember' to store memories."
+            return context
+        except Exception as exc:
+            return f"Context unavailable: {exc}"
 
     # ------------------------------------------------------------------
     # 1. slm://recent

package/src/superlocalmemory/mcp/server.py

@@ -58,11 +58,13 @@ def reset_engine():
 from superlocalmemory.mcp.tools_core import register_core_tools
 from superlocalmemory.mcp.tools_v28 import register_v28_tools
 from superlocalmemory.mcp.tools_v3 import register_v3_tools
+from superlocalmemory.mcp.tools_active import register_active_tools
 from superlocalmemory.mcp.resources import register_resources
 
 register_core_tools(server, get_engine)
 register_v28_tools(server, get_engine)
 register_v3_tools(server, get_engine)
+register_active_tools(server, get_engine)
 register_resources(server, get_engine)
 
 

package/src/superlocalmemory/mcp/tools_active.py

@@ -0,0 +1,205 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3.1 — Active Memory MCP Tools.
+
+session_init    — Auto-recall project context at session start.
+observe         — Monitor conversation for auto-capture (decisions/bugs/prefs).
+report_feedback — Record explicit feedback on recall results for learning.
+
+These tools transform SLM from a passive database into an active
+intelligence layer that learns and improves over time.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+
+def register_active_tools(server, get_engine: Callable) -> None:
+    """Register 3 active memory tools on *server*."""
+
+    # ------------------------------------------------------------------
+    # 1. session_init — Auto-recall project context at session start
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def session_init(
+        project_path: str = "",
+        query: str = "",
+        max_results: int = 10,
+    ) -> dict:
+        """Initialize session with relevant memory context.
+
+        Call this ONCE at the start of every session. Returns:
+        - Recent decisions and patterns for this project
+        - Top relevant memories based on project path or query
+        - Learning status (signal count, ranking phase)
+
+        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
+
+            engine = get_engine()
+            rules = RulesEngine()
+
+            if not rules.should_recall("session_start"):
+                return {"success": True, "context": "", "memories": [], "message": "Auto-recall disabled"}
+
+            recall_config = rules.get_recall_config()
+            auto = AutoRecall(
+                engine=engine,
+                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)
+
+            # Get learning status
+            pid = engine.profile_id
+            feedback_count = 0
+            try:
+                feedback_count = engine._adaptive_learner.get_feedback_count(pid)
+            except Exception:
+                pass
+
+            return {
+                "success": True,
+                "context": context,
+                "memories": memories[:max_results],
+                "memory_count": len(memories),
+                "learning": {
+                    "feedback_signals": feedback_count,
+                    "phase": 1 if feedback_count < 50 else (2 if feedback_count < 200 else 3),
+                    "status": "collecting" if feedback_count < 50 else ("learning" if feedback_count < 200 else "trained"),
+                },
+            }
+        except Exception as exc:
+            logger.exception("session_init failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 2. observe — Auto-capture decisions/bugs/preferences
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def observe(
+        content: str,
+        agent_id: str = "mcp_client",
+    ) -> dict:
+        """Observe conversation content for automatic memory capture.
+
+        Send conversation snippets here. The system evaluates whether
+        the content contains decisions, bug fixes, or preferences worth
+        storing. If so, it auto-captures them with classification metadata.
+
+        Call this after making decisions, fixing bugs, or expressing preferences.
+        The system will NOT store low-confidence or irrelevant content.
+        """
+        try:
+            from superlocalmemory.hooks.auto_capture import AutoCapture
+            from superlocalmemory.hooks.rules_engine import RulesEngine
+
+            engine = get_engine()
+            rules = RulesEngine()
+
+            auto = AutoCapture(
+                engine=engine,
+                config=rules.get_capture_config(),
+            )
+
+            decision = auto.evaluate(content)
+
+            if not decision.capture:
+                return {
+                    "captured": False,
+                    "reason": decision.reason,
+                    "category": decision.category,
+                    "confidence": round(decision.confidence, 3),
+                }
+
+            # Check rules engine for category-level permission
+            if not rules.should_capture(decision.category, decision.confidence):
+                return {
+                    "captured": False,
+                    "reason": f"Category '{decision.category}' disabled in rules",
+                    "category": decision.category,
+                    "confidence": round(decision.confidence, 3),
+                }
+
+            # Auto-store via engine
+            stored = auto.capture(
+                content,
+                category=decision.category,
+                metadata={"agent_id": agent_id, "source": "auto-observe"},
+            )
+
+            return {
+                "captured": stored,
+                "category": decision.category,
+                "confidence": round(decision.confidence, 3),
+                "reason": decision.reason,
+            }
+        except Exception as exc:
+            logger.exception("observe failed")
+            return {"captured": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 3. report_feedback — Explicit feedback for learning
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def report_feedback(
+        fact_id: str,
+        feedback: str = "relevant",
+        query: str = "",
+    ) -> dict:
+        """Report whether a recalled memory was useful.
+
+        feedback: "relevant" (memory was helpful), "irrelevant" (not useful),
+                  "partial" (somewhat relevant).
+
+        This feedback trains the adaptive ranker to return better results
+        over time. The more feedback, the smarter the system gets.
+        """
+        try:
+            engine = get_engine()
+            pid = engine.profile_id
+
+            if feedback not in ("relevant", "irrelevant", "partial"):
+                return {"success": False, "error": f"Invalid feedback: {feedback}. Use relevant/irrelevant/partial"}
+
+            record = engine._adaptive_learner.record_feedback(
+                query=query,
+                fact_id=fact_id,
+                feedback_type=feedback,
+                profile_id=pid,
+            )
+
+            count = engine._adaptive_learner.get_feedback_count(pid)
+
+            return {
+                "success": True,
+                "feedback_id": record.feedback_id,
+                "total_signals": count,
+                "phase": 1 if count < 50 else (2 if count < 200 else 3),
+                "message": f"Feedback recorded. {count} total signals."
+                + (" Phase 2 unlocked!" if count == 50 else "")
+                + (" Phase 3 (ML) unlocked!" if count == 200 else ""),
+            }
+        except Exception as exc:
+            logger.exception("report_feedback failed")
+            return {"success": False, "error": str(exc)}

package/src/superlocalmemory/mcp/tools_core.py

@@ -20,6 +20,52 @@ from typing import Any, Callable
 logger = logging.getLogger(__name__)
 
 
+def _record_recall_hits(get_engine: Callable, query: str, results: list[dict]) -> None:
+    """Record implicit feedback + learning signals for each recall.
+
+    Non-blocking, non-critical — failures silently ignored.
+    Feeds: FeedbackCollector + Co-Retrieval + Confidence Boost.
+    """
+    try:
+        from pathlib import Path
+        engine = get_engine()
+        pid = engine.profile_id
+        slm_dir = Path.home() / ".superlocalmemory"
+        fact_ids = [r.get("fact_id", "") for r in results[:10] if r.get("fact_id")]
+        if not fact_ids:
+            return
+
+        # 1. Implicit feedback (recall_hit signals for adaptive learner)
+        try:
+            from superlocalmemory.learning.feedback import FeedbackCollector
+            collector = FeedbackCollector(slm_dir / "learning.db")
+            collector.record_implicit(
+                profile_id=pid, query=query,
+                fact_ids_returned=fact_ids, fact_ids_available=fact_ids,
+            )
+        except Exception:
+            pass
+
+        # 2. Co-retrieval signals (strengthen implicit graph edges)
+        try:
+            from superlocalmemory.learning.signals import LearningSignals
+            signals = LearningSignals(slm_dir / "learning.db")
+            signals.record_co_retrieval(pid, fact_ids)
+        except Exception:
+            pass
+
+        # 3. Confidence boost (accessed facts get +0.02, cap 1.0)
+        try:
+            from superlocalmemory.learning.signals import LearningSignals
+            mem_db = str(slm_dir / "memory.db")
+            for fid in fact_ids[:5]:
+                LearningSignals.boost_confidence(mem_db, fid)
+        except Exception:
+            pass
+    except Exception:
+        pass
+
+
 def register_core_tools(server, get_engine: Callable) -> None:
     """Register the 13 core MCP tools on *server*."""
 
@@ -57,6 +103,11 @@ def register_core_tools(server, get_engine: Callable) -> None:
             pool = WorkerPool.shared()
             result = pool.recall(query, limit=limit)
             if result.get("ok"):
+                # Record implicit feedback: every returned result is a recall_hit
+                try:
+                    _record_recall_hits(get_engine, query, result.get("results", []))
+                except Exception:
+                    pass  # Feedback is non-critical, never block recall
                 return {
                     "success": True,
                     "results": result.get("results", []),

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

@@ -45,9 +45,18 @@ async def behavioral_status():
         recent_outcomes = []
         try:
             tracker = OutcomeTracker(db_path)
-            total_outcomes = tracker.get_outcome_count(profile=profile)
-            outcome_breakdown = tracker.get_outcome_breakdown(profile=profile)
-            recent_outcomes = tracker.get_recent_outcomes(profile=profile, limit=20)
+            all_outcomes = tracker.get_outcomes(profile_id=profile, limit=50)
+            total_outcomes = len(all_outcomes)
+            for o in all_outcomes:
+                key = o.outcome if hasattr(o, 'outcome') else str(o)
+                if key in outcome_breakdown:
+                    outcome_breakdown[key] += 1
+            recent_outcomes = [
+                {"outcome": o.outcome, "action_type": o.action_type,
+                 "timestamp": o.timestamp}
+                for o in all_outcomes[:20]
+                if hasattr(o, 'outcome')
+            ]
         except Exception as exc:
             logger.debug("outcome tracker: %s", exc)
 
@@ -56,8 +65,8 @@ async def behavioral_status():
         cross_project_transfers = 0
         try:
             store = BehavioralPatternStore(db_path)
-            patterns = store.get_patterns(profile=profile)
-            cross_project_transfers = store.get_cross_project_count(profile=profile)
+            patterns = store.get_patterns(profile_id=profile)
+            cross_project_transfers = 0
         except Exception as exc:
             logger.debug("pattern store: %s", exc)
 
@@ -69,6 +78,12 @@ async def behavioral_status():
             "patterns": patterns,
             "cross_project_transfers": cross_project_transfers,
             "recent_outcomes": recent_outcomes,
+            "stats": {
+                "success_count": outcome_breakdown.get("success", 0),
+                "failure_count": outcome_breakdown.get("failure", 0),
+                "partial_count": outcome_breakdown.get("partial", 0),
+                "patterns_count": len(patterns),
+            },
         }
     except Exception as e:
         logger.error("behavioral_status error: %s", e)

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

@@ -79,22 +79,45 @@ async def learning_status():
         active_profile = get_active_profile()
         result["active_profile"] = active_profile
 
-        # Ranking phase
-        result["ranking_phase"] = "baseline"
+        # Real signal count from V3.1 learning_feedback table
+        signal_count = 0
+        try:
+            from superlocalmemory.learning.feedback import FeedbackCollector
+            from pathlib import Path
+            learning_db = Path.home() / ".superlocalmemory" / "learning.db"
+            if learning_db.exists():
+                collector = FeedbackCollector(learning_db)
+                signal_count = collector.get_feedback_count(active_profile)
+        except Exception:
+            pass
+
+        # Ranking phase based on real signal count
+        if signal_count >= 200:
+            result["ranking_phase"] = "ml_model"
+        elif signal_count >= 20:
+            result["ranking_phase"] = "rule_based"
+        else:
+            result["ranking_phase"] = "baseline"
 
-        # Feedback stats
+        # Feedback stats — merge old system + new V3.1 signals
+        stats_dict = {"feedback_count": signal_count, "active_profile": active_profile}
         feedback = _get_feedback()
         if feedback:
             try:
-                summary = feedback.get_feedback_summary()
-                result["stats"] = summary
-                result["profile_feedback"] = {
-                    "profile": active_profile,
-                    "signals": summary.get("total_signals", 0),
-                }
+                old_stats = feedback.get_feedback_summary()
+                if isinstance(old_stats, dict):
+                    old_stats["feedback_count"] = signal_count
+                    old_stats["active_profile"] = active_profile
+                    stats_dict = old_stats
             except Exception as exc:
                 logger.debug("feedback summary: %s", exc)
 
+        result["stats"] = stats_dict
+        result["profile_feedback"] = {
+            "profile": active_profile,
+            "signals": signal_count,
+        }
+
         # Engagement
         engagement = _get_engagement()
         if engagement:
@@ -105,9 +128,43 @@ async def learning_status():
         else:
             result["engagement"] = None
 
-        # Tech preferences (stub until learning DB populated)
-        result["tech_preferences"] = []
-        result["workflow_patterns"] = []
+        # Tech preferences + workflow patterns from V3.1 behavioral store
+        try:
+            from superlocalmemory.learning.behavioral import BehavioralPatternStore
+            from pathlib import Path
+            learning_db = Path.home() / ".superlocalmemory" / "learning.db"
+            if learning_db.exists():
+                store = BehavioralPatternStore(str(learning_db))
+                all_patterns = store.get_patterns(profile_id=active_profile)
+                tech = [
+                    {"key": "tech", "value": p.get("metadata", {}).get("value", p.get("pattern_key", "")),
+                     "confidence": p.get("confidence", 0), "evidence": p.get("evidence_count", 0)}
+                    for p in all_patterns if p.get("pattern_type") == "tech_preference"
+                ]
+                workflows = [
+                    {"type": p.get("pattern_type"), "key": p.get("pattern_key", ""),
+                     "value": p.get("metadata", {}).get("value", ""),
+                     "confidence": p.get("confidence", 0)}
+                    for p in all_patterns if p.get("pattern_type") in ("temporal", "interest")
+                ]
+                result["tech_preferences"] = tech
+                result["workflow_patterns"] = workflows
+
+                # Privacy stats
+                import os
+                db_size = os.path.getsize(str(learning_db)) // 1024 if learning_db.exists() else 0
+                stats_dict["db_size_kb"] = db_size
+                stats_dict["transferable_patterns"] = len(all_patterns)
+                stats_dict["models_trained"] = 1 if signal_count >= 200 else 0
+                stats_dict["tracked_sources"] = len(set(
+                    p.get("pattern_type") for p in all_patterns
+                ))
+            else:
+                result["tech_preferences"] = []
+                result["workflow_patterns"] = []
+        except Exception:
+            result["tech_preferences"] = []
+            result["workflow_patterns"] = []
         result["source_scores"] = {}
 
     except Exception as e:

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

@@ -13,7 +13,7 @@ from typing import Optional
 
 from fastapi import APIRouter, HTTPException, Query
 
-from .helpers import get_db_connection, dict_factory, get_active_profile, DB_PATH
+from .helpers import get_db_connection, dict_factory, get_active_profile, DB_PATH, MEMORY_DIR
 
 logger = logging.getLogger("superlocalmemory.routes.stats")
 router = APIRouter()
@@ -306,10 +306,38 @@ async def get_patterns():
 
         if not table_name:
             conn.close()
-            return {
-                "patterns": {}, "total_patterns": 0, "pattern_types": [],
-                "message": "Pattern learning not initialized.",
-            }
+            # Fall through to V3.1 behavioral pattern store
+            try:
+                from superlocalmemory.learning.behavioral import BehavioralPatternStore
+                store = BehavioralPatternStore(str(MEMORY_DIR / "learning.db"))
+                raw = store.get_patterns(profile_id=active_profile)
+                grouped = defaultdict(list)
+                for p in raw:
+                    meta = p.get("metadata", {})
+                    grouped[p["pattern_type"]].append({
+                        "pattern_type": p["pattern_type"],
+                        "key": meta.get("key", p.get("pattern_key", "")),
+                        "value": meta.get("value", p.get("pattern_key", "")),
+                        "confidence": p.get("confidence", 0),
+                        "evidence_count": p.get("evidence_count", 0),
+                    })
+                all_patterns = [p for ps in grouped.values() for p in ps]
+                confs = [p["confidence"] for p in all_patterns if p.get("confidence")]
+                return {
+                    "patterns": dict(grouped),
+                    "total_patterns": len(all_patterns),
+                    "pattern_types": list(grouped.keys()),
+                    "confidence_stats": {
+                        "avg": sum(confs) / len(confs) if confs else 0,
+                        "min": min(confs) if confs else 0,
+                        "max": max(confs) if confs else 0,
+                    },
+                }
+            except Exception:
+                return {
+                    "patterns": {}, "total_patterns": 0, "pattern_types": [],
+                    "message": "Pattern learning not initialized.",
+                }
 
         if table_name == 'identity_patterns':
             cursor.execute("""

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

@@ -339,6 +339,13 @@ async def recall_trace(request: Request):
             except Exception:
                 pass
 
+        # Record learning signals (non-blocking, non-critical)
+        try:
+            _record_learning_signals(query, result.get("results", []))
+        except Exception as _sig_exc:
+            import logging as _log
+            _log.getLogger(__name__).warning("Learning signal error: %s", _sig_exc)
+
         return {
             "query": query,
             "query_type": result.get("query_type", "unknown"),
@@ -351,6 +358,44 @@ async def recall_trace(request: Request):
         return JSONResponse({"error": str(e)}, status_code=500)
 
 
+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"
+    config = SLMConfig.load()
+    pid = config.active_profile
+    fact_ids = [r.get("fact_id", "") for r in results[:10] if r.get("fact_id")]
+    if not fact_ids:
+        return
+
+    try:
+        from superlocalmemory.learning.feedback import FeedbackCollector
+        collector = FeedbackCollector(slm_dir / "learning.db")
+        collector.record_implicit(
+            profile_id=pid, query=query,
+            fact_ids_returned=fact_ids, fact_ids_available=fact_ids,
+        )
+    except Exception:
+        pass
+
+    try:
+        from superlocalmemory.learning.signals import LearningSignals
+        signals = LearningSignals(slm_dir / "learning.db")
+        signals.record_co_retrieval(pid, fact_ids)
+    except Exception:
+        pass
+
+    try:
+        from superlocalmemory.learning.signals import LearningSignals
+        mem_db = str(slm_dir / "memory.db")
+        for fid in fact_ids[:5]:
+            LearningSignals.boost_confidence(mem_db, fid)
+    except Exception:
+        pass
+
+
 # ── Trust Dashboard ──────────────────────────────────────────
 
 @router.get("/trust/dashboard")
@@ -521,3 +566,51 @@ async def ide_connect(request: Request):
             return {"results": results}
     except Exception as e:
         return JSONResponse({"error": str(e)}, status_code=500)
+
+
+# ── Active Memory (V3.1) ────────────────────────────────────
+
+@router.get("/learning/signals")
+async def learning_signals():
+    """Get zero-cost learning signal statistics."""
+    try:
+        from superlocalmemory.learning.signals import LearningSignals
+        from superlocalmemory.core.config import SLMConfig
+        from superlocalmemory.server.routes.helpers import DB_PATH
+        learning_db = DB_PATH.parent / "learning.db"
+        signals = LearningSignals(learning_db)
+        config = SLMConfig.load()
+        pid = config.active_profile
+        return {"success": True, **signals.get_signal_stats(pid)}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+@router.post("/learning/consolidate")
+async def run_consolidation(request: Request):
+    """Run sleep-time consolidation. Body: {dry_run: true/false}."""
+    try:
+        body = await request.json()
+        dry_run = body.get("dry_run", False)
+        from superlocalmemory.learning.consolidation_worker import ConsolidationWorker
+        from superlocalmemory.core.config import SLMConfig
+        from superlocalmemory.server.routes.helpers import DB_PATH
+        worker = ConsolidationWorker(
+            memory_db=str(DB_PATH),
+            learning_db=str(DB_PATH.parent / "learning.db"),
+        )
+        config = SLMConfig.load()
+        stats = worker.run(config.active_profile, dry_run=dry_run)
+        return {"success": True, **stats}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+@router.get("/hooks/status")
+async def hooks_status():
+    """Check if Claude Code hooks are installed."""
+    try:
+        from superlocalmemory.hooks.claude_code_hooks import check_status
+        return {"success": True, **check_status()}
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}