htm 0.0.2 → 0.0.10

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

@@ -0,0 +1,67 @@
+# Class: HTM::TagService
+**Inherits:** Object
+    
+
+Tag Service - Processes and validates hierarchical tags
+
+This service wraps the configured tag extractor and provides:
+*   Response parsing (string or array)
+*   Format validation (lowercase, alphanumeric, hyphens, colons)
+*   Depth validation (max 5 levels)
+*   Ontology consistency
+*   Circuit breaker protection for external LLM failures
+
+The actual LLM call is delegated to HTM.configuration.tag_extractor
+
+
+# Class Methods
+## circuit_breaker() {: #method-c-circuit_breaker }
+Get or create the circuit breaker for tag service
+**`@return`** [HTM::CircuitBreaker] The circuit breaker instance
+
+## extract(content , existing_ontology: []) {: #method-c-extract }
+Extract tags with validation and processing
+**`@param`** [String] Text to analyze
+
+**`@param`** [Array<String>] Sample of existing tags for context
+
+**`@raise`** [CircuitBreakerOpenError] If circuit breaker is open
+
+**`@return`** [Array<String>] Validated tag names
+
+## parse_hierarchy(tag ) {: #method-c-parse_hierarchy }
+Parse hierarchical structure of a tag
+**`@param`** [String] Hierarchical tag (e.g., "ai:llm:embedding")
+
+**`@return`** [Hash] Hierarchy structure
+{
+  full: "ai:llm:embedding",
+  root: "ai",
+  parent: "ai:llm",
+  levels: ["ai", "llm", "embedding"],
+  depth: 3
+}
+
+## parse_tags(raw_tags ) {: #method-c-parse_tags }
+Parse tag response (handles string or array input)
+**`@param`** [String, Array] Raw response from extractor
+
+**`@return`** [Array<String>] Parsed tag strings
+
+## reset_circuit_breaker!() {: #method-c-reset_circuit_breaker! }
+Reset the circuit breaker (useful for testing)
+**`@return`** [void] 
+
+## valid_tag?(tag ) {: #method-c-valid_tag? }
+Validate single tag format
+**`@param`** [String] Tag to validate
+
+**`@return`** [Boolean] True if valid
+
+## validate_and_filter_tags(tags ) {: #method-c-validate_and_filter_tags }
+Validate and filter tags
+**`@param`** [Array<String>] Parsed tags
+
+**`@return`** [Array<String>] Valid tags only
+
+

data/docs/api/yard/HTM/Timeframe/Result.md

@@ -0,0 +1,24 @@
+# Class: HTM::Timeframe::Result
+**Inherits:** Struct
+    
+
+Result structure for :auto mode
+
+
+# Attributes
+## extracted[RW] {: #attribute-i-extracted }
+Returns the value of attribute extracted
+
+**`@return`** [Object] the current value of extracted
+
+## query[RW] {: #attribute-i-query }
+Returns the value of attribute query
+
+**`@return`** [Object] the current value of query
+
+## timeframe[RW] {: #attribute-i-timeframe }
+Returns the value of attribute timeframe
+
+**`@return`** [Object] the current value of timeframe
+
+

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

@@ -0,0 +1,40 @@
+# Class: HTM::Timeframe
+**Inherits:** Object
+    
+
+Timeframe - Normalizes various timeframe inputs for database queries
+
+Handles multiple input types and normalizes them to either:
+*   nil (no timeframe filter)
+*   Range (single time window)
+*   Array<Range> (multiple time windows, OR'd together)
+
+
+**`@example`**
+```ruby
+Timeframe.normalize(nil)                    # => nil (no filter)
+Timeframe.normalize(Date.today)             # => Range for entire day
+Timeframe.normalize(Time.now)               # => Range for entire day
+Timeframe.normalize("last week")            # => Range from chronic/extractor
+Timeframe.normalize(:auto, query: "...")    # => Extract from query text
+Timeframe.normalize(range1..range2)         # => Pass through
+Timeframe.normalize([range1, range2])       # => Array of ranges
+```
+# Class Methods
+## normalize(input , query: nil) {: #method-c-normalize }
+Normalize a timeframe input to nil, Range, or Array<Range>
+**`@param`** [nil, Range, Array, Date, DateTime, Time, String, Symbol] Timeframe specification
+
+**`@param`** [String, nil] Query text (required when input is :auto)
+
+**`@return`** [nil, Range, Array<Range>] Normalized timeframe
+
+**`@return`** [Result] When input is :auto, returns Result with :timeframe, :query, :extracted
+
+## valid?(input ) {: #method-c-valid? }
+Check if a value is a valid timeframe input
+**`@param`** [Object] Value to check
+
+**`@return`** [Boolean] 
+
+

data/docs/api/yard/HTM/TimeframeExtractor/Result.md

@@ -0,0 +1,24 @@
+# Class: HTM::TimeframeExtractor::Result
+**Inherits:** Struct
+    
+
+Result structure for extracted timeframe
+
+
+# Attributes
+## original_expression[RW] {: #attribute-i-original_expression }
+Returns the value of attribute original_expression
+
+**`@return`** [Object] the current value of original_expression
+
+## query[RW] {: #attribute-i-query }
+Returns the value of attribute query
+
+**`@return`** [Object] the current value of query
+
+## timeframe[RW] {: #attribute-i-timeframe }
+Returns the value of attribute timeframe
+
+**`@return`** [Object] the current value of timeframe
+
+

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

@@ -0,0 +1,45 @@
+# Class: HTM::TimeframeExtractor
+**Inherits:** Object
+    
+
+Timeframe Extractor - Extracts temporal expressions from queries
+
+This service parses natural language time expressions from recall queries and
+returns both the timeframe and the cleaned query text.
+
+Supports:
+*   Standard time expressions via Chronic gem ("yesterday", "last week", etc.)
+*   "few" keyword mapped to FEW constant (e.g., "few days ago" → "3 days ago")
+*   "recent/recently" without units defaults to FEW days
+
+
+**`@example`**
+```ruby
+result = TimeframeExtractor.extract("what did we discuss last week about PostgreSQL")
+result[:query]     # => "what did we discuss about PostgreSQL"
+result[:timeframe] # => #<Range: 2025-11-21..2025-11-28>
+```
+**`@example`**
+```ruby
+result = TimeframeExtractor.extract("show me notes from a few days ago")
+result[:timeframe] # => Time object for 3 days ago
+```
+**`@example`**
+```ruby
+result = TimeframeExtractor.extract("what did we recently discuss")
+result[:timeframe] # => Range from 3 days ago to now
+```
+# Class Methods
+## extract(query ) {: #method-c-extract }
+Extract timeframe from a query string
+**`@param`** [String] The query to parse
+
+**`@return`** [Result] Struct with :query (cleaned), :timeframe, :original_expression
+
+## temporal?(query ) {: #method-c-temporal? }
+Check if query contains a temporal expression
+**`@param`** [String] The query to check
+
+**`@return`** [Boolean] 
+
+

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

@@ -0,0 +1,20 @@
+# Exception: HTM::ValidationError
+**Inherits:** HTM::Error
+    
+
+Raised when input validation fails
+
+Common causes:
+*   Empty or nil content for remember()
+*   Content exceeding maximum size limit
+*   Invalid tag format
+*   Invalid recall strategy
+*   Invalid timeframe format
+
+
+**`@example`**
+```ruby
+htm.remember("")  # => raises ValidationError
+htm.remember("x", tags: ["INVALID!"])  # => raises ValidationError
+```
+

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

@@ -0,0 +1,131 @@
+# Class: HTM::WorkingMemory
+**Inherits:** Object
+    
+
+Working Memory - Token-limited active context for immediate LLM use
+
+WorkingMemory manages the active conversation context within token limits.
+When full, it evicts less important or older nodes back to long-term storage.
+
+Thread Safety: All public methods are protected by a mutex to ensure safe
+concurrent access from multiple threads.
+
+
+# Attributes
+## max_tokens[RW] {: #attribute-i-max_tokens }
+Returns the value of attribute max_tokens.
+
+
+# Instance Methods
+## add(key, value, token_count:, access_count:0, last_accessed:nil, from_recall:false) {: #method-i-add }
+Add a node to working memory
+
+**`@param`** [String] Node identifier
+
+**`@param`** [String] Node content
+
+**`@param`** [Integer] Number of tokens in this node
+
+**`@param`** [Integer] Access count from long-term memory (default: 0)
+
+**`@param`** [Time, nil] Last access time from long-term memory
+
+**`@param`** [Boolean] Whether this node was recalled from long-term memory
+
+**`@return`** [void] 
+
+## add_from_sync(id:, content:, token_count:, created_at:) {: #method-i-add_from_sync }
+Add a node from sync notification (bypasses normal add flow)
+
+Called by RobotGroup when another robot adds to working memory. Does not
+trigger notifications to avoid infinite loops.
+
+**`@param`** [Integer] Node database ID
+
+**`@param`** [String] Node content
+
+**`@param`** [Integer] Token count
+
+**`@param`** [Time] When node was created
+
+**`@return`** [void] 
+
+## assemble_context(strategy:, max_tokens:nil) {: #method-i-assemble_context }
+Assemble context string for LLM
+
+**`@param`** [Symbol] Assembly strategy (:recent, :frequent, :balanced)
+- :recent - Most recently accessed (LRU)
+- :frequent - Most frequently accessed (LFU)
+- :balanced - Combines frequency × recency
+
+**`@param`** [Integer, nil] Optional token limit
+
+**`@return`** [String] Assembled context
+
+## clear() {: #method-i-clear }
+Clear all nodes from working memory
+
+**`@return`** [void] 
+
+## clear_from_sync() {: #method-i-clear_from_sync }
+Clear all nodes from sync notification
+
+Called by RobotGroup when another robot clears working memory.
+
+**`@return`** [void] 
+
+## evict_to_make_space(needed_tokens) {: #method-i-evict_to_make_space }
+Evict nodes to make space
+
+Uses LFU + LRU strategy: Least Frequently Used + Least Recently Used Nodes
+with low access count and old timestamps are evicted first
+
+**`@param`** [Integer] Number of tokens needed
+
+**`@return`** [Array<Hash>] Evicted nodes
+
+## has_space?(token_count) {: #method-i-has_space? }
+Check if there's space for a node
+
+**`@param`** [Integer] Number of tokens needed
+
+**`@return`** [Boolean] true if space available
+
+## initialize(max_tokens:) {: #method-i-initialize }
+Initialize working memory
+
+**`@param`** [Integer] Maximum tokens allowed in working memory
+
+**`@return`** [WorkingMemory] a new instance of WorkingMemory
+
+## node_count() {: #method-i-node_count }
+Get node count
+
+**`@return`** [Integer] Number of nodes in working memory
+
+## remove(key) {: #method-i-remove }
+Remove a node from working memory
+
+**`@param`** [String] Node identifier
+
+**`@return`** [void] 
+
+## remove_from_sync(node_id) {: #method-i-remove_from_sync }
+Remove a node from sync notification
+
+Called by RobotGroup when another robot evicts from working memory.
+
+**`@param`** [Integer] Node database ID
+
+**`@return`** [void] 
+
+## token_count() {: #method-i-token_count }
+Get current token count
+
+**`@return`** [Integer] Total tokens in working memory
+
+## utilization_percentage() {: #method-i-utilization_percentage }
+Get utilization percentage
+
+**`@return`** [Float] Percentage of working memory used
+

data/docs/api/yard/HTM.md

@@ -0,0 +1,80 @@
+# Class: HTM
+**Inherits:** Object
+    
+
+HTM (Hierarchical Temporary Memory) error classes
+
+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
+**`@yield`** [config] Configuration object
+
+**`@yieldparam`** [HTM::Configuration] 
+
+
+**`@example`**
+```ruby
+HTM.configure do |config|
+  config.embedding_generator = ->(text) { MyEmbedder.embed(text) }
+  config.tag_extractor = ->(text, ontology) { MyTagger.extract(text, ontology) }
+end
+```
+**`@example`**
+```ruby
+HTM.configure  # Uses RubyLLM defaults
+```
+## count_tokens(text ) {: #method-c-count_tokens }
+Count tokens using configured counter
+**`@param`** [String] Text to count tokens for
+
+**`@return`** [Integer] Token count
+
+## embed(text ) {: #method-c-embed }
+Generate embedding using EmbeddingService
+**`@param`** [String] Text to embed
+
+**`@return`** [Array<Float>] Embedding vector (original, not padded)
+
+## extract_tags(text , existing_ontology: []) {: #method-c-extract_tags }
+Extract tags using TagService
+**`@param`** [String] Text to analyze
+
+**`@param`** [Array<String>] Sample of existing tags for context
+
+**`@return`** [Array<String>] Extracted and validated tag names
+
+## logger() {: #method-c-logger }
+Get configured logger
+**`@return`** [Logger] Configured logger instance
+
+## reset_configuration!() {: #method-c-reset_configuration! }
+Reset configuration to defaults
+# Attributes
+## configuration[RW] {: #attribute-c-configuration }
+Get current configuration
+
+**`@return`** [HTM::Configuration] 
+
+

data/docs/api/yard/index.csv

@@ -0,0 +1,179 @@
+name,type,path
+HTM::JobAdapter,Module,HTM/JobAdapter.md
+HTM::JobAdapter.enqueue,Method,HTM/JobAdapter.md#method-c-enqueue
+HTM::Observability,Module,HTM/Observability.md
+HTM::Observability.cache_stats,Method,HTM/Observability.md#method-c-cache_stats
+HTM::Observability.circuit_breaker_stats,Method,HTM/Observability.md#method-c-circuit_breaker_stats
+HTM::Observability.collect_all,Method,HTM/Observability.md#method-c-collect_all
+HTM::Observability.connection_pool_stats,Method,HTM/Observability.md#method-c-connection_pool_stats
+HTM::Observability.health_check,Method,HTM/Observability.md#method-c-health_check
+HTM::Observability.healthy?,Method,HTM/Observability.md#method-c-healthy?
+HTM::Observability.memory_stats,Method,HTM/Observability.md#method-c-memory_stats
+HTM::Observability.query_timing_stats,Method,HTM/Observability.md#method-c-query_timing_stats
+HTM::Observability.record_embedding_timing,Method,HTM/Observability.md#method-c-record_embedding_timing
+HTM::Observability.record_query_timing,Method,HTM/Observability.md#method-c-record_query_timing
+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,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_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!
+configuration,Attribute,HTM.md#attribute-c-configuration
+HTM::ActiveRecordConfig,Class,HTM/ActiveRecordConfig.md
+HTM::ActiveRecordConfig.connected?,Method,HTM/ActiveRecordConfig.md#method-c-connected?
+HTM::ActiveRecordConfig.connection_stats,Method,HTM/ActiveRecordConfig.md#method-c-connection_stats
+HTM::ActiveRecordConfig.disconnect!,Method,HTM/ActiveRecordConfig.md#method-c-disconnect!
+HTM::ActiveRecordConfig.establish_connection!,Method,HTM/ActiveRecordConfig.md#method-c-establish_connection!
+HTM::ActiveRecordConfig.load_database_config,Method,HTM/ActiveRecordConfig.md#method-c-load_database_config
+HTM::ActiveRecordConfig.verify_extensions!,Method,HTM/ActiveRecordConfig.md#method-c-verify_extensions!
+HTM::CircuitBreaker,Class,HTM/CircuitBreaker.md
+HTM::CircuitBreaker.call,Method,HTM/CircuitBreaker.md#method-i-call
+HTM::CircuitBreaker.closed?,Method,HTM/CircuitBreaker.md#method-i-closed?
+HTM::CircuitBreaker.half_open?,Method,HTM/CircuitBreaker.md#method-i-half_open?
+HTM::CircuitBreaker.initialize,Method,HTM/CircuitBreaker.md#method-i-initialize
+HTM::CircuitBreaker.open?,Method,HTM/CircuitBreaker.md#method-i-open?
+HTM::CircuitBreaker.reset!,Method,HTM/CircuitBreaker.md#method-i-reset!
+HTM::CircuitBreaker.stats,Method,HTM/CircuitBreaker.md#method-i-stats
+failure_count,Attribute,HTM/CircuitBreaker.md#attribute-i-failure_count
+last_failure_time,Attribute,HTM/CircuitBreaker.md#attribute-i-last_failure_time
+name,Attribute,HTM/CircuitBreaker.md#attribute-i-name
+state,Attribute,HTM/CircuitBreaker.md#attribute-i-state
+HTM::Configuration,Class,HTM/Configuration.md
+HTM::Configuration.configure_ruby_llm,Method,HTM/Configuration.md#method-i-configure_ruby_llm
+HTM::Configuration.initialize,Method,HTM/Configuration.md#method-i-initialize
+HTM::Configuration.normalize_ollama_model,Method,HTM/Configuration.md#method-i-normalize_ollama_model
+HTM::Configuration.reset_to_defaults,Method,HTM/Configuration.md#method-i-reset_to_defaults
+HTM::Configuration.validate!,Method,HTM/Configuration.md#method-i-validate!
+anthropic_api_key,Attribute,HTM/Configuration.md#attribute-i-anthropic_api_key
+azure_api_key,Attribute,HTM/Configuration.md#attribute-i-azure_api_key
+azure_api_version,Attribute,HTM/Configuration.md#attribute-i-azure_api_version
+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
+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
+embedding_generator,Attribute,HTM/Configuration.md#attribute-i-embedding_generator
+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
+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
+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
+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
+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
+HTM::Database.default_config,Method,HTM/Database.md#method-c-default_config
+HTM::Database.drop,Method,HTM/Database.md#method-c-drop
+HTM::Database.dump_schema,Method,HTM/Database.md#method-c-dump_schema
+HTM::Database.generate_docs,Method,HTM/Database.md#method-c-generate_docs
+HTM::Database.info,Method,HTM/Database.md#method-c-info
+HTM::Database.load_schema,Method,HTM/Database.md#method-c-load_schema
+HTM::Database.migrate,Method,HTM/Database.md#method-c-migrate
+HTM::Database.migration_status,Method,HTM/Database.md#method-c-migration_status
+HTM::Database.parse_connection_params,Method,HTM/Database.md#method-c-parse_connection_params
+HTM::Database.parse_connection_url,Method,HTM/Database.md#method-c-parse_connection_url
+HTM::Database.seed,Method,HTM/Database.md#method-c-seed
+HTM::Database.setup,Method,HTM/Database.md#method-c-setup
+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.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!
+HTM::Error,Class,HTM/Error.md
+HTM::ValidationError,Class,HTM/ValidationError.md
+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::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::Railtie,Class,HTM/Railtie.md
+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.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::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?
+HTM::TimeframeExtractor::Result,Class,HTM/TimeframeExtractor/Result.md
+original_expression,Attribute,HTM/TimeframeExtractor/Result.md#attribute-i-original_expression
+query,Attribute,HTM/TimeframeExtractor/Result.md#attribute-i-query
+timeframe,Attribute,HTM/TimeframeExtractor/Result.md#attribute-i-timeframe
+HTM::Timeframe,Class,HTM/Timeframe.md
+HTM::Timeframe.normalize,Method,HTM/Timeframe.md#method-c-normalize
+HTM::Timeframe.valid?,Method,HTM/Timeframe.md#method-c-valid?
+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::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
+HTM::WorkingMemory.assemble_context,Method,HTM/WorkingMemory.md#method-i-assemble_context
+HTM::WorkingMemory.clear,Method,HTM/WorkingMemory.md#method-i-clear
+HTM::WorkingMemory.clear_from_sync,Method,HTM/WorkingMemory.md#method-i-clear_from_sync
+HTM::WorkingMemory.evict_to_make_space,Method,HTM/WorkingMemory.md#method-i-evict_to_make_space
+HTM::WorkingMemory.has_space?,Method,HTM/WorkingMemory.md#method-i-has_space?
+HTM::WorkingMemory.initialize,Method,HTM/WorkingMemory.md#method-i-initialize
+HTM::WorkingMemory.node_count,Method,HTM/WorkingMemory.md#method-i-node_count
+HTM::WorkingMemory.remove,Method,HTM/WorkingMemory.md#method-i-remove
+HTM::WorkingMemory.remove_from_sync,Method,HTM/WorkingMemory.md#method-i-remove_from_sync
+HTM::WorkingMemory.token_count,Method,HTM/WorkingMemory.md#method-i-token_count
+HTM::WorkingMemory.utilization_percentage,Method,HTM/WorkingMemory.md#method-i-utilization_percentage
+max_tokens,Attribute,HTM/WorkingMemory.md#attribute-i-max_tokens

data/docs/api/yard-reference.md

@@ -0,0 +1,51 @@
+# YARD API Reference
+
+Complete API documentation generated by [YARD](https://yardoc.org/) with [yard-markdown](https://github.com/skatkov/yard-markdown).
+
+<div class="grid cards" markdown>
+
+-   :material-book-open-variant:{ .lg .middle } **API Documentation**
+
+    ---
+
+    Browse the complete API reference with method signatures, parameters, and examples.
+
+-   :material-chart-bar:{ .lg .middle } **Documentation Coverage**
+
+    ---
+
+    Run `rake htm:doc:stats` to see documentation coverage statistics.
+
+</div>
+
+## Classes & Modules
+
+| Class/Module | Description |
+|--------------|-------------|
+| [HTM](yard/HTM.md) | Main API class for memory operations |
+| [HTM::CircuitBreaker](yard/HTM/CircuitBreaker.md) | Fault tolerance for external services |
+| [HTM::Configuration](yard/HTM/Configuration.md) | Multi-provider LLM configuration |
+| [HTM::Database](yard/HTM/Database.md) | Database schema and connection management |
+| [HTM::EmbeddingService](yard/HTM/EmbeddingService.md) | Vector embedding generation service |
+| [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::TagService](yard/HTM/TagService.md) | Hierarchical tag extraction service |
+| [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 |
+
+## Generating Documentation
+
+```bash
+# Build YARD documentation
+rake htm:doc:yard
+
+# Start live-reload server (HTML mode)
+rake htm:doc:server
+
+# Show coverage statistics
+rake htm:doc:stats
+```