superlocalmemory 3.3.5 → 3.3.7

package/README.md

@@ -3,7 +3,8 @@
 </p>
 
 <h1 align="center">SuperLocalMemory V3.3</h1>
-<p align="center"><strong>The first local-only AI memory to break 74% retrieval on LoCoMo.<br/>No cloud. No APIs. No data leaves your machine.</strong></p>
+<p align="center"><strong>Every other AI forgets. Yours won't.</strong><br/><em>Infinite memory for Claude Code, Cursor, Windsurf & 17+ AI tools.</em></p>
+<p align="center"><code>v3.3.6</code> — Install once. Every session remembers the last. Automatically.</p>
 
 <p align="center">
   <code>+16pp vs Mem0 (zero cloud)</code> &nbsp;·&nbsp; <code>85% Open-Domain (best of any system)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.3.5",
+  "version": "3.3.7",
   "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.7"
 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/core/embedding_worker.py

@@ -23,9 +23,10 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import json
+import os
 import signal
 import sys
-import os
+import threading
 
 # Force CPU BEFORE any torch import
 os.environ["CUDA_VISIBLE_DEVICES"] = ""
@@ -41,8 +42,33 @@ if sys.platform != "win32":
     signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
 
 
+def _start_parent_watchdog() -> None:
+    """Monitor parent process — self-terminate if parent dies.
+
+    Prevents orphaned workers that consume 500-800 MB each when the parent
+    process crashes, is killed, or exits without cleanup.
+
+    V3.3.7: Added after incident where orphaned workers consumed 33 GB.
+    """
+    parent_pid = os.getppid()
+
+    def _watch() -> None:
+        import time
+        while True:
+            time.sleep(5)
+            try:
+                os.kill(parent_pid, 0)
+            except OSError:
+                os._exit(0)
+
+    t = threading.Thread(target=_watch, daemon=True, name="parent-watchdog")
+    t.start()
+
+
 def _worker_main() -> None:
     """Main loop: read JSON requests from stdin, write responses to stdout."""
+    _start_parent_watchdog()  # V3.3.7: self-terminate if parent dies
+
     import numpy as np
 
     model = None

package/src/superlocalmemory/core/embeddings.py

@@ -15,6 +15,7 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
+import atexit
 import json
 import logging
 import os
@@ -22,11 +23,15 @@ import subprocess
 import sys
 import threading
 import time
+import weakref
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import numpy as np
 
+# Track all live embedding services for atexit cleanup
+_live_embedding_services: set[weakref.ref] = set()
+
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
@@ -69,6 +74,17 @@ class EmbeddingService:
         self._worker_ready = False
         self._request_count: int = 0
 
+        # Register for atexit cleanup (prevent orphaned workers)
+        ref = weakref.ref(self, _live_embedding_services.discard)
+        _live_embedding_services.add(ref)
+
+    def __del__(self) -> None:
+        """Kill worker subprocess when service is garbage-collected."""
+        try:
+            self._kill_worker()
+        except Exception:
+            pass
+
     @property
     def is_available(self) -> bool:
         """Check if embedding service can produce embeddings."""
@@ -338,3 +354,26 @@ class EmbeddingService:
             raise DimensionMismatchError(
                 f"Embedding dimension {actual} != expected {self._config.dimension}"
             )
+
+
+# ---------------------------------------------------------------------------
+# Module-level atexit: kill ALL embedding workers on process exit
+# ---------------------------------------------------------------------------
+
+def _cleanup_all_embedding_services() -> None:
+    """Kill all embedding worker subprocesses on interpreter exit.
+
+    Prevents orphaned 500-800 MB sentence-transformer workers surviving
+    after parent exits (especially during test runs with parallel agents).
+    """
+    for ref in list(_live_embedding_services):
+        svc = ref()
+        if svc is not None:
+            try:
+                svc._kill_worker()
+            except Exception:
+                pass
+    _live_embedding_services.clear()
+
+
+atexit.register(_cleanup_all_embedding_services)

package/src/superlocalmemory/core/recall_worker.py

@@ -20,6 +20,7 @@ import json
 import os
 import signal
 import sys
+import threading
 
 # Force CPU BEFORE any torch import
 os.environ["CUDA_VISIBLE_DEVICES"] = ""
@@ -34,6 +35,29 @@ os.environ["TORCH_DEVICE"] = "cpu"
 if sys.platform != "win32":
     signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
 
+
+def _start_parent_watchdog() -> None:
+    """Monitor parent process — self-terminate if parent dies.
+
+    Prevents orphaned workers that consume 500+ MB each when the parent
+    process crashes, is killed, or exits without cleanup.
+
+    V3.3.7: Added after incident where orphaned workers consumed 33 GB.
+    """
+    parent_pid = os.getppid()
+
+    def _watch() -> None:
+        import time
+        while True:
+            time.sleep(5)
+            try:
+                os.kill(parent_pid, 0)
+            except OSError:
+                os._exit(0)
+
+    t = threading.Thread(target=_watch, daemon=True, name="parent-watchdog")
+    t.start()
+
 _engine = None
 
 
@@ -209,6 +233,8 @@ def _handle_status() -> dict:
 
 def _worker_main() -> None:
     """Main loop: read JSON requests from stdin, write responses to stdout."""
+    _start_parent_watchdog()  # V3.3.7: self-terminate if parent dies
+
     for line in sys.stdin:
         line = line.strip()
         if not line: