superlocalmemory 3.4.12 → 3.4.14

package/README.md

@@ -533,3 +533,33 @@ Part of [Qualixar](https://qualixar.com) · Author: [Varun Pratap Bhardwaj](http
 <p align="center">
   <sub>Built with mathematical rigor. Not in the race — here to help everyone build better AI memory systems.</sub>
 </p>
+
+---
+
+## ⭐ Support This Project
+
+If this project solves a real problem for you, **please star the repo** — it helps other developers discover Qualixar and signals that the AI agent reliability community is growing. Every star matters.
+
+[![Star History Chart](https://api.star-history.com/svg?repos=qualixar/superlocalmemory&type=Date)](https://star-history.com/#qualixar/superlocalmemory&Date)
+
+---
+
+## Part of the Qualixar AI Agent Reliability Platform
+
+Qualixar is building the open-source infrastructure for AI agent reliability engineering. Seven products, seven peer-reviewed papers, one coherent platform. Each tool solves one reliability pillar:
+
+| Product | Purpose | Install | Paper |
+|---------|---------|---------|-------|
+| **[SuperLocalMemory](https://github.com/qualixar/superlocalmemory)** | Persistent memory + learning for AI agents | `npx superlocalmemory` | [arXiv:2604.04514](https://arxiv.org/abs/2604.04514) |
+| **[Qualixar OS](https://github.com/qualixar/qualixar-os)** | Universal agent runtime (13 execution topologies) | `npx qualixar-os` | [arXiv:2604.06392](https://arxiv.org/abs/2604.06392) |
+| **[SLM Mesh](https://github.com/qualixar/slm-mesh)** | P2P coordination across AI agent sessions | `npm i slm-mesh` | — |
+| **[SLM MCP Hub](https://github.com/qualixar/slm-mcp-hub)** | Federate 430+ MCP tools through one gateway | `pip install slm-mcp-hub` | — |
+| **[AgentAssay](https://github.com/qualixar/agentassay)** | Token-efficient AI agent testing | `pip install agentassay` | [arXiv:2603.02601](https://arxiv.org/abs/2603.02601) |
+| **[AgentAssert](https://github.com/qualixar/agentassert-abc)** | Behavioral contracts + drift detection | `pip install agentassert` | [arXiv:2602.22302](https://arxiv.org/abs/2602.22302) |
+| **[SkillFortify](https://github.com/qualixar/skillfortify)** | Formal verification for AI agent skills | `pip install skillfortify` | [arXiv:2603.00195](https://arxiv.org/abs/2603.00195) |
+
+**Zero cloud dependency. Local-first. EU AI Act compliant.**
+
+Start here → **[qualixar.com](https://qualixar.com)** · [All papers on Qualixar HuggingFace](https://huggingface.co/Qualixar)
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.12",
+  "version": "3.4.14",
   "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",
@@ -89,4 +89,4 @@
   "dependencies": {
     "docx": "^9.5.1"
   }
-}
+}

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.4.12"
+version = "3.4.14"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/cli/commands.py

@@ -230,20 +230,43 @@ def cmd_restart(args: Namespace) -> None:
     _log(1, "Kill all SLM processes", "ok", f"{killed} processes killed")
     time.sleep(3)
 
-    # Step 2: Clean stale files
+    # Step 2: Clean stale files + HOLD the lock to prevent races
+    # v3.4.13: Do NOT delete daemon.lock — HOLD it instead.
+    # If we delete it, `slm mcp` (still running in Claude) will see no lock,
+    # acquire a NEW lock, and start a second daemon during our restart.
     cleaned = []
-    for fname in ("daemon.pid", "daemon.port", "daemon.lock"):
+    for fname in ("daemon.pid", "daemon.port", ".embedding-worker.pid", ".reranker-worker.pid"):
         fpath = slm_dir / fname
         if fpath.exists():
             fpath.unlink(missing_ok=True)
             cleaned.append(fname)
+
+    # Hold the lock file to block other processes from starting a daemon
+    _LOCK_FILE = slm_dir / "daemon.lock"
+    _LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
+    restart_lock_fd = None
+    try:
+        restart_lock_fd = open(_LOCK_FILE, "w")
+        if sys.platform != "win32":
+            import fcntl
+            fcntl.flock(restart_lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except Exception:
+        pass  # Best-effort — don't block restart if lock fails
+
     _log(2, "Clean stale state files", "ok",
          f"removed: {', '.join(cleaned)}" if cleaned else "already clean")
 
-    # Step 3: Start fresh daemon
+    # Step 3: Start fresh daemon (lock still held — no races)
     time.sleep(1)
     from superlocalmemory.cli.daemon import ensure_daemon
     started = ensure_daemon()
+
+    # Release restart lock — daemon is now running with its own lock
+    if restart_lock_fd:
+        try:
+            restart_lock_fd.close()
+        except Exception:
+            pass
     _log(3, "Start fresh daemon", "ok" if started else "fail",
          "daemon started" if started else "failed to start — check slm doctor")
 
@@ -750,8 +773,8 @@ def cmd_remember(args: Namespace) -> None:
         except Exception:
             pass  # Fall through to pending store
 
-        # Fallback: store-first pattern (Option C — zero data loss)
-        import subprocess
+        # v3.4.13: Store to pending DB (zero data loss) — daemon processes in background.
+        # NO subprocess spawn. Daemon's background loop picks up pending memories.
         from superlocalmemory.cli.pending_store import store_pending
 
         row_id = store_pending(
@@ -759,19 +782,6 @@ def cmd_remember(args: Namespace) -> None:
             tags=args.tags or "",
         )
 
-        cmd = [sys.executable, "-m", "superlocalmemory.cli.main",
-               "remember", args.content, "--sync"]
-        if args.tags:
-            cmd.extend(["--tags", args.tags])
-        log_dir = __import__("pathlib").Path.home() / ".superlocalmemory" / "logs"
-        log_dir.mkdir(parents=True, exist_ok=True)
-        log_file = log_dir / "async-remember.log"
-        with open(log_file, "a") as lf:
-            subprocess.Popen(
-                cmd, stdout=subprocess.DEVNULL, stderr=lf,
-                start_new_session=True,
-            )
-
         if use_json:
             from superlocalmemory.cli.json_output import json_print
             json_print("remember", data={"queued": True, "async": True,

package/src/superlocalmemory/cli/daemon.py

@@ -288,15 +288,60 @@ def stop_daemon() -> bool:
         except Exception:
             pass
 
-    # Clean up PID/port files
+    # Clean up PID/port files + worker PID files
     _PID_FILE.unlink(missing_ok=True)
     _PORT_FILE.unlink(missing_ok=True)
+    # v3.4.13: Clean worker PID files (singleton guards)
+    for pidfile in (".embedding-worker.pid", ".reranker-worker.pid"):
+        (Path.home() / ".superlocalmemory" / pidfile).unlink(missing_ok=True)
 
+    # v3.4.13: Wait for ALL workers to actually die before returning.
+    # Without this, `slm restart` starts a new daemon before old workers exit,
+    # causing duplicate embedding_workers (1.6GB each).
     if killed:
-        logger.info("Stopped %d SLM processes", killed)
+        logger.info("Stopped %d SLM processes, waiting for exit...", killed)
+        _wait_for_workers_dead(timeout=10)
+
     return True
 
 
+def _wait_for_workers_dead(timeout: int = 10) -> None:
+    """Wait until no SLM worker processes remain alive."""
+    targets = [
+        "superlocalmemory.server.unified_daemon",
+        "superlocalmemory.core.embedding_worker",
+        "superlocalmemory.core.recall_worker",
+        "superlocalmemory.core.reranker_worker",
+    ]
+    my_pid = os.getpid()
+    deadline = time.time() + timeout
+
+    while time.time() < deadline:
+        alive = False
+        try:
+            import psutil
+            for proc in psutil.process_iter(["pid", "cmdline"]):
+                try:
+                    if proc.pid == my_pid:
+                        continue
+                    cmdline = " ".join(proc.info.get("cmdline") or [])
+                    if any(t in cmdline for t in targets):
+                        alive = True
+                        break
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+        except ImportError:
+            # No psutil — just wait a fixed time
+            time.sleep(3)
+            return
+
+        if not alive:
+            return
+        time.sleep(0.5)
+
+    logger.warning("Some SLM workers still alive after %ds timeout", timeout)
+
+
 # ---------------------------------------------------------------------------
 # Server: HTTP request handler with engine singleton
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/core/embeddings.py

@@ -62,19 +62,50 @@ class DimensionMismatchError(RuntimeError):
 # ---------------------------------------------------------------------------
 
 _EMBEDDING_LOCK_FILE = Path.home() / ".superlocalmemory" / ".embedding.lock"
-_MAX_CONCURRENT_WORKERS = int(os.environ.get("SLM_MAX_EMBEDDING_WORKERS", 2))
+_EMBEDDING_PID_FILE = Path.home() / ".superlocalmemory" / ".embedding-worker.pid"
+_MAX_CONCURRENT_WORKERS = int(os.environ.get("SLM_MAX_EMBEDDING_WORKERS", 1))
 _embedding_lock_fd: int | None = None
 
 
+def _is_embedding_worker_alive() -> bool:
+    """Check if an embedding worker PID file exists and that PID is alive.
+
+    v3.4.13: Machine-wide singleton guard. Before spawning a new worker,
+    check if one is already running. Prevents duplicate 1.6GB workers.
+    """
+    try:
+        if not _EMBEDDING_PID_FILE.exists():
+            return False
+        pid = int(_EMBEDDING_PID_FILE.read_text().strip())
+        os.kill(pid, 0)  # Signal 0 = check if alive
+        return True
+    except (ValueError, OSError, ProcessLookupError):
+        # PID file invalid or process dead — clean up stale file
+        _EMBEDDING_PID_FILE.unlink(missing_ok=True)
+        return False
+
+
+def register_embedding_worker_pid(pid: int) -> None:
+    """Write the embedding worker PID to the machine-wide PID file."""
+    _EMBEDDING_PID_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _EMBEDDING_PID_FILE.write_text(str(pid))
+
+
 def acquire_embedding_lock(timeout: float = 5.0) -> bool:
     """Acquire system-wide embedding worker lock.
 
-    Uses fcntl.flock on Unix. On Windows, falls back to allowing (no lock).
-    Returns True if lock acquired, False if timed out (another worker active).
+    v3.4.13: First checks if a worker PID is already alive (fast path).
+    Falls back to fcntl.flock on Unix. On Windows, falls back to PID check only.
+    Returns True if lock acquired (safe to spawn), False if another worker active.
     """
     global _embedding_lock_fd
+
+    # v3.4.13: Fast path — if a worker PID is alive, don't even try the lock
+    if _is_embedding_worker_alive():
+        return False
+
     if sys.platform == "win32":
-        return True  # No file locking on Windows — daemon routing is primary defense
+        return True  # No file locking on Windows — PID check above is the guard
 
     import fcntl
     _EMBEDDING_LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
@@ -389,11 +420,21 @@ class EmbeddingService:
         return True
 
     def _ensure_worker(self) -> None:
-        """Spawn worker subprocess if not running."""
+        """Spawn worker subprocess if not running.
+
+        v3.4.13: Machine-wide singleton — checks PID file before spawning.
+        Only ONE embedding_worker can exist at a time on the machine.
+        """
         if self._worker_proc is not None and self._worker_proc.poll() is None:
             return
         self._worker_proc = None
 
+        # v3.4.13: Check if another worker is already alive (machine-wide)
+        if _is_embedding_worker_alive():
+            logger.debug("Embedding worker already alive (PID file), skipping spawn")
+            self._available = False
+            return
+
         # V3.3.28: Check memory pressure before spawning
         if not self._check_memory_pressure():
             logger.warning("Skipping embedding worker spawn due to memory pressure")
@@ -419,8 +460,10 @@ class EmbeddingService:
                 text=True,
                 bufsize=1,
                 env=env,
-                start_new_session=True,  # Prevent terminal signals bleeding to worker
+                start_new_session=True,
             )
+            # v3.4.13: Register PID for machine-wide singleton guard
+            register_embedding_worker_pid(self._worker_proc.pid)
             logger.info("Embedding worker spawned (PID %d)", self._worker_proc.pid)
             self._worker_ready = True
         except Exception as exc:

package/src/superlocalmemory/hooks/hook_handlers.py

@@ -21,6 +21,8 @@ import subprocess
 import sys
 import tempfile
 import time
+import urllib.request
+import urllib.error
 
 # ---------------------------------------------------------------------------
 # Cross-platform temp paths
@@ -34,6 +36,30 @@ _LAST_CONSOLIDATION = os.path.join(
 )
 
 
+_DAEMON_URL = "http://127.0.0.1:8765"
+
+
+def _daemon_post(path: str, body: dict, timeout: float = 3.0) -> bool:
+    """POST to SLM daemon via stdlib urllib. Returns True on success.
+
+    v3.4.13: Hooks route through daemon HTTP instead of spawning subprocesses.
+    This eliminates the memory blast from concurrent worker spawns.
+    Uses ONLY stdlib — no httpx, no requests.
+    """
+    try:
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            f"{_DAEMON_URL}{path}",
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=timeout)
+        return True
+    except Exception:
+        return False
+
+
 def handle_hook(action: str) -> None:
     """Dispatch to the appropriate hook handler. Called from main() fast path."""
     handlers = {
@@ -202,15 +228,9 @@ def _hook_checkpoint() -> None:
         if _cooldown_elapsed(lock_file, _OBSERVE_COOLDOWN, now):
             _write_timestamp(lock_file, now)
 
-            # Direct observe — SLM records the change even if Claude ignores
-            try:
-                subprocess.Popen(
-                    ["slm", "observe", f"File changed: {basename}"],
-                    stdout=subprocess.DEVNULL,
-                    stderr=subprocess.DEVNULL,
-                )
-            except Exception:
-                pass
+            # v3.4.13: Route through daemon HTTP (not subprocess) to prevent
+            # memory blast from concurrent embedding_worker spawns.
+            _daemon_post("/observe", {"content": f"File changed: {basename}"})
 
             # Log to session activity
             try:
@@ -286,33 +306,20 @@ def _hook_stop() -> None:
 
     summary = " | ".join(parts)
 
-    # --- Save to SLM ---
-    try:
-        subprocess.run(
-            ["slm", "observe", summary],
-            capture_output=True, timeout=8,
-        )
-    except Exception:
-        try:
-            subprocess.run(
-                ["slm", "remember", summary],
-                capture_output=True, timeout=8,
-            )
-        except Exception:
-            pass
-
-    # --- Post-session skill evolution trigger (best-effort) ---
-    try:
-        session_id = os.environ.get("CLAUDE_SESSION_ID", "")
-        if session_id:
-            subprocess.Popen(
-                ["slm", "evolve", "--session", session_id],
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-                start_new_session=True,
-            )
-    except Exception:
-        pass
+    # --- Save to SLM (v3.4.13: daemon HTTP, not subprocess) ---
+    if not _daemon_post("/observe", {"content": summary}, timeout=5.0):
+        # Fallback: try /remember if observe failed
+        _daemon_post("/remember", {"content": summary, "tags": "session-end"}, timeout=5.0)
+
+    # --- Post-session skill evolution trigger (best-effort, via tool-event) ---
+    session_id = os.environ.get("CLAUDE_SESSION_ID", "")
+    if session_id:
+        _daemon_post("/api/v3/tool-event", {
+            "tool_name": "session_end",
+            "event_type": "session_end",
+            "session_id": session_id,
+            "output_summary": summary[:500],
+        })
 
     # --- Auto-consolidation (if >24h since last run) ---
     _maybe_consolidate()

package/src/superlocalmemory/retrieval/reranker.py

@@ -27,8 +27,25 @@ import time
 import weakref
 from typing import Any
 
+from pathlib import Path
+
 from superlocalmemory.storage.models import AtomicFact
 
+_RERANKER_PID_FILE = Path.home() / ".superlocalmemory" / ".reranker-worker.pid"
+
+
+def _is_reranker_worker_alive() -> bool:
+    """Check if a reranker worker PID is already alive (machine-wide singleton)."""
+    try:
+        if not _RERANKER_PID_FILE.exists():
+            return False
+        pid = int(_RERANKER_PID_FILE.read_text().strip())
+        os.kill(pid, 0)
+        return True
+    except (ValueError, OSError, ProcessLookupError):
+        _RERANKER_PID_FILE.unlink(missing_ok=True)
+        return False
+
 # Track all live reranker instances for atexit cleanup
 _live_rerankers: set[weakref.ref] = set()
 
@@ -148,12 +165,21 @@ class CrossEncoderReranker:
     # ------------------------------------------------------------------
 
     def _ensure_worker(self) -> None:
-        """Spawn worker subprocess if not running. Non-blocking."""
+        """Spawn worker subprocess if not running. Machine-wide singleton.
+
+        v3.4.13: Checks PID file before spawning — only ONE reranker worker
+        can exist at a time on the machine.
+        """
         if self._worker_proc is not None and self._worker_proc.poll() is None:
             return
         self._worker_proc = None
         self._worker_ready = False
 
+        # v3.4.13: Machine-wide singleton guard
+        if _is_reranker_worker_alive():
+            logger.debug("Reranker worker already alive (PID file), skipping spawn")
+            return
+
         worker_module = "superlocalmemory.core.reranker_worker"
         try:
             env = {
@@ -175,6 +201,9 @@ class CrossEncoderReranker:
                 env=env,
                 start_new_session=True,
             )
+            # v3.4.13: Register PID for machine-wide singleton
+            _RERANKER_PID_FILE.parent.mkdir(parents=True, exist_ok=True)
+            _RERANKER_PID_FILE.write_text(str(self._worker_proc.pid))
             logger.info(
                 "Reranker worker spawned (PID %d)", self._worker_proc.pid,
             )