superlocalmemory 3.3.5 → 3.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.3.5",
+  "version": "3.3.6",
   "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.3.5"
+version = "3.3.6"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/postinstall.js

@@ -213,17 +213,48 @@ if (fs.existsSync(V2_HOME) && fs.existsSync(path.join(V2_HOME, 'memory.db'))) {
     console.log('');
 }
 
+// --- Step 5: Auto-install Claude Code hooks ---
+// "Install once, forget forever" — hooks enable automatic memory lifecycle
+const hooksDisabledFile = path.join(SLM_HOME, 'hooks', '.hooks-disabled');
+if (fs.existsSync(hooksDisabledFile)) {
+    console.log('⊘ Claude Code hooks: skipped (user opted out via slm hooks remove)');
+} else {
+    console.log('\nInstalling Claude Code hooks (auto-memory lifecycle)...');
+    const hookResult = spawnSync(pythonParts[0], [
+        ...pythonParts.slice(1), '-m', 'superlocalmemory.cli.main', 'hooks', 'install',
+    ], {
+        stdio: 'pipe', timeout: 15000,
+        env: {
+            ...process.env,
+            PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || ''),
+            PYTHONPATH: path.join(__dirname, '..', 'src') + ':' + (process.env.PYTHONPATH || ''),
+        },
+    });
+
+    if (hookResult.status === 0) {
+        console.log('✓ Claude Code hooks installed (auto-recall, auto-observe, auto-save)');
+        console.log('  SLM: Hooks installed into Claude Code (slm hooks remove to undo)');
+    } else {
+        console.log('⚠ Claude Code hooks not installed (run: slm hooks install)');
+        // Non-fatal — don't block npm install
+    }
+}
+
 // --- Done ---
 console.log('════════════════════════════════════════════════════════════');
 console.log('  ✓ SuperLocalMemory V3 installed successfully!');
 console.log('');
 console.log('  Quick start:');
-console.log('    slm setup          # First-time configuration');
+console.log('    Just open Claude Code — memory works automatically!');
+console.log('');
+console.log('  Other commands:');
 console.log('    slm doctor         # Pre-flight check (verify everything works)');
 console.log('    slm warmup         # Pre-download embedding model (~500MB)');
 console.log('    slm remember "..." # Store a memory');
 console.log('    slm recall "..."   # Search memories');
 console.log('    slm dashboard      # Open 17-tab web dashboard');
+console.log('    slm hooks status   # Check hook installation');
+console.log('    slm hooks remove   # Opt out of auto-memory hooks');
 console.log('');
 console.log('  Prerequisites satisfied:');
 console.log('    ✓ Python 3.11+');

package/src/superlocalmemory/cli/commands.py

@@ -18,7 +18,16 @@ from argparse import Namespace
 
 def dispatch(args: Namespace) -> None:
     """Route CLI command to the appropriate handler."""
+    # Auto-install/upgrade hooks on version change (single file read, ~0.1ms)
+    if args.command not in ("hooks", "init", "mcp"):
+        try:
+            from superlocalmemory.hooks.claude_code_hooks import auto_install_if_needed
+            auto_install_if_needed()
+        except Exception:
+            pass
+
     handlers = {
+        "init": cmd_init,
         "setup": cmd_setup,
         "mode": cmd_mode,
         "provider": cmd_provider,
@@ -923,6 +932,14 @@ def cmd_trace(args: Namespace) -> None:
 
 def cmd_mcp(_args: Namespace) -> None:
     """Start the V3 MCP server (stdio transport for IDE integration)."""
+    # Auto-install hooks on MCP startup (fast path: ~0.1ms if already current)
+    # CRITICAL: No stdout — MCP uses stdio transport, any print corrupts protocol
+    try:
+        from superlocalmemory.hooks.claude_code_hooks import auto_install_if_needed
+        auto_install_if_needed()
+    except Exception:
+        pass
+
     from superlocalmemory.mcp.server import server
 
     server.run(transport="stdio")
@@ -1142,6 +1159,99 @@ def cmd_profile(args: Namespace) -> None:
 # -- Active Memory commands (V3.1) ------------------------------------------
 
 
+def cmd_init(args: Namespace) -> None:
+    """One-command setup: mode + hooks + IDE connect + warmup."""
+    from pathlib import Path
+    from superlocalmemory.core.config import SLMConfig
+
+    force = getattr(args, "force", False)
+
+    config_exists = (Path.home() / ".superlocalmemory" / "config.json").exists()
+
+    print()
+    print("SuperLocalMemory — One-Time Setup")
+    print("=" * 40)
+
+    # Step 1: Mode selection (interactive)
+    if force or not config_exists:
+        print()
+        from superlocalmemory.cli.setup_wizard import run_wizard
+        run_wizard()
+    else:
+        config = SLMConfig.load()
+        print(f"\n  Already configured: Mode {config.mode.value.upper()}")
+        print(f"  Profile: {config.active_profile}")
+
+    # Step 2: Install hooks (gate always OFF by default)
+    print()
+    print("Installing Claude Code hooks...")
+    from superlocalmemory.hooks.claude_code_hooks import install_hooks, check_status
+
+    status = check_status()
+
+    if status["installed"] and not force:
+        if status["needs_upgrade"]:
+            from superlocalmemory.hooks.claude_code_hooks import upgrade_hooks
+            result = upgrade_hooks()
+            if result.get("upgraded"):
+                print(f"  Hooks upgraded: {result['from_version']} -> {result['to_version']}")
+            else:
+                print(f"  Upgrade issue: {result.get('reason', result.get('errors', ''))}")
+        else:
+            print(f"  Hooks already installed (v{status['version']})")
+    else:
+        result = install_hooks(include_gate=False)
+        if result["success"]:
+            print(f"  Hooks installed: {', '.join(result['hooks_added'])}")
+            print("  SLM: Hooks installed into Claude Code (slm hooks remove to undo)")
+        else:
+            print(f"  Hook install failed: {result['errors']}")
+
+    # Step 3: IDE connection
+    print()
+    print("Detecting IDEs...")
+    try:
+        from superlocalmemory.hooks.ide_connector import IDEConnector
+        connector = IDEConnector()
+        results = connector.connect_all()
+        for ide_id, ide_status in results.items():
+            print(f"  {ide_id}: {ide_status}")
+    except Exception as exc:
+        print(f"  IDE detection skipped: {exc}")
+
+    # Step 4: Warmup (embedding model)
+    print()
+    print("Checking embedding model...")
+    try:
+        from superlocalmemory.core.config import SLMConfig as _Cfg
+        cfg = _Cfg.load()
+        model_name = cfg.embedding.model_name
+        print(f"  Model: {model_name}")
+        # Quick check: try creating embedding service (auto-downloads if needed)
+        from superlocalmemory.core.embeddings import EmbeddingService
+        svc = EmbeddingService(cfg.embedding)
+        test_result = svc.embed_text("test")
+        if test_result is not None and len(test_result) > 0:
+            print("  Status: ready")
+        else:
+            print("  Status: model not available (run: slm warmup)")
+    except Exception as exc:
+        print(f"  Warmup skipped: {exc}")
+        print("  Run 'slm warmup' later to download the embedding model.")
+
+    # Done
+    print()
+    print("=" * 40)
+    print("SLM is active. Your AI now remembers you.")
+    print()
+    print("What happens next:")
+    print("  - Open Claude Code in any project")
+    print("  - SLM auto-injects your memory context")
+    print("  - Decisions, bugs, preferences are captured automatically")
+    print("  - Session summaries saved when you close")
+    print()
+
+
 def cmd_hooks(args: Namespace) -> None:
     """Manage Claude Code hooks for invisible memory injection."""
     from superlocalmemory.hooks.claude_code_hooks import (
@@ -1149,28 +1259,38 @@ def cmd_hooks(args: Namespace) -> None:
     )
 
     action = getattr(args, "action", "status")
+    # Gate is OFF by default. --gate opts in (for brave users).
+    include_gate = getattr(args, "gate", False)
+
     if action == "install":
-        result = install_hooks()
-        if result["scripts"] and result["settings"]:
+        result = install_hooks(include_gate=include_gate)
+        if result["success"]:
             print("SLM hooks installed in Claude Code.")
-            print("Memory context will auto-inject on every new session.")
+            print(f"  Hook types: {', '.join(result['hooks_added'])}")
+            if include_gate:
+                print("  Gate: ON (enforces session_init — experimental)")
+            print("  SLM: Hooks installed into Claude Code (slm hooks remove to undo)")
         else:
-            print(f"Installation incomplete: {result['errors']}")
+            print(f"Installation failed: {result['errors']}")
     elif action == "remove":
         result = remove_hooks()
-        if result["scripts"] and result["settings"]:
+        if result["success"]:
             print("SLM hooks removed from Claude Code.")
         else:
-            print(f"Removal incomplete: {result['errors']}")
+            print(f"Removal failed: {result['errors']}")
     else:
         result = check_status()
         if result["installed"]:
-            print("SLM hooks: INSTALLED")
-            print(f"  Scripts: {result['hooks_dir']}")
-            print("  Claude Code settings: configured")
+            print(f"SLM hooks: INSTALLED (v{result['version']})")
+            print(f"  Hook types: {', '.join(result['hook_types'])}")
+            print(f"  Gate: {'ON' if result['gate_enabled'] else 'OFF'}")
+            if result["needs_upgrade"]:
+                print(f"  Update available: {result['version']} -> {result['latest_version']}")
+                print("  Run: slm hooks install")
         else:
             print("SLM hooks: NOT INSTALLED")
             print("  Run: slm hooks install")
+            print("  Or:  slm init  (full setup)")
 
 
 def cmd_session_context(args: Namespace) -> None:

package/src/superlocalmemory/cli/main.py

@@ -70,6 +70,12 @@ documentation:
 
 def main() -> None:
     """Parse CLI arguments and dispatch to command handlers."""
+    # Fast path: hook invocations bypass argparse entirely (stdlib only, ~30ms)
+    if len(sys.argv) >= 3 and sys.argv[1] == "hook":
+        from superlocalmemory.hooks.hook_handlers import handle_hook
+        handle_hook(sys.argv[2])
+        return
+
     from superlocalmemory.cli.json_output import _get_version
     _ver = _get_version()
 
@@ -85,6 +91,15 @@ def main() -> None:
     sub = parser.add_subparsers(dest="command", title="commands")
 
     # -- Setup & Config ------------------------------------------------
+    init_p = sub.add_parser("init", help="One-command setup: mode + hooks + IDE + warmup")
+    init_p.add_argument(
+        "--force", action="store_true", help="Re-run full setup even if already configured",
+    )
+    init_p.add_argument(
+        "--gate", action="store_true",
+        help="Enable PreToolUse gate (experimental — blocks tools until session_init)",
+    )
+
     sub.add_parser("setup", help="Interactive first-time setup wizard")
 
     mode_p = sub.add_parser("mode", help="Get or set operating mode (a/b/c)")
@@ -182,6 +197,10 @@ def main() -> None:
         "action", nargs="?", default="status",
         choices=["install", "remove", "status"], help="Action (default: status)",
     )
+    hooks_p.add_argument(
+        "--gate", action="store_true",
+        help="Enable PreToolUse gate (experimental — blocks tools until session_init)",
+    )
 
     ctx_p = sub.add_parser("session-context", help="Print session context (for hooks)")
     ctx_p.add_argument("query", nargs="?", default="", help="Optional context query")

package/src/superlocalmemory/hooks/claude_code_hooks.py

@@ -2,15 +2,17 @@
 # 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.
+"""Claude Code hook integration — hybrid approach (v3.3.6).
 
-Installs hooks into Claude Code's settings.json that auto-inject
-SLM context on session start and auto-capture on tool use.
+CRITICAL PATH (gate + init-done): Shell built-ins only. Cannot crash.
+VALUE-ADD (start, checkpoint, stop): Python via `slm hook <name>`,
+  wrapped with `2>/dev/null || true` so errors are invisible.
 
 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
+    slm hooks install       Install all hooks into Claude Code
+    slm hooks remove        Remove SLM hooks from Claude Code
+    slm hooks status        Check installation status
+    slm init                Full setup including hooks
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
 """
@@ -19,157 +21,384 @@ from __future__ import annotations
 
 import json
 import logging
-import shutil
+import sys
+import tempfile
 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": {
+VERSION_DIR = Path.home() / ".superlocalmemory" / "hooks"
+VERSION_FILE = VERSION_DIR / ".version"
+DISABLED_FILE = VERSION_DIR / ".hooks-disabled"
+HOOKS_VERSION = "3.3.6"
+
+# Cross-platform temp dir and marker paths
+_TMP = tempfile.gettempdir()
+_MARKER = f"{_TMP}/slm-session-initialized"
+_START_MARKER = f"{_TMP}/slm-session-start-time"
+
+# Tools that the gate should block (everything except SLM/ToolSearch)
+_GATED_TOOLS = "Bash|Read|Write|Edit|Glob|Grep|Agent|WebFetch|WebSearch|NotebookEdit"
+
+# ---------------------------------------------------------------------------
+# Platform-specific gate commands (shell built-ins only — CANNOT crash)
+# ---------------------------------------------------------------------------
+
+def _gate_cmd() -> str:
+    """Gate command: pure shell, no Python, ~1ms.
+
+    Logic: if initialized → allow. If no session started → allow. Else → block.
+    Uses specific matcher to exclude SLM tools, so no stdin parsing needed.
+    """
+    if sys.platform == "win32":
+        marker_win = _MARKER.replace("/", "\\")
+        start_win = _START_MARKER.replace("/", "\\")
+        return (
+            f'cmd /c "if exist {marker_win} (exit /b 0)'
+            f' else if not exist {start_win} (exit /b 0)'
+            f' else (echo [SLM] Call mcp__superlocalmemory__session_init first & exit /b 2)"'
+        )
+    return (
+        f"test -f {_MARKER}"
+        f" || test ! -f {_START_MARKER}"
+        " || { echo '[SLM] Call mcp__superlocalmemory__session_init first'; exit 2; }"
+    )
+
+
+def _init_done_cmd() -> str:
+    """Init-done command: pure shell touch, ~1ms."""
+    if sys.platform == "win32":
+        return f'cmd /c "echo.>{_MARKER.replace("/", chr(92))}"'
+    return f"touch {_MARKER}"
+
+
+def _wrap_python_cmd(hook_name: str) -> str:
+    """Wrap a Python hook with error absorption. Any crash → invisible."""
+    if sys.platform == "win32":
+        return f'cmd /c "slm hook {hook_name} 2>NUL || exit /b 0"'
+    return f"slm hook {hook_name} 2>/dev/null || true"
+
+
+# ---------------------------------------------------------------------------
+# Hook definitions for settings.json
+# ---------------------------------------------------------------------------
+
+def _hook_definitions(include_gate: bool = False) -> dict[str, list]:
+    """Build Claude Code hook entries.
+
+    Critical path (gate, init-done): Shell built-ins. Cannot crash.
+    Value-add (start, checkpoint, stop): Python with error wrapper.
+    """
+    defs: dict[str, list] = {
         "SessionStart": [
             {
-                "type": "command",
-                "command": str(HOOKS_DIR / "slm-session-start.sh"),
-                "timeout": 10000,
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": _wrap_python_cmd("start"),
+                        "timeout": 15000,
+                    }
+                ]
+            }
+        ],
+        "PostToolUse": [
+            {
+                "matcher": "Write|Edit",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": _wrap_python_cmd("checkpoint"),
+                        "timeout": 5000,
+                    }
+                ],
+            }
+        ],
+        "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": _wrap_python_cmd("stop"),
+                        "timeout": 10000,
+                    }
+                ]
             }
         ],
     }
-}
 
+    if include_gate:
+        defs["PreToolUse"] = [
+            {
+                "matcher": _GATED_TOOLS,
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": _gate_cmd(),
+                        "timeout": 500,
+                    }
+                ],
+            }
+        ]
+        defs["PostToolUse"].insert(0, {
+            "matcher": "mcp__superlocalmemory__session_init",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": _init_done_cmd(),
+                    "timeout": 500,
+                }
+            ],
+        })
+
+    return defs
+
+
+# ---------------------------------------------------------------------------
+# Identify SLM hooks in existing settings
+# ---------------------------------------------------------------------------
+
+def _is_slm_hook_entry(entry: dict) -> bool:
+    """Check if a hook entry belongs to SLM."""
+    for hook in entry.get("hooks", []):
+        cmd = hook.get("command", "")
+        if ("slm hook" in cmd
+                or "slm-session" in cmd
+                or ".superlocalmemory/hooks/" in cmd
+                or "slm-session-initialized" in cmd):
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Safe settings.json merge / removal
+# ---------------------------------------------------------------------------
+
+def _merge_hooks(settings: dict, hook_defs: dict) -> dict:
+    """Merge SLM hooks into settings, preserving all non-SLM hooks."""
+    if "hooks" not in settings:
+        settings["hooks"] = {}
+
+    for hook_type, slm_entries in hook_defs.items():
+        existing = settings["hooks"].get(hook_type, [])
+        cleaned = [e for e in existing if not _is_slm_hook_entry(e)]
+        cleaned.extend(slm_entries)
+        settings["hooks"][hook_type] = cleaned
+
+    return settings
+
+
+def _remove_slm_hooks(settings: dict) -> dict:
+    """Remove all SLM hook entries, preserve non-SLM hooks."""
+    hooks = settings.get("hooks", {})
+    for hook_type in list(hooks.keys()):
+        cleaned = [e for e in hooks[hook_type] if not _is_slm_hook_entry(e)]
+        if cleaned:
+            hooks[hook_type] = cleaned
+        else:
+            del hooks[hook_type]
+    if not hooks and "hooks" in settings:
+        del settings["hooks"]
+    return settings
+
+
+def _read_settings() -> dict:
+    """Read Claude Code settings.json, return empty dict if missing."""
+    if CLAUDE_SETTINGS.exists():
+        return json.loads(CLAUDE_SETTINGS.read_text())
+    return {}
+
+
+def _write_settings(settings: dict) -> None:
+    """Write settings.json with pretty formatting."""
+    CLAUDE_SETTINGS.parent.mkdir(parents=True, exist_ok=True)
+    CLAUDE_SETTINGS.write_text(json.dumps(settings, indent=2) + "\n")
 
-def install_hooks() -> dict:
-    """Install SLM hooks into Claude Code settings."""
-    results = {"scripts": False, "settings": False, "errors": []}
 
-    # 1. Create hook scripts
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def install_hooks(include_gate: bool = False) -> dict:
+    """Install SLM hooks into Claude Code settings.json.
+
+    Critical path uses shell built-ins (cannot crash).
+    Value-add uses Python with error wrappers (crashes invisible).
+    Never overwrites non-SLM hooks.
+    Clears .hooks-disabled marker (explicit install = user wants hooks).
+    """
+    result = {
+        "success": False, "errors": [],
+        "hooks_added": [], "gate_enabled": include_gate,
+    }
+
     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
+        settings = _read_settings()
+        hook_defs = _hook_definitions(include_gate=include_gate)
+        settings = _merge_hooks(settings, hook_defs)
+        _write_settings(settings)
+        result["hooks_added"] = list(hook_defs.keys())
+        result["success"] = True
     except Exception as exc:
-        results["errors"].append(f"Script creation failed: {exc}")
+        result["errors"].append(f"Settings update 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
+        VERSION_DIR.mkdir(parents=True, exist_ok=True)
+        VERSION_FILE.write_text(HOOKS_VERSION)
+        # Clear disabled marker — explicit install means user wants hooks
+        if DISABLED_FILE.exists():
+            DISABLED_FILE.unlink()
     except Exception as exc:
-        results["errors"].append(f"Settings update failed: {exc}")
+        result["errors"].append(f"Version file failed: {exc}")
 
-    return results
+    return result
 
 
 def remove_hooks() -> dict:
-    """Remove SLM hooks from Claude Code settings."""
-    results = {"scripts": False, "settings": False, "errors": []}
+    """Remove all SLM hooks from Claude Code settings.json.
+
+    Writes a .hooks-disabled marker so auto-install paths respect
+    the user's explicit choice. Cleared by explicit `install_hooks()`.
+    """
+    result = {"success": False, "errors": []}
 
-    # 1. Remove hook scripts
     try:
-        if HOOKS_DIR.exists():
-            shutil.rmtree(HOOKS_DIR)
-        results["scripts"] = True
+        settings = _read_settings()
+        settings = _remove_slm_hooks(settings)
+        _write_settings(settings)
+        result["success"] = True
     except Exception as exc:
-        results["errors"].append(f"Script removal failed: {exc}")
+        result["errors"].append(f"Settings cleanup 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}")
+        if VERSION_FILE.exists():
+            VERSION_FILE.unlink()
+        # Mark as explicitly disabled — auto-install will respect this
+        VERSION_DIR.mkdir(parents=True, exist_ok=True)
+        DISABLED_FILE.write_text("removed by user\n")
+    except Exception:
+        pass
 
-    return results
+    return result
 
 
 def check_status() -> dict:
-    """Check if SLM hooks are installed."""
-    scripts_ok = all(
-        (HOOKS_DIR / name).exists()
-        for name in HOOK_SCRIPTS
-    )
+    """Check SLM hook installation status."""
+    installed_version = ""
+    if VERSION_FILE.exists():
+        try:
+            installed_version = VERSION_FILE.read_text().strip()
+        except Exception:
+            pass
 
-    settings_ok = False
+    hook_types_found: list[str] = []
+    has_gate = 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)
-            )
+        settings = _read_settings()
+        for hook_type, entries in settings.get("hooks", {}).items():
+            if any(_is_slm_hook_entry(e) for e in entries):
+                hook_types_found.append(hook_type)
+        has_gate = "PreToolUse" in hook_types_found
     except Exception:
         pass
 
+    installed = len(hook_types_found) >= 3
+
     return {
-        "installed": scripts_ok and settings_ok,
-        "scripts": scripts_ok,
-        "settings": settings_ok,
-        "hooks_dir": str(HOOKS_DIR),
+        "installed": installed,
+        "version": installed_version,
+        "latest_version": HOOKS_VERSION,
+        "needs_upgrade": bool(installed_version and installed_version != HOOKS_VERSION),
+        "hook_types": hook_types_found,
+        "gate_enabled": has_gate,
     }
+
+
+def upgrade_hooks() -> dict:
+    """Upgrade existing hooks to current version. Non-interactive."""
+    status = check_status()
+
+    if not status["installed"] and not status["version"]:
+        return {"upgraded": False, "reason": "No hooks installed"}
+
+    include_gate = status["gate_enabled"]
+    result = install_hooks(include_gate=include_gate)
+    result["upgraded"] = result["success"]
+    result["from_version"] = status["version"]
+    result["to_version"] = HOOKS_VERSION
+    return result
+
+
+def auto_install_if_needed() -> dict | None:
+    """Auto-install hooks if not present and not explicitly disabled.
+
+    Called from MCP server startup and npm postinstall.
+    Returns install result, or None if skipped.
+
+    Fast path: version file exists and matches → ~0.1ms, returns None.
+    """
+    try:
+        # Respect explicit opt-out
+        if DISABLED_FILE.exists():
+            return None
+
+        # Already installed and current → skip
+        if VERSION_FILE.exists():
+            installed = VERSION_FILE.read_text().strip()
+            if installed == HOOKS_VERSION:
+                return None
+
+        # Install with clear message
+        result = install_hooks(include_gate=False)
+        if result["success"]:
+            logger.info(
+                "SLM: Hooks installed into Claude Code (slm hooks remove to undo)"
+            )
+        return result
+    except Exception as exc:
+        logger.debug("Auto-install check failed: %s", exc)
+        return None
+
+
+def auto_upgrade_check() -> None:
+    """Silent auto-upgrade on version mismatch. ~0.1ms when current."""
+    try:
+        if not VERSION_FILE.exists():
+            legacy_script = VERSION_DIR / "slm-session-start.sh"
+            if legacy_script.exists():
+                _migrate_legacy_hooks()
+            return
+
+        installed = VERSION_FILE.read_text().strip()
+        if installed == HOOKS_VERSION:
+            return
+
+        result = upgrade_hooks()
+        if result.get("upgraded"):
+            logger.info("SLM hooks upgraded %s -> %s", installed, HOOKS_VERSION)
+    except Exception as exc:
+        logger.debug("Hook auto-upgrade failed: %s", exc)
+
+
+def _migrate_legacy_hooks() -> None:
+    """Migrate from bash-script hooks (pre-3.3.6) to hybrid hooks."""
+    try:
+        settings = _read_settings()
+        has_legacy = False
+        for entries in settings.get("hooks", {}).values():
+            for e in entries:
+                for h in e.get("hooks", []):
+                    if ".superlocalmemory/hooks/" in h.get("command", ""):
+                        has_legacy = True
+                        break
+
+        if has_legacy:
+            settings = _remove_slm_hooks(settings)
+            hook_defs = _hook_definitions(include_gate=False)
+            settings = _merge_hooks(settings, hook_defs)
+            _write_settings(settings)
+            VERSION_DIR.mkdir(parents=True, exist_ok=True)
+            VERSION_FILE.write_text(HOOKS_VERSION)
+            logger.info("Migrated legacy bash hooks to hybrid hooks (v%s)", HOOKS_VERSION)
+    except Exception as exc:
+        logger.debug("Legacy hook migration failed: %s", exc)

package/src/superlocalmemory/hooks/hook_handlers.py

@@ -0,0 +1,394 @@
+# 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 handlers — zero-dependency, cross-platform.
+
+All handlers use ONLY Python stdlib (sys, os, json, tempfile, subprocess, time).
+No SLM imports in the hot path. Called via:  slm hook <start|gate|init-done|checkpoint|stop>
+
+The main() entry point in cli/main.py has a fast path that dispatches here
+BEFORE argparse or any heavy imports.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+
+# ---------------------------------------------------------------------------
+# Cross-platform temp paths
+# ---------------------------------------------------------------------------
+_TMP = tempfile.gettempdir()
+_MARKER = os.path.join(_TMP, "slm-session-initialized")
+_START_TIME = os.path.join(_TMP, "slm-session-start-time")
+_ACTIVITY_LOG = os.path.join(_TMP, "slm-session-activity")
+_LAST_CONSOLIDATION = os.path.join(
+    os.path.expanduser("~"), ".superlocalmemory", ".last-consolidation",
+)
+
+
+def handle_hook(action: str) -> None:
+    """Dispatch to the appropriate hook handler. Called from main() fast path."""
+    handlers = {
+        "start": _hook_start,
+        "gate": _hook_gate,
+        "init-done": _hook_init_done,
+        "checkpoint": _hook_checkpoint,
+        "stop": _hook_stop,
+    }
+    handler = handlers.get(action)
+    if handler is None:
+        print(f"Unknown hook action: {action}", file=sys.stderr)
+        sys.exit(1)
+    handler()
+
+
+# ---------------------------------------------------------------------------
+# 1. SESSION START — SessionStart hook
+# ---------------------------------------------------------------------------
+
+def _hook_start() -> None:
+    """Clean markers, inject SQL-fast context, print session_init mandate."""
+    # Clean stale markers from previous sessions
+    for f in (_MARKER, _START_TIME, _ACTIVITY_LOG):
+        try:
+            os.remove(f)
+        except OSError:
+            pass
+
+    # Record session start time
+    with open(_START_TIME, "w") as f:
+        f.write(str(int(time.time())))
+
+    # Initialize activity log
+    with open(_ACTIVITY_LOG, "w") as f:
+        f.write("")
+
+    # Reap orphan MCP processes (background, best-effort)
+    try:
+        if sys.platform != "win32":
+            subprocess.Popen(
+                ["sh", "-c",
+                 "ps -eo pid,args 2>/dev/null"
+                 " | grep -E 'node.*\\.bin/|node.*slm |uv tool uvx'"
+                 " | grep -v grep"
+                 " | awk '{print $1, $NF}'"
+                 " | sort -k2,2 -k1,1rn"
+                 " | awk '{if($2==p)print $1; p=$2}'"
+                 " | xargs kill 2>/dev/null"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+    except Exception:
+        pass
+
+    # Print session context (SQL-fast path, <500ms)
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    project_name = os.path.basename(project_dir)
+    try:
+        result = subprocess.run(
+            ["slm", "session-context", project_name],
+            capture_output=True, text=True, timeout=12,
+        )
+        if result.stdout.strip():
+            print(result.stdout.strip())
+    except Exception:
+        print("# SLM Session Context — unavailable")
+
+    # Mandatory session_init instruction
+    print()
+    print("## MANDATORY: SLM Session Init")
+    print("BEFORE your first response, call:")
+    print(f"  mcp__superlocalmemory__session_init with project_path='{project_dir}'"
+          " and a topic from the user's first message")
+    print("session_init returns both context AND memories — no separate recall needed.")
+
+
+# ---------------------------------------------------------------------------
+# 2. GATE — PreToolUse hook (default, enforces session_init)
+# ---------------------------------------------------------------------------
+
+def _hook_gate() -> None:
+    """Block non-SLM tools until session_init has been called.
+
+    Fast path (~30ms): marker file exists → exit 0.
+    Slow path (~80ms): parse JSON stdin, allow SLM tools, block rest.
+    """
+    # Fast path: already initialized
+    if os.path.exists(_MARKER):
+        sys.exit(0)
+
+    # Safety: if session-start never ran, don't gate (avoid lockout)
+    if not os.path.exists(_START_TIME):
+        sys.exit(0)
+
+    # Parse tool name from stdin
+    tool_name = ""
+    if not sys.stdin.isatty():
+        try:
+            data = json.load(sys.stdin)
+            tool_name = data.get("tool_name", "")
+        except Exception:
+            # Can't parse input — don't block (safety)
+            sys.exit(0)
+
+    # Allow SLM tools through (needed to call session_init itself)
+    if tool_name.startswith("mcp__superlocalmemory__"):
+        sys.exit(0)
+
+    # Allow ToolSearch through (needed to fetch SLM tool schemas)
+    if tool_name == "ToolSearch":
+        sys.exit(0)
+
+    # Block everything else
+    print("[SLM-GATE] BLOCKED: Call mcp__superlocalmemory__session_init"
+          " before using other tools.")
+    sys.exit(2)
+
+
+# ---------------------------------------------------------------------------
+# 3. INIT DONE — PostToolUse hook for session_init
+# ---------------------------------------------------------------------------
+
+def _hook_init_done() -> None:
+    """Create marker file to lift the gate for the rest of the session."""
+    with open(_MARKER, "w") as f:
+        f.write(str(int(time.time())))
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# 4. CHECKPOINT — PostToolUse hook for Write|Edit
+# ---------------------------------------------------------------------------
+
+_OBSERVE_COOLDOWN = 300   # 5 minutes per file
+_RECALL_INTERVAL = 900    # 15 minutes
+_LEARN_INTERVAL = 1800    # 30 minutes
+
+
+def _hook_checkpoint() -> None:
+    """Auto-observe file changes + periodic recall/learn reminders.
+
+    1. Directly calls `slm observe` for file change tracking (no Claude needed)
+    2. Suggests richer observe to Claude
+    3. Periodic recall refresh reminder
+    4. Periodic learn/patterns reminder
+    """
+    now = int(time.time())
+
+    # Parse file_path from stdin
+    file_path = ""
+    if not sys.stdin.isatty():
+        try:
+            data = json.load(sys.stdin)
+            tool_input = data.get("tool_input", {})
+            if isinstance(tool_input, dict):
+                file_path = tool_input.get("file_path", "")
+        except Exception:
+            pass
+
+    # --- Auto-observe file change (direct, no Claude needed) ---
+    if file_path:
+        basename = os.path.basename(file_path)
+        lock_file = os.path.join(_TMP, f"slm-obs-{_safe_hash(file_path)}")
+
+        if _cooldown_elapsed(lock_file, _OBSERVE_COOLDOWN, now):
+            _write_timestamp(lock_file, now)
+
+            # Direct observe — SLM records the change even if Claude ignores
+            try:
+                subprocess.Popen(
+                    ["slm", "observe", f"File changed: {basename}"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+            except Exception:
+                pass
+
+            # Log to session activity
+            try:
+                with open(_ACTIVITY_LOG, "a") as f:
+                    f.write(f"{now}|{basename}\n")
+            except Exception:
+                pass
+
+            # Suggest richer observe to Claude (with semantic context)
+            print(f"[SLM-AUTO] File changed: {basename}"
+                  " — Call mcp__superlocalmemory__observe with a 1-line"
+                  " summary of what was changed and why.")
+
+    # --- Periodic recall reminder (every 15 min) ---
+    recall_lock = os.path.join(_TMP, "slm-recall-reminder")
+    if _cooldown_elapsed(recall_lock, _RECALL_INTERVAL, now):
+        _write_timestamp(recall_lock, now)
+        print("[SLM] 15+ min since last context refresh."
+              " Call mcp__superlocalmemory__recall with current work topic.")
+
+    # --- Periodic learn reminder (every 30 min) ---
+    learn_lock = os.path.join(_TMP, "slm-learn-reminder")
+    if _cooldown_elapsed(learn_lock, _LEARN_INTERVAL, now):
+        _write_timestamp(learn_lock, now)
+        print("[SLM] Call mcp__superlocalmemory__get_learned_patterns"
+              " to adapt to learned preferences.")
+
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# 5. STOP — Stop hook (session end)
+# ---------------------------------------------------------------------------
+
+def _hook_stop() -> None:
+    """Save rich session summary + trigger auto-consolidation."""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    project_name = os.path.basename(project_dir)
+    timestamp = time.strftime("%Y-%m-%d %H:%M")
+
+    # --- Git context ---
+    git_branch = _run_quiet(["git", "-C", project_dir, "branch", "--show-current"])
+    git_diff = _run_quiet(
+        ["git", "-C", project_dir, "diff", "--stat"],
+        postprocess=lambda s: s.strip().rsplit("\n", 1)[-1].strip() if s.strip() else "",
+    )
+    recent_commits = _run_quiet(
+        ["git", "-C", project_dir, "log", "--oneline", "-5", "--since=3 hours ago"],
+    )
+
+    # --- Files from activity log ---
+    modified = ""
+    try:
+        if os.path.exists(_ACTIVITY_LOG):
+            with open(_ACTIVITY_LOG) as f:
+                files = sorted({line.split("|", 1)[1].strip()
+                                for line in f if "|" in line})
+            modified = ", ".join(files[:20])
+    except Exception:
+        pass
+
+    # --- Build summary ---
+    parts = [f"[{project_name}] session ended {timestamp}"]
+    if git_branch:
+        parts.append(f"branch: {git_branch}")
+    if git_diff:
+        parts.append(f"uncommitted: {git_diff}")
+    if recent_commits:
+        commits = "; ".join(recent_commits.strip().split("\n")[:5])
+        parts.append(f"recent: {commits}")
+    if modified:
+        parts.append(f"files: {modified}")
+
+    summary = " | ".join(parts)
+
+    # --- Save to SLM ---
+    try:
+        subprocess.run(
+            ["slm", "observe", summary],
+            capture_output=True, timeout=8,
+        )
+    except Exception:
+        try:
+            subprocess.run(
+                ["slm", "remember", summary],
+                capture_output=True, timeout=8,
+            )
+        except Exception:
+            pass
+
+    # --- Auto-consolidation (if >24h since last run) ---
+    _maybe_consolidate()
+
+    # --- Clean up session markers ---
+    for f in (_MARKER, _START_TIME, _ACTIVITY_LOG):
+        try:
+            os.remove(f)
+        except OSError:
+            pass
+
+    # Clean rate-limit locks
+    for name in os.listdir(_TMP):
+        if name.startswith("slm-obs-") or name.startswith("slm-recall-") or name.startswith("slm-learn-"):
+            try:
+                os.remove(os.path.join(_TMP, name))
+            except OSError:
+                pass
+
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# Helpers (stdlib only)
+# ---------------------------------------------------------------------------
+
+def _safe_hash(s: str) -> str:
+    """Simple string hash for rate-limit lock file names."""
+    h = 0
+    for c in s:
+        h = (h * 31 + ord(c)) & 0xFFFFFFFF
+    return format(h, "08x")
+
+
+def _cooldown_elapsed(lock_file: str, interval: int, now: int) -> bool:
+    """Check if enough time has passed since last timestamp in lock_file."""
+    try:
+        if os.path.exists(lock_file):
+            with open(lock_file) as f:
+                last = int(f.read().strip())
+            return (now - last) >= interval
+    except (ValueError, OSError):
+        pass
+    return True
+
+
+def _write_timestamp(path: str, ts: int) -> None:
+    """Write a unix timestamp to a file."""
+    try:
+        with open(path, "w") as f:
+            f.write(str(ts))
+    except OSError:
+        pass
+
+
+def _run_quiet(cmd: list[str], timeout: int = 5, postprocess=None) -> str:
+    """Run a command quietly, return stdout or empty string."""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        out = result.stdout.strip()
+        if postprocess and out:
+            out = postprocess(out)
+        return out
+    except Exception:
+        return ""
+
+
+def _maybe_consolidate() -> None:
+    """Run cognitive consolidation if last run was >24h ago. Non-blocking."""
+    try:
+        last_ts = 0
+        if os.path.exists(_LAST_CONSOLIDATION):
+            with open(_LAST_CONSOLIDATION) as f:
+                last_ts = int(f.read().strip())
+
+        now = int(time.time())
+        if (now - last_ts) < 86400:  # 24 hours
+            return
+
+        # Update timestamp FIRST to prevent concurrent runs
+        os.makedirs(os.path.dirname(_LAST_CONSOLIDATION), exist_ok=True)
+        with open(_LAST_CONSOLIDATION, "w") as f:
+            f.write(str(now))
+
+        # Run consolidation in background (don't block session end)
+        subprocess.Popen(
+            ["slm", "consolidate", "--cognitive"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except Exception:
+        pass