superlocalmemory 3.3.20 → 3.3.21

package/src/superlocalmemory/code_graph/watcher.py

@@ -0,0 +1,207 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Module
+
+"""CodeGraphWatcher — file system watcher with debounce.
+
+Wraps watchdog Observer in a daemon thread. 300ms debounce coalesces
+rapid file changes. Only reacts to supported source extensions.
+Ignored directories (node_modules, .git, __pycache__, etc.) are skipped.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.code_graph.service import CodeGraphService
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SUPPORTED_EXTENSIONS: frozenset[str] = frozenset({
+    ".py", ".ts", ".tsx", ".js", ".jsx",
+})
+
+IGNORED_DIRS: frozenset[str] = frozenset({
+    "node_modules", ".git", "__pycache__", ".venv", "venv",
+    "dist", "build", ".tox", ".mypy_cache", ".pytest_cache",
+    "coverage", ".next", ".nuxt", ".eggs", "egg-info",
+})
+
+DEBOUNCE_SECONDS: float = 0.3
+
+
+# ---------------------------------------------------------------------------
+# Event handler
+# ---------------------------------------------------------------------------
+
+class _DebouncedHandler:
+    """File system event handler with debounce logic.
+
+    Accumulates changed file paths and flushes them after DEBOUNCE_SECONDS
+    of inactivity. Uses a threading.Timer for the debounce.
+    """
+
+    def __init__(self, repo_root: str, callback) -> None:
+        self._repo_root = repo_root
+        self._callback = callback
+        self._pending: dict[str, float] = {}
+        self._timer: threading.Timer | None = None
+        self._lock = threading.Lock()
+
+    def on_event(self, src_path: str, is_delete: bool = False) -> None:
+        """Handle a file system event."""
+        # Filter by extension
+        ext = os.path.splitext(src_path)[1]
+        if ext not in SUPPORTED_EXTENSIONS:
+            return
+
+        # Filter by ignored directories
+        parts = Path(src_path).parts
+        for part in parts:
+            if part in IGNORED_DIRS:
+                return
+
+        with self._lock:
+            if is_delete:
+                # Deletions are immediate
+                self._flush_immediate([src_path])
+                return
+
+            self._pending[src_path] = time.time()
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(DEBOUNCE_SECONDS, self._flush)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _flush(self) -> None:
+        """Flush pending changes to the callback."""
+        with self._lock:
+            paths = list(self._pending.keys())
+            self._pending.clear()
+            self._timer = None
+
+        if paths:
+            try:
+                self._callback(paths)
+            except Exception as exc:
+                logger.warning("Watcher callback failed: %s", exc)
+
+    def _flush_immediate(self, paths: list[str]) -> None:
+        """Flush specific paths immediately (for deletions)."""
+        try:
+            self._callback(paths)
+        except Exception as exc:
+            logger.warning("Watcher callback failed: %s", exc)
+
+    def cancel(self) -> None:
+        """Cancel any pending timer."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            self._pending.clear()
+
+
+# ---------------------------------------------------------------------------
+# CodeGraphWatcher
+# ---------------------------------------------------------------------------
+
+class CodeGraphWatcher:
+    """Watches a repository for file changes and triggers incremental updates.
+
+    Runs in a daemon thread — never blocks the main thread (HR-6).
+    """
+
+    def __init__(self, repo_root: str, service: CodeGraphService) -> None:
+        self._repo_root = str(repo_root)
+        self._service = service
+        self._observer = None
+        self._handler = None
+        self._running = False
+
+    def start(self) -> None:
+        """Start watching. Non-blocking — spawns a daemon thread."""
+        try:
+            from watchdog.observers import Observer
+            from watchdog.events import FileSystemEventHandler
+        except ImportError:
+            raise ImportError(
+                "watchdog not installed. Install with: pip install superlocalmemory[code-graph]"
+            )
+
+        def _on_changes(paths: list[str]) -> None:
+            """Called by debounced handler with accumulated changes."""
+            try:
+                rel_paths = []
+                root = Path(self._repo_root)
+                for p in paths:
+                    try:
+                        rel = str(Path(p).relative_to(root))
+                        rel_paths.append(rel)
+                    except ValueError:
+                        rel_paths.append(p)
+
+                logger.info(
+                    "Watcher detected %d changed files, updating graph",
+                    len(rel_paths),
+                )
+                # Placeholder: incremental update would go here
+                # The service doesn't have an incremental_update method yet
+                # but this is where it would be called
+            except Exception as exc:
+                logger.warning("Watcher update failed: %s", exc)
+
+        self._handler = _DebouncedHandler(self._repo_root, _on_changes)
+
+        class _WatchdogBridge(FileSystemEventHandler):
+            """Bridge between watchdog events and our debounced handler."""
+
+            def __init__(self, handler: _DebouncedHandler) -> None:
+                self._handler = handler
+
+            def on_modified(self, event):
+                if not event.is_directory:
+                    self._handler.on_event(event.src_path)
+
+            def on_created(self, event):
+                if not event.is_directory:
+                    self._handler.on_event(event.src_path)
+
+            def on_deleted(self, event):
+                if not event.is_directory:
+                    self._handler.on_event(event.src_path, is_delete=True)
+
+        self._observer = Observer()
+        bridge = _WatchdogBridge(self._handler)
+        self._observer.schedule(bridge, self._repo_root, recursive=True)
+        self._observer.daemon = True
+        self._observer.start()
+        self._running = True
+        logger.info("CodeGraphWatcher started for %s", self._repo_root)
+
+    def stop(self) -> None:
+        """Stop watching and clean up."""
+        if self._handler is not None:
+            self._handler.cancel()
+        if self._observer is not None:
+            self._observer.stop()
+            self._observer.join(timeout=5)
+            self._observer = None
+        self._running = False
+        logger.info("CodeGraphWatcher stopped")
+
+    @property
+    def is_running(self) -> bool:
+        """Whether the watcher is currently running."""
+        return self._running

package/src/superlocalmemory/core/embedding_worker.py

@@ -164,13 +164,15 @@ def _worker_main() -> None:
             except Exception as exc:
                 _respond({"ok": False, "error": str(exc)})
 
-            # V3.3.16: RSS watchdog — self-terminate if memory exceeds 1.5GB.
+            # V3.3.16: RSS watchdog — self-terminate if memory exceeds limit.
             # PyTorch on ARM64 Mac never returns memory to OS. After ~200 embeds
             # a worker that started at 300MB grows to 17GB+. Parent auto-respawns
             # a fresh worker on next request (existing mechanism in embeddings.py).
+            # V3.3.21: Configurable via SLM_EMBED_WORKER_RSS_LIMIT_MB (default 2500MB).
             import resource
+            _rss_limit = int(os.environ.get("SLM_EMBED_WORKER_RSS_LIMIT_MB", 2500))
             rss_mb = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024 / 1024
-            if rss_mb > 2500:
+            if rss_mb > _rss_limit:
                 sys.exit(0)
 
             continue

package/src/superlocalmemory/core/embeddings.py

@@ -52,8 +52,14 @@ class DimensionMismatchError(RuntimeError):
 _IDLE_TIMEOUT_SECONDS = 120  # 2 minutes — kill worker after idle
 # V3.3.12: Configurable via SLM_EMBED_IDLE_TIMEOUT env var (seconds)
 _IDLE_TIMEOUT_SECONDS = int(os.environ.get("SLM_EMBED_IDLE_TIMEOUT", _IDLE_TIMEOUT_SECONDS))
-_SUBPROCESS_RESPONSE_TIMEOUT = 180  # V3.3.12: 180s (was 120s) — respawns on stressed systems need more time
-_WORKER_RECYCLE_AFTER = 1000  # Recycle worker after N requests (C++ fragmentation prevention)
+# V3.3.21: Configurable response timeout — 180s default, but batch ingestion
+# (2-turn chunks across 10 conversations) needs 600s+ to survive cold-start
+# model downloads and ARM64 ONNX compilation pauses.
+_SUBPROCESS_RESPONSE_TIMEOUT = int(os.environ.get("SLM_EMBED_RESPONSE_TIMEOUT", 180))
+# V3.3.21: Increase recycle threshold to 5000 (was 1000). With 2-turn chunks,
+# a single conversation produces ~50-80 store calls. 10 conversations = 500-800.
+# Recycling at 1000 caused mid-ingestion worker death → timeout cascade.
+_WORKER_RECYCLE_AFTER = int(os.environ.get("SLM_EMBED_RECYCLE_AFTER", 5000))
 
 
 class EmbeddingService:

package/src/superlocalmemory/core/engine.py

@@ -212,6 +212,38 @@ class MemoryEngine:
             self._config.mode.value, self._profile_id,
         )
 
+        # V3.3.21: Process any pending memories from failed async remember.
+        # Zero cost if no pending.db exists. Backward compatible.
+        self._process_pending_memories()
+
+    def _process_pending_memories(self) -> None:
+        """Process pending memories from store-first async pattern.
+
+        Called on initialize(). If pending.db doesn't exist or has no items,
+        returns immediately (~0ms). If items exist, processes them through the
+        normal store() pipeline and marks them done/failed.
+        """
+        try:
+            from superlocalmemory.cli.pending_store import (
+                get_pending, mark_done, mark_failed,
+            )
+        except ImportError:
+            return
+
+        base_dir = self._config.base_dir
+        pending = get_pending(base_dir, limit=20)
+        if not pending:
+            return
+
+        logger.info("Processing %d pending memories from async store", len(pending))
+        for item in pending:
+            try:
+                self.store(item["content"])
+                mark_done(item["id"], base_dir)
+            except Exception as exc:
+                logger.warning("Pending memory %d failed: %s", item["id"], exc)
+                mark_failed(item["id"], str(exc), base_dir)
+
     # -- Store operations ---------------------------------------------------
 
     def store(

package/src/superlocalmemory/core/engine_wiring.py

@@ -334,6 +334,11 @@ def _init_spreading_activation(
     vector_store: Any,
 ) -> Any | None:
     """Create SpreadingActivation for Phase 3 5th retrieval channel."""
+    # V3.3.21: Guard against None vector_store. Without embeddings, SA's
+    # search() crashes with "'NoneType' has no attribute 'search'".
+    if vector_store is None:
+        logger.debug("SpreadingActivation skipped: no vector_store")
+        return None
     try:
         from superlocalmemory.retrieval.spreading_activation import (
             SpreadingActivation,

package/src/superlocalmemory/core/store_pipeline.py

@@ -172,7 +172,12 @@ def run_store(
     # This ensures BM25 and semantic search can always find the original text.
     # V3.3.12: Extract entities from verbatim content so entity channel + temporal
     # channel can find it (was entities=[] which made 4/6 channels blind).
-    if content.strip() and len(content.strip()) >= 20:
+    # V3.3.20: Stronger verbatim filter — skip greetings, filler, short phrases.
+    # Verbatim facts with just "Hey! How are you?" dilute embeddings and add noise.
+    _MIN_VERBATIM_WORDS = 8
+    if (content.strip()
+            and len(content.strip()) >= 40
+            and len(content.strip().split()) >= _MIN_VERBATIM_WORDS):
         import uuid
         import re as _re
         _verbatim_text = content.strip()
@@ -197,6 +202,23 @@ def run_store(
         if verbatim.content.strip().lower() not in extracted_texts:
             facts.append(verbatim)
 
+    # V3.3.21: If fact extraction produced nothing (short input like "this is test"),
+    # store the raw content as a minimal fact. User explicitly called `slm remember` —
+    # their data should NEVER be silently dropped. The min-length and min-word filters
+    # are designed for automatic conversation extraction, not explicit user storage.
+    if not facts and content.strip():
+        import uuid
+        facts = [AtomicFact(
+            fact_id=uuid.uuid4().hex[:16],
+            content=content.strip(),
+            fact_type=FactType.SEMANTIC,
+            entities=[],
+            session_id=session_id,
+            observation_date=parsed_date,
+            confidence=0.7,
+            importance=0.3,
+        )]
+
     if not facts:
         return []
 

package/src/superlocalmemory/encoding/fact_extractor.py

@@ -212,7 +212,40 @@ def _try_parse_date(raw: str, reference_date: str | None = None) -> str | None:
     except Exception:
         pass
 
-    # dateparser for relative dates (yesterday, last week, next Friday)
+    # V3.3.21: Rule-based relative date resolution (no dateparser dependency).
+    # Handles the 90% case: yesterday, today, tomorrow, last X, next X.
+    raw_lower = raw.strip().lower()
+    if reference_date:
+        try:
+            from datetime import datetime, timedelta
+            ref_dt = du_parser.parse(reference_date)
+            _RELATIVE_MAP: dict[str, int] = {
+                "yesterday": -1, "today": 0, "tomorrow": 1,
+                "the day before": -2, "the other day": -2,
+                "day before yesterday": -2,
+            }
+            if raw_lower in _RELATIVE_MAP:
+                resolved = ref_dt + timedelta(days=_RELATIVE_MAP[raw_lower])
+                return resolved.date().isoformat()
+            # "last week" = -7, "last month" ≈ -30, "last year" = -365
+            if raw_lower == "last week":
+                return (ref_dt - timedelta(days=7)).date().isoformat()
+            if raw_lower == "last month":
+                month = ref_dt.month - 1 or 12
+                year = ref_dt.year if ref_dt.month > 1 else ref_dt.year - 1
+                return f"{year}-{month:02d}-{ref_dt.day:02d}"
+            if raw_lower == "last year":
+                return f"{ref_dt.year - 1}-{ref_dt.month:02d}-{ref_dt.day:02d}"
+            if raw_lower == "next week":
+                return (ref_dt + timedelta(days=7)).date().isoformat()
+            if raw_lower == "next month":
+                month = ref_dt.month + 1 if ref_dt.month < 12 else 1
+                year = ref_dt.year if ref_dt.month < 12 else ref_dt.year + 1
+                return f"{year}-{month:02d}-{ref_dt.day:02d}"
+        except Exception:
+            pass
+
+    # dateparser for complex relative dates (optional dependency)
     try:
         import dateparser
         settings: dict[str, Any] = {"PREFER_DATES_FROM": "past"}
@@ -223,6 +256,8 @@ def _try_parse_date(raw: str, reference_date: str | None = None) -> str | None:
         result = dateparser.parse(raw, settings=settings)
         if result:
             return result.date().isoformat()
+    except ImportError:
+        pass
     except Exception:
         pass
 
@@ -521,19 +556,45 @@ class FactExtractor:
             if _is_filler(sent):
                 continue
             normalized = sent.strip()
-            if normalized in seen_texts or len(normalized) < 10:
+            if normalized in seen_texts or len(normalized) < 20:
                 continue
             seen_texts.add(normalized)
 
-            # Resolve [Speaker]: prefix to "Speaker" in content
-            # "[Caroline]: I went to..." → "Caroline: I went to..."
+            # V3.3.21: Resolve [Speaker]: prefix AND first-person pronouns.
+            # "[Caroline]: I went to the gym" → "Caroline went to the gym"
+            # This makes facts self-contained and entity-rich for retrieval.
+            # Previous: just prepended "Caroline: I went..." which left pronouns.
             import re as _re
-            _spk_match = _re.match(r"^\[([A-Za-z ]+)\]:\s*", normalized)
+            _resolved_speaker: str | None = None
+            _spk_match = _re.match(r"^\[([A-Za-z ]+)\]:?\s*", normalized)
             if _spk_match:
-                speaker_name = _spk_match.group(1)
-                normalized = f"{speaker_name}: {normalized[_spk_match.end():]}"
+                _resolved_speaker = _spk_match.group(1)
+                rest = normalized[_spk_match.end():]
+                # Replace first-person pronouns with speaker name
+                rest = _re.sub(r"\bI'm\b", f"{_resolved_speaker} is", rest)
+                rest = _re.sub(r"\bI've\b", f"{_resolved_speaker} has", rest)
+                rest = _re.sub(r"\bI'll\b", f"{_resolved_speaker} will", rest)
+                rest = _re.sub(r"\bI'd\b", f"{_resolved_speaker} would", rest)
+                rest = _re.sub(r"\bI was\b", f"{_resolved_speaker} was", rest)
+                rest = _re.sub(r"\bI am\b", f"{_resolved_speaker} is", rest)
+                rest = _re.sub(r"\bI\b", _resolved_speaker, rest)
+                rest = _re.sub(r"\bmy\b", f"{_resolved_speaker}'s", rest, flags=_re.IGNORECASE)
+                rest = _re.sub(r"\bme\b", _resolved_speaker, rest)
+                rest = _re.sub(r"\bmyself\b", _resolved_speaker, rest, flags=_re.IGNORECASE)
+                normalized = rest
+
+            # V3.3.21 R4: Post-resolution filler + length check.
+            # After stripping [Speaker]: prefix, the remaining text may be
+            # just "Hey!", "Yeah totally!", "Thanks Mel!" — pure noise.
+            # These passed the pre-resolution filler check because the prefix
+            # was still attached. Re-check after resolution.
+            if _is_filler(normalized) or len(normalized.strip()) < 20:
+                continue
 
             entities = _extract_entities(normalized)
+            # Ensure resolved speaker is in entities list
+            if _resolved_speaker and _resolved_speaker not in entities:
+                entities = [_resolved_speaker] + entities
             fact_type = _classify_sentence(normalized)
 
             # Three-date model: extract and resolve relative dates

package/src/superlocalmemory/infra/event_bus.py

@@ -39,6 +39,11 @@ VALID_EVENT_TYPES = frozenset([
     "trust.signal",         # V3: trust score change
     "compliance.audit",     # V3: compliance event logged
     "learning.feedback",    # V3: learning feedback received
+    # CodeGraph events (v3.4) — NOTE: "graph.updated" is SLM entity graph, "code_graph.*" is AST code graph
+    "code_graph.built",          # Full code graph build completed
+    "code_graph.updated",        # Incremental code graph update completed
+    "code_graph.node_changed",   # Function/class signature or body changed
+    "code_graph.node_deleted",   # Function/class/file removed from codebase
 ])
 
 

package/src/superlocalmemory/mcp/server.py

@@ -114,6 +114,7 @@ from superlocalmemory.mcp.tools_v3 import register_v3_tools
 from superlocalmemory.mcp.tools_active import register_active_tools
 from superlocalmemory.mcp.tools_v33 import register_v33_tools
 from superlocalmemory.mcp.resources import register_resources
+from superlocalmemory.mcp.tools_code_graph import register_code_graph_tools
 
 register_core_tools(_target, get_engine)
 register_v28_tools(_target, get_engine)
@@ -121,6 +122,28 @@ register_v3_tools(_target, get_engine)
 register_active_tools(_target, get_engine)
 register_v33_tools(_target, get_engine)
 register_resources(server, get_engine)  # Resources always registered (not tools)
+register_code_graph_tools(server, get_engine)  # CodeGraph: registered on `server` (always visible when installed)
+
+
+# V3.3.21: Eager engine warmup — start initializing BEFORE first tool call.
+# The MCP server process starts when the IDE launches. Previously, the engine
+# was lazy-loaded on first tool call → 23s cold start for the user.
+# Now: engine starts warming in a background thread immediately. By the time
+# the first tool call arrives (1-2s later), the engine is already warm.
+# This applies to ALL IDEs: Claude Code, Cursor, Antigravity, Gemini CLI, etc.
+def _eager_warmup() -> None:
+    """Pre-warm engine in background thread."""
+    import logging
+    _logger = logging.getLogger(__name__)
+    try:
+        get_engine()
+        _logger.info("MCP engine pre-warmed successfully")
+    except Exception as exc:
+        _logger.debug("MCP engine pre-warmup failed (non-fatal): %s", exc)
+
+import threading
+_warmup_thread = threading.Thread(target=_eager_warmup, daemon=True, name="mcp-warmup")
+_warmup_thread.start()
 
 
 if __name__ == "__main__":