htm 0.0.30 → 0.0.32

data/lib/htm/mcp/cli.rb

@@ -138,51 +138,16 @@ class HTM
       end
 
       def check_database_config!
-        unless ENV['HTM_DATABASE__URL'] || ENV['HTM_DATABASE__NAME']
-          warn "Error: Database not configured."
-          warn "Set HTM_DATABASE__URL or HTM_DATABASE__NAME environment variable."
-          warn "Run 'htm_mcp help' for details."
-          exit 1
-        end
+        return if ENV['HTM_DATABASE__URL'] || ENV['HTM_DATABASE__NAME']
+        warn "Error: Database not configured."
+        warn "Set HTM_DATABASE__URL or HTM_DATABASE__NAME environment variable."
+        warn "Run 'htm_mcp help' for details."
+        exit 1
       end
 
       def print_error_suggestion(error_message)
-        msg = error_message.to_s.downcase
-
         warn ""
-        if msg.include?("does not exist")
-          warn "Suggestion: The database does not exist. Create it with:"
-          warn "  createdb #{extract_dbname(ENV['HTM_DATABASE__URL'] || ENV['HTM_DATABASE__NAME'])}"
-          warn "Then initialize the schema with:"
-          warn "  htm_mcp setup"
-        elsif msg.include?("password authentication failed") || msg.include?("no password supplied")
-          warn "Suggestion: Check your database credentials."
-          warn "Verify HTM_DATABASE__URL has correct username and password:"
-          warn "  postgresql://USER:PASSWORD@localhost:5432/DATABASE"
-        elsif msg.include?("connection refused") || msg.include?("could not connect")
-          warn "Suggestion: PostgreSQL server is not running or not accepting connections."
-          warn "Start PostgreSQL with:"
-          warn "  brew services start postgresql@17  # macOS with Homebrew"
-          warn "  sudo systemctl start postgresql    # Linux"
-        elsif msg.include?("role") && msg.include?("does not exist")
-          warn "Suggestion: The database user does not exist. Create it with:"
-          warn "  createuser -s YOUR_USERNAME"
-        elsif msg.include?("permission denied")
-          warn "Suggestion: The user lacks permission to access this database."
-          warn "Grant access or use a different user with appropriate privileges."
-        elsif msg.include?("timeout") || msg.include?("timed out")
-          warn "Suggestion: Connection timed out. Check:"
-          warn "  - PostgreSQL is running"
-          warn "  - Firewall allows connections on port 5432"
-          warn "  - Host address is correct"
-        elsif msg.include?("extension") && msg.include?("vector")
-          warn "Suggestion: pgvector extension is not installed. Install it with:"
-          warn "  brew install pgvector  # macOS"
-          warn "Then enable it in your database:"
-          warn "  psql -d DATABASE -c 'CREATE EXTENSION vector;'"
-        else
-          warn "Suggestion: Run 'htm_mcp help' for configuration details."
-        end
+        suggestion_lines_for(error_message.to_s.downcase).each { |line| warn line }
       end
 
       def extract_dbname(url_or_name)
@@ -190,7 +155,7 @@ class HTM
 
         # Extract database name from URL like postgresql://user@host:port/dbname
         if url_or_name =~ %r{/([^/?]+)(?:\?|$)}
-          $1
+          ::Regexp.last_match(1)
         else
           "htm_development"
         end
@@ -231,7 +196,7 @@ class HTM
           pending = check_migration_status
           puts
 
-          if pending > 0
+          if pending.positive?
             warn "Warning: #{pending} pending migration(s) detected."
             warn "  Run 'htm_mcp setup' to apply pending migrations."
             puts
@@ -255,7 +220,8 @@ class HTM
             version: File.basename(file).split('_').first,
             name: File.basename(file, '.rb')
           }
-        end.sort_by { |m| m[:version] }
+        end
+        available_migrations = available_migrations.sort_by { |m| m[:version] }
 
         # Ensure Sequel connection for migration check
         HTM::SequelConfig.establish_connection!
@@ -308,12 +274,9 @@ class HTM
 
         begin
           require 'yaml'
-          config_data = YAML.safe_load(
-            File.read(path),
-            permitted_classes: [Symbol],
+          config_data = YAML.safe_load_file(path, permitted_classes: [Symbol],
             symbolize_names: true,
-            aliases: true
-          ) || {}
+            aliases: true) || {}
 
           # Determine which section to use based on environment
           env = HTM::Config.env.to_sym
@@ -425,7 +388,7 @@ class HTM
         args = args.dup
 
         # Handle -c / --config option first (can be combined with other commands)
-        config_loaded = handle_config_option(args)
+        handle_config_option(args)
 
         # Process remaining command
         case args[0]&.downcase
@@ -448,12 +411,12 @@ class HTM
           # 'stdio' is accepted for compatibility with MCP clients that pass it as an argument
           return false
         when /^-/
-          $stderr.puts "Unknown option: #{args[0]}"
-          $stderr.puts "Run 'htm_mcp help' for usage."
+          warn "Unknown option: #{args[0]}"
+          warn "Run 'htm_mcp help' for usage."
           exit 1
         else
-          $stderr.puts "Unknown command: #{args[0]}"
-          $stderr.puts "Run 'htm_mcp help' for usage."
+          warn "Unknown command: #{args[0]}"
+          warn "Run 'htm_mcp help' for usage."
           exit 1
         end
         true
@@ -494,7 +457,7 @@ class HTM
         if args.empty? || args.first == '--tasks' || args.first == '-T'
           # Check for optional pattern after -T/--tasks
           pattern = nil
-          if args.first == '--tasks' || args.first == '-T'
+          if ['--tasks', '-T'].include?(args.first)
             pattern = args[1] # May be nil if no pattern provided
           end
           list_rake_tasks(pattern: pattern)
@@ -532,7 +495,7 @@ class HTM
 
         # Load all HTM task files
         tasks_dir = File.expand_path('../../tasks', __dir__)
-        Dir.glob(File.join(tasks_dir, '*.rake')).sort.each do |rake_file|
+        Dir.glob(File.join(tasks_dir, '*.rake')).each do |rake_file|
           load rake_file
         end
       end
@@ -542,8 +505,8 @@ class HTM
 
         # Collect tasks with descriptions, sorted by name
         tasks = Rake.application.tasks
-          .select { |t| t.comment && t.name.start_with?('htm:') }
-          .sort_by(&:name)
+                    .select { |t| t.comment && t.name.start_with?('htm:') }
+                    .sort_by(&:name)
 
         # Filter by pattern if provided (matches task name)
         if pattern
@@ -577,6 +540,44 @@ class HTM
         puts "Run with: htm_mcp rake <task_name>"
         puts "Example:  htm_mcp rake htm:db:stats"
       end
+
+      private
+
+      def suggestion_lines_for(msg)
+        if msg.include?("does not exist") && !msg.include?("role")
+          dbname = extract_dbname(ENV['HTM_DATABASE__URL'] || ENV.fetch('HTM_DATABASE__NAME', nil))
+          ["Suggestion: The database does not exist. Create it with:",
+           "  createdb #{dbname}",
+           "Then initialize the schema with:", "  htm_mcp setup"]
+        elsif msg.include?("password authentication failed") || msg.include?("no password supplied")
+          ["Suggestion: Check your database credentials.",
+           "Verify HTM_DATABASE__URL has correct username and password:",
+           "  postgresql://USER:PASSWORD@localhost:5432/DATABASE"]
+        elsif msg.include?("connection refused") || msg.include?("could not connect")
+          ["Suggestion: PostgreSQL server is not running or not accepting connections.",
+           "Start PostgreSQL with:",
+           "  brew services start postgresql@17  # macOS with Homebrew",
+           "  sudo systemctl start postgresql    # Linux"]
+        elsif msg.include?("role") && msg.include?("does not exist")
+          ["Suggestion: The database user does not exist. Create it with:",
+           "  createuser -s YOUR_USERNAME"]
+        elsif msg.include?("permission denied")
+          ["Suggestion: The user lacks permission to access this database.",
+           "Grant access or use a different user with appropriate privileges."]
+        elsif msg.include?("timeout") || msg.include?("timed out")
+          ["Suggestion: Connection timed out. Check:",
+           "  - PostgreSQL is running",
+           "  - Firewall allows connections on port 5432",
+           "  - Host address is correct"]
+        elsif msg.include?("extension") && msg.include?("vector")
+          ["Suggestion: pgvector extension is not installed. Install it with:",
+           "  brew install pgvector  # macOS",
+           "Then enable it in your database:",
+           "  psql -d DATABASE -c 'CREATE EXTENSION vector;'"]
+        else
+          ["Suggestion: Run 'htm_mcp help' for configuration details."]
+        end
+      end
     end
   end
 end

data/lib/htm/mcp/server.rb

@@ -28,12 +28,11 @@ class HTM
       end
 
       def check_database_config!
-        unless ENV['HTM_DATABASE__URL'] || ENV['HTM_DATABASE__NAME']
-          warn "Error: Database not configured."
-          warn "Set HTM_DATABASE__URL or HTM_DATABASE__NAME environment variable."
-          warn "Run 'htm_mcp help' for details."
-          exit 1
-        end
+        return if ENV['HTM_DATABASE__URL'] || ENV['HTM_DATABASE__NAME']
+        warn "Error: Database not configured."
+        warn "Set HTM_DATABASE__URL or HTM_DATABASE__NAME environment variable."
+        warn "Run 'htm_mcp help' for details."
+        exit 1
       end
 
       def verify_database_connection!

data/lib/htm/mcp/tools.rb

@@ -88,44 +88,38 @@ class HTM
       end
 
       def call
-        htm = Session.htm_instance
+        htm   = Session.htm_instance
         robot = HTM::Models::Robot[htm.robot_id]
         Session.logger&.info "GetWorkingMemoryTool called for robot=#{htm.robot_name}"
 
-        # Get all nodes in working memory with their metadata
-        # Filter out any robot_nodes where the node has been deleted
-        working_memory_nodes = robot.robot_nodes_dataset
-                                    .in_working_memory
-                                    .eager(node: :tags)
-                                    .order(Sequel.desc(:last_remembered_at))
-                                    .all
-                                    .filter_map do |rn|
-          node = rn.node
-          next unless node  # Exclude if node is nil (was deleted)
+        nodes = robot.robot_nodes_dataset
+                     .in_working_memory
+                     .eager(node: :tags)
+                     .order(Sequel.desc(:last_remembered_at))
+                     .all
+                     .filter_map { |rn| format_working_memory_entry(rn) }
 
-          {
-            id:                 node.id,
-            content:            node.content,
-            tags:               node.tags.map(&:name),
-            remember_count:     rn.remember_count,
-            last_remembered_at: rn.last_remembered_at&.iso8601,
-            created_at:         node.created_at.iso8601
-          }
-        end
-
-        Session.logger&.info "GetWorkingMemoryTool complete: #{working_memory_nodes.length} nodes in working memory"
-
-        {
-          success:        true,
-          robot_id:       htm.robot_id,
-          robot_name:     htm.robot_name,
-          count:          working_memory_nodes.length,
-          working_memory: working_memory_nodes
-        }.to_json
+        Session.logger&.info "GetWorkingMemoryTool complete: #{nodes.length} nodes in working memory"
+        { success: true, robot_id: htm.robot_id, robot_name: htm.robot_name, count: nodes.length, working_memory: nodes }.to_json
       rescue StandardError => e
         Session.logger&.error "GetWorkingMemoryTool error: #{e.message}"
         { success: false, error: e.message, count: 0, working_memory: [] }.to_json
       end
+
+      private
+
+      def format_working_memory_entry(rn)
+        node = rn.node
+        return nil unless node
+        {
+          id:                 node.id,
+          content:            node.content,
+          tags:               node.tags.map(&:name),
+          remember_count:     rn.remember_count,
+          last_remembered_at: rn.last_remembered_at&.iso8601,
+          created_at:         node.created_at.iso8601
+        }
+      end
     end
 
     # Tool: Remember information
@@ -221,10 +215,10 @@ class HTM
           Time.new(now.year, now.month, now.day)..now
         when 'this week'
           # 7 days ago
-          (now - 7 * 24 * 60 * 60)..now
+          (now - (7 * 24 * 60 * 60))..now
         when 'this month'
           # 30 days ago
-          (now - 30 * 24 * 60 * 60)..now
+          (now - (30 * 24 * 60 * 60))..now
         else
           # Try to parse as ISO8601 range (start..end)
           if timeframe.include?('..')
@@ -438,14 +432,14 @@ class HTM
         robot = HTM::Models::Robot[htm.robot_id]
         Session.logger&.info "StatsTool called for robot=#{htm.robot_name}"
 
-        # Note: Node uses set_dataset to exclude deleted, so .count returns active nodes
+        # NOTE: Node uses set_dataset to exclude deleted, so .count returns active nodes
         total_nodes           = HTM::Models::Node.count
         deleted_nodes         = HTM::Models::Node.deleted.count
         nodes_with_embeddings = HTM::Models::Node.with_embeddings.count
         nodes_with_tags       = HTM::Models::Node
-                                  .join(:node_tags, node_id: :id)
-                                  .distinct
-                                  .count
+                                .join(:node_tags, node_id: :id)
+                                .distinct
+                                .count
         total_tags            = HTM::Models::Tag.count
         total_robots          = HTM::Models::Robot.count
 

data/lib/htm/migration.rb

@@ -41,24 +41,24 @@ class HTM
     private
 
     # Delegate common methods to db
-    def create_table(name, **options, &block)
-      db.create_table(name, **options, &block)
+    def create_table(name, **, &)
+      db.create_table(name, **, &)
     end
 
-    def drop_table(name, **options)
-      db.drop_table(name, **options)
+    def drop_table(name, **)
+      db.drop_table(name, **)
     end
 
-    def alter_table(name, &block)
-      db.alter_table(name, &block)
+    def alter_table(name, &)
+      db.alter_table(name, &)
     end
 
-    def add_index(table, columns, **options)
-      db.add_index(table, columns, **options)
+    def add_index(table, columns, **)
+      db.add_index(table, columns, **)
     end
 
-    def drop_index(table, columns, **options)
-      db.drop_index(table, columns, **options)
+    def drop_index(table, columns, **)
+      db.drop_index(table, columns, **)
     end
 
     def run(sql)

data/lib/htm/models/node.rb

@@ -43,7 +43,7 @@ class HTM
       # Validations
       def validate
         super
-        validates_presence [:content, :content_hash]
+        validates_presence %i[content content_hash]
         validates_unique :content_hash
       end
 
@@ -110,7 +110,6 @@ class HTM
 
           # Select distance operator based on metric
           operator = case distance.to_s
-                     when "cosine" then "<=>"
                      when "euclidean", "l2" then "<->"
                      when "inner_product" then "<#>"
                      else "<=>"
@@ -356,7 +355,7 @@ class HTM
       def to_hash
         values.transform_keys(&:to_s)
       end
-      alias_method :attributes, :to_hash
+      alias attributes to_hash
     end
   end
 end

data/lib/htm/models/node_relationship.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+class HTM
+  module Models
+    # NodeRelationship model - weighted directed edge between two nodes
+    #
+    # Edges are stored in both directions so the CTE traversal only needs
+    # WHERE source_id IN (seeds) rather than an OR across both columns.
+    #
+    # Weights are Jaccard similarity scores for tag_cooccurrence edges:
+    #   weight = |tags(A) ∩ tags(B)| / |tags(A) ∪ tags(B)|
+    #
+    class NodeRelationship < Sequel::Model(:node_relationships)
+      REL_TYPES = %w[related_to supports contradicts derived_from].freeze
+      ORIGINS   = %w[tag_cooccurrence tag_hierarchy explicit].freeze
+
+      # Associations
+      many_to_one :source_node, class: 'HTM::Models::Node', key: :source_id
+      many_to_one :target_node, class: 'HTM::Models::Node', key: :target_id
+
+      # Plugins
+      plugin :validation_helpers
+      plugin :timestamps, update_on_create: true
+
+      # Validations
+      def validate
+        super
+        validates_presence %i[source_id target_id rel_type origin weight]
+        validates_includes REL_TYPES, :rel_type, allow_missing: true
+        validates_includes ORIGINS,   :origin,   allow_missing: true
+        validates_unique %i[source_id target_id rel_type], message: 'relationship already exists'
+        errors.add(:source_id, 'cannot relate a node to itself') if source_id && source_id == target_id
+        errors.add(:weight, 'must be between 0.0 and 1.0') if weight && !weight.between?(0.0, 1.0)
+      end
+
+      # Dataset methods (scopes)
+      dataset_module do
+        def by_origin(origin)
+          where(origin: origin.to_s)
+        end
+
+        def by_rel_type(rel_type)
+          where(rel_type: rel_type.to_s)
+        end
+
+        def above_weight(min_weight)
+          where { weight >= min_weight }
+        end
+
+        def neighbors_of(node_id)
+          where(source_id: node_id).order(Sequel.desc(:weight))
+        end
+
+        def between_nodes(source_id, target_id)
+          where(source_id: source_id, target_id: target_id)
+        end
+      end
+
+      # Hooks
+      def before_create
+        self.created_at ||= Time.now
+        self.updated_at ||= Time.now
+        super
+      end
+
+      def before_save
+        self.updated_at = Time.now if changed_columns.any?
+        super
+      end
+    end
+  end
+end

data/lib/htm/models/node_tag.rb

@@ -15,8 +15,8 @@ class HTM
       # Validations
       def validate
         super
-        validates_presence [:node_id, :tag_id]
-        validates_unique [:node_id, :tag_id], message: "already associated with this node"
+        validates_presence %i[node_id tag_id]
+        validates_unique %i[node_id tag_id], message: "already associated with this node"
       end
 
       # Dataset methods (scopes)

data/lib/htm/models/robot_node.rb

@@ -19,8 +19,8 @@ class HTM
       # Validations
       def validate
         super
-        validates_presence [:robot_id, :node_id]
-        validates_unique [:robot_id, :node_id], message: 'already linked to this node'
+        validates_presence %i[robot_id node_id]
+        validates_unique %i[robot_id node_id], message: 'already linked to this node'
       end
 
       # Dataset methods (scopes)

data/lib/htm/models/tag.rb

@@ -15,14 +15,14 @@ class HTM
       plugin :timestamps, update_on_create: true
 
       # Tag name format regex
-      TAG_FORMAT = /\A[a-z0-9\-]+(:[a-z0-9\-]+)*\z/
+      TAG_FORMAT = /\A[a-z0-9-]+(:[a-z0-9-]+)*\z/
 
       # Validations
       def validate
         super
         validates_presence :name
         validates_format TAG_FORMAT, :name,
-          message: "must be lowercase with hyphens, using colons for hierarchy (e.g., 'database:postgresql:performance')"
+                         message: "must be lowercase with hyphens, using colons for hierarchy (e.g., 'database:postgresql:performance')"
         validates_unique :name, message: "already exists"
       end
 
@@ -233,8 +233,7 @@ class HTM
 
           line_prefix = is_last_array.map { |was_last| was_last ? '    ' : '|   ' }.join
 
-          branch = is_last ? '+-- ' : '+-- '
-          result += "#{line_prefix}#{branch}#{key}\n"
+          result += "#{line_prefix}+-- #{key}\n"
 
           children = node[key]
           unless children.empty?
@@ -313,44 +312,58 @@ class HTM
 
       # Generate SVG tree visualization (internal helper)
       def self.generate_tree_svg(tree_data, positions, width, height, padding, node_width, node_height, title)
-        colors = ['#3B82F6', '#8B5CF6', '#EC4899', '#F59E0B', '#10B981', '#6366F1']
-
+        colors    = ['#3B82F6', '#8B5CF6', '#EC4899', '#F59E0B', '#10B981', '#6366F1']
         svg_lines = []
         svg_lines << %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{width} #{height + 40}">)
         svg_lines << '  <rect width="100%" height="100%" fill="transparent"/>'
-
-        svg_lines << %Q(  <text x="#{width / 2}" y="25" text-anchor="middle" fill="#F3F4F6" font-family="system-ui, sans-serif" font-size="16" font-weight="bold">#{title}</text>)
+        svg_lines << svg_title_element(width, title)
 
         positions.each do |path, pos|
           parent_path = path.include?(':') ? path.split(':')[0..-2].join(':') : nil
           next unless parent_path && positions[parent_path]
+          svg_lines.concat svg_node_elements(path, pos, positions[parent_path], colors, padding, node_width, node_height)
+        end
 
-          parent_pos = positions[parent_path]
-          x1 = padding + (parent_pos[:x] * (node_width + 40)) + node_width
-          y1 = 40 + padding + (parent_pos[:y] * (node_height + 20)) + (node_height / 2)
-          x2 = padding + (pos[:x] * (node_width + 40))
-          y2 = 40 + padding + (pos[:y] * (node_height + 20)) + (node_height / 2)
+        svg_lines << '</svg>'
+        svg_lines.join("\n")
+      end
 
-          mid_x = (x1 + x2) / 2
-          svg_lines << %Q(  <path d="M#{x1},#{y1} C#{mid_x},#{y1} #{mid_x},#{y2} #{x2},#{y2}" stroke="#4B5563" stroke-width="2" fill="none"/>)
-        end
+      def self.svg_title_element(width, title)
+        %(  <text x="#{width / 2}" y="25" text-anchor="middle" fill="#F3F4F6" font-family="system-ui, sans-serif" font-size="16" font-weight="bold">#{title}</text>) # rubocop:disable Layout/LineLength
+      end
 
-        positions.each do |path, pos|
-          depth = path.count(':')
-          color = colors[depth % colors.size]
+      def self.svg_node_elements(path, pos, parent_pos, colors, padding, node_width, node_height)
+        c     = svg_node_coords(pos, parent_pos, padding, node_width, node_height)
+        color = colors[path.count(':') % colors.size]
+        [
+          svg_edge_path(c[:x1], c[:y1], c[:x2], c[:y2]),
+          svg_node_rect(c[:x], c[:y], node_width, node_height, color),
+          svg_node_label(c[:x], c[:y], node_width, node_height, pos[:label])
+        ]
+      end
 
-          x = padding + (pos[:x] * (node_width + 40))
-          y = 40 + padding + (pos[:y] * (node_height + 20))
+      def self.svg_node_coords(pos, parent_pos, padding, node_width, node_height)
+        x2 = padding + (pos[:x] * (node_width + 40))
+        y2 = 40 + padding + (pos[:y] * (node_height + 20)) + (node_height / 2)
+        {
+          x1: padding + (parent_pos[:x] * (node_width + 40)) + node_width,
+          y1: 40 + padding + (parent_pos[:y] * (node_height + 20)) + (node_height / 2),
+          x2: x2, y2: y2,
+          x:  x2, y:  40 + padding + (pos[:y] * (node_height + 20))
+        }
+      end
 
-          svg_lines << %Q(  <rect x="#{x}" y="#{y}" width="#{node_width}" height="#{node_height}" rx="6" fill="#{color}" opacity="0.9"/>)
+      def self.svg_edge_path(x1, y1, x2, y2)
+        mid_x = (x1 + x2) / 2
+        %(  <path d="M#{x1},#{y1} C#{mid_x},#{y1} #{mid_x},#{y2} #{x2},#{y2}" stroke="#4B5563" stroke-width="2" fill="none"/>)
+      end
 
-          text_x = x + (node_width / 2)
-          text_y = y + (node_height / 2) + 4
-          svg_lines << %Q(  <text x="#{text_x}" y="#{text_y}" text-anchor="middle" fill="#FFFFFF" font-family="system-ui, sans-serif" font-size="11" font-weight="500">#{pos[:label]}</text>)
-        end
+      def self.svg_node_rect(x, y, node_width, node_height, color)
+        %(  <rect x="#{x}" y="#{y}" width="#{node_width}" height="#{node_height}" rx="6" fill="#{color}" opacity="0.9"/>)
+      end
 
-        svg_lines << '</svg>'
-        svg_lines.join("\n")
+      def self.svg_node_label(x, y, node_width, node_height, label)
+        %(  <text x="#{x + (node_width / 2)}" y="#{y + (node_height / 2) + 4}" text-anchor="middle" fill="#FFFFFF" font-family="system-ui, sans-serif" font-size="11" font-weight="500">#{label}</text>) # rubocop:disable Layout/LineLength
       end
 
       # Instance methods