superlocalmemory 3.0.16 → 3.0.18

package/bin/slm-npm

@@ -81,6 +81,14 @@ const result = spawnSync(pythonParts[0], [
     env: {
         ...process.env,
         PYTHONPATH: SRC_DIR + (process.env.PYTHONPATH ? path.delimiter + process.env.PYTHONPATH : ''),
+        // Prevent PyTorch Metal/MPS GPU memory reservation on Apple Silicon.
+        // Without these, macOS Activity Monitor shows 3-6 GB for a 40 MB process.
+        PYTORCH_MPS_HIGH_WATERMARK_RATIO: '0.0',
+        PYTORCH_MPS_MEM_LIMIT: '0',
+        PYTORCH_ENABLE_MPS_FALLBACK: '1',
+        TOKENIZERS_PARALLELISM: 'false',
+        TORCH_DEVICE: 'cpu',
+        CUDA_VISIBLE_DEVICES: '',
     },
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.0.16",
+  "version": "3.0.18",
   "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.0.16"
+version = "3.0.18"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}

package/src/superlocalmemory/cli/commands.py

@@ -23,6 +23,7 @@ def dispatch(args: Namespace) -> None:
         "provider": cmd_provider,
         "connect": cmd_connect,
         "migrate": cmd_migrate,
+        "list": cmd_list,
         "remember": cmd_remember,
         "recall": cmd_recall,
         "forget": cmd_forget,
@@ -113,6 +114,34 @@ def cmd_migrate(args: Namespace) -> None:
     _migrate(args)
 
 
+def cmd_list(args: Namespace) -> None:
+    """List recent memories chronologically."""
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.engine import MemoryEngine
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    engine.initialize()
+
+    limit = getattr(args, "limit", 20)
+    facts = engine._db.get_all_facts(engine.profile_id)
+    # Sort by created_at descending, take limit
+    facts.sort(key=lambda f: f.created_at or "", reverse=True)
+    facts = facts[:limit]
+
+    if not facts:
+        print("No memories stored yet.")
+        return
+
+    print(f"Recent memories ({len(facts)}):\n")
+    for i, f in enumerate(facts, 1):
+        date = (f.created_at or "")[:19]
+        ftype_raw = getattr(f, "fact_type", "")
+        ftype = ftype_raw.value if hasattr(ftype_raw, "value") else str(ftype_raw)
+        content = f.content[:100] + ("..." if len(f.content) > 100 else "")
+        print(f"  {i:3d}. [{date}] ({ftype}) {content}")
+
+
 def cmd_remember(args: Namespace) -> None:
     """Store a memory via the engine."""
     from superlocalmemory.core.config import SLMConfig

package/src/superlocalmemory/cli/main.py

@@ -11,76 +11,140 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
+# CRITICAL: Set BEFORE any torch/transformers import to prevent Metal/MPS
+# GPU memory reservation on Apple Silicon. Without this, macOS Activity
+# Monitor shows 3-6 GB for what is actually a 40 MB process.
+import os as _os
+_os.environ.setdefault('PYTORCH_MPS_HIGH_WATERMARK_RATIO', '0.0')
+_os.environ.setdefault('PYTORCH_MPS_MEM_LIMIT', '0')
+_os.environ.setdefault('PYTORCH_ENABLE_MPS_FALLBACK', '1')
+_os.environ.setdefault('TOKENIZERS_PARALLELISM', 'false')
+_os.environ.setdefault('TORCH_DEVICE', 'cpu')
+
 import argparse
 import sys
 
+_HELP_EPILOG = """\
+operating modes:
+  Mode A  Local Guardian — Zero cloud, zero LLM. All processing stays on
+          your machine. Full EU AI Act compliance. Best for privacy-first
+          use, air-gapped systems, and regulated environments.
+          Retrieval score: 74.8% on LoCoMo benchmark.
+
+  Mode B  Smart Local — Uses a local Ollama LLM for summarization and
+          enrichment. Data never leaves your network. EU AI Act compliant.
+          Requires: ollama running locally with a model pulled.
+
+  Mode C  Full Power — Uses a cloud LLM (OpenAI, Anthropic, etc.) for
+          maximum accuracy. Best retrieval quality, agentic multi-hop.
+          Retrieval score: 87.7% on LoCoMo benchmark.
+
+quick start:
+  slm setup                   Interactive first-time setup
+  slm remember "some fact"    Store a memory
+  slm recall "search query"   Semantic search across memories
+  slm list -n 20              Show 20 most recent memories
+  slm dashboard               Open web dashboard at localhost:8765
+
+ide integration:
+  slm mcp                     Start MCP server (used by IDEs)
+  slm connect                 Auto-configure all detected IDEs
+  slm connect cursor           Configure a specific IDE
+
+examples:
+  slm remember "Project X uses PostgreSQL 16" --tags "project-x,db"
+  slm recall "which database does project X use"
+  slm list -n 50
+  slm mode a                  Switch to zero-LLM mode
+  slm trace "auth flow"       Recall with per-channel score breakdown
+  slm health                  Check math layer status
+  slm dashboard --port 9000   Dashboard on custom port
+
+documentation:
+  Website:    https://superlocalmemory.com
+  GitHub:     https://github.com/qualixar/superlocalmemory
+  Paper:      https://arxiv.org/abs/2603.14588
+"""
+
 
 def main() -> None:
     """Parse CLI arguments and dispatch to command handlers."""
-    parser = argparse.ArgumentParser(prog="slm", description="SuperLocalMemory V3")
-    sub = parser.add_subparsers(dest="command")
+    try:
+        from importlib.metadata import version as _pkg_version
+        _ver = _pkg_version("superlocalmemory")
+    except Exception:
+        _ver = "unknown"
+
+    parser = argparse.ArgumentParser(
+        prog="slm",
+        description=f"SuperLocalMemory V3 ({_ver}) — AI agent memory with mathematical foundations",
+        epilog=_HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"superlocalmemory {_ver}",
+    )
+    sub = parser.add_subparsers(dest="command", title="commands")
 
-    # Setup
-    sub.add_parser("setup", help="Run setup wizard")
+    # -- Setup & Config ------------------------------------------------
+    sub.add_parser("setup", help="Interactive first-time setup wizard")
 
-    # Mode
-    mode_p = sub.add_parser("mode", help="Get or set operating mode")
+    mode_p = sub.add_parser("mode", help="Get or set operating mode (a/b/c)")
     mode_p.add_argument(
         "value", nargs="?", choices=["a", "b", "c"], help="Mode to set",
     )
 
-    # Provider
-    provider_p = sub.add_parser("provider", help="Get or set LLM provider")
+    provider_p = sub.add_parser("provider", help="Get or set LLM provider for Mode B/C")
     provider_p.add_argument(
         "action", nargs="?", choices=["set"], help="Action",
     )
 
-    # Connect
-    connect_p = sub.add_parser("connect", help="Configure IDE integrations")
+    connect_p = sub.add_parser("connect", help="Auto-configure IDE integrations (17+ IDEs)")
     connect_p.add_argument("ide", nargs="?", help="Specific IDE to configure")
     connect_p.add_argument(
         "--list", action="store_true", help="List all supported IDEs",
     )
 
-    # Migrate
-    migrate_p = sub.add_parser("migrate", help="Migrate from V2")
+    migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(
         "--rollback", action="store_true", help="Rollback migration",
     )
 
-    # Memory ops
-    remember_p = sub.add_parser("remember", help="Store a memory")
+    # -- Memory Operations ---------------------------------------------
+    remember_p = sub.add_parser("remember", help="Store a memory (extracts facts, builds graph)")
     remember_p.add_argument("content", help="Content to remember")
     remember_p.add_argument("--tags", default="", help="Comma-separated tags")
 
-    recall_p = sub.add_parser("recall", help="Search memories")
+    recall_p = sub.add_parser("recall", help="Semantic search with 4-channel retrieval")
     recall_p.add_argument("query", help="Search query")
-    recall_p.add_argument("--limit", type=int, default=10, help="Max results")
+    recall_p.add_argument("--limit", type=int, default=10, help="Max results (default 10)")
+
+    forget_p = sub.add_parser("forget", help="Delete memories matching a query")
+    forget_p.add_argument("query", help="Query to match for deletion")
 
-    forget_p = sub.add_parser("forget", help="Delete memories matching query")
-    forget_p.add_argument("query", help="Query to match")
+    list_p = sub.add_parser("list", help="List recent memories chronologically")
+    list_p.add_argument(
+        "--limit", "-n", type=int, default=20, help="Number of entries (default 20)",
+    )
 
-    # Status & diagnostics
-    sub.add_parser("status", help="System status")
-    sub.add_parser("health", help="Math layer health")
+    # -- Diagnostics ---------------------------------------------------
+    sub.add_parser("status", help="System status (mode, profile, DB size)")
+    sub.add_parser("health", help="Math layer health (Fisher-Rao, Sheaf, Langevin)")
 
-    trace_p = sub.add_parser("trace", help="Recall with channel breakdown")
+    trace_p = sub.add_parser("trace", help="Recall with per-channel score breakdown")
     trace_p.add_argument("query", help="Search query")
 
-    # MCP server (for IDE integration)
+    # -- Services ------------------------------------------------------
     sub.add_parser("mcp", help="Start MCP server (stdio transport for IDE integration)")
+    sub.add_parser("warmup", help="Pre-download embedding model (~500MB, one-time)")
 
-    # Warmup (pre-download model)
-    sub.add_parser("warmup", help="Pre-download embedding model (~500MB)")
-
-    # Dashboard
-    dashboard_p = sub.add_parser("dashboard", help="Open web dashboard")
+    dashboard_p = sub.add_parser("dashboard", help="Open 17-tab web dashboard")
     dashboard_p.add_argument(
         "--port", type=int, default=8765, help="Port (default 8765)",
     )
 
-    # Profiles
-    profile_p = sub.add_parser("profile", help="Profile management")
+    # -- Profiles ------------------------------------------------------
+    profile_p = sub.add_parser("profile", help="Profile management (list/switch/create)")
     profile_p.add_argument(
         "action", choices=["list", "switch", "create"], help="Action",
     )

package/src/superlocalmemory/core/embedding_worker.py

@@ -0,0 +1,120 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Subprocess embedding worker — isolates PyTorch memory from main process.
+
+The main process (dashboard/MCP) stays at ~60 MB. All PyTorch/model memory
+lives in this worker subprocess, which auto-kills after idle timeout.
+
+Protocol (JSON over stdin/stdout):
+  Request:  {"cmd": "embed",  "texts": ["hello"]}
+  Response: {"ok": true, "vectors": [[0.1, ...]], "dim": 768}
+
+  Request:  {"cmd": "ping"}
+  Response: {"ok": true}
+
+  Request:  {"cmd": "quit"}
+  (worker exits)
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import os
+
+# Force CPU BEFORE any torch import
+os.environ["CUDA_VISIBLE_DEVICES"] = ""
+os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"
+os.environ["PYTORCH_MPS_MEM_LIMIT"] = "0"
+os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+os.environ["TORCH_DEVICE"] = "cpu"
+
+
+def _worker_main() -> None:
+    """Main loop: read JSON requests from stdin, write responses to stdout."""
+    import numpy as np
+
+    model = None
+    model_name = None
+    dim = 0
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            _respond({"ok": False, "error": "Invalid JSON"})
+            continue
+
+        cmd = req.get("cmd", "")
+
+        if cmd == "quit":
+            break
+
+        if cmd == "ping":
+            _respond({"ok": True})
+            continue
+
+        if cmd == "load":
+            name = req.get("model_name", "nomic-ai/nomic-embed-text-v1.5")
+            expected_dim = req.get("dimension", 768)
+            try:
+                from sentence_transformers import SentenceTransformer
+                model = SentenceTransformer(name, trust_remote_code=True, device="cpu")
+                dim = model.get_sentence_embedding_dimension()
+                if dim != expected_dim:
+                    _respond({"ok": False, "error": f"Dimension mismatch: {dim} != {expected_dim}"})
+                    model = None
+                    continue
+                model_name = name
+                _respond({"ok": True, "dim": dim, "model": name})
+            except Exception as exc:
+                _respond({"ok": False, "error": str(exc)})
+            continue
+
+        if cmd == "embed":
+            texts = req.get("texts", [])
+            if not texts:
+                _respond({"ok": False, "error": "No texts provided"})
+                continue
+            if model is None:
+                # Auto-load if not yet loaded
+                name = req.get("model_name", "nomic-ai/nomic-embed-text-v1.5")
+                expected_dim = req.get("dimension", 768)
+                try:
+                    from sentence_transformers import SentenceTransformer
+                    model = SentenceTransformer(name, trust_remote_code=True, device="cpu")
+                    dim = model.get_sentence_embedding_dimension()
+                    model_name = name
+                except Exception as exc:
+                    _respond({"ok": False, "error": f"Model load failed: {exc}"})
+                    continue
+            try:
+                vecs = model.encode(texts, normalize_embeddings=True)
+                if isinstance(vecs, np.ndarray) and vecs.ndim == 2:
+                    result = [vecs[i].tolist() for i in range(vecs.shape[0])]
+                else:
+                    result = [np.asarray(v, dtype=np.float32).tolist() for v in vecs]
+                _respond({"ok": True, "vectors": result, "dim": dim})
+            except Exception as exc:
+                _respond({"ok": False, "error": str(exc)})
+            continue
+
+        _respond({"ok": False, "error": f"Unknown command: {cmd}"})
+
+
+def _respond(data: dict) -> None:
+    """Write JSON response to stdout, flush immediately."""
+    sys.stdout.write(json.dumps(data) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    _worker_main()