htm 0.0.1 → 0.0.10

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
+```

data/docs/architecture/adrs/001-postgresql-timescaledb.md

@@ -299,7 +299,7 @@ ALTER TABLE nodes SET (
 - [pgvector Documentation](https://github.com/pgvector/pgvector)
 - [PostgreSQL Full-Text Search](https://www.postgresql.org/docs/current/textsearch.html)
 - [HTM Database Schema Guide](../../development/schema.md)
-- [HTM Configuration Guide](../../installation.md)
+- [HTM Configuration Guide](../../getting-started/installation.md)
 
 ---
 

data/docs/architecture/adrs/003-ollama-embeddings.md

@@ -404,7 +404,7 @@ htm = HTM.new(
 - [pgvector Documentation](https://github.com/pgvector/pgvector)
 - [pgai Documentation](https://github.com/timescale/pgai)
 - [ADR-011: Database-Side Embedding Generation with pgai](011-pgai-integration.md) - **Supersedes this ADR**
-- [HTM Setup Guide](../../installation.md)
+- [HTM Setup Guide](../../getting-started/installation.md)
 
 ---
 

data/docs/architecture/adrs/010-redis-working-memory-rejected.md

@@ -30,18 +30,7 @@ During architectural review, we identified that working memory is currently vola
 
 ### Current Architecture (Two-Tier)
 
-```
-┌─────────────────┐
-│   HTM Instance  │
-│                 │
-│  ┌───────────┐  │     ┌──────────────┐
-│  │ Working   │  │────>│  PostgreSQL  │
-│  │ Memory    │  │     │ (Long-Term)  │
-│  │ (Hash)    │  │     │              │
-│  └───────────┘  │     └──────────────┘
-│   volatile      │       persistent
-└─────────────────┘
-```
+![Current Two-Tier Architecture](../../assets/images/adr-010-current-architecture.svg)
 
 **How it works**:
 1. `add_node()` saves **immediately** to PostgreSQL
@@ -53,21 +42,7 @@ During architectural review, we identified that working memory is currently vola
 
 ### Proposed Architecture (Three-Tier)
 
-```
-┌─────────────────┐
-│   HTM Instance  │
-│                 │
-│      ││          │
-│      ││          │
-│      ▼▼          │
-│  ┌───────────┐  │     ┌──────────────┐
-│  │   Redis   │  │────>│  PostgreSQL  │
-│  │ (Working) │  │     │ (Long-Term)  │
-│  │           │  │     │              │
-│  └───────────┘  │     └──────────────┘
-│   persistent    │       persistent
-└─────────────────┘
-```
+![Proposed Three-Tier Architecture (Rejected)](../../assets/images/adr-010-proposed-architecture.svg)
 
 **Proposed changes**:
 - Store working memory in Redis (shared across processes)

data/docs/architecture/adrs/index.md

@@ -174,24 +174,13 @@ Proposal to add Redis as a persistent storage layer for working memory was thoro
 
 ## ADR Dependencies
 
-```
-ADR-001 (Storage)
-  └─> ADR-002 (Two-Tier Memory)
-        ├─> ADR-007 (Eviction Strategy)
-        ├─> ADR-009 (Never-Forget)
-        └─> ADR-010 (Redis WM - Rejected Alternative)
-  └─> ADR-003 (Embeddings)
-        └─> ADR-005 (RAG Retrieval)
-  └─> ADR-004 (Hive Mind)
-        └─> ADR-008 (Robot ID)
-  └─> ADR-006 (Context Assembly)
-```
+![ADR Dependency Tree](../../assets/images/adr-dependency-tree.svg)
 
 ## Related Documentation
 
 - [HTM API Guide](../../api/index.md)
 - [Database Schema](../../development/schema.md)
-- [Configuration Guide](../../installation.md)
+- [Configuration Guide](../../getting-started/installation.md)
 - [Development Workflow](../../development/index.md)
 
 ## Contributing to ADRs