superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/core/priority_queue.py

@@ -1,61 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Weighted fair scheduler for high/low job lanes.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import threading
-from typing import Literal
-
-Lane = Literal["high", "low"]
-
-
-class WFQScheduler:
-    """Deficit-round-robin-ish scheduler over two lanes.
-
-    Tracks served counts and picks the lane whose ratio is furthest
-    below its target share. Approximates the target ratio over any
-    rolling window without requiring a time source.
-    """
-
-    def __init__(self, high_weight: int = 70, low_weight: int = 30) -> None:
-        if high_weight <= 0 or low_weight <= 0:
-            raise ValueError("weights must be positive")
-        self.high_weight = high_weight
-        self.low_weight = low_weight
-        self._served = {"high": 0, "low": 0}
-        self._lock = threading.Lock()
-
-    def pick_lane(self, *, has_high: bool, has_low: bool) -> Lane | None:
-        if not has_high and not has_low:
-            return None
-        if has_high and not has_low:
-            return "high"
-        if has_low and not has_high:
-            return "low"
-        with self._lock:
-            total = self._served["high"] + self._served["low"]
-            if total == 0:
-                return "high"
-            total_weight = self.high_weight + self.low_weight
-            high_target = self.high_weight / total_weight
-            low_target = self.low_weight / total_weight
-            high_ratio = self._served["high"] / total
-            low_ratio = self._served["low"] / total
-            # Pick whichever lane is further below its target
-            high_deficit = high_target - high_ratio
-            low_deficit = low_target - low_ratio
-            return "high" if high_deficit >= low_deficit else "low"
-
-    def record_served(self, lane: Lane) -> None:
-        with self._lock:
-            self._served[lane] += 1
-
-    def snapshot(self) -> dict[str, int]:
-        with self._lock:
-            return dict(self._served)

package/src/superlocalmemory/core/pruning_engine.py

@@ -1,216 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""SuperLocalMemory v3.4.5 — Graph Pruning Engine.
-
-Reduces graph edge count without losing meaningful connections.
-Strategies:
-  1. Chain collapse: A→B→C → remove B→C if A→B exists with higher weight
-  2. Garbage entity removal: remove edges connected to garbage entities
-  3. Low-activity edge decay: edges between entities not accessed in 90+ days
-
-CRITICAL RULE: NEVER delete atomic_facts. Only prune graph_edges.
-Edges are derivable from facts — they can be regenerated.
-Facts are the permanent record.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import logging
-from datetime import datetime, timedelta, UTC
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from superlocalmemory.storage.database import DatabaseManager
-
-logger = logging.getLogger(__name__)
-
-# Thresholds
-LOW_ACTIVITY_DAYS = 90
-CHAIN_COLLAPSE_MIN_WEIGHT_RATIO = 0.8
-BATCH_SIZE = 500
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-def prune_graph(
-    db: DatabaseManager,
-    profile_id: str = "default",
-    dry_run: bool = False,
-) -> dict[str, int]:
-    """Prune graph edges using all strategies.
-
-    Returns counts of edges removed per strategy.
-    Safe to run repeatedly — idempotent.
-    """
-    stats = {
-        "chain_collapsed": 0,
-        "garbage_removed": 0,
-        "low_activity_decayed": 0,
-        "total_removed": 0,
-        "edges_before": 0,
-        "edges_after": 0,
-    }
-
-    # Count before
-    rows = db.execute(
-        "SELECT COUNT(*) as c FROM graph_edges", ()
-    )
-    stats["edges_before"] = rows[0]["c"] if rows else 0
-
-    # Strategy 1: Chain collapse
-    collapsed = _collapse_chains(db, profile_id, dry_run)
-    stats["chain_collapsed"] = collapsed
-
-    # Strategy 2: Garbage entity edges
-    garbage = _remove_garbage_edges(db, profile_id, dry_run)
-    stats["garbage_removed"] = garbage
-
-    # Strategy 3: Low-activity edge decay
-    decayed = _decay_low_activity_edges(db, profile_id, dry_run)
-    stats["low_activity_decayed"] = decayed
-
-    stats["total_removed"] = collapsed + garbage + decayed
-
-    # Count after
-    rows = db.execute(
-        "SELECT COUNT(*) as c FROM graph_edges", ()
-    )
-    stats["edges_after"] = rows[0]["c"] if rows else 0
-
-    if stats["total_removed"] > 0:
-        logger.info(
-            "Graph pruning: %d edges removed (%d → %d)",
-            stats["total_removed"], stats["edges_before"], stats["edges_after"],
-        )
-
-    return stats
-
-
-# ---------------------------------------------------------------------------
-# Strategy 1: Chain Collapse
-# ---------------------------------------------------------------------------
-
-def _collapse_chains(db: DatabaseManager, profile_id: str, dry_run: bool) -> int:
-    """Collapse redundant chain edges.
-
-    If A→B (weight=0.9) and B→C (weight=0.5), and A→C also exists,
-    remove B→C if A→C weight >= B→C weight * threshold.
-
-    This preserves the semantic connection (A→C is stronger) while
-    removing intermediate edges.
-    """
-    try:
-        rows = db.execute("""
-            SELECT ge1.source_id as a, ge1.target_id as b, ge1.weight as w_ab,
-                   ge2.source_id as b2, ge2.target_id as c, ge2.weight as w_bc,
-                   ge3.weight as w_ac
-            FROM graph_edges ge1
-            JOIN graph_edges ge2 ON ge1.target_id = ge2.source_id
-            LEFT JOIN graph_edges ge3 ON ge1.source_id = ge3.source_id
-                                       AND ge2.target_id = ge3.target_id
-            WHERE ge3.weight >= ge2.weight * ?
-            LIMIT ?
-        """, (CHAIN_COLLAPSE_MIN_WEIGHT_RATIO, BATCH_SIZE))
-    except Exception as exc:
-        logger.warning("Chain collapse query failed: %s", exc)
-        return 0
-
-    remove_ids = []
-    for row in rows:
-        b_id = row["b"]
-        c_id = row["c"]
-        # Remove B→C edge
-        if not dry_run:
-            db.execute(
-                "DELETE FROM graph_edges WHERE source_id = ? AND target_id = ?",
-                (b_id, c_id),
-            )
-        remove_ids.append((b_id, c_id))
-
-    if remove_ids and not dry_run:
-        logger.info("Chain collapse: removed %d edges", len(remove_ids))
-
-    return len(remove_ids)
-
-
-# ---------------------------------------------------------------------------
-# Strategy 2: Garbage Entity Edges
-# ---------------------------------------------------------------------------
-
-def _remove_garbage_edges(db: DatabaseManager, profile_id: str, dry_run: bool) -> int:
-    """Remove edges connected to garbage/blacklisted entities."""
-    try:
-        rows = db.execute("""
-            SELECT ge.source_id, ge.target_id
-            FROM graph_edges ge
-            WHERE ge.source_id IN (SELECT term FROM entity_blacklist)
-               OR ge.target_id IN (SELECT term FROM entity_blacklist)
-            LIMIT ?
-        """, (BATCH_SIZE,))
-    except Exception:
-        return 0
-
-    count = 0
-    for row in rows:
-        if not dry_run:
-            db.execute(
-                "DELETE FROM graph_edges WHERE source_id = ? AND target_id = ?",
-                (row["source_id"], row["target_id"]),
-            )
-        count += 1
-
-    if count and not dry_run:
-        logger.info("Garbage edges removed: %d", count)
-
-    return count
-
-
-# ---------------------------------------------------------------------------
-# Strategy 3: Low-Activity Edge Decay
-# ---------------------------------------------------------------------------
-
-def _decay_low_activity_edges(
-    db: DatabaseManager, profile_id: str, dry_run: bool,
-) -> int:
-    """Remove edges between entities not accessed in 90+ days.
-
-    Only removes edges where BOTH connected entities have no recent access.
-    """
-    cutoff = (datetime.now(UTC) - timedelta(days=LOW_ACTIVITY_DAYS)).isoformat()
-
-    try:
-        rows = db.execute("""
-            SELECT ge.source_id, ge.target_id
-            FROM graph_edges ge
-            WHERE ge.source_id NOT IN (
-                SELECT DISTINCT entity_id FROM fact_access_log
-                WHERE accessed_at >= ?
-            )
-            AND ge.target_id NOT IN (
-                SELECT DISTINCT entity_id FROM fact_access_log
-                WHERE accessed_at >= ?
-            )
-            LIMIT ?
-        """, (cutoff, cutoff, BATCH_SIZE))
-    except Exception:
-        return 0
-
-    count = 0
-    for row in rows:
-        if not dry_run:
-            db.execute(
-                "DELETE FROM graph_edges WHERE source_id = ? AND target_id = ?",
-                (row["source_id"], row["target_id"]),
-            )
-        count += 1
-
-    if count and not dry_run:
-        logger.info("Low-activity edges decayed: %d", count)
-
-    return count

package/src/superlocalmemory/core/queue_dispatcher.py

@@ -1,73 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Queue-backed dispatcher coordinator.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from typing import Any
-
-from superlocalmemory.core import rate_limit as rl
-from superlocalmemory.core import recall_queue as rq
-from superlocalmemory.core.engine_lock import EngineRWLock
-
-
-class QueueDispatcher:
-    """Coordinates rate-limit check, enqueue, and poll for callers."""
-
-    def __init__(
-        self,
-        *,
-        db_path: Path | str,
-        global_rps: float = 100.0,
-        per_pid_rps: float = 30.0,
-        per_agent_rps: float = 10.0,
-    ) -> None:
-        self.queue = rq.RecallQueue(db_path=db_path)
-        self.engine_lock = EngineRWLock()
-        self._rate = rl.LayeredRateLimiter(
-            global_rps=global_rps,
-            per_pid_rps=per_pid_rps,
-            per_agent_rps=per_agent_rps,
-        )
-        # Module handles kept for test introspection.
-        self.rl = rl
-        self.rq = rq
-
-    def _check_rate(self, *, pid: int, agent_id: str | None) -> None:
-        self._rate.check_and_consume(pid=pid, agent_id=agent_id)
-
-    def dispatch(
-        self,
-        *,
-        query: str,
-        limit_n: int,
-        mode: str,
-        agent_id: str,
-        session_id: str,
-        tenant_id: str = "",
-        namespace: str = "",
-        priority: str = "high",
-        stall_timeout_s: float = 25.0,
-        timeout_s: float = 30.0,
-    ) -> dict[str, Any]:
-        self._check_rate(pid=os.getpid(), agent_id=agent_id)
-        rid = self.queue.enqueue(
-            query=query, limit_n=limit_n, mode=mode,
-            agent_id=agent_id, session_id=session_id,
-            tenant_id=tenant_id, namespace=namespace,
-            priority=priority, stall_timeout_s=stall_timeout_s,
-        )
-        try:
-            return self.queue.poll_result(rid, timeout_s=timeout_s)
-        finally:
-            self.queue.unsubscribe(rid)
-
-    def close(self) -> None:
-        self.queue.close()

package/src/superlocalmemory/core/slmignore.py

@@ -1,125 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — Stage 8 SB-5
-
-"""Path-level opt-out via ``.slmignore``.
-
-A repository-scoped escape hatch: drop a ``.slmignore`` at any
-ancestor of a workspace and SLM will skip hooks / recall / remember
-for any path inside that ancestor. Roughly the shape of ``.gitignore``
-but with simpler matching — one path pattern per line, ``#`` comments,
-whitespace stripped.
-
-Matching rules (intentionally minimal):
-
-- Lines starting with ``#`` or empty ⇒ ignored.
-- A line like ``node_modules`` matches any path segment named
-  ``node_modules`` anywhere in the resolved absolute path.
-- A line starting with ``/`` is an absolute-prefix match
-  (``/Users/me/secret`` matches everything under that dir).
-- Glob chars ``*`` / ``?`` are treated literally — keep it boring,
-  avoid re-implementing ``.gitignore``'s subtleties.
-
-Cache: the parsed ignore list is memoised per ignore-file path + mtime.
-Look-up cost at the hook hot path is O(depth × patterns) and
-patterns ≤ 50 in practice.
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-_FILENAME = ".slmignore"
-_CACHE: dict[tuple[str, float], tuple[str, ...]] = {}
-_CACHE_CAP = 64
-
-
-def _load_patterns(ignore_path: Path) -> tuple[str, ...]:
-    """Parse one ``.slmignore`` file, memoised by path + mtime."""
-    try:
-        stat = ignore_path.stat()
-    except OSError:
-        return ()
-    key = (str(ignore_path), stat.st_mtime)
-    cached = _CACHE.get(key)
-    if cached is not None:
-        return cached
-    try:
-        raw = ignore_path.read_text(encoding="utf-8", errors="ignore")
-    except OSError:
-        return ()
-    patterns: list[str] = []
-    for line in raw.splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        patterns.append(stripped)
-    result = tuple(patterns)
-    if len(_CACHE) >= _CACHE_CAP:
-        _CACHE.clear()
-    _CACHE[key] = result
-    return result
-
-
-def _iter_ancestor_ignores(target: Path) -> list[tuple[Path, tuple[str, ...]]]:
-    """Walk from ``target`` up to the filesystem root collecting ignore files."""
-    hits: list[tuple[Path, tuple[str, ...]]] = []
-    seen_dirs: set[Path] = set()
-    probe = target if target.is_dir() else target.parent
-    while probe not in seen_dirs:
-        seen_dirs.add(probe)
-        candidate = probe / _FILENAME
-        if candidate.is_file():
-            patterns = _load_patterns(candidate)
-            if patterns:
-                hits.append((candidate.parent, patterns))
-        if probe.parent == probe:
-            break
-        probe = probe.parent
-    return hits
-
-
-def path_is_ignored(target: str | Path) -> bool:
-    """Return True iff any ancestor ``.slmignore`` ignores the given path.
-
-    Absolute paths are resolved (symlinks preserved — we match on name,
-    not realpath, so a symlink into an ignored dir still matches).
-    Non-existent targets are allowed; we walk the theoretical ancestry.
-    """
-    p = Path(target)
-    try:
-        abs_path = p.resolve(strict=False)
-    except OSError:
-        abs_path = p
-    segments = set(abs_path.parts)
-    for ignore_dir, patterns in _iter_ancestor_ignores(abs_path):
-        for pat in patterns:
-            if pat.startswith("/"):
-                # Absolute prefix: the ignore file's directory provides the
-                # anchor for relative-looking absolute patterns.
-                candidate = Path(pat)
-                try:
-                    abs_path.relative_to(candidate)
-                    return True
-                except ValueError:
-                    continue
-            else:
-                # Match any path segment.
-                if pat in segments:
-                    return True
-                # Also honour a per-ignore-dir relative path.
-                rel = abs_path.relative_to(ignore_dir) if (
-                    ignore_dir in abs_path.parents or ignore_dir == abs_path
-                ) else None
-                if rel is not None and pat in set(rel.parts):
-                    return True
-    return False
-
-
-def clear_cache() -> None:
-    """Test-only helper: drop the memoised pattern cache."""
-    _CACHE.clear()
-
-
-__all__ = ("path_is_ignored", "clear_cache")

package/src/superlocalmemory/infra/heartbeat_monitor.py

@@ -1,140 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - 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