superlocalmemory 3.4.56 → 3.4.59

package/CHANGELOG.md

@@ -5,6 +5,113 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.4.59] - 2026-05-31 — Graph Edge Cap + Recall Reliability
+
+**Fixes SLM falling into degraded FTS5 mode on every session start**, and stops
+the knowledge graph from growing into an O(n²) edge explosion that made recall
+slow as the fact corpus scaled beyond 10K facts.
+
+### Root Causes Fixed
+
+**1. MCP timeout too aggressive for dense graphs (degraded mode bug)**
+The v3.4.57 timeout reduction (60s→8s) was correct for small graphs but
+backfired at scale. With a 17K-fact corpus and 2.1M graph edges, full 6-channel
+recall (including spreading activation + Hopfield) takes 13–15s. The 8s timeout
+always expired → `pool_recall` raised `PoolError` → session_init fell back to
+emergency FTS5 BM25. Every session started in degraded mode silently.
+
+**Fix:** `DaemonPoolProxy.timeout_s` raised from 8s to 30s. Covers the current
+worst-case (13.4s full recall) with 2× headroom. The orphan-flood concern from
+v3.4.57 is mitigated by the ingest cap reductions below, which stop the graph
+from growing further.
+
+**2. Knowledge graph edge explosion (O(n²) growth)**
+At 17K facts, the corpus hit 2.1M graph edges (avg 121 per node). Root cause:
+`_MAX_ENTITY_EDGES_PER_ENTITY = 20` was designed for ~500-fact graphs. At scale,
+hub entities (appearing in 1000s of facts) accumulated 5000+ edges per node.
+Spreading activation must fan out across all edges per node, causing 9s SA time.
+
+**Fixes:**
+- `_MAX_ENTITY_EDGES_PER_ENTITY` lowered from 20 → 5
+- `_MAX_CAUSAL_EDGES_PER_ENTITY` lowered from 20 → 5
+- **Hub node filter added:** nodes already at ≥ 200 total edges are skipped
+  during ingest. High-frequency hub nodes (e.g. a term appearing in every fact)
+  link everything to everything — they are graph noise, not graph signal.
+- Hub cache shared across entity/causal edge builders per `build_edges` call to
+  avoid redundant DB queries.
+
+**3. Spreading activation UNION query not using indexes (SA slow path)**
+The `_get_unified_neighbors` UNION ALL query fetched all edges for a node then
+sorted them, preventing the `idx_edges_source_weight` and `idx_edges_target_weight`
+covering indexes from terminating early. Fix: push `ORDER BY weight DESC LIMIT ?`
+inside each UNION branch (wrapped in `SELECT * FROM (...)` per SQLite compound
+SELECT syntax). SQLite now stops after `max_neighbors_per_node` rows per branch
+using the covering index instead of materialising the full edge set.
+
+**4. Degree-cap pruner added to graph_pruner.py**
+New `_cap_node_degree()` function using `ROW_NUMBER() OVER (PARTITION BY source_id
+ORDER BY weight DESC)` — single-pass window function, no Python loops. Integrated
+into `prune_graph()` as `cap_degree=True` (default). Automatically runs during
+scheduled maintenance cycles to keep hub nodes bounded.
+
+### Changed
+- `mcp/_daemon_proxy.py`: `timeout_s` default 8.0 → 30.0
+- `encoding/graph_builder.py`: entity + causal caps 20 → 5; hub filter at 200 edges
+- `core/graph_pruner.py`: `_cap_node_degree()` added; `prune_graph()` gains `cap_degree` param
+- `retrieval/spreading_activation.py`: UNION LIMIT pushed inside each branch
+
+### Tests
+4053 passed, 15 skipped — no regressions.
+
+---
+
+## [3.4.58] - 2026-05-30 — Permanent OpenMP SIGSEGV Fix
+
+**Eliminates the recurring Python crash popup on macOS Apple Silicon.** Any user
+who triggered a LightGBM retrain cycle (background learning after ~50 recalls)
+would see a macOS crash report for `Python [PID]` with SIGSEGV at
+`__kmp_suspend_initialize_thread + 32`. This release permanently fixes the root
+cause in the SLM source — no system changes required.
+
+### Root Cause
+SLM's dependency set ships **three separate `libomp.dylib` binaries** on macOS ARM:
+- `torch==2.11.0` bundles `/opt/llvm-openmp/lib/libomp.dylib` (860 KB)
+- `scikit-learn==1.8.0` bundles its own `/opt/llvm-openmp/lib/libomp.dylib` (678 KB)
+- `lightgbm==4.6.0` resolves to homebrew's `/opt/homebrew/opt/libomp/lib/libomp.dylib` (739 KB)
+
+When `lgb.Dataset(X, ...)` called `LGBM_DatasetCreateFromMat` → OpenMP `fork_call`
+with `num_threads = os.cpu_count() - 1` (9 threads on M4 Mac), the parallel
+worker threads were allocated by LightGBM's libomp but attempted to synchronize
+via PyTorch's libomp thread pool. The two runtimes have incompatible internal
+thread structs — the barrier release read address `0x580` (null + struct offset),
+causing `EXC_BAD_ACCESS (SIGSEGV)` in Thread 26.
+
+**All macOS Apple Silicon users with the standard SLM install were affected.**
+The crash fired silently in a background consolidation worker, causing the
+`slm mcp` subprocess to restart repeatedly, generating the persistent crash popup.
+
+### Fixed
+- **`ranker_retrain_online.py` line 198** — `num_threads = max(1, os.cpu_count()-1)`
+  changed to a safe cap of **2 threads** (configurable via `SLM_LGBM_THREADS` env
+  var). With ≤2 threads, the problematic parallel fork path in
+  `DatasetLoader::ConstructFromSampleData` is avoided entirely. SLM's training
+  datasets (50–5,000 rows) see ~90% of max-core throughput at 2 threads — the
+  difference is under 200ms per retrain cycle.
+- **`__init__.py`** — `KMP_DUPLICATE_LIB_OK` changed from `os.environ.setdefault`
+  (could be overridden to FALSE) to unconditional `os.environ[...] = "TRUE"`.
+  Added `OMP_NUM_THREADS=2` cap (respects user override) as belt-and-suspenders
+  at the OS level before any C library reads the thread count.
+
+### New environment variables
+- `SLM_LGBM_THREADS` — override the LightGBM thread count (default: `2`).
+  Only increase if your system has a unified single-runtime OpenMP setup.
+
+### Why not fix the dylib collision instead?
+Patching `libomp.dylib` on users' systems via `install_name_tool` is fragile:
+it breaks on package updates, requires write access to site-packages, and fails
+if SIP prevents modifying signed binaries. The source fix is permanent, upgrade-safe,
+and works identically on every user's machine regardless of their exact package versions.
+
 ## [3.4.52] - 2026-05-28 — Warm Memory, No Cold Starts
 
 **Production resilience for session_init.** No quality degradation as the primary path: full 6-channel recall (semantic + BM25 + entity + temporal + Hopfield + spreading-activation, Fisher-Rao fusion) is preserved. The cold-start problem is fixed at the infrastructure layer, not by downgrading retrieval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.56",
