superlocalmemory 3.0.37 → 3.1.1

package/README.md

@@ -84,7 +84,7 @@ slm status
 }
 ```
 
-24 MCP tools available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools.
+27 MCP tools + 7 resources available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools. **V3.1: Active Memory tools auto-learn your patterns.**
 
 ### Dual Interface: MCP + CLI
 
@@ -247,6 +247,42 @@ slm dashboard    # Opens at http://localhost:8765
 
 ---
 
+## Active Memory (V3.1) — Memory That Learns
+
+Most AI memory systems are passive databases — you store, you search, you get results. **SuperLocalMemory learns.**
+
+Every recall you make generates learning signals. Over time, the system adapts to your patterns:
+
+| Phase | Signals | What Happens |
+|-------|---------|-------------|
+| **Baseline** | 0-19 | Cross-encoder ranking (default behavior) |
+| **Rule-Based** | 20+ | Heuristic boosts: recency, access count, trust score |
+| **ML Model** | 200+ | LightGBM model trained on YOUR usage patterns |
+
+### Zero-Cost Learning Signals
+No LLM tokens spent. Four mathematical signals computed locally:
+- **Co-Retrieval** — memories retrieved together strengthen their connections
+- **Confidence Lifecycle** — accessed facts get boosted, unused facts decay
+- **Channel Performance** — tracks which retrieval channel works best for your queries
+- **Entropy Gap** — surprising content gets prioritized for deeper indexing
+
+### Auto-Capture & Auto-Recall
+```bash
+slm hooks install     # Install Claude Code hooks for invisible injection
+slm observe "We decided to use PostgreSQL"  # Auto-detects decisions, bugs, preferences
+slm session-context   # Get relevant context at session start
+```
+
+### MCP Active Memory Tools
+Three new tools for AI assistants:
+- `session_init` — call at session start, get relevant project context automatically
+- `observe` — send conversation content, auto-captures decisions/bugs/preferences
+- `report_feedback` — explicit feedback for faster learning
+
+**No competitor learns at zero token cost.** Mem0, Zep, and Letta all require cloud LLM calls for their learning loops. SLM learns through mathematics.
+
+---
+
 ## Features
 
 ### Retrieval

package/docs/getting-started.md

@@ -2,7 +2,7 @@
 > SuperLocalMemory V3 Documentation
 > https://superlocalmemory.com | Part of Qualixar
 
-Get your AI's memory system running in under 5 minutes.
+Get your AI's memory system running in under 5 minutes. **V3.1: Now with Active Memory — your memory learns from your usage and gets smarter over time, at zero token cost.**
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.0.37",
+  "version": "3.1.1",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.0.37"
+version = "3.1.1"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}
@@ -26,6 +26,7 @@ dependencies = [
     "fastapi[all]>=0.135.1",
     "uvicorn>=0.42.0",
     "websockets>=16.0",
+    "lightgbm>=4.0.0",
 ]
 
 [project.optional-dependencies]

package/src/superlocalmemory/cli/commands.py

@@ -37,6 +37,9 @@ def dispatch(args: Namespace) -> None:
         "warmup": cmd_warmup,
         "dashboard": cmd_dashboard,
         "profile": cmd_profile,
+        "hooks": cmd_hooks,
+        "session-context": cmd_session_context,
+        "observe": cmd_observe,
     }
     handler = handlers.get(args.command)
     if handler:
@@ -288,6 +291,12 @@ def cmd_recall(args: Namespace) -> None:
         ])
         return
 
+    # Record learning signals (CLI path — works without MCP)
+    try:
+        _cli_record_signals(config, args.query, response.results)
+    except Exception:
+        pass
+
     if not response.results:
         print("No memories found.")
         return
@@ -295,6 +304,26 @@ def cmd_recall(args: Namespace) -> None:
         print(f"  {i}. [{r.score:.2f}] {r.fact.content[:120]}")
 
 
+def _cli_record_signals(config, query, results):
+    """Record learning signals from CLI recall (no MCP dependency)."""
+    from pathlib import Path
+    from superlocalmemory.learning.feedback import FeedbackCollector
+    from superlocalmemory.learning.signals import LearningSignals
+    slm_dir = Path.home() / ".superlocalmemory"
+    pid = config.active_profile
+    fact_ids = [r.fact.fact_id for r in results[:10]]
+    if not fact_ids:
+        return
+    FeedbackCollector(slm_dir / "learning.db").record_implicit(
+        profile_id=pid, query=query,
+        fact_ids_returned=fact_ids, fact_ids_available=fact_ids,
+    )
+    signals = LearningSignals(slm_dir / "learning.db")
+    signals.record_co_retrieval(pid, fact_ids)
+    for fid in fact_ids[:5]:
+        LearningSignals.boost_confidence(str(slm_dir / "memory.db"), fid)
+
+
 def cmd_forget(args: Namespace) -> None:
     """Delete memories matching a query."""
     from superlocalmemory.core.engine import MemoryEngine
@@ -763,3 +792,96 @@ def cmd_profile(args: Namespace) -> None:
         )
         ensure_profile_in_json(args.name)
         print(f"Created profile: {args.name}")
+
+
+# -- Active Memory commands (V3.1) ------------------------------------------
+
+
+def cmd_hooks(args: Namespace) -> None:
+    """Manage Claude Code hooks for invisible memory injection."""
+    from superlocalmemory.hooks.claude_code_hooks import (
+        install_hooks, remove_hooks, check_status,
+    )
+
+    action = getattr(args, "action", "status")
+    if action == "install":
+        result = install_hooks()
+        if result["scripts"] and result["settings"]:
+            print("SLM hooks installed in Claude Code.")
+            print("Memory context will auto-inject on every new session.")
+        else:
+            print(f"Installation incomplete: {result['errors']}")
+    elif action == "remove":
+        result = remove_hooks()
+        if result["scripts"] and result["settings"]:
+            print("SLM hooks removed from Claude Code.")
+        else:
+            print(f"Removal incomplete: {result['errors']}")
+    else:
+        result = check_status()
+        if result["installed"]:
+            print("SLM hooks: INSTALLED")
+            print(f"  Scripts: {result['hooks_dir']}")
+            print("  Claude Code settings: configured")
+        else:
+            print("SLM hooks: NOT INSTALLED")
+            print("  Run: slm hooks install")
+
+
+def cmd_session_context(args: Namespace) -> None:
+    """Print session context (for hook scripts and piping)."""
+    from superlocalmemory.hooks.auto_recall import AutoRecall
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.engine import MemoryEngine
+
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        auto = AutoRecall(
+            engine=engine,
+            config={"enabled": True, "max_memories_injected": 10, "relevance_threshold": 0.3},
+        )
+        context = auto.get_session_context(
+            query=getattr(args, "query", "") or "recent decisions and important context",
+        )
+        if context:
+            print(context)
+    except Exception as exc:
+        logger.debug("session-context failed: %s", exc)
+
+
+def cmd_observe(args: Namespace) -> None:
+    """Evaluate and auto-capture content from stdin or argument."""
+    import sys
+    from superlocalmemory.hooks.auto_capture import AutoCapture
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.engine import MemoryEngine
+
+    content = getattr(args, "content", "") or ""
+    if not content and not sys.stdin.isatty():
+        content = sys.stdin.read().strip()
+
+    if not content:
+        print("No content to observe.")
+        return
+
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        auto = AutoCapture(engine=engine)
+        decision = auto.evaluate(content)
+
+        if decision.capture:
+            stored = auto.capture(content, category=decision.category)
+            if stored:
+                print(f"Auto-captured: {decision.category} (confidence: {decision.confidence:.2f})")
+            else:
+                print(f"Detected {decision.category} but store failed.")
+        else:
+            print(f"Not captured: {decision.reason}")
+    except Exception as exc:
+        logger.debug("observe failed: %s", exc)

package/src/superlocalmemory/cli/main.py

@@ -170,6 +170,19 @@ def main() -> None:
     profile_p.add_argument("name", nargs="?", help="Profile name")
     profile_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
+    # -- Active Memory (V3.1) ------------------------------------------
+    hooks_p = sub.add_parser("hooks", help="Manage Claude Code hooks for auto memory injection")
+    hooks_p.add_argument(
+        "action", nargs="?", default="status",
+        choices=["install", "remove", "status"], help="Action (default: status)",
+    )
+
+    ctx_p = sub.add_parser("session-context", help="Print session context (for hooks)")
+    ctx_p.add_argument("query", nargs="?", default="", help="Optional context query")
+
+    obs_p = sub.add_parser("observe", help="Auto-capture content (pipe or argument)")
+    obs_p.add_argument("content", nargs="?", default="", help="Content to evaluate")
+
     args = parser.parse_args()
 
     if not args.command:

package/src/superlocalmemory/core/engine.py

@@ -460,6 +460,15 @@ class MemoryEngine:
                 except Exception as exc:
                     logger.debug("Agentic sufficiency skipped: %s", exc)
 
+        # Adaptive re-ranking (V3.1 Active Memory)
+        # Phase 1 (< 50 signals): no change (cross-encoder order preserved)
+        # Phase 2 (50+): heuristic boosts (recency, access, trust)
+        # Phase 3 (200+): LightGBM ML ranking
+        try:
+            response = self._apply_adaptive_ranking(response, query, pid)
+        except Exception as exc:
+            logger.debug("Adaptive ranking skipped: %s", exc)
+
         # Reconsolidation: access updates trust + count (neuroscience principle)
         if self._trust_scorer:
             for r in response.results:
@@ -614,6 +623,60 @@ class MemoryEngine:
         if not self._initialized:
             self.initialize()
 
+    def _apply_adaptive_ranking(self, response, query: str, pid: str):
+        """Apply adaptive re-ranking if enough learning signals exist.
+
+        Phase 1 (< 50 signals): returns response unchanged (backward compat).
+        Phase 2 (50+): heuristic boosts from recency, access count, trust.
+        Phase 3 (200+): LightGBM ML-based reranking.
+        """
+        from superlocalmemory.learning.feedback import FeedbackCollector
+        from pathlib import Path
+
+        learning_db = Path.home() / ".superlocalmemory" / "learning.db"
+        if not learning_db.exists():
+            return response
+
+        collector = FeedbackCollector(learning_db)
+        signal_count = collector.get_feedback_count(pid)
+
+        if signal_count < 50:
+            return response  # Phase 1: no change
+
+        from superlocalmemory.learning.ranker import AdaptiveRanker
+        ranker = AdaptiveRanker(signal_count=signal_count)
+
+        result_dicts = []
+        for r in response.results:
+            result_dicts.append({
+                "score": r.score,
+                "cross_encoder_score": r.score,
+                "trust_score": r.trust_score,
+                "channel_scores": r.channel_scores or {},
+                "fact": {
+                    "age_days": 0,
+                    "access_count": r.fact.access_count,
+                },
+                "_original": r,
+            })
+
+        query_context = {"query_type": response.query_type}
+        reranked = ranker.rerank(result_dicts, query_context)
+
+        # Rebuild response with new ordering
+        new_results = [d["_original"] for d in reranked]
+
+        from superlocalmemory.storage.models import RecallResponse
+        return RecallResponse(
+            query=response.query,
+            mode=response.mode,
+            results=new_results,
+            query_type=response.query_type,
+            channel_weights=response.channel_weights,
+            total_candidates=response.total_candidates,
+            retrieval_time_ms=response.retrieval_time_ms,
+        )
+
     def _init_encoding(self) -> None:
         from superlocalmemory.encoding.fact_extractor import FactExtractor
         from superlocalmemory.encoding.entity_resolver import EntityResolver

package/src/superlocalmemory/core/summarizer.py

@@ -94,14 +94,13 @@ class Summarizer:
     # ------------------------------------------------------------------
 
     def _has_llm(self) -> bool:
-        """Check if LLM is available (AND warm for Ollama).
+        """Check if LLM is available.
 
-        For Mode B (Ollama): only returns True if the model is already
-        loaded in memory. NEVER triggers a cold model load — that would
-        spike 5+ GB of RAM on every recall, unacceptable on ≤32 GB machines.
+        Mode B: Ollama assumed running (num_ctx: 4096 caps memory at 5.5 GB).
+        Mode C: Requires API key for cloud provider.
         """
         if self._mode == "b":
-            return self._is_ollama_model_warm()
+            return True
         if self._mode == "c":
             return bool(
                 os.environ.get("OPENROUTER_API_KEY")
@@ -109,27 +108,6 @@ class Summarizer:
             )
         return False
 
-    def _is_ollama_model_warm(self) -> bool:
-        """Check if the LLM model is already loaded in Ollama memory.
-
-        Queries Ollama /api/ps. Returns True only if our model is loaded,
-        preventing cold-load memory spikes during recall.
-        """
-        try:
-            import httpx
-            model = getattr(self._config.llm, 'model', None) or "llama3.1:8b"
-            model_base = model.split(":")[0]
-            with httpx.Client(timeout=httpx.Timeout(2.0)) as client:
-                resp = client.get("http://localhost:11434/api/ps")
-                if resp.status_code != 200:
-                    return False
-                for m in resp.json().get("models", []):
-                    if model_base in m.get("name", ""):
-                        return True
-            return False
-        except Exception:
-            return False
-
     def _call_llm(self, prompt: str, max_tokens: int = 200) -> str:
         """Route to Ollama (B) or OpenRouter (C)."""
         if self._mode == "b":

package/src/superlocalmemory/hooks/claude_code_hooks.py

@@ -0,0 +1,175 @@
+# 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
+
+"""Claude Code Hook Integration — invisible memory injection.
+
+Installs hooks into Claude Code's settings.json that auto-inject
+SLM context on session start and auto-capture on tool use.
+
+Usage:
+    slm hooks install    Install hooks into Claude Code settings
+    slm hooks status     Check if hooks are installed
+    slm hooks remove     Remove SLM hooks from settings
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CLAUDE_SETTINGS = Path.home() / ".claude" / "settings.json"
+HOOKS_DIR = Path.home() / ".superlocalmemory" / "hooks"
+
+# The hook scripts that Claude Code will execute
+HOOK_SCRIPTS = {
+    "slm-session-start.sh": """\
+#!/bin/bash
+# SLM Active Memory — Session Start Hook
+# Auto-recalls relevant context at session start
+slm session-context 2>/dev/null || true
+""",
+    "slm-auto-capture.sh": """\
+#!/bin/bash
+# SLM Active Memory — Auto-Capture Hook
+# Evaluates tool output for decisions/bugs/preferences
+# Input comes via stdin from Claude Code PostToolUse event
+INPUT=$(cat)
+if [ -n "$INPUT" ]; then
+    echo "$INPUT" | slm observe 2>/dev/null || true
+fi
+""",
+}
+
+# Hook definitions for Claude Code settings.json
+HOOK_DEFINITIONS = {
+    "hooks": {
+        "SessionStart": [
+            {
+                "type": "command",
+                "command": str(HOOKS_DIR / "slm-session-start.sh"),
+                "timeout": 10000,
+            }
+        ],
+    }
+}
+
+
+def install_hooks() -> dict:
+    """Install SLM hooks into Claude Code settings."""
+    results = {"scripts": False, "settings": False, "errors": []}
+
+    # 1. Create hook scripts
+    try:
+        HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+        for name, content in HOOK_SCRIPTS.items():
+            path = HOOKS_DIR / name
+            path.write_text(content)
+            path.chmod(0o755)
+        results["scripts"] = True
+    except Exception as exc:
+        results["errors"].append(f"Script creation failed: {exc}")
+
+    # 2. Update Claude Code settings.json
+    try:
+        if not CLAUDE_SETTINGS.parent.exists():
+            CLAUDE_SETTINGS.parent.mkdir(parents=True, exist_ok=True)
+
+        settings = {}
+        if CLAUDE_SETTINGS.exists():
+            settings = json.loads(CLAUDE_SETTINGS.read_text())
+
+        # Merge hooks without overwriting existing ones
+        if "hooks" not in settings:
+            settings["hooks"] = {}
+
+        # Add SessionStart hook if not present
+        session_hooks = settings["hooks"].get("SessionStart", [])
+        slm_hook_cmd = str(HOOKS_DIR / "slm-session-start.sh")
+        already_installed = any(
+            h.get("command", "") == slm_hook_cmd
+            for h in session_hooks if isinstance(h, dict)
+        )
+
+        if not already_installed:
+            session_hooks.append({
+                "type": "command",
+                "command": slm_hook_cmd,
+                "timeout": 10000,
+            })
+            settings["hooks"]["SessionStart"] = session_hooks
+
+        CLAUDE_SETTINGS.write_text(json.dumps(settings, indent=2))
+        results["settings"] = True
+    except Exception as exc:
+        results["errors"].append(f"Settings update failed: {exc}")
+
+    return results
+
+
+def remove_hooks() -> dict:
+    """Remove SLM hooks from Claude Code settings."""
+    results = {"scripts": False, "settings": False, "errors": []}
+
+    # 1. Remove hook scripts
+    try:
+        if HOOKS_DIR.exists():
+            shutil.rmtree(HOOKS_DIR)
+        results["scripts"] = True
+    except Exception as exc:
+        results["errors"].append(f"Script removal failed: {exc}")
+
+    # 2. Remove from Claude Code settings
+    try:
+        if CLAUDE_SETTINGS.exists():
+            settings = json.loads(CLAUDE_SETTINGS.read_text())
+            if "hooks" in settings and "SessionStart" in settings["hooks"]:
+                slm_hook_cmd = str(HOOKS_DIR / "slm-session-start.sh")
+                settings["hooks"]["SessionStart"] = [
+                    h for h in settings["hooks"]["SessionStart"]
+                    if not (isinstance(h, dict) and h.get("command", "") == slm_hook_cmd)
+                ]
+                if not settings["hooks"]["SessionStart"]:
+                    del settings["hooks"]["SessionStart"]
+                if not settings["hooks"]:
+                    del settings["hooks"]
+                CLAUDE_SETTINGS.write_text(json.dumps(settings, indent=2))
+            results["settings"] = True
+    except Exception as exc:
+        results["errors"].append(f"Settings cleanup failed: {exc}")
+
+    return results
+
+
+def check_status() -> dict:
+    """Check if SLM hooks are installed."""
+    scripts_ok = all(
+        (HOOKS_DIR / name).exists()
+        for name in HOOK_SCRIPTS
+    )
+
+    settings_ok = False
+    try:
+        if CLAUDE_SETTINGS.exists():
+            settings = json.loads(CLAUDE_SETTINGS.read_text())
+            session_hooks = settings.get("hooks", {}).get("SessionStart", [])
+            slm_hook_cmd = str(HOOKS_DIR / "slm-session-start.sh")
+            settings_ok = any(
+                h.get("command", "") == slm_hook_cmd
+                for h in session_hooks if isinstance(h, dict)
+            )
+    except Exception:
+        pass
+
+    return {
+        "installed": scripts_ok and settings_ok,
+        "scripts": scripts_ok,
+        "settings": settings_ok,
+        "hooks_dir": str(HOOKS_DIR),
+    }