htm 0.0.14 → 0.0.17

data/lib/htm/tasks.rb

@@ -8,7 +8,7 @@
 #
 # This will make the following tasks available:
 #
-# Database tasks (all respect RAILS_ENV, default: development):
+# Database tasks (all respect HTM_ENV/RAILS_ENV, default: development):
 #   rake htm:db:create     # Create database if it doesn't exist
 #   rake htm:db:setup      # Set up HTM database schema and run migrations
 #   rake htm:db:migrate    # Run pending database migrations
@@ -20,10 +20,13 @@
 #   rake htm:db:drop       # Drop all HTM tables (destructive!)
 #   rake htm:db:reset      # Drop and recreate database (destructive!)
 #
+# Environment detection priority: HTM_ENV > RAILS_ENV > RACK_ENV > 'development'
+#
 # Examples:
-#   RAILS_ENV=test rake htm:db:create   # Create htm_test database
-#   RAILS_ENV=test rake htm:db:setup    # Setup test database with migrations
-#   RAILS_ENV=test rake htm:db:drop     # Drop test database
+#   HTM_ENV=test rake htm:db:create    # Create htm_test database
+#   HTM_ENV=test rake htm:db:setup     # Setup test database with migrations
+#   HTM_ENV=test rake htm:db:drop      # Drop test database
+#   RAILS_ENV=test rake htm:db:create  # Also works (for Rails apps)
 #
 # Async job tasks:
 #   rake htm:jobs:stats              # Show async job statistics

data/lib/htm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class HTM
-  VERSION = '0.0.14'
+  VERSION = '0.0.17'
 end

data/lib/htm/working_memory_channel.rb

@@ -0,0 +1,250 @@
+# examples/robot_groups/lib/htm/working_memory_channel.rb
+# frozen_string_literal: true
+
+class HTM
+  # Provides real-time synchronization of working memory changes across multiple
+  # robots using PostgreSQL LISTEN/NOTIFY pub/sub mechanism.
+  #
+  # This class enables distributed robots to maintain synchronized working memory
+  # by broadcasting change notifications through PostgreSQL channels. When one robot
+  # adds, evicts, or clears working memory, all other robots in the group receive
+  # immediate notification.
+  #
+  # @example Basic usage
+  #   channel = HTM::WorkingMemoryChannel.new('support-team', db_config)
+  #
+  #   # Subscribe to changes
+  #   channel.on_change do |event, node_id, robot_id|
+  #     case event
+  #     when :added   then puts "Node #{node_id} added by robot #{robot_id}"
+  #     when :evicted then puts "Node #{node_id} evicted by robot #{robot_id}"
+  #     when :cleared then puts "Working memory cleared by robot #{robot_id}"
+  #     end
+  #   end
+  #
+  #   # Start listening in background thread
+  #   channel.start_listening
+  #
+  #   # Publish a change
+  #   channel.notify(:added, node_id: 123, robot_id: 456)
+  #
+  #   # Cleanup when done
+  #   channel.stop_listening
+  #
+  # @see HTM::RobotGroup Higher-level coordination using this channel
+  #
+  class WorkingMemoryChannel
+    # Prefix used for all PostgreSQL channel names
+    # @return [String]
+    CHANNEL_PREFIX = 'htm_wm'
+
+    # Number of notifications received since channel was created
+    # @return [Integer]
+    attr_reader :notifications_received
+
+    # Creates a new working memory channel for a robot group.
+    #
+    # The channel name is derived from the group name with non-alphanumeric
+    # characters replaced by underscores to ensure PostgreSQL compatibility.
+    #
+    # @param group_name [String] Name of the robot group (used to create unique channel)
+    # @param db_config [Hash] PostgreSQL connection configuration hash
+    # @option db_config [String] :host Database host
+    # @option db_config [Integer] :port Database port
+    # @option db_config [String] :dbname Database name
+    # @option db_config [String] :user Database user
+    # @option db_config [String] :password Database password (optional)
+    #
+    # @example
+    #   db_config = { host: 'localhost', port: 5432, dbname: 'htm_dev', user: 'postgres' }
+    #   channel = HTM::WorkingMemoryChannel.new('customer-support', db_config)
+    #
+    def initialize(group_name, db_config)
+      @group_name             = group_name
+      @channel                = "#{CHANNEL_PREFIX}_#{group_name.gsub(/[^a-z0-9_]/i, '_')}"
+      @db_config              = db_config
+      @listeners              = []
+      @listen_thread          = nil
+      @stop_requested         = false
+      @notifications_received = 0
+      @mutex                  = Mutex.new
+    end
+
+    # @!group Publishing
+
+    # Broadcasts a working memory change notification to all listeners.
+    #
+    # Uses PostgreSQL's pg_notify function to send a JSON payload containing
+    # the event type, affected node ID, originating robot ID, and timestamp.
+    #
+    # @param event [Symbol] Type of change (:added, :evicted, or :cleared)
+    # @param node_id [Integer, nil] ID of the affected node (nil for :cleared events)
+    # @param robot_id [Integer] ID of the robot that triggered the change
+    # @return [void]
+    #
+    # @example Notify that a node was added
+    #   channel.notify(:added, node_id: 123, robot_id: 1)
+    #
+    # @example Notify that working memory was cleared
+    #   channel.notify(:cleared, node_id: nil, robot_id: 1)
+    #
+    def notify(event, node_id:, robot_id:)
+      payload = {
+        event: event,
+        node_id: node_id,
+        robot_id: robot_id,
+        timestamp: Time.now.iso8601
+      }.to_json
+
+      with_connection do |conn|
+        conn.exec_params('SELECT pg_notify($1, $2)', [@channel, payload])
+      end
+    end
+
+    # @!endgroup
+
+    # @!group Subscribing
+
+    # Registers a callback to be invoked when working memory changes occur.
+    #
+    # Multiple callbacks can be registered; all will be called for each event.
+    # Callbacks are invoked synchronously within the listener thread.
+    #
+    # @yield [event, node_id, robot_id] Block called for each notification
+    # @yieldparam event [Symbol] Type of change (:added, :evicted, or :cleared)
+    # @yieldparam node_id [Integer, nil] ID of the affected node
+    # @yieldparam robot_id [Integer] ID of the robot that triggered the change
+    # @return [void]
+    #
+    # @example Register a change handler
+    #   channel.on_change do |event, node_id, robot_id|
+    #     puts "Received #{event} event for node #{node_id}"
+    #   end
+    #
+    def on_change(&callback)
+      @mutex.synchronize { @listeners << callback }
+    end
+
+    # Starts listening for notifications in a background thread.
+    #
+    # Creates a dedicated PostgreSQL connection that uses LISTEN to receive
+    # notifications. The thread polls every 0.5 seconds, allowing for clean
+    # shutdown via {#stop_listening}.
+    #
+    # @return [Thread] The background listener thread
+    #
+    # @example Start and verify listening
+    #   thread = channel.start_listening
+    #   puts "Listening: #{channel.listening?}"  # => true
+    #
+    def start_listening
+      @stop_requested = false
+      @listen_thread  = Thread.new do
+        listen_loop
+      end
+      @listen_thread.abort_on_exception = true
+      @listen_thread
+    end
+
+    # Stops the background listener thread.
+    #
+    # Signals the listener to stop, waits up to 0.5 seconds for clean exit,
+    # then forcefully terminates if still running. The PostgreSQL connection
+    # is closed automatically.
+    #
+    # @return [void]
+    #
+    # @example Clean shutdown
+    #   channel.stop_listening
+    #   puts "Listening: #{channel.listening?}"  # => false
+    #
+    def stop_listening
+      @stop_requested = true
+      # Give the thread a moment to exit cleanly
+      @listen_thread&.join(0.5)
+      @listen_thread&.kill if @listen_thread&.alive?
+      @listen_thread = nil
+    end
+
+    # @!endgroup
+
+    # @!group Status
+
+    # Checks if the listener thread is currently active.
+    #
+    # @return [Boolean] true if listening for notifications, false otherwise
+    #
+    # @example
+    #   channel.start_listening
+    #   channel.listening?  # => true
+    #   channel.stop_listening
+    #   channel.listening?  # => false
+    #
+    def listening?
+      @listen_thread&.alive? || false
+    end
+
+    # Returns the PostgreSQL channel name used for notifications.
+    #
+    # The channel name is derived from the group name with a prefix and
+    # sanitization of special characters.
+    #
+    # @return [String] The PostgreSQL LISTEN/NOTIFY channel name
+    #
+    # @example
+    #   channel = HTM::WorkingMemoryChannel.new('my-group', db_config)
+    #   channel.channel_name  # => "htm_wm_my_group"
+    #
+    def channel_name
+      @channel
+    end
+
+    # @!endgroup
+
+    private
+
+    def listen_loop
+      conn = PG.connect(@db_config)
+      conn.exec("LISTEN #{conn.escape_identifier(@channel)}")
+
+      until @stop_requested
+        # Wait for notification with timeout (allows checking @stop_requested)
+        conn.wait_for_notify(0.5) do |_channel, _pid, payload|
+          handle_notification(payload)
+        end
+      end
+    rescue PG::Error => e
+      unless @stop_requested
+        HTM.logger.error "WorkingMemoryChannel error: #{e.message}"
+        sleep 1
+        retry
+      end
+    ensure
+      conn&.close
+    end
+
+    def handle_notification(payload)
+      data = JSON.parse(payload, symbolize_names: true)
+
+      @mutex.synchronize do
+        @notifications_received += 1
+        @listeners.each do |callback|
+          callback.call(
+            data[:event].to_sym,
+            data[:node_id],
+            data[:robot_id]
+          )
+        end
+      end
+    rescue JSON::ParserError => e
+      HTM.logger.error "Invalid notification payload: #{e.message}"
+    end
+
+    def with_connection
+      conn = PG.connect(@db_config)
+      yield conn
+    ensure
+      conn&.close
+    end
+  end
+end

data/lib/htm.rb

@@ -21,6 +21,8 @@ require_relative "htm/loaders/markdown_chunker"
 require_relative "htm/loaders/markdown_loader"
 require_relative "htm/observability"
 require_relative "htm/telemetry"
+require_relative "htm/working_memory_channel"
+require_relative "htm/robot_group"
 
 require "pg"
 require "securerandom"

data/lib/tasks/htm.rake

@@ -68,14 +68,13 @@ namespace :htm do
       end
     end
 
-    desc "Verify database connection (respects RAILS_ENV)"
+    desc "Verify database connection (respects HTM_ENV/RAILS_ENV)"
     task :verify do
       require 'htm'
 
-      env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
       config = HTM::ActiveRecordConfig.load_database_config
 
-      puts "Verifying HTM database connection (#{env})..."
+      puts "Verifying HTM database connection (#{HTM.env})..."
       puts "  Host: #{config[:host]}"
       puts "  Port: #{config[:port]}"
       puts "  Database: #{config[:database]}"
@@ -107,14 +106,13 @@ namespace :htm do
       end
     end
 
-    desc "Open PostgreSQL console (respects RAILS_ENV)"
+    desc "Open PostgreSQL console (respects HTM_ENV/RAILS_ENV)"
     task :console do
       require 'htm'
 
-      env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
       config = HTM::ActiveRecordConfig.load_database_config
 
-      puts "Connecting to #{config[:database]} (#{env})..."
+      puts "Connecting to #{config[:database]} (#{HTM.env})..."
       exec "psql", "-h", config[:host],
                    "-p", config[:port].to_s,
                    "-U", config[:username],
@@ -416,15 +414,14 @@ namespace :htm do
       end
     end
 
-    desc "Create database if it doesn't exist (respects RAILS_ENV)"
+    desc "Create database if it doesn't exist (respects HTM_ENV/RAILS_ENV)"
     task :create do
       require 'htm'
 
-      env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
       config = HTM::ActiveRecordConfig.load_database_config
       db_name = config[:database]
 
-      puts "Creating database: #{db_name} (#{env})"
+      puts "Creating database: #{db_name} (#{HTM.env})"
 
       admin_config = config.dup
       admin_config[:database] = 'postgres'

data/mkdocs.yml

@@ -199,6 +199,7 @@ nav:
       - Multi-Robot Usage: guides/multi-robot.md
       - Search Strategies: guides/search-strategies.md
       - Context Assembly: guides/context-assembly.md
+      - MCP Server: guides/mcp-server.md
   - API Reference:
       - api/index.md
       - HTM Class: api/htm.md
@@ -245,6 +246,7 @@ nav:
       - Setup: development/setup.md
       - Testing: development/testing.md
       - Contributing: development/contributing.md
+      - Rake Tasks Reference: development/rake-tasks.md
       - Database Schema: development/schema.md
       - Database Tables:
           - database/README.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: htm
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.17
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -256,7 +256,7 @@ description: |
 email:
 - dvanhoozer@gmail.com
 executables:
-- htm_mcp.rb
+- htm_mcp
 extensions: []
 extra_rdoc_files: []
 files:
@@ -290,7 +290,7 @@ files:
 - README.md
 - Rakefile
 - SETUP.md
-- bin/htm_mcp.rb
+- bin/htm_mcp
 - config/database.yml
 - db/migrate/00001_enable_extensions.rb
 - db/migrate/00002_create_robots.rb
@@ -299,11 +299,6 @@ files:
 - db/migrate/00005_create_tags.rb
 - db/migrate/00006_create_node_tags.rb
 - db/migrate/00007_create_robot_nodes.rb
-- db/migrate/00009_add_working_memory_to_robot_nodes.rb
-- db/migrate/00010_add_soft_delete_to_associations.rb
-- db/migrate/00011_add_performance_indexes.rb
-- db/migrate/00012_add_tags_trigram_index.rb
-- db/migrate/00013_enable_lz4_compression.rb
 - db/schema.sql
 - db/seed_data/README.md
 - db/seed_data/presidents.md
@@ -331,17 +326,26 @@ files:
 - docs/api/yard/HTM/LongTermMemory.md
 - docs/api/yard/HTM/NotFoundError.md
 - docs/api/yard/HTM/Observability.md
+- docs/api/yard/HTM/PropositionError.md
+- docs/api/yard/HTM/PropositionService.md
+- docs/api/yard/HTM/QueryCache.md
 - docs/api/yard/HTM/QueryTimeoutError.md
 - docs/api/yard/HTM/Railtie.md
 - docs/api/yard/HTM/ResourceExhaustedError.md
+- docs/api/yard/HTM/RobotGroup.md
+- docs/api/yard/HTM/SqlBuilder.md
 - docs/api/yard/HTM/TagError.md
 - docs/api/yard/HTM/TagService.md
+- docs/api/yard/HTM/Telemetry.md
+- docs/api/yard/HTM/Telemetry/NullInstrument.md
+- docs/api/yard/HTM/Telemetry/NullMeter.md
 - docs/api/yard/HTM/Timeframe.md
 - docs/api/yard/HTM/Timeframe/Result.md
 - docs/api/yard/HTM/TimeframeExtractor.md
 - docs/api/yard/HTM/TimeframeExtractor/Result.md
 - docs/api/yard/HTM/ValidationError.md
 - docs/api/yard/HTM/WorkingMemory.md
+- docs/api/yard/HTM/WorkingMemoryChannel.md
 - docs/api/yard/index.csv
 - docs/architecture/adrs/001-postgresql-timescaledb.md
 - docs/architecture/adrs/002-two-tier-memory.md
@@ -381,7 +385,9 @@ files:
 - docs/assets/images/htm-working-memory-architecture.svg
 - docs/assets/images/htm.jpg
 - docs/assets/images/htm_demo.gif
+- docs/assets/images/multi-provider-failover.svg
 - docs/assets/images/project-structure.svg
+- docs/assets/images/robot-group-architecture.svg
 - docs/assets/images/test-directory-structure.svg
 - docs/assets/js/mathjax.js
 - docs/assets/videos/htm_video.mp4
@@ -419,6 +425,7 @@ files:
 - docs/database_rake_tasks.md
 - docs/development/contributing.md
 - docs/development/index.md
+- docs/development/rake-tasks.md
 - docs/development/schema.md
 - docs/development/setup.md
 - docs/development/testing.md
@@ -430,8 +437,10 @@ files:
 - docs/guides/getting-started.md
 - docs/guides/index.md
 - docs/guides/long-term-memory.md
+- docs/guides/mcp-server.md
 - docs/guides/multi-robot.md
 - docs/guides/recalling-memories.md
+- docs/guides/robot-groups.md
 - docs/guides/search-strategies.md
 - docs/guides/working-memory.md
 - docs/images/htm-er-diagram.svg
@@ -450,8 +459,56 @@ files:
 - examples/example_app/app.rb
 - examples/file_loader_usage.rb
 - examples/mcp_client.rb
-- examples/robot_groups/lib/robot_group.rb
-- examples/robot_groups/lib/working_memory_channel.rb
+- examples/rails_app/.gitignore
+- examples/rails_app/Gemfile
+- examples/rails_app/Gemfile.lock
+- examples/rails_app/Procfile.dev
+- examples/rails_app/README.md
+- examples/rails_app/Rakefile
+- examples/rails_app/app/assets/stylesheets/application.css
+- examples/rails_app/app/assets/stylesheets/inter-font.css
+- examples/rails_app/app/controllers/application_controller.rb
+- examples/rails_app/app/controllers/dashboard_controller.rb
+- examples/rails_app/app/controllers/files_controller.rb
+- examples/rails_app/app/controllers/memories_controller.rb
+- examples/rails_app/app/controllers/robots_controller.rb
+- examples/rails_app/app/controllers/search_controller.rb
+- examples/rails_app/app/controllers/tags_controller.rb
+- examples/rails_app/app/javascript/application.js
+- examples/rails_app/app/javascript/controllers/application.js
+- examples/rails_app/app/javascript/controllers/index.js
+- examples/rails_app/app/views/dashboard/index.html.erb
+- examples/rails_app/app/views/files/index.html.erb
+- examples/rails_app/app/views/files/new.html.erb
+- examples/rails_app/app/views/files/show.html.erb
+- examples/rails_app/app/views/layouts/application.html.erb
+- examples/rails_app/app/views/memories/_memory_card.html.erb
+- examples/rails_app/app/views/memories/deleted.html.erb
+- examples/rails_app/app/views/memories/edit.html.erb
+- examples/rails_app/app/views/memories/index.html.erb
+- examples/rails_app/app/views/memories/new.html.erb
+- examples/rails_app/app/views/memories/show.html.erb
+- examples/rails_app/app/views/robots/index.html.erb
+- examples/rails_app/app/views/robots/new.html.erb
+- examples/rails_app/app/views/robots/show.html.erb
+- examples/rails_app/app/views/search/index.html.erb
+- examples/rails_app/app/views/shared/_navbar.html.erb
+- examples/rails_app/app/views/shared/_stat_card.html.erb
+- examples/rails_app/app/views/tags/index.html.erb
+- examples/rails_app/app/views/tags/show.html.erb
+- examples/rails_app/bin/dev
+- examples/rails_app/bin/rails
+- examples/rails_app/bin/rake
+- examples/rails_app/config.ru
+- examples/rails_app/config/application.rb
+- examples/rails_app/config/boot.rb
+- examples/rails_app/config/database.yml
+- examples/rails_app/config/environment.rb
+- examples/rails_app/config/importmap.rb
+- examples/rails_app/config/routes.rb
+- examples/rails_app/config/tailwind.config.js
+- examples/rails_app/log/.keep
+- examples/rails_app/tmp/local_secret.txt
 - examples/robot_groups/multi_process.rb
 - examples/robot_groups/robot_worker.rb
 - examples/robot_groups/same_process.rb
@@ -485,6 +542,11 @@ files:
 - lib/htm/long_term_memory/robot_operations.rb
 - lib/htm/long_term_memory/tag_operations.rb
 - lib/htm/long_term_memory/vector_search.rb
+- lib/htm/mcp/cli.rb
+- lib/htm/mcp/group_tools.rb
+- lib/htm/mcp/resources.rb
+- lib/htm/mcp/server.rb
+- lib/htm/mcp/tools.rb
 - lib/htm/models/file_source.rb
 - lib/htm/models/node.rb
 - lib/htm/models/node_tag.rb
@@ -495,6 +557,7 @@ files:
 - lib/htm/proposition_service.rb
 - lib/htm/query_cache.rb
 - lib/htm/railtie.rb
+- lib/htm/robot_group.rb
 - lib/htm/sql_builder.rb
 - lib/htm/tag_service.rb
 - lib/htm/tasks.rb
@@ -503,6 +566,7 @@ files:
 - lib/htm/timeframe_extractor.rb
 - lib/htm/version.rb
 - lib/htm/working_memory.rb
+- lib/htm/working_memory_channel.rb
 - lib/tasks/db.rake
 - lib/tasks/doc.rake
 - lib/tasks/files.rake
@@ -532,7 +596,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.0.dev
+rubygems_version: 4.0.1
 specification_version: 4
 summary: Hierarchical Temporal Memory for LLM robots
 test_files: []