+  "version": "3.4.59",
   "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.4.56"
+version = "3.4.59"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/__init__.py

@@ -1,9 +1,34 @@
 """SuperLocalMemory — information-geometric agent memory."""
 
 import os
-os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
 
-__version__ = "3.4.56"
+# --- OpenMP multi-library guard (permanent fix, v3.4.58) -------------------
+# SLM ships with torch, scikit-learn, and lightgbm — each bundles its own
+# libomp.dylib on macOS ARM (Apple Silicon). When all three are loaded in the
+# same process, the Intel OpenMP runtime detects duplicate libraries and either
+# (a) emits OMP: Error #15 and aborts, or (b) crashes with SIGSEGV in
+# __kmp_suspend_initialize_thread (address 0x580 — null thread-struct deref)
+# when LightGBM's parallel fork tries to coordinate with PyTorch's thread pool.
+#
+# KMP_DUPLICATE_LIB_OK=TRUE tells the runtime to elect one master instance
+# and continue rather than abort. This is the upstream-recommended workaround
+# for mixed-dependency environments (PyTorch docs, scikit-learn FAQ, LightGBM
+# issue #3877). Use unconditional assignment — not setdefault — so user env
+# cannot accidentally disable this safety net by setting it to FALSE.
+#
+# OMP_NUM_THREADS=2 caps the maximum thread count before any C library reads
+# it. With ≤2 threads the problematic parallel fork path in LightGBM's
+# DatasetLoader::ConstructFromSampleData is avoided on all observed crash
+# configurations. SLM datasets are small (50–5 000 rows); 2 threads gives
+# ~90% of the performance of max-core training at zero crash risk.
+# Users who need more threads can set SLM_LGBM_THREADS=N to override
+# the per-call cap in ranker_retrain_online.py.
+os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"
+if "OMP_NUM_THREADS" not in os.environ:
+    os.environ["OMP_NUM_THREADS"] = "2"
+# ---------------------------------------------------------------------------
+
+__version__ = "3.4.59"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/core/config.py

@@ -1000,80 +1000,87 @@ class SLMConfig:
         new_mode: str,
         base_dir: Path | None = None,
     ) -> "SLMConfig":
-        """Switch to a different mode, preserving the old mode's config.
-
-        v3.4.54: Saves the current config as ``mode_{old}.json``, then
-        loads ``mode_{new}.json`` (or creates it from defaults if it
-        doesn't exist). Writes ``current_mode`` and persists the new
-        active config as ``config.json`` for backward compatibility
-        with tooling that reads it directly.
+        """Switch to a different mode, preserving ALL non-mode settings.
+
+        v3.4.58 fix: Only ``config.mode`` changes. The previous implementation
+        called ``for_mode()`` (which resets embedding/LLM/retrieval to mode
+        defaults) whenever the target mode's per-mode file didn't exist.
+        This silently clobbered custom embeddings, endpoints, and LLM config.
+
+        Correct behavior:
+          - Load the current (old) config from config.json.
+          - Save it to mode_{old}.json for the 3-mode system.
+          - If mode_{new}.json exists, load it (user had a prior config for that mode).
+          - If mode_{new}.json does NOT exist: start from the OLD config, change
+            only the mode field. This preserves embedding, retrieval, forgetting, etc.
+          - Exception: if user has NO LLM provider AND is switching to B/C, populate
+            sensible LLM defaults so the daemon doesn't start dead.
+          - Write the result to config.json (backward compat) and current_mode.
 
         Returns the new active config.
         """
+        import copy
+        import dataclasses
+
         from superlocalmemory.storage.models import Mode as _M
         _base = base_dir or DEFAULT_BASE_DIR
         _base.mkdir(parents=True, exist_ok=True)
 
         old_config = cls.load(_base / "config.json")
         old_mode = old_config.mode.value.lower()
-
         new_mode_val = _M(new_mode.lower())
 
-        # 1. Save current config to its per-mode file (unless already
-        #    matched — prevents overwriting user customizations)
+        # 1. Save current config to its per-mode file (preserve customizations)
         if old_mode != new_mode.lower():
             old_path = cls._mode_config_path(_base, old_config.mode)
             old_config.save(old_path)
 
-        # 2. Try to load the target mode's saved config.
+        # 2. Determine new config:
+        #    a) mode_{new}.json exists → user had prior config for this mode, use it
+        #    b) otherwise → copy old config, change only mode
         new_path = cls._mode_config_path(_base, new_mode_val)
-        need_migration = False
         if new_path.exists():
             try:
                 new_config = cls.load(new_path)
-                # Ensure the loaded config actually has the right mode
                 if new_config.mode != new_mode_val:
-                    new_config = cls.for_mode(new_mode_val, base_dir=_base)
+                    # Corrupt/mismatched mode file — rebuild preserving old values
+                    new_config = copy.copy(old_config)
+                    new_config.mode = new_mode_val
             except Exception:
-                new_config = cls.for_mode(new_mode_val, base_dir=_base)
+                new_config = copy.copy(old_config)
+                new_config.mode = new_mode_val
         else:
-            # First time switching to this mode: try migrating from
-            # legacy config.json if it was already in this mode
-            legacy = _base / "config.json"
-            if legacy.exists():
-                try:
-                    import json
-                    _data = json.loads(legacy.read_text(encoding="utf-8"))
-                    _legacy_mode = _data.get("mode", "").lower()
-                    if _legacy_mode == new_mode.lower():
-                        # config.json IS this mode — use it directly
-                        new_config = cls.load(legacy)
-                        need_migration = True
-                    else:
-                        new_config = cls.for_mode(new_mode_val, base_dir=_base)
-                except Exception:
-                    new_config = cls.for_mode(new_mode_val, base_dir=_base)
-            else:
-                new_config = cls.for_mode(new_mode_val, base_dir=_base)
+            # First time switching to this mode: start from old config, change mode only.
+            # Use dataclasses.replace() to produce a new frozen-compatible object.
+            new_config = dataclasses.replace(old_config, mode=new_mode_val)
+
+        # 3. LLM default population — ONLY if user has no provider AND switching to B/C.
+        #    Never overwrites an existing provider.
+        if new_mode_val in (_M.B, _M.C) and not new_config.llm.provider:
+            if new_mode_val == _M.B:
+                new_config = dataclasses.replace(
+                    new_config,
+                    llm=LLMConfig(
+                        provider="ollama",
+                        model="llama3.2",
+                        api_base="http://localhost:11434",
+                    ),
+                )
+            else:  # Mode C
+                new_config = dataclasses.replace(
+                    new_config,
+                    llm=LLMConfig(
+                        provider="openrouter",
+                        model="anthropic/claude-sonnet-4",
+                    ),
+                )
 
-        # 3. Save as active config.json (backward compat)
+        # 4. Save as active config.json (backward compat)
         new_config.save(_base / "config.json", mode_change=True)
 
-        # 4. Write current_mode
+        # 5. Write current_mode
         cls.write_current_mode(new_mode, _base)
 
-        # 5. On first migration, also save mode_a.json and mode_c.json
-        #    so users have a complete set
-        if need_migration:
-            for _m in (_M.A, _M.B, _M.C):
-                _mp = cls._mode_config_path(_base, _m)
-                if not _mp.exists():
-                    try:
-                        _mc = cls.for_mode(_m, base_dir=_base)
-                        _mc.save(_mp)
-                    except Exception:
-                        pass
-
         return new_config
 
     @classmethod

package/src/superlocalmemory/core/graph_pruner.py

@@ -28,12 +28,18 @@ from pathlib import Path
 logger = logging.getLogger("superlocalmemory.graph_pruner")
 
 _CHAIN_BATCH_LIMIT = 10_000
+# v3.4.59: Nodes with more than this many total edges (in+out) are hub nodes.
+# SA and entity_graph channels cap fan-out at 30/node, so edges beyond this
+# threshold provide zero additional recall signal while bloating the graph.
+_MAX_DEGREE_PER_NODE: int = 100
+_HUB_PRUNE_BATCH: int = 500  # delete edges in batches to avoid giant IN clauses
 
 
 def prune_graph(
     db_path: str | Path,
     profile_id: str = "default",
     dry_run: bool = False,
+    cap_degree: bool = True,
 ) -> dict:
     """Run all graph pruning strategies for a specific profile.
 
@@ -41,7 +47,7 @@ def prune_graph(
     """
     conn = sqlite3.connect(str(db_path))
     conn.execute("PRAGMA journal_mode=WAL")
-    conn.execute("PRAGMA busy_timeout=10000")
+    conn.execute("PRAGMA busy_timeout=30000")
     conn.row_factory = sqlite3.Row
 
     stats = {
@@ -49,6 +55,7 @@ def prune_graph(
         "supersedes_collapsed": 0,
         "self_loops_removed": 0,
         "duplicates_removed": 0,
+        "hub_edges_removed": 0,
         "total_before": 0,
         "total_after": 0,
     }
@@ -72,6 +79,10 @@ def prune_graph(
         stats["supersedes_collapsed"] = _collapse_supersedes_chains(
             c, profile_id, dry_run,
         )
+        if cap_degree:
+            stats["hub_edges_removed"] = _cap_node_degree(
+                c, profile_id, _MAX_DEGREE_PER_NODE, dry_run,
+            )
 
         if dry_run:
             c.execute("ROLLBACK")
@@ -91,10 +102,11 @@ def prune_graph(
         prefix = "(dry-run) " if dry_run else ""
         logger.info(
             "%sGraph pruning: removed %d edges (%.1f%%) in %.1fs — "
-            "orphans=%d, supersedes=%d, self_loops=%d, duplicates=%d",
+            "orphans=%d, supersedes=%d, self_loops=%d, duplicates=%d, hub_cap=%d",
             prefix, total_removed, pct, elapsed,
             stats["orphans_removed"], stats["supersedes_collapsed"],
             stats["self_loops_removed"], stats["duplicates_removed"],
+            stats["hub_edges_removed"],
         )
 
     except Exception as exc:
@@ -288,3 +300,81 @@ def _collapse_supersedes_chains(
     )
 
     return len(delete_ids)
+
+
+def _cap_node_degree(
+    c: sqlite3.Cursor,
+    profile_id: str,
+    max_degree: int,
+    dry_run: bool,
+) -> int:
+    """Remove low-weight edges from hub nodes (nodes with degree > max_degree).
+
+    v3.4.59: At 17K facts, popular entities (SLM, Claude, AgentAssert) caused
+    1.4M+ entity edges — avg 121 per node, some nodes with 5000+. SA fan-out
+    is capped at 30/node during traversal, so edges beyond max_degree add zero
+    recall signal while making every graph query scan millions of rows.
+
+    Algorithm (single-pass window function — no Python loops):
+      1. ROW_NUMBER() OVER (PARTITION BY source_id ORDER BY weight DESC) ranks
+         every edge per node in one full table scan.
+      2. Edges with rn > max_degree are deleted in a single DELETE statement.
+      Requires SQLite 3.25+ (window functions). System is on 3.53.1.
+    """
+    if dry_run:
+        c.execute(
+            """
+            SELECT COUNT(*) as cnt FROM (
+                SELECT edge_id,
+                       ROW_NUMBER() OVER (
+                           PARTITION BY source_id ORDER BY weight DESC
+                       ) as rn
+                FROM graph_edges
+                WHERE profile_id = ?
+            ) WHERE rn > ?
+            """,
+            (profile_id, max_degree),
+        )
+        excess = c.fetchone()["cnt"]
+        logger.info(
+            "(dry-run) _cap_node_degree: ~%d edges would be removed (max_degree=%d)",
+            excess, max_degree,
+        )
+        return excess
+
+    # Step 1: build temp keep-list in one pass (ROW_NUMBER ranks by weight DESC)
+    c.execute("CREATE TEMP TABLE IF NOT EXISTS _slm_keep_edges (edge_id TEXT PRIMARY KEY)")
+    c.execute("DELETE FROM _slm_keep_edges")  # idempotent if called twice
+    c.execute(
+        """
+        INSERT INTO _slm_keep_edges (edge_id)
+        SELECT edge_id FROM (
+            SELECT edge_id,
+                   ROW_NUMBER() OVER (
+                       PARTITION BY source_id ORDER BY weight DESC
+                   ) as rn
+            FROM graph_edges
+            WHERE profile_id = ?
+        ) WHERE rn <= ?
+        """,
+        (profile_id, max_degree),
+    )
+
+    # Step 2: delete everything not in keep-list (single DELETE)
+    c.execute(
+        """
+        DELETE FROM graph_edges
+        WHERE profile_id = ?
+          AND edge_id NOT IN (SELECT edge_id FROM _slm_keep_edges)
+        """,
+        (profile_id,),
+    )
+    deleted = c.rowcount
+
+    c.execute("DROP TABLE IF EXISTS _slm_keep_edges")
+
+    logger.info(
+        "_cap_node_degree: deleted %d low-weight edges (max_degree=%d)",
+        deleted, max_degree,
+    )
+    return deleted

package/src/superlocalmemory/encoding/graph_builder.py

@@ -76,11 +76,12 @@ class GraphBuilder:
 
     def build_edges(self, new_fact: AtomicFact, profile_id: str) -> list[GraphEdge]:
         """Create ALL relevant edges for *new_fact*. Persists and returns them."""
+        hub_cache: dict[str, int] = {}  # shared across edge types to avoid redundant queries
         edges: list[GraphEdge] = []
-        edges.extend(self._build_entity_edges(new_fact, profile_id))
+        edges.extend(self._build_entity_edges(new_fact, profile_id, hub_cache))
         edges.extend(self._build_temporal_edges(new_fact, profile_id))
         edges.extend(self._build_semantic_edges(new_fact, profile_id))
-        edges.extend(self._build_causal_edges(new_fact, profile_id))
+        edges.extend(self._build_causal_edges(new_fact, profile_id, hub_cache))
 
         for edge in edges:
             self._db.store_edge(edge)
@@ -142,17 +143,33 @@ class GraphBuilder:
 
     # -- Edge builders (private) -------------------------------------------
 
-    # V3.3.12: Cap entity edges per entity to prevent O(n²) explosion.
-    # With 500+ facts sharing a popular entity, creating an edge to each
-    # produced 44K+ edges and 22-min ingestion. Cap to 20 most recent per entity.
-    _MAX_ENTITY_EDGES_PER_ENTITY: int = 20
+    # v3.4.59: Lowered from 20→5. At 17K facts, 20 edges × many entities per fact
+    # produces 1.4M+ entity edges and 13s recalls. 5 is sufficient graph signal.
+    _MAX_ENTITY_EDGES_PER_ENTITY: int = 5
+    # v3.4.59: Hub filter — nodes with > 200 total edges are "gravity wells"
+    # (e.g. every fact mentions "SLM"). Skip adding more edges to them.
+    _MAX_HUB_DEGREE: int = 200
+
+    def _node_degree(self, fact_id: str, profile_id: str, cache: dict[str, int]) -> int:
+        """Cached total degree (in + out) for a node."""
+        if fact_id not in cache:
+            rows = self._db.execute(
+                "SELECT COUNT(*) as cnt FROM graph_edges "
+                "WHERE profile_id = ? AND (source_id = ? OR target_id = ?)",
+                (profile_id, fact_id, fact_id),
+            )
+            cache[fact_id] = int(dict(rows[0])["cnt"]) if rows else 0
+        return cache[fact_id]
 
     def _build_entity_edges(
         self, new_fact: AtomicFact, profile_id: str,
+        hub_cache: dict[str, int] | None = None,
     ) -> list[GraphEdge]:
         """ENTITY edges: shared canonical entity — capped to most recent per entity."""
         if not new_fact.canonical_entities:
             return []
+        if hub_cache is None:
+            hub_cache = {}
         edges: list[GraphEdge] = []
         seen: set[str] = set()
 
@@ -163,6 +180,8 @@ class GraphBuilder:
                     break
                 if other.fact_id == new_fact.fact_id or other.fact_id in seen:
                     continue
+                if self._node_degree(other.fact_id, profile_id, hub_cache) >= self._MAX_HUB_DEGREE:
+                    continue  # skip hub nodes — they link everything to everything
                 if self._edge_exists(new_fact.fact_id, other.fact_id, EdgeType.ENTITY, profile_id):
                     continue
                 seen.add(other.fact_id)
@@ -261,17 +280,20 @@ class GraphBuilder:
                 break
         return edges
 
-    # V3.3.13: Cap causal edges per entity to prevent O(n²) explosion (same as entity/temporal).
-    _MAX_CAUSAL_EDGES_PER_ENTITY: int = 20
+    # v3.4.59: Lowered from 20→5, same reasoning as entity cap.
+    _MAX_CAUSAL_EDGES_PER_ENTITY: int = 5
 
     def _build_causal_edges(
         self, new_fact: AtomicFact, profile_id: str,
+        hub_cache: dict[str, int] | None = None,
     ) -> list[GraphEdge]:
         """CAUSAL edges: causal markers + shared entity. Direction: cause -> effect."""
         if not any(p.search(new_fact.content) for p in _CAUSAL_CUES):
             return []
         if not new_fact.canonical_entities:
             return []
+        if hub_cache is None:
+            hub_cache = {}
 
         edges: list[GraphEdge] = []
         seen: set[str] = set()
@@ -282,6 +304,8 @@ class GraphBuilder:
                     break
                 if other.fact_id == new_fact.fact_id or other.fact_id in seen:
                     continue
+                if self._node_degree(other.fact_id, profile_id, hub_cache) >= self._MAX_HUB_DEGREE:
+                    continue
                 if self._edge_exists(other.fact_id, new_fact.fact_id, EdgeType.CAUSAL, profile_id):
                     continue
                 seen.add(other.fact_id)

package/src/superlocalmemory/infra/process_reaper.py

@@ -46,7 +46,7 @@ class ReaperConfig:
 
     enabled: bool = True
     heartbeat_interval_seconds: int = 60
-    orphan_age_threshold_hours: float = 4.0
+    orphan_age_threshold_hours: float = 1.0  # v3.4.57: reduced from 4.0 — confirmed-dead parent = safe to kill after 1h
     pid_file_path: str = ""  # Empty = default (~/.superlocalmemory/slm.pids)
     graceful_timeout_seconds: float = 5.0
 

package/src/superlocalmemory/learning/ranker_retrain_legacy.py

@@ -147,6 +147,13 @@ def _retrain_ranker_impl(
             objective, sorted(_allowed_objectives),
         )
         objective = "lambdarank"
+    # SAFE THREAD CAP — v3.4.58 permanent fix for OpenMP multi-library SIGSEGV.
+    # See ranker_retrain_online.py for full explanation. Same cap applies here:
+    # the legacy path hits the identical LGBM_DatasetCreateFromMat → OpenMP
+    # parallel fork. On macOS ARM with torch+sklearn+lightgbm, >2 threads
+    # triggers the libomp multi-runtime SIGSEGV in __kmp_suspend_initialize_thread.
+    _lgbm_threads_env = os.environ.get("SLM_LGBM_THREADS", "").strip()
+    _lgbm_num_threads = int(_lgbm_threads_env) if _lgbm_threads_env.isdigit() else 2
     params = {
         "objective": objective,
         "metric": "ndcg",
@@ -156,8 +163,9 @@ def _retrain_ranker_impl(
         "num_leaves": 31,
         "min_data_in_leaf": 20,
         "verbosity": -1,
-        "num_threads": max(1, (os.cpu_count() or 2) - 1),
+        "num_threads": _lgbm_num_threads,
     }
+
     try:
         booster_new = lgb.train(params, ds_train, num_boost_round=50)
     except lgb.basic.LightGBMError as exc:

package/src/superlocalmemory/learning/ranker_retrain_online.py

@@ -195,7 +195,17 @@ def _train_booster(
     params = dict(RETRAIN_HYPERPARAM_CAPS)
     params["objective"] = objective
     params["label_gain"] = gain
-    params["num_threads"] = max(1, (os.cpu_count() or 2) - 1)
+    # SAFE THREAD CAP — v3.4.58 permanent fix for OpenMP multi-library SIGSEGV.
+    # Using os.cpu_count()-1 (e.g. 9 on M4 Mac) triggers a race in LightGBM's
+    # DatasetLoader::ConstructFromSampleData when PyTorch's libomp and
+    # LightGBM's libomp are both loaded. The parallel OpenMP fork crosses
+    # libomp runtime boundaries → SIGSEGV in __kmp_suspend_initialize_thread.
+    # 2 threads avoids the crash path and is sufficient for SLM's small datasets.
+    # Override with SLM_LGBM_THREADS env var if you need more (and have a
+    # single-runtime environment with libomp unified).
+    _lgbm_threads_env = os.environ.get("SLM_LGBM_THREADS", "").strip()
+    params["num_threads"] = int(_lgbm_threads_env) if _lgbm_threads_env.isdigit() else 2
+
     num_boost_round = int(params.pop("num_boost_round"))
 
     start = time.monotonic()

package/src/superlocalmemory/mcp/_daemon_proxy.py

@@ -36,7 +36,7 @@ class DaemonPoolProxy:
     envelopes — the adapter is responsible for surfacing those.
     """
 
-    def __init__(self, port: int, *, timeout_s: float = 60.0) -> None:
+    def __init__(self, port: int, *, timeout_s: float = 30.0) -> None:  # v3.4.59: 8s→30s — observed recall takes 13.4s on dense graph (2.1M edges); 8s always timed out → degraded mode
         self._port = port
         self._timeout = timeout_s
 

package/src/superlocalmemory/mcp/server.py

@@ -241,5 +241,42 @@ _warmup_thread = threading.Thread(target=_eager_warmup, daemon=True, name="mcp-w
 _warmup_thread.start()
 
 
+# V3.4.57: Parent watchdog — self-terminate when the IDE/Claude session dies.
+# FastMCP relies on stdin EOF to stop, but stdin EOF is NOT guaranteed on
+# crash or force-quit. Without this, every abnormal exit leaves an orphaned
+# slm mcp process consuming ~100-200 MB indefinitely. 22 orphans caused a
+# daemon deadlock on May 30 2026 (241% CPU, session_init timeouts).
+def _parent_watchdog() -> None:
+    """Exit when parent IDE process (Claude Code, Cursor, etc.) dies.
+
+    Polls os.getppid() every 10 seconds. On macOS/Linux, when a parent
+    dies the child is reparented to PID 1 (init) — getppid() returns 1.
+    Also validates the original parent is still alive via os.kill(ppid, 0).
+    Uses os._exit(0) to bypass any atexit handlers that might hang.
+    """
+    import os as _os_wd, time as _time
+    _wlog = logging.getLogger(__name__ + ".watchdog")
+    initial_ppid = _os_wd.getppid()
+    if initial_ppid <= 1:
+        return  # Already reparented at startup — don't self-terminate
+    while True:
+        _time.sleep(10)
+        try:
+            current_ppid = _os_wd.getppid()
+            if current_ppid != initial_ppid or current_ppid <= 1:
+                _wlog.info("Parent PID changed (%d→%d), self-terminating", initial_ppid, current_ppid)
+                _os_wd._exit(0)
+            _os_wd.kill(initial_ppid, 0)  # Raises ProcessLookupError if dead
+        except ProcessLookupError:
+            _wlog.info("Parent PID %d gone, self-terminating", initial_ppid)
+            _os_wd._exit(0)
+        except Exception:
+            pass  # Transient errors — keep watching
+
+
+_watchdog_thread = threading.Thread(target=_parent_watchdog, daemon=True, name="parent-watchdog")
+_watchdog_thread.start()
+
+
 if __name__ == "__main__":
     server.run(transport="stdio")

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -234,27 +234,47 @@ class SpreadingActivation:
         the highest-signal edges.
         """
         try:
+            # v3.4.59: LIMIT pushed inside each UNION branch so SQLite can use
+            # idx_edges_source_weight / idx_edges_target_weight and stop after
+            # max_neighbors_per_node rows per branch instead of materializing
+            # all 2.1M edges then sorting. Each branch wrapped in SELECT * FROM (...)
+            # because SQLite requires parentheses for ORDER BY+LIMIT in compound SELECTs.
+            lim = self._config.max_neighbors_per_node
             rows = self._db.execute(
                 """
                 SELECT neighbor_id, weight FROM (
-                    SELECT target_id AS neighbor_id, weight FROM graph_edges
+                    SELECT * FROM (
+                        SELECT target_id AS neighbor_id, weight FROM graph_edges
                         WHERE source_id = ? AND profile_id = ?
+                        ORDER BY weight DESC LIMIT ?
+                    )
                     UNION ALL
-                    SELECT target_fact_id AS neighbor_id, weight FROM association_edges
+                    SELECT * FROM (
+                        SELECT target_fact_id AS neighbor_id, weight FROM association_edges
                         WHERE source_fact_id = ? AND profile_id = ?
+                        ORDER BY weight DESC LIMIT ?
+                    )
                     UNION ALL
-                    SELECT source_id AS neighbor_id, weight FROM graph_edges
+                    SELECT * FROM (
+                        SELECT source_id AS neighbor_id, weight FROM graph_edges
                         WHERE target_id = ? AND profile_id = ?
+                        ORDER BY weight DESC LIMIT ?
+                    )
                     UNION ALL
-                    SELECT source_fact_id AS neighbor_id, weight FROM association_edges
+                    SELECT * FROM (
+                        SELECT source_fact_id AS neighbor_id, weight FROM association_edges
                         WHERE target_fact_id = ? AND profile_id = ?
+                        ORDER BY weight DESC LIMIT ?
+                    )
                 )
                 ORDER BY weight DESC
                 LIMIT ?
                 """,
-                (node_id, profile_id, node_id, profile_id,
-                 node_id, profile_id, node_id, profile_id,
-                 self._config.max_neighbors_per_node),
+                (node_id, profile_id, lim,
+                 node_id, profile_id, lim,
+                 node_id, profile_id, lim,
+                 node_id, profile_id, lim,
+                 lim),
             )
             return [
                 (dict(r)["neighbor_id"], dict(r)["weight"]) for r in rows

package/src/superlocalmemory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.4.56
+Version: 3.4.59
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later