superlocalmemory 3.2.3 → 3.3.1

package/src/superlocalmemory/hooks/auto_invoker.py

@@ -42,8 +42,14 @@ class AutoInvoker:
     - trust_scorer: TrustScorer (for per-fact trust)
     - embedder: EmbeddingService (for query encoding)
     - config: AutoInvokeConfig
+    - prompt_injector: PromptInjector or None (V3.3 soft prompt injection)
     """
 
+    # Lifecycle zones that are excluded from auto-invoke results.
+    # "archived" was always skipped; "forgotten" added in V3.3 for
+    # forgetting-aware auto-invoke (Phase A integration).
+    _EXCLUDED_ZONES: frozenset[str] = frozenset({"archived", "forgotten"})
+
     def __init__(
         self,
         db,                    # DatabaseManager
@@ -51,12 +57,14 @@ class AutoInvoker:
         trust_scorer=None,     # TrustScorer (existing)
         embedder=None,         # EmbeddingService for query encoding
         config=None,           # AutoInvokeConfig
+        prompt_injector=None,  # PromptInjector (V3.3 soft prompt injection)
     ) -> None:
         self._db = db
         self._vector_store = vector_store
         self._trust_scorer = trust_scorer
         self._embedder = embedder
         self._config = config or AutoInvokeConfig()
+        self._prompt_injector = prompt_injector
 
     # ------------------------------------------------------------------
     # Public API: AutoRecall-compatible interface (Rule 16 / AI-04)
@@ -68,6 +76,9 @@ class AutoInvoker:
         EXACT same signature as AutoRecall.get_session_context().
         Returns a formatted string of relevant memories suitable
         for injection into an AI's system prompt.
+
+        V3.3: If a PromptInjector is wired, soft prompts are prepended
+        to the memory context with priority (soft prompts first).
         """
         if not self._config.enabled:
             return ""
@@ -79,10 +90,16 @@ class AutoInvoker:
                 limit=self._config.max_memories_injected,
             )
 
-            if not results:
-                return ""
+            memory_context = self.format_for_injection(results) if results else ""
 
-            return self.format_for_injection(results)
+            # V3.3: Inject soft prompts (priority over memory context)
+            soft_prompt_text = self._get_soft_prompt_text()
+            if soft_prompt_text and self._prompt_injector is not None:
+                return self._prompt_injector.inject_into_context(
+                    soft_prompt_text, memory_context,
+                )
+
+            return soft_prompt_text + ("\n\n" + memory_context if memory_context else "") if soft_prompt_text else memory_context
         except Exception as exc:
             logger.debug("Auto-invoke failed: %s", exc)
             return ""
@@ -210,10 +227,12 @@ class AutoInvoker:
                 logger.debug("VectorStore search failed: %s", exc)
 
         # Fallback: text search for candidates (Mode A degradation)
+        # V3.3: Exclude archived/forgotten facts from candidates
         try:
             rows = self._db.execute(
                 "SELECT fact_id FROM atomic_facts "
                 "WHERE profile_id = ? AND content LIKE ? "
+                "AND COALESCE(lifecycle, 'active') NOT IN ('archived', 'forgotten') "
                 "ORDER BY access_count DESC LIMIT ?",
                 (profile_id, f"%{query[:50]}%", top_k),
             )
@@ -431,11 +450,9 @@ class AutoInvoker:
                 return None
             fact_data = dict(fact_rows[0])
 
-            # Skip archived facts unless config allows
-            if (
-                fact_data.get("lifecycle") in ("archived",)
-                and not self._config.include_archived
-            ):
+            # Skip archived/forgotten facts unless config allows (V3.3: forgetting-aware)
+            lifecycle = fact_data.get("lifecycle", "")
+            if lifecycle in self._EXCLUDED_ZONES and not self._config.include_archived:
                 return None
 
             # Get contextual description
@@ -482,3 +499,24 @@ class AutoInvoker:
             f"(FOK >= {self._config.fok_threshold})_"
         )
         return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # V3.3: Soft prompt injection
+    # ------------------------------------------------------------------
+
+    def _get_soft_prompt_text(self) -> str:
+        """Retrieve soft prompt text via PromptInjector (V3.3).
+
+        Returns assembled soft prompt text, or "" if injector is not
+        wired or no active soft prompts exist. Errors are logged and
+        swallowed -- soft prompt failure MUST NOT block auto-invoke.
+        """
+        if self._prompt_injector is None:
+            return ""
+        try:
+            return self._prompt_injector.get_injection_context(
+                self._config.profile_id,
+            )
+        except Exception as exc:
+            logger.debug("Soft prompt injection failed: %s", exc)
+            return ""

package/src/superlocalmemory/hooks/auto_parameterize.py

@@ -0,0 +1,147 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3.3
+
+"""AutoParameterizeHook — Trigger parameterization on consolidation events.
+
+Runs the full pipeline: extract -> generate -> store -> lifecycle review.
+Rate-limited to config.refresh_interval_hours. Tracks session effectiveness.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.parameterization.pattern_extractor import PatternExtractor
+    from superlocalmemory.parameterization.soft_prompt_generator import SoftPromptGenerator
+    from superlocalmemory.parameterization.prompt_injector import PromptInjector
+    from superlocalmemory.parameterization.prompt_lifecycle import PromptLifecycleManager
+    from superlocalmemory.core.config import ParameterizationConfig
+
+logger = logging.getLogger(__name__)
+
+
+class AutoParameterizeHook:
+    """Hook that triggers soft prompt parameterization on consolidation.
+
+    Called by the consolidation engine after a consolidation cycle completes.
+    Rate-limited to prevent excessive recomputation.
+    """
+
+    def __init__(
+        self,
+        extractor: PatternExtractor,
+        generator: SoftPromptGenerator,
+        injector: PromptInjector,
+        lifecycle: PromptLifecycleManager,
+        config: ParameterizationConfig,
+    ) -> None:
+        self._extractor = extractor
+        self._generator = generator
+        self._injector = injector
+        self._lifecycle = lifecycle
+        self._config = config
+        self._last_run: str | None = None
+
+    # ------------------------------------------------------------------
+    # Event handlers
+    # ------------------------------------------------------------------
+
+    def on_consolidation_complete(self, profile_id: str) -> dict:
+        """Triggered after consolidation engine finishes.
+
+        Runs: extract -> generate -> store -> lifecycle review.
+
+        Args:
+            profile_id: Profile that was consolidated.
+
+        Returns:
+            Status dict with pipeline results.
+        """
+        if not self._config.enabled:
+            return {"status": "disabled"}
+
+        # Rate limit check
+        if self._last_run is not None:
+            try:
+                last = datetime.fromisoformat(self._last_run)
+                if last.tzinfo is None:
+                    last = last.replace(tzinfo=timezone.utc)
+                now = datetime.now(timezone.utc)
+                interval = timedelta(hours=self._config.refresh_interval_hours)
+                if now - last < interval:
+                    return {"status": "rate_limited"}
+            except (ValueError, TypeError):
+                pass
+
+        # Step 1: Extract patterns
+        patterns = self._extractor.extract(profile_id)
+        if not patterns:
+            return {"status": "no_patterns", "count": 0}
+
+        # Step 2: Generate prompts
+        prompts = self._generator.generate(patterns, profile_id)
+        if not prompts:
+            return {"status": "no_prompts", "patterns": len(patterns)}
+
+        # Step 3: Store prompts
+        stored = self._injector.store_prompts(prompts)
+
+        # Step 4: Run lifecycle review
+        lifecycle_stats = self._lifecycle.run_lifecycle_review(profile_id)
+
+        # Update last run timestamp
+        self._last_run = datetime.now(timezone.utc).isoformat()
+
+        return {
+            "status": "success",
+            "patterns": len(patterns),
+            "prompts": stored,
+            "lifecycle": lifecycle_stats,
+        }
+
+    def on_session_end(
+        self, profile_id: str, session_outcome: str,
+    ) -> None:
+        """Triggered at session end for effectiveness tracking.
+
+        Maps session outcome to feedback signals and updates
+        effectiveness for all active prompt categories.
+
+        Args:
+            profile_id: Profile for the ending session.
+            session_outcome: "success" | "failure" | "partial"
+        """
+        if not self._config.effectiveness_tracking:
+            return
+
+        # Map outcome to signals
+        signal_map: dict[str, dict[str, float]] = {
+            "success": {"session_success": 1.0},
+            "failure": {"session_failure": 1.0},
+            "partial": {"session_success": 0.5},
+        }
+        signals = signal_map.get(session_outcome, {})
+        if not signals:
+            return
+
+        # Update effectiveness for all active categories
+        for category in [
+            "identity", "tech_preference", "communication_style",
+            "workflow_pattern", "project_context", "decision_history",
+            "avoidance",
+        ]:
+            try:
+                self._lifecycle.update_effectiveness(
+                    profile_id, category, signals,
+                )
+            except Exception as exc:
+                logger.debug(
+                    "Failed to update effectiveness for %s: %s",
+                    category, exc,
+                )

package/src/superlocalmemory/infra/heartbeat_monitor.py

@@ -0,0 +1,140 @@
+# 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 -- Parent Heartbeat Monitor.
+
+Daemon thread that checks if the parent process (IDE/Claude session) is
+still alive. If the parent dies, initiates graceful shutdown to prevent
+zombie SLM processes consuming 1.5-2 GB each.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class HeartbeatMonitor:
+    """Monitor parent process liveness via a daemon thread.
+
+    When the parent PID is detected as dead, calls the provided
+    shutdown_callback. The monitoring thread is a daemon thread
+    (auto-dies with the main process per HR-06).
+    """
+
+    def __init__(
+        self,
+        parent_pid: int,
+        interval_seconds: int,
+        shutdown_callback: Callable[[], None],
+    ) -> None:
+        self._parent_pid = parent_pid
+        self._interval = interval_seconds
+        self._shutdown_callback = shutdown_callback
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._running = False
+
+    # -- Lifecycle ----------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the heartbeat monitoring daemon thread."""
+        if self._running:
+            logger.warning("Heartbeat monitor already running")
+            return
+
+        # HR-02 equivalent: refuse to monitor PID 0 or 1
+        if self._parent_pid <= 1:
+            logger.warning(
+                "Refusing to monitor PID %d (<= 1), heartbeat not started",
+                self._parent_pid,
+            )
+            return
+
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._monitor_loop,
+            name="slm-heartbeat",
+            daemon=True,
+        )
+        self._thread.start()
+        self._running = True
+        logger.info(
+            "Heartbeat monitor started: watching parent PID %d every %ds",
+            self._parent_pid,
+            self._interval,
+        )
+
+    def stop(self) -> None:
+        """Stop the heartbeat monitor gracefully."""
+        if not self._running:
+            return
+
+        self._stop_event.set()
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=self._interval + 2)
+
+        self._running = False
+        logger.info("Heartbeat monitor stopped")
+
+    # -- Properties ---------------------------------------------------------
+
+    @property
+    def is_running(self) -> bool:
+        """Whether the monitor thread is active."""
+        return self._running
+
+    # -- Internal -----------------------------------------------------------
+
+    def _monitor_loop(self) -> None:
+        """Heartbeat loop running in daemon thread.
+
+        Uses threading.Event.wait(timeout) instead of time.sleep()
+        because Event.wait() is immediately interruptible by stop(),
+        while sleep() blocks for the full duration.
+        """
+        logger.debug(
+            "Heartbeat loop started for parent PID %d", self._parent_pid
+        )
+
+        while not self._stop_event.is_set():
+            stopped = self._stop_event.wait(timeout=self._interval)
+            if stopped:
+                break
+
+            if not self._is_parent_alive():
+                logger.warning(
+                    "Parent PID %d died, initiating graceful shutdown",
+                    self._parent_pid,
+                )
+                try:
+                    self._shutdown_callback()
+                except Exception:
+                    logger.exception("Shutdown callback failed")
+                break
+
+        logger.debug("Heartbeat loop exited")
+
+    def _is_parent_alive(self) -> bool:
+        """Check if parent PID is still a running process.
+
+        Conservative: returns True on PermissionError (parent exists
+        but is owned by another user).
+        """
+        if self._parent_pid <= 1:
+            return False
+
+        try:
+            os.kill(self._parent_pid, 0)
+            return True
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True  # Alive, different user -- conservative
+        except OSError:
+            return False

package/src/superlocalmemory/infra/pid_manager.py

@@ -0,0 +1,193 @@
+# 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 -- PID File Manager.
+
+Atomic JSON-based PID tracking. Records which SLM processes are running
+and their parent PIDs for orphan detection.
+
+File format: {"pids": [{"pid": 1234, "ppid": 5678, "started_at": "2026-03-30T14:25:01"}]}
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# PidRecord -- frozen dataclass for a single process entry
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class PidRecord:
+    """A single PID record stored in the PID file."""
+
+    pid: int
+    ppid: int
+    started_at: str
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize to a JSON-compatible dictionary."""
+        return {
+            "pid": self.pid,
+            "ppid": self.ppid,
+            "started_at": self.started_at,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> PidRecord:
+        """Deserialize from a dictionary (as read from JSON)."""
+        return PidRecord(
+            pid=int(d["pid"]),
+            ppid=int(d["ppid"]),
+            started_at=str(d["started_at"]),
+        )
+
+
+# ---------------------------------------------------------------------------
+# PidManager -- atomic JSON PID file management
+# ---------------------------------------------------------------------------
+
+class PidManager:
+    """Manage a JSON file tracking running SLM process PIDs.
+
+    Uses atomic temp-file-then-rename writes so the file is never
+    corrupted by a crash mid-write.
+    """
+
+    def __init__(self, pid_file_path: Path) -> None:
+        self._path = pid_file_path
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+    # -- Read ---------------------------------------------------------------
+
+    def read_all(self) -> list[PidRecord]:
+        """Read all PID records from the PID file.
+
+        Returns empty list if the file is missing, corrupt, or malformed.
+        Corrupt files are deleted so the next write starts clean.
+        """
+        if not self._path.exists():
+            return []
+
+        try:
+            raw = self._path.read_text(encoding="utf-8")
+            data = json.loads(raw)
+
+            if not isinstance(data, dict) or "pids" not in data:
+                logger.warning("Malformed PID file %s, resetting", self._path)
+                return []
+
+            return [
+                PidRecord.from_dict(entry)
+                for entry in data["pids"]
+                if isinstance(entry, dict)
+            ]
+
+        except json.JSONDecodeError:
+            logger.warning("Corrupt PID file %s, deleting", self._path)
+            try:
+                self._path.unlink(missing_ok=True)
+            except OSError:
+                pass
+            return []
+
+        except OSError as exc:
+            logger.warning("Cannot read PID file %s: %s", self._path, exc)
+            return []
+
+    # -- Write (atomic) -----------------------------------------------------
+
+    def _write_all(self, records: list[PidRecord]) -> None:
+        """Atomically write all PID records to the PID file.
+
+        Uses temp-file-then-rename pattern:
+        - Write to a temp file in the same directory
+        - os.replace() is atomic on POSIX (single inode swap)
+        - On crash: either old file or new file, never corruption
+        """
+        data = {"pids": [r.to_dict() for r in records]}
+        content = json.dumps(data, indent=2)
+
+        tmp_path: str | None = None
+        try:
+            fd, tmp_path = tempfile.mkstemp(
+                dir=str(self._path.parent),
+                suffix=".tmp",
+                prefix="slm-pids-",
+            )
+            os.write(fd, content.encode("utf-8"))
+            os.fsync(fd)
+            os.close(fd)
+            os.replace(tmp_path, str(self._path))
+            tmp_path = None  # Consumed by replace, no cleanup needed
+
+        except OSError as exc:
+            logger.warning("Cannot write PID file %s: %s", self._path, exc)
+
+        finally:
+            if tmp_path is not None:
+                try:
+                    Path(tmp_path).unlink(missing_ok=True)
+                except OSError:
+                    pass
+
+    # -- Register / Remove --------------------------------------------------
+
+    def register(self, pid: int, ppid: int) -> None:
+        """Add current process to PID file (replaces stale entry for same PID)."""
+        records = self.read_all()
+        records = [r for r in records if r.pid != pid]
+
+        new_record = PidRecord(
+            pid=pid,
+            ppid=ppid,
+            started_at=datetime.now(UTC).isoformat(),
+        )
+        records.append(new_record)
+        self._write_all(records)
+
+    def remove(self, pid: int) -> bool:
+        """Remove a PID from the file. Returns True if found and removed."""
+        records = self.read_all()
+        new_records = [r for r in records if r.pid != pid]
+
+        if len(new_records) == len(records):
+            return False
+
+        self._write_all(new_records)
+        return True
+
+    # -- Housekeeping -------------------------------------------------------
+
+    def cleanup_dead(self) -> int:
+        """Remove all PIDs that are no longer running.
+
+        Returns number of dead PIDs removed.
+        """
+        records = self.read_all()
+        alive: list[PidRecord] = []
+        removed = 0
+
+        for r in records:
+            try:
+                os.kill(r.pid, 0)
+                alive.append(r)
+            except ProcessLookupError:
+                removed += 1
+            except PermissionError:
+                alive.append(r)  # Exists but owned by another user
+
+        if removed > 0:
+            self._write_all(alive)
+
+        return removed