htm 0.0.11 → 0.0.15

data/docs/api/yard/HTM/Telemetry.md

@@ -0,0 +1,109 @@
+# Module: HTM::Telemetry
+    
+
+OpenTelemetry-based observability for HTM
+
+Provides opt-in metrics collection with zero overhead when disabled. Uses the
+null object pattern - when telemetry is disabled or the SDK is not available,
+all metric operations are no-ops.
+
+**`@see`** [] for full implementation details
+
+
+**`@example`**
+```ruby
+HTM.configure do |config|
+  config.telemetry_enabled = true
+end
+```
+**`@example`**
+```ruby
+# Export to OTLP endpoint
+ENV['OTEL_METRICS_EXPORTER'] = 'otlp'
+ENV['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'
+```
+# Class Methods
+## cache_operations() {: #method-c-cache_operations }
+Counter for cache operations (hits, misses)
+**`@return`** [OpenTelemetry::Metrics::Counter, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.cache_operations.add(1, attributes: { 'operation' => 'hit' })
+```
+## embedding_latency() {: #method-c-embedding_latency }
+Histogram for embedding generation latency
+**`@return`** [OpenTelemetry::Metrics::Histogram, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.embedding_latency.record(145, attributes: { 'provider' => 'ollama', 'status' => 'success' })
+```
+## enabled?() {: #method-c-enabled? }
+Check if telemetry is enabled and SDK is available
+**`@return`** [Boolean] true if telemetry should be active
+
+## job_counter() {: #method-c-job_counter }
+Counter for job execution (enqueued, completed, failed)
+**`@return`** [OpenTelemetry::Metrics::Counter, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.job_counter.add(1, attributes: { 'job' => 'embedding', 'status' => 'success' })
+```
+## measure(histogram , attributes {}) {: #method-c-measure }
+Measure execution time of a block and record to a histogram
+**`@param`** [OpenTelemetry::Metrics::Histogram, NullInstrument] The histogram to record to
+
+**`@param`** [Hash] Attributes to attach to the measurement
+
+**`@return`** [Object] The result of the block
+
+**`@yield`** [] The block to measure
+
+
+**`@example`**
+```ruby
+result = Telemetry.measure(Telemetry.embedding_latency, 'provider' => 'ollama') do
+  generate_embedding(text)
+end
+```
+## meter() {: #method-c-meter }
+Get the meter for creating instruments
+**`@return`** [OpenTelemetry::Metrics::Meter, NullMeter] Real or null meter
+
+## reset!() {: #method-c-reset! }
+Reset telemetry state (for testing)
+**`@return`** [void] 
+
+## sdk_available?() {: #method-c-sdk_available? }
+Check if OpenTelemetry SDK is installed
+**`@return`** [Boolean] true if SDK can be loaded
+
+## search_latency() {: #method-c-search_latency }
+Histogram for search operation latency
+**`@return`** [OpenTelemetry::Metrics::Histogram, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.search_latency.record(50, attributes: { 'strategy' => 'vector' })
+```
+## setup() {: #method-c-setup }
+Initialize OpenTelemetry SDK
+
+Called automatically when telemetry is enabled. Safe to call multiple times.
+**`@return`** [void] 
+
+## tag_latency() {: #method-c-tag_latency }
+Histogram for tag extraction latency
+**`@return`** [OpenTelemetry::Metrics::Histogram, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.tag_latency.record(250, attributes: { 'provider' => 'ollama', 'status' => 'success' })
+```

data/docs/api/yard/HTM/WorkingMemoryChannel.md

@@ -0,0 +1,176 @@
+# Class: HTM::WorkingMemoryChannel
+**Inherits:** Object
+    
+
+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.
+
+**`@see`** [] Higher-level coordination using this channel
+
+
+**`@example`**
+```ruby
+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
+```
+# Attributes
+## notifications_received[RW] {: #attribute-i-notifications_received }
+Number of notifications received since channel was created
+
+**`@return`** [Integer] 
+
+
+# Instance Methods
+## channel_name() {: #method-i-channel_name }
+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`**
+```ruby
+channel = HTM::WorkingMemoryChannel.new('my-group', db_config)
+channel.channel_name  # => "htm_wm_my_group"
+```
+## initialize(group_name, db_config) {: #method-i-initialize }
+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.
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@param`** [String] Name of the robot group (used to create unique channel)
+
+**`@param`** [Hash] PostgreSQL connection configuration hash
+
+**`@return`** [WorkingMemoryChannel] a new instance of WorkingMemoryChannel
+
+
+**`@example`**
+```ruby
+db_config = { host: 'localhost', port: 5432, dbname: 'htm_dev', user: 'postgres' }
+channel = HTM::WorkingMemoryChannel.new('customer-support', db_config)
+```
+## listening?() {: #method-i-listening? }
+Checks if the listener thread is currently active.
+
+**`@return`** [Boolean] true if listening for notifications, false otherwise
+
+
+**`@example`**
+```ruby
+channel.start_listening
+channel.listening?  # => true
+channel.stop_listening
+channel.listening?  # => false
+```
+## notify(event, node_id:, robot_id:) {: #method-i-notify }
+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`** [Symbol] Type of change (:added, :evicted, or :cleared)
+
+**`@param`** [Integer, nil] ID of the affected node (nil for :cleared events)
+
+**`@param`** [Integer] ID of the robot that triggered the change
+
+**`@return`** [void] 
+
+
+**`@example`**
+```ruby
+channel.notify(:added, node_id: 123, robot_id: 1)
+```
+**`@example`**
+```ruby
+channel.notify(:cleared, node_id: nil, robot_id: 1)
+```
+## on_change(&callback) {: #method-i-on_change }
+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.
+
+**`@return`** [void] 
+
+**`@yield`** [event, node_id, robot_id] Block called for each notification
+
+**`@yieldparam`** [Symbol] Type of change (:added, :evicted, or :cleared)
+
+**`@yieldparam`** [Integer, nil] ID of the affected node
+
+**`@yieldparam`** [Integer] ID of the robot that triggered the change
+
+
+**`@example`**
+```ruby
+channel.on_change do |event, node_id, robot_id|
+  puts "Received #{event} event for node #{node_id}"
+end
+```
+## start_listening() {: #method-i-start_listening }
+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`**
+```ruby
+thread = channel.start_listening
+puts "Listening: #{channel.listening?}"  # => true
+```
+## stop_listening() {: #method-i-stop_listening }
+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`**
+```ruby
+channel.stop_listening
+puts "Listening: #{channel.listening?}"  # => false
+```

data/docs/api/yard/HTM.md

@@ -2,30 +2,10 @@
 **Inherits:** Object
     
 
-HTM (Hierarchical Temporary Memory) error classes
+examples/robot_groups/lib/htm/working_memory_channel.rb frozen_string_literal:
+true
 
-All HTM errors inherit from HTM::Error, allowing you to catch all HTM-related
-errors with a single rescue clause.
 
-
-**`@example`**
-```ruby
-begin
-  htm.remember("some content")
-rescue HTM::Error => e
-  logger.error "HTM error: #{e.message}"
-end
-```
-**`@example`**
-```ruby
-begin
-  htm.forget(node_id, soft: false)
-rescue HTM::NotFoundError
-  puts "Node not found"
-rescue HTM::ValidationError
-  puts "Invalid input"
-end
-```
 # Class Methods
 ## configure() {: #method-c-configure }
 Configure HTM
@@ -57,6 +37,12 @@ Generate embedding using EmbeddingService
 
 **`@return`** [Array<Float>] Embedding vector (original, not padded)
 
+## extract_propositions(text ) {: #method-c-extract_propositions }
+Extract propositions using PropositionService
+**`@param`** [String] Text to analyze
+
+**`@return`** [Array<String>] Extracted atomic propositions
+
 ## extract_tags(text , existing_ontology: []) {: #method-c-extract_tags }
 Extract tags using TagService
 **`@param`** [String] Text to analyze

data/docs/api/yard/index.csv

@@ -15,10 +15,23 @@ HTM::Observability.record_query_timing,Method,HTM/Observability.md#method-c-reco
 HTM::Observability.record_tag_timing,Method,HTM/Observability.md#method-c-record_tag_timing
 HTM::Observability.reset_metrics!,Method,HTM/Observability.md#method-c-reset_metrics!
 HTM::Observability.service_timing_stats,Method,HTM/Observability.md#method-c-service_timing_stats
+HTM::Telemetry,Module,HTM/Telemetry.md
+HTM::Telemetry.cache_operations,Method,HTM/Telemetry.md#method-c-cache_operations
+HTM::Telemetry.embedding_latency,Method,HTM/Telemetry.md#method-c-embedding_latency
+HTM::Telemetry.enabled?,Method,HTM/Telemetry.md#method-c-enabled?
+HTM::Telemetry.job_counter,Method,HTM/Telemetry.md#method-c-job_counter
+HTM::Telemetry.measure,Method,HTM/Telemetry.md#method-c-measure
+HTM::Telemetry.meter,Method,HTM/Telemetry.md#method-c-meter
+HTM::Telemetry.reset!,Method,HTM/Telemetry.md#method-c-reset!
+HTM::Telemetry.sdk_available?,Method,HTM/Telemetry.md#method-c-sdk_available?
+HTM::Telemetry.search_latency,Method,HTM/Telemetry.md#method-c-search_latency
+HTM::Telemetry.setup,Method,HTM/Telemetry.md#method-c-setup
+HTM::Telemetry.tag_latency,Method,HTM/Telemetry.md#method-c-tag_latency
 HTM,Class,HTM.md
 HTM.configure,Method,HTM.md#method-c-configure
 HTM.count_tokens,Method,HTM.md#method-c-count_tokens
 HTM.embed,Method,HTM.md#method-c-embed
+HTM.extract_propositions,Method,HTM.md#method-c-extract_propositions
 HTM.extract_tags,Method,HTM.md#method-c-extract_tags
 HTM.logger,Method,HTM.md#method-c-logger
 HTM.reset_configuration!,Method,HTM.md#method-c-reset_configuration!
@@ -55,6 +68,11 @@ azure_endpoint,Attribute,HTM/Configuration.md#attribute-i-azure_endpoint
 bedrock_access_key,Attribute,HTM/Configuration.md#attribute-i-bedrock_access_key
 bedrock_region,Attribute,HTM/Configuration.md#attribute-i-bedrock_region
 bedrock_secret_key,Attribute,HTM/Configuration.md#attribute-i-bedrock_secret_key
+chunk_overlap,Attribute,HTM/Configuration.md#attribute-i-chunk_overlap
+chunk_size,Attribute,HTM/Configuration.md#attribute-i-chunk_size
+circuit_breaker_failure_threshold,Attribute,HTM/Configuration.md#attribute-i-circuit_breaker_failure_threshold
+circuit_breaker_half_open_max_calls,Attribute,HTM/Configuration.md#attribute-i-circuit_breaker_half_open_max_calls
+circuit_breaker_reset_timeout,Attribute,HTM/Configuration.md#attribute-i-circuit_breaker_reset_timeout
 connection_timeout,Attribute,HTM/Configuration.md#attribute-i-connection_timeout
 deepseek_api_key,Attribute,HTM/Configuration.md#attribute-i-deepseek_api_key
 embedding_dimensions,Attribute,HTM/Configuration.md#attribute-i-embedding_dimensions
@@ -62,19 +80,32 @@ embedding_generator,Attribute,HTM/Configuration.md#attribute-i-embedding_generat
 embedding_model,Attribute,HTM/Configuration.md#attribute-i-embedding_model
 embedding_provider,Attribute,HTM/Configuration.md#attribute-i-embedding_provider
 embedding_timeout,Attribute,HTM/Configuration.md#attribute-i-embedding_timeout
+extract_propositions,Attribute,HTM/Configuration.md#attribute-i-extract_propositions
 gemini_api_key,Attribute,HTM/Configuration.md#attribute-i-gemini_api_key
 huggingface_api_key,Attribute,HTM/Configuration.md#attribute-i-huggingface_api_key
 job_backend,Attribute,HTM/Configuration.md#attribute-i-job_backend
 logger,Attribute,HTM/Configuration.md#attribute-i-logger
+max_embedding_dimension,Attribute,HTM/Configuration.md#attribute-i-max_embedding_dimension
+max_tag_depth,Attribute,HTM/Configuration.md#attribute-i-max_tag_depth
 ollama_url,Attribute,HTM/Configuration.md#attribute-i-ollama_url
 openai_api_key,Attribute,HTM/Configuration.md#attribute-i-openai_api_key
 openai_organization,Attribute,HTM/Configuration.md#attribute-i-openai_organization
 openai_project,Attribute,HTM/Configuration.md#attribute-i-openai_project
 openrouter_api_key,Attribute,HTM/Configuration.md#attribute-i-openrouter_api_key
+proposition_extractor,Attribute,HTM/Configuration.md#attribute-i-proposition_extractor
+proposition_model,Attribute,HTM/Configuration.md#attribute-i-proposition_model
+proposition_provider,Attribute,HTM/Configuration.md#attribute-i-proposition_provider
+proposition_timeout,Attribute,HTM/Configuration.md#attribute-i-proposition_timeout
+relevance_access_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_access_weight
+relevance_recency_half_life_hours,Attribute,HTM/Configuration.md#attribute-i-relevance_recency_half_life_hours
+relevance_recency_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_recency_weight
+relevance_semantic_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_semantic_weight
+relevance_tag_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_tag_weight
 tag_extractor,Attribute,HTM/Configuration.md#attribute-i-tag_extractor
 tag_model,Attribute,HTM/Configuration.md#attribute-i-tag_model
 tag_provider,Attribute,HTM/Configuration.md#attribute-i-tag_provider
 tag_timeout,Attribute,HTM/Configuration.md#attribute-i-tag_timeout
+telemetry_enabled,Attribute,HTM/Configuration.md#attribute-i-telemetry_enabled
 token_counter,Attribute,HTM/Configuration.md#attribute-i-token_counter
 week_start,Attribute,HTM/Configuration.md#attribute-i-week_start
 HTM::Database,Class,HTM/Database.md
@@ -94,6 +125,7 @@ HTM::EmbeddingService,Class,HTM/EmbeddingService.md
 HTM::EmbeddingService.circuit_breaker,Method,HTM/EmbeddingService.md#method-c-circuit_breaker
 HTM::EmbeddingService.format_for_storage,Method,HTM/EmbeddingService.md#method-c-format_for_storage
 HTM::EmbeddingService.generate,Method,HTM/EmbeddingService.md#method-c-generate
+HTM::EmbeddingService.max_dimension,Method,HTM/EmbeddingService.md#method-c-max_dimension
 HTM::EmbeddingService.pad_embedding,Method,HTM/EmbeddingService.md#method-c-pad_embedding
 HTM::EmbeddingService.reset_circuit_breaker!,Method,HTM/EmbeddingService.md#method-c-reset_circuit_breaker!
 HTM::EmbeddingService.validate_embedding!,Method,HTM/EmbeddingService.md#method-c-validate_embedding!
@@ -103,51 +135,87 @@ HTM::ResourceExhaustedError,Class,HTM/ResourceExhaustedError.md
 HTM::NotFoundError,Class,HTM/NotFoundError.md
 HTM::EmbeddingError,Class,HTM/EmbeddingError.md
 HTM::TagError,Class,HTM/TagError.md
+HTM::PropositionError,Class,HTM/PropositionError.md
 HTM::DatabaseError,Class,HTM/DatabaseError.md
 HTM::QueryTimeoutError,Class,HTM/QueryTimeoutError.md
 HTM::AuthorizationError,Class,HTM/AuthorizationError.md
 HTM::CircuitBreakerOpenError,Class,HTM/CircuitBreakerOpenError.md
 HTM::LongTermMemory,Class,HTM/LongTermMemory.md
-HTM::LongTermMemory.add,Method,HTM/LongTermMemory.md#method-i-add
-HTM::LongTermMemory.add_tag,Method,HTM/LongTermMemory.md#method-i-add_tag
-HTM::LongTermMemory.batch_load_node_tags,Method,HTM/LongTermMemory.md#method-i-batch_load_node_tags
-HTM::LongTermMemory.calculate_relevance,Method,HTM/LongTermMemory.md#method-i-calculate_relevance
 HTM::LongTermMemory.clear_cache!,Method,HTM/LongTermMemory.md#method-i-clear_cache!
-HTM::LongTermMemory.delete,Method,HTM/LongTermMemory.md#method-i-delete
-HTM::LongTermMemory.exists?,Method,HTM/LongTermMemory.md#method-i-exists?
-HTM::LongTermMemory.find_query_matching_tags,Method,HTM/LongTermMemory.md#method-i-find_query_matching_tags
-HTM::LongTermMemory.get_node_tags,Method,HTM/LongTermMemory.md#method-i-get_node_tags
 HTM::LongTermMemory.initialize,Method,HTM/LongTermMemory.md#method-i-initialize
-HTM::LongTermMemory.link_robot_to_node,Method,HTM/LongTermMemory.md#method-i-link_robot_to_node
-HTM::LongTermMemory.mark_evicted,Method,HTM/LongTermMemory.md#method-i-mark_evicted
-HTM::LongTermMemory.node_topics,Method,HTM/LongTermMemory.md#method-i-node_topics
-HTM::LongTermMemory.nodes_by_topic,Method,HTM/LongTermMemory.md#method-i-nodes_by_topic
-HTM::LongTermMemory.ontology_structure,Method,HTM/LongTermMemory.md#method-i-ontology_structure
 HTM::LongTermMemory.pool_size,Method,HTM/LongTermMemory.md#method-i-pool_size
-HTM::LongTermMemory.popular_tags,Method,HTM/LongTermMemory.md#method-i-popular_tags
-HTM::LongTermMemory.register_robot,Method,HTM/LongTermMemory.md#method-i-register_robot
-HTM::LongTermMemory.retrieve,Method,HTM/LongTermMemory.md#method-i-retrieve
-HTM::LongTermMemory.search,Method,HTM/LongTermMemory.md#method-i-search
-HTM::LongTermMemory.search_by_tags,Method,HTM/LongTermMemory.md#method-i-search_by_tags
-HTM::LongTermMemory.search_fulltext,Method,HTM/LongTermMemory.md#method-i-search_fulltext
-HTM::LongTermMemory.search_hybrid,Method,HTM/LongTermMemory.md#method-i-search_hybrid
-HTM::LongTermMemory.search_with_relevance,Method,HTM/LongTermMemory.md#method-i-search_with_relevance
 HTM::LongTermMemory.shutdown,Method,HTM/LongTermMemory.md#method-i-shutdown
 HTM::LongTermMemory.stats,Method,HTM/LongTermMemory.md#method-i-stats
-HTM::LongTermMemory.topic_relationships,Method,HTM/LongTermMemory.md#method-i-topic_relationships
-HTM::LongTermMemory.track_access,Method,HTM/LongTermMemory.md#method-i-track_access
-HTM::LongTermMemory.update_last_accessed,Method,HTM/LongTermMemory.md#method-i-update_last_accessed
-HTM::LongTermMemory.update_robot_activity,Method,HTM/LongTermMemory.md#method-i-update_robot_activity
 query_timeout,Attribute,HTM/LongTermMemory.md#attribute-i-query_timeout
+HTM::PropositionService,Class,HTM/PropositionService.md
+HTM::PropositionService.circuit_breaker,Method,HTM/PropositionService.md#method-c-circuit_breaker
+HTM::PropositionService.extract,Method,HTM/PropositionService.md#method-c-extract
+HTM::PropositionService.parse_propositions,Method,HTM/PropositionService.md#method-c-parse_propositions
+HTM::PropositionService.reset_circuit_breaker!,Method,HTM/PropositionService.md#method-c-reset_circuit_breaker!
+HTM::PropositionService.valid_proposition?,Method,HTM/PropositionService.md#method-c-valid_proposition?
+HTM::PropositionService.validate_and_filter_propositions,Method,HTM/PropositionService.md#method-c-validate_and_filter_propositions
+HTM::QueryCache,Class,HTM/QueryCache.md
+HTM::QueryCache.clear!,Method,HTM/QueryCache.md#method-i-clear!
+HTM::QueryCache.enabled?,Method,HTM/QueryCache.md#method-i-enabled?
+HTM::QueryCache.fetch,Method,HTM/QueryCache.md#method-i-fetch
+HTM::QueryCache.initialize,Method,HTM/QueryCache.md#method-i-initialize
+HTM::QueryCache.invalidate!,Method,HTM/QueryCache.md#method-i-invalidate!
+HTM::QueryCache.invalidate_methods!,Method,HTM/QueryCache.md#method-i-invalidate_methods!
+HTM::QueryCache.stats,Method,HTM/QueryCache.md#method-i-stats
+enabled,Attribute,HTM/QueryCache.md#attribute-i-enabled
 HTM::Railtie,Class,HTM/Railtie.md
+HTM::RobotGroup,Class,HTM/RobotGroup.md
+HTM::RobotGroup.active?,Method,HTM/RobotGroup.md#method-i-active?
+HTM::RobotGroup.active_robot_names,Method,HTM/RobotGroup.md#method-i-active_robot_names
+HTM::RobotGroup.add_active,Method,HTM/RobotGroup.md#method-i-add_active
+HTM::RobotGroup.add_passive,Method,HTM/RobotGroup.md#method-i-add_passive
+HTM::RobotGroup.clear_working_memory,Method,HTM/RobotGroup.md#method-i-clear_working_memory
+HTM::RobotGroup.demote,Method,HTM/RobotGroup.md#method-i-demote
+HTM::RobotGroup.failover!,Method,HTM/RobotGroup.md#method-i-failover!
+HTM::RobotGroup.in_sync?,Method,HTM/RobotGroup.md#method-i-in_sync?
+HTM::RobotGroup.initialize,Method,HTM/RobotGroup.md#method-i-initialize
+HTM::RobotGroup.member?,Method,HTM/RobotGroup.md#method-i-member?
+HTM::RobotGroup.member_ids,Method,HTM/RobotGroup.md#method-i-member_ids
+HTM::RobotGroup.passive?,Method,HTM/RobotGroup.md#method-i-passive?
+HTM::RobotGroup.passive_robot_names,Method,HTM/RobotGroup.md#method-i-passive_robot_names
+HTM::RobotGroup.promote,Method,HTM/RobotGroup.md#method-i-promote
+HTM::RobotGroup.recall,Method,HTM/RobotGroup.md#method-i-recall
+HTM::RobotGroup.remember,Method,HTM/RobotGroup.md#method-i-remember
+HTM::RobotGroup.remove,Method,HTM/RobotGroup.md#method-i-remove
+HTM::RobotGroup.shutdown,Method,HTM/RobotGroup.md#method-i-shutdown
+HTM::RobotGroup.status,Method,HTM/RobotGroup.md#method-i-status
+HTM::RobotGroup.sync_all,Method,HTM/RobotGroup.md#method-i-sync_all
+HTM::RobotGroup.sync_robot,Method,HTM/RobotGroup.md#method-i-sync_robot
+HTM::RobotGroup.sync_stats,Method,HTM/RobotGroup.md#method-i-sync_stats
+HTM::RobotGroup.transfer_working_memory,Method,HTM/RobotGroup.md#method-i-transfer_working_memory
+HTM::RobotGroup.working_memory_contents,Method,HTM/RobotGroup.md#method-i-working_memory_contents
+channel,Attribute,HTM/RobotGroup.md#attribute-i-channel
+max_tokens,Attribute,HTM/RobotGroup.md#attribute-i-max_tokens
+name,Attribute,HTM/RobotGroup.md#attribute-i-name
+HTM::SqlBuilder,Class,HTM/SqlBuilder.md
+HTM::SqlBuilder.apply_metadata,Method,HTM/SqlBuilder.md#method-c-apply_metadata
+HTM::SqlBuilder.apply_timeframe,Method,HTM/SqlBuilder.md#method-c-apply_timeframe
+HTM::SqlBuilder.metadata_condition,Method,HTM/SqlBuilder.md#method-c-metadata_condition
+HTM::SqlBuilder.pad_embedding,Method,HTM/SqlBuilder.md#method-c-pad_embedding
+HTM::SqlBuilder.sanitize_embedding,Method,HTM/SqlBuilder.md#method-c-sanitize_embedding
+HTM::SqlBuilder.sanitize_like_pattern,Method,HTM/SqlBuilder.md#method-c-sanitize_like_pattern
+HTM::SqlBuilder.timeframe_condition,Method,HTM/SqlBuilder.md#method-c-timeframe_condition
 HTM::TagService,Class,HTM/TagService.md
 HTM::TagService.circuit_breaker,Method,HTM/TagService.md#method-c-circuit_breaker
 HTM::TagService.extract,Method,HTM/TagService.md#method-c-extract
+HTM::TagService.max_depth,Method,HTM/TagService.md#method-c-max_depth
 HTM::TagService.parse_hierarchy,Method,HTM/TagService.md#method-c-parse_hierarchy
 HTM::TagService.parse_tags,Method,HTM/TagService.md#method-c-parse_tags
 HTM::TagService.reset_circuit_breaker!,Method,HTM/TagService.md#method-c-reset_circuit_breaker!
 HTM::TagService.valid_tag?,Method,HTM/TagService.md#method-c-valid_tag?
 HTM::TagService.validate_and_filter_tags,Method,HTM/TagService.md#method-c-validate_and_filter_tags
+HTM::Telemetry::NullMeter,Class,HTM/Telemetry/NullMeter.md
+HTM::Telemetry::NullMeter.create_counter,Method,HTM/Telemetry/NullMeter.md#method-i-create_counter
+HTM::Telemetry::NullMeter.create_histogram,Method,HTM/Telemetry/NullMeter.md#method-i-create_histogram
+HTM::Telemetry::NullMeter.create_up_down_counter,Method,HTM/Telemetry/NullMeter.md#method-i-create_up_down_counter
+HTM::Telemetry::NullInstrument,Class,HTM/Telemetry/NullInstrument.md
+HTM::Telemetry::NullInstrument.add,Method,HTM/Telemetry/NullInstrument.md#method-i-add
+HTM::Telemetry::NullInstrument.record,Method,HTM/Telemetry/NullInstrument.md#method-i-record
 HTM::TimeframeExtractor,Class,HTM/TimeframeExtractor.md
 HTM::TimeframeExtractor.extract,Method,HTM/TimeframeExtractor.md#method-c-extract
 HTM::TimeframeExtractor.temporal?,Method,HTM/TimeframeExtractor.md#method-c-temporal?
@@ -162,6 +230,15 @@ HTM::Timeframe::Result,Class,HTM/Timeframe/Result.md
 extracted,Attribute,HTM/Timeframe/Result.md#attribute-i-extracted
 query,Attribute,HTM/Timeframe/Result.md#attribute-i-query
 timeframe,Attribute,HTM/Timeframe/Result.md#attribute-i-timeframe
+HTM::WorkingMemoryChannel,Class,HTM/WorkingMemoryChannel.md
+HTM::WorkingMemoryChannel.channel_name,Method,HTM/WorkingMemoryChannel.md#method-i-channel_name
+HTM::WorkingMemoryChannel.initialize,Method,HTM/WorkingMemoryChannel.md#method-i-initialize
+HTM::WorkingMemoryChannel.listening?,Method,HTM/WorkingMemoryChannel.md#method-i-listening?
+HTM::WorkingMemoryChannel.notify,Method,HTM/WorkingMemoryChannel.md#method-i-notify
+HTM::WorkingMemoryChannel.on_change,Method,HTM/WorkingMemoryChannel.md#method-i-on_change
+HTM::WorkingMemoryChannel.start_listening,Method,HTM/WorkingMemoryChannel.md#method-i-start_listening
+HTM::WorkingMemoryChannel.stop_listening,Method,HTM/WorkingMemoryChannel.md#method-i-stop_listening
+notifications_received,Attribute,HTM/WorkingMemoryChannel.md#attribute-i-notifications_received
 HTM::WorkingMemory,Class,HTM/WorkingMemory.md
 HTM::WorkingMemory.add,Method,HTM/WorkingMemory.md#method-i-add
 HTM::WorkingMemory.add_from_sync,Method,HTM/WorkingMemory.md#method-i-add_from_sync

data/docs/api/yard-reference.md

@@ -30,12 +30,20 @@ Complete API documentation generated by [YARD](https://yardoc.org/) with [yard-m
 | [HTM::JobAdapter](yard/HTM/JobAdapter.md) | Background job abstraction layer |
 | [HTM::LongTermMemory](yard/HTM/LongTermMemory.md) | PostgreSQL-backed permanent storage |
 | [HTM::Observability](yard/HTM/Observability.md) | Metrics and logging instrumentation |
+| [HTM::PropositionService](yard/HTM/PropositionService.md) | HTM::PropositionService class |
+| [HTM::QueryCache](yard/HTM/QueryCache.md) | HTM::QueryCache class |
+| [HTM::RobotGroup](yard/HTM/RobotGroup.md) | HTM::RobotGroup class |
+| [HTM::SqlBuilder](yard/HTM/SqlBuilder.md) | HTM::SqlBuilder class |
 | [HTM::TagService](yard/HTM/TagService.md) | Hierarchical tag extraction service |
+| [HTM::Telemetry](yard/HTM/Telemetry.md) | HTM::Telemetry class |
+| [HTM::Telemetry::NullInstrument](yard/HTM/Telemetry/NullInstrument.md) | HTM::Telemetry::NullInstrument class |
+| [HTM::Telemetry::NullMeter](yard/HTM/Telemetry/NullMeter.md) | HTM::Telemetry::NullMeter class |
 | [HTM::Timeframe](yard/HTM/Timeframe.md) | Time-based query filtering |
 | [HTM::Timeframe::Result](yard/HTM/Timeframe/Result.md) | HTM::Timeframe::Result class |
 | [HTM::TimeframeExtractor](yard/HTM/TimeframeExtractor.md) | Natural language time parsing |
 | [HTM::TimeframeExtractor::Result](yard/HTM/TimeframeExtractor/Result.md) | HTM::TimeframeExtractor::Result class |
 | [HTM::WorkingMemory](yard/HTM/WorkingMemory.md) | Token-limited in-memory cache |
+| [HTM::WorkingMemoryChannel](yard/HTM/WorkingMemoryChannel.md) | HTM::WorkingMemoryChannel class |
 
 ## Generating Documentation
 

data/docs/architecture/index.md

@@ -1,6 +1,6 @@
 # Architecture Overview
 
-HTM (Hierarchical Temporary Memory) implements a sophisticated two-tier memory system designed specifically for LLM-based applications ("robots"). This architecture enables robots to maintain long-term context across sessions while managing token budgets efficiently.
+HTM (Hierarchical Temporal Memory) implements a sophisticated two-tier memory system designed specifically for LLM-based applications ("robots"). This architecture enables robots to maintain long-term context across sessions while managing token budgets efficiently.
 
 ## System Overview
 

data/docs/assets/images/multi-provider-failover.svg

@@ -0,0 +1,51 @@
+<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Multi-Provider Failover Strategy</text>
+
+  <!-- Primary -->
+  <rect x="50" y="80" width="200" height="100" fill="rgba(76, 175, 80, 0.2)" stroke="#4CAF50" stroke-width="2" rx="5"/>
+  <text x="150" y="105" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">PRIMARY</text>
+  <text x="150" y="130" text-anchor="middle" fill="#E0E0E0" font-size="14">OpenAI GPT-4</text>
+  <text x="150" y="155" text-anchor="middle" fill="#B0B0B0" font-size="10">Fast, cost-effective</text>
+  <text x="150" y="170" text-anchor="middle" fill="#B0B0B0" font-size="10">JSON output format</text>
+
+  <!-- Standby 1 -->
+  <rect x="300" y="80" width="200" height="100" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="2" rx="5"/>
+  <text x="400" y="105" text-anchor="middle" fill="#FF9800" font-size="12" font-weight="bold">STANDBY 1</text>
+  <text x="400" y="130" text-anchor="middle" fill="#E0E0E0" font-size="14">Anthropic Claude</text>
+  <text x="400" y="155" text-anchor="middle" fill="#B0B0B0" font-size="10">Different provider</text>
+  <text x="400" y="170" text-anchor="middle" fill="#B0B0B0" font-size="10">XML output format</text>
+
+  <!-- Standby 2 -->
+  <rect x="550" y="80" width="200" height="100" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="2" rx="5"/>
+  <text x="650" y="105" text-anchor="middle" fill="#FF9800" font-size="12" font-weight="bold">STANDBY 2</text>
+  <text x="650" y="130" text-anchor="middle" fill="#E0E0E0" font-size="14">Google Gemini</text>
+  <text x="650" y="155" text-anchor="middle" fill="#B0B0B0" font-size="10">Third provider option</text>
+  <text x="650" y="170" text-anchor="middle" fill="#B0B0B0" font-size="10">Markdown output format</text>
+
+  <!-- Arrows -->
+  <path d="M 250 130 L 290 130" stroke="#4CAF50" stroke-width="2" marker-end="url(#arrow-fail)"/>
+  <path d="M 500 130 L 540 130" stroke="#FF9800" stroke-width="2" marker-end="url(#arrow-fail)"/>
+  <text x="270" y="120" fill="#F44336" font-size="10">failover</text>
+  <text x="520" y="120" fill="#F44336" font-size="10">failover</text>
+
+  <!-- Shared Context Box -->
+  <rect x="150" y="230" width="500" height="80" fill="rgba(33, 150, 243, 0.15)" stroke="#2196F3" stroke-width="2" rx="5"/>
+  <text x="400" y="260" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Shared Working Memory</text>
+  <text x="400" y="285" text-anchor="middle" fill="#2196F3" font-size="12">Same context across all providers</text>
+
+  <!-- Connections to shared -->
+  <line x1="150" y1="180" x2="200" y2="230" stroke="#4CAF50" stroke-width="1.5"/>
+  <line x1="400" y1="180" x2="400" y2="230" stroke="#FF9800" stroke-width="1.5"/>
+  <line x1="650" y1="180" x2="600" y2="230" stroke="#FF9800" stroke-width="1.5"/>
+
+  <!-- Key points -->
+  <text x="400" y="350" text-anchor="middle" fill="#4CAF50" font-size="12">Context is shared</text>
+  <text x="400" y="370" text-anchor="middle" fill="#F44336" font-size="12">Prompts are provider-specific</text>
+
+  <defs>
+    <marker id="arrow-fail" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#F44336"/>
+    </marker>
+  </defs>
+</svg>