htm 0.0.18 → 0.0.30

data/docs/api/yard/HTM.md

@@ -6,61 +6,4 @@ examples/robot_groups/lib/htm/working_memory_channel.rb frozen_string_literal:
 true
 
 
-# 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_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
-
-**`@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

@@ -28,14 +28,6 @@ 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!
-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
@@ -55,59 +47,82 @@ 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
-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
-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
-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::ConfigSection,Class,HTM/ConfigSection.md
+HTM::ConfigSection.[],Method,HTM/ConfigSection.md#method-i-[]
+HTM::ConfigSection.[]=,Method,HTM/ConfigSection.md#method-i-[]=
+HTM::ConfigSection.each,Method,HTM/ConfigSection.md#method-i-each
+HTM::ConfigSection.initialize,Method,HTM/ConfigSection.md#method-i-initialize
+HTM::ConfigSection.keys,Method,HTM/ConfigSection.md#method-i-keys
+HTM::ConfigSection.merge,Method,HTM/ConfigSection.md#method-i-merge
+HTM::ConfigSection.method_missing,Method,HTM/ConfigSection.md#method-i-method_missing
+HTM::ConfigSection.respond_to_missing?,Method,HTM/ConfigSection.md#method-i-respond_to_missing?
+HTM::ConfigSection.to_h,Method,HTM/ConfigSection.md#method-i-to_h
+HTM::Config,Class,HTM/Config.md
+HTM::Config.anthropic_api_key,Method,HTM/Config.md#method-i-anthropic_api_key
+HTM::Config.azure_api_key,Method,HTM/Config.md#method-i-azure_api_key
+HTM::Config.azure_api_version,Method,HTM/Config.md#method-i-azure_api_version
+HTM::Config.azure_endpoint,Method,HTM/Config.md#method-i-azure_endpoint
+HTM::Config.bedrock_access_key,Method,HTM/Config.md#method-i-bedrock_access_key
+HTM::Config.bedrock_region,Method,HTM/Config.md#method-i-bedrock_region
+HTM::Config.bedrock_secret_key,Method,HTM/Config.md#method-i-bedrock_secret_key
+HTM::Config.chunk_overlap,Method,HTM/Config.md#method-i-chunk_overlap
+HTM::Config.chunk_size,Method,HTM/Config.md#method-i-chunk_size
+HTM::Config.circuit_breaker_failure_threshold,Method,HTM/Config.md#method-i-circuit_breaker_failure_threshold
+HTM::Config.circuit_breaker_half_open_max_calls,Method,HTM/Config.md#method-i-circuit_breaker_half_open_max_calls
+HTM::Config.circuit_breaker_reset_timeout,Method,HTM/Config.md#method-i-circuit_breaker_reset_timeout
+HTM::Config.configure_ruby_llm,Method,HTM/Config.md#method-i-configure_ruby_llm
+HTM::Config.database_config,Method,HTM/Config.md#method-i-database_config
+HTM::Config.database_configured?,Method,HTM/Config.md#method-i-database_configured?
+HTM::Config.database_url,Method,HTM/Config.md#method-i-database_url
+HTM::Config.deepseek_api_key,Method,HTM/Config.md#method-i-deepseek_api_key
+HTM::Config.development?,Method,HTM/Config.md#method-i-development?
+HTM::Config.embedding_dimensions,Method,HTM/Config.md#method-i-embedding_dimensions
+HTM::Config.embedding_model,Method,HTM/Config.md#method-i-embedding_model
+HTM::Config.embedding_provider,Method,HTM/Config.md#method-i-embedding_provider
+HTM::Config.embedding_timeout,Method,HTM/Config.md#method-i-embedding_timeout
+HTM::Config.environment,Method,HTM/Config.md#method-i-environment
+HTM::Config.extract_propositions,Method,HTM/Config.md#method-i-extract_propositions
+HTM::Config.gemini_api_key,Method,HTM/Config.md#method-i-gemini_api_key
+HTM::Config.huggingface_api_key,Method,HTM/Config.md#method-i-huggingface_api_key
+HTM::Config.initialize,Method,HTM/Config.md#method-i-initialize
+HTM::Config.job_backend,Method,HTM/Config.md#method-i-job_backend
+HTM::Config.max_embedding_dimension,Method,HTM/Config.md#method-i-max_embedding_dimension
+HTM::Config.max_tag_depth,Method,HTM/Config.md#method-i-max_tag_depth
+HTM::Config.normalize_ollama_model,Method,HTM/Config.md#method-i-normalize_ollama_model
+HTM::Config.ollama_url,Method,HTM/Config.md#method-i-ollama_url
+HTM::Config.openai_api_key,Method,HTM/Config.md#method-i-openai_api_key
+HTM::Config.openai_organization,Method,HTM/Config.md#method-i-openai_organization
+HTM::Config.openai_project,Method,HTM/Config.md#method-i-openai_project
+HTM::Config.openrouter_api_key,Method,HTM/Config.md#method-i-openrouter_api_key
+HTM::Config.production?,Method,HTM/Config.md#method-i-production?
+HTM::Config.proposition_model,Method,HTM/Config.md#method-i-proposition_model
+HTM::Config.proposition_provider,Method,HTM/Config.md#method-i-proposition_provider
+HTM::Config.proposition_timeout,Method,HTM/Config.md#method-i-proposition_timeout
+HTM::Config.refresh_ollama_models!,Method,HTM/Config.md#method-i-refresh_ollama_models!
+HTM::Config.relevance_access_weight,Method,HTM/Config.md#method-i-relevance_access_weight
+HTM::Config.relevance_recency_half_life_hours,Method,HTM/Config.md#method-i-relevance_recency_half_life_hours
+HTM::Config.relevance_recency_weight,Method,HTM/Config.md#method-i-relevance_recency_weight
+HTM::Config.relevance_semantic_weight,Method,HTM/Config.md#method-i-relevance_semantic_weight
+HTM::Config.relevance_tag_weight,Method,HTM/Config.md#method-i-relevance_tag_weight
+HTM::Config.reset_to_defaults,Method,HTM/Config.md#method-i-reset_to_defaults
+HTM::Config.service_name,Method,HTM/Config.md#method-i-service_name
+HTM::Config.tag_model,Method,HTM/Config.md#method-i-tag_model
+HTM::Config.tag_provider,Method,HTM/Config.md#method-i-tag_provider
+HTM::Config.tag_timeout,Method,HTM/Config.md#method-i-tag_timeout
+HTM::Config.test?,Method,HTM/Config.md#method-i-test?
+HTM::Config.validate!,Method,HTM/Config.md#method-i-validate!
+HTM::Config.validate_settings!,Method,HTM/Config.md#method-i-validate_settings!
+HTM::Config.active_xdg_config_file,Method,HTM/Config.md#method-c-active_xdg_config_file
+HTM::Config.config_section_with_defaults,Method,HTM/Config.md#method-c-config_section_with_defaults
+HTM::Config.deep_merge_hashes,Method,HTM/Config.md#method-c-deep_merge_hashes
+HTM::Config.env,Method,HTM/Config.md#method-c-env
+HTM::Config.xdg_config_file,Method,HTM/Config.md#method-c-xdg_config_file
+HTM::Config.xdg_config_paths,Method,HTM/Config.md#method-c-xdg_config_paths
+embedding_generator,Attribute,HTM/Config.md#attribute-i-embedding_generator
+logger,Attribute,HTM/Config.md#attribute-i-logger
+proposition_extractor,Attribute,HTM/Config.md#attribute-i-proposition_extractor
+tag_extractor,Attribute,HTM/Config.md#attribute-i-tag_extractor
+token_counter,Attribute,HTM/Config.md#attribute-i-token_counter
 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

data/docs/api/yard-reference.md

@@ -24,7 +24,8 @@ Complete API documentation generated by [YARD](https://yardoc.org/) with [yard-m
 |--------------|-------------|
 | [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::Config](yard/HTM/Config.md) | HTM::Config class |
+| [HTM::ConfigSection](yard/HTM/ConfigSection.md) | HTM::ConfigSection class |
 | [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 |

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

@@ -1,23 +1,25 @@
-# ADR-003: Ollama as Default Embedding Provider
+# ADR-003: Default Embedding Provider Selection
 
-**Status**: Accepted (Reinstated After ADR-011 Reversal)
+**Status**: Accepted (Updated for Multi-Provider Support)
 
-**Date**: 2025-10-25 (Updated: 2025-10-27)
+**Date**: 2025-10-25 (Updated: 2025-12-21)
 
 **Decision Makers**: Dewayne VanHoozer, Claude (Anthropic)
 
 ---
 
-!!! success "Architecture Status (October 2025)"
-    **October 27, 2025**: This ADR is once again the current architecture. Following the reversal of ADR-011, HTM has returned to client-side embedding generation using Ollama as the default provider. Embeddings are generated in Ruby before database insertion.
+!!! success "Architecture Status"
+    HTM uses RubyLLM for embedding generation, supporting multiple providers. **Ollama is the default** for local development, but users can configure any supported provider (OpenAI, Anthropic, Gemini, Azure, Bedrock, DeepSeek) based on their requirements.
 
 ## Quick Summary
 
-HTM uses **Ollama with the nomic-embed-text model** as the default embedding provider, prioritizing local-first, privacy-preserving operation with zero API costs while supporting pluggable alternatives (OpenAI).
+HTM uses **Ollama with the nomic-embed-text model** as the **default** embedding provider for local development, prioritizing local-first, privacy-preserving operation with zero API costs. However, **HTM fully supports multiple providers** through RubyLLM, allowing users to choose OpenAI, Gemini, Azure, Bedrock, or other providers for production deployments.
 
-**Why**: Local embeddings eliminate API costs, preserve privacy, and enable offline operation while maintaining good semantic search quality.
+**Why Ollama as default**: Local embeddings eliminate API costs, preserve privacy, and enable offline operation—ideal for development and privacy-sensitive applications.
 
-**Impact**: Users must install Ollama locally, trading convenience for privacy and cost savings. Client-side embedding generation provides reliable operation without complex database extension dependencies.
+**Why multi-provider support**: Production deployments may require higher-quality embeddings, managed services, or integration with existing cloud infrastructure.
+
+**Impact**: Ollama is recommended for getting started quickly, but users can easily switch providers via configuration for their specific needs.
 
 ---
 
@@ -47,7 +49,16 @@ HTM requires vector embeddings for semantic search functionality. Embeddings con
 
 ## Decision
 
-We will use **Ollama with the gpt-oss model** as the default embedding provider for HTM, while supporting pluggable alternatives (OpenAI, Cohere, etc.).
+We will use **Ollama with the nomic-embed-text model** as the **default** embedding provider for HTM, while providing **full support for multiple providers** through RubyLLM:
+
+- **Ollama** (default) - Local, privacy-preserving, free
+- **OpenAI** - High-quality, production-ready
+- **Gemini** - Google Cloud integration
+- **Azure** - Enterprise Azure deployments
+- **Bedrock** - AWS integration
+- **DeepSeek** - Cost-effective alternative
+
+Users configure their preferred provider via `HTM.configure` or environment variables.
 
 ---
 
@@ -205,38 +216,36 @@ end
 
 ### User Configuration
 
-!!! info "pgai Configuration"
-    With pgai, configuration sets database session variables. Embedding generation happens automatically via triggers.
+Configure your preferred provider globally or per-instance:
 
 ```ruby
-# Default: Ollama with nomic-embed-text (768 dimensions)
-htm = HTM.new(robot_name: "My Robot")
-
-# Explicit Ollama configuration
-htm = HTM.new(
-  robot_name: "My Robot",
-  embedding_provider: :ollama,
-  embedding_model: 'nomic-embed-text'
-)
+# Global configuration (recommended)
+HTM.configure do |config|
+  # Ollama (default for development)
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
+
+  # Or OpenAI (recommended for production)
+  # config.embedding.provider = :openai
+  # config.embedding.model = 'text-embedding-3-small'
+
+  # Or Gemini
+  # config.embedding.provider = :gemini
+  # config.embedding.model = 'text-embedding-004'
+end
 
-# Use different Ollama model
-htm = HTM.new(
-  robot_name: "My Robot",
-  embedding_provider: :ollama,
-  embedding_model: 'mxbai-embed-large',  # 1024 dimensions
-  embedding_dimensions: 1024
-)
+# Initialize HTM
+htm = HTM.new(robot_name: "My Robot")
 
-# Use OpenAI
-htm = HTM.new(
-  robot_name: "My Robot",
-  embedding_provider: :openai,
-  embedding_model: 'text-embedding-3-small'  # 1536 dimensions
-)
+# Add memory - embedding generated via configured provider
+htm.remember("PostgreSQL is awesome", tags: ["database"])
+```
 
-# Add node - embedding generated automatically by database trigger!
-htm.add_node("fact_001", "PostgreSQL is awesome", type: :fact)
-# No embedding parameter needed - pgai handles it in the database
+**Environment variables for cloud providers:**
+```bash
+export OPENAI_API_KEY="sk-..."      # For OpenAI
+export GEMINI_API_KEY="..."         # For Gemini
+export ANTHROPIC_API_KEY="sk-..."   # For Anthropic
 ```
 
 ---

data/docs/architecture/adrs/004-hive-mind.md

@@ -420,7 +420,7 @@ htm = HTM.new(
 - [Multi-Agent Systems](https://en.wikipedia.org/wiki/Multi-agent_system)
 - [ADR-002: Two-Tier Memory](002-two-tier-memory.md)
 - [ADR-008: Robot Identification](008-robot-identification.md)
-- [Multi-Robot Guide](../../guides/multi-robot.md)
+- [Multi-Robot Guide](../../robots/multi-robot.md)
 
 ---
 

data/docs/architecture/adrs/008-robot-identification.md

@@ -608,7 +608,7 @@ htm = HTM.new(
 - [ULID Specification](https://github.com/ulid/spec)
 - [Robot Registry Pattern](https://martinfowler.com/eaaCatalog/registry.html)
 - [ADR-004: Hive Mind Architecture](004-hive-mind.md)
-- [Multi-Robot Guide](../../guides/multi-robot.md)
+- [Multi-Robot Guide](../../robots/multi-robot.md)
 
 ---
 

data/docs/architecture/index.md

@@ -29,7 +29,7 @@ HTM provides intelligent memory management through five core components that wor
   <!-- Embedding Service -->
   <rect x="550" y="200" width="200" height="120" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="2" rx="5"/>
   <text x="650" y="235" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Embedding Service</text>
-  <text x="650" y="255" text-anchor="middle" fill="#B0B0B0" font-size="11">Ollama/OpenAI</text>
+  <text x="650" y="255" text-anchor="middle" fill="#B0B0B0" font-size="11">Multi-Provider (RubyLLM)</text>
   <text x="650" y="275" text-anchor="middle" fill="#B0B0B0" font-size="11">Vector Embeddings</text>
   <text x="650" y="295" text-anchor="middle" fill="#B0B0B0" font-size="11">Semantic Search</text>
 
@@ -113,12 +113,14 @@ Durable PostgreSQL storage for permanent knowledge retention. All memories are s
 
 Generates vector embeddings for semantic search and manages token counting for memory management.
 
-**Supported Providers:**
+**Supported Providers (via RubyLLM):**
 
-- **Ollama** (default): Local embedding models (gpt-oss, nomic-embed-text, mxbai-embed-large)
+- **Ollama** (default): Local embedding models (nomic-embed-text, mxbai-embed-large)
 - **OpenAI**: text-embedding-3-small, text-embedding-3-large
-- **Cohere**: embed-english-v3.0, embed-multilingual-v3.0
-- **Local**: Transformers.js for browser/edge deployment
+- **Gemini**: text-embedding-004
+- **Azure**: Azure OpenAI Service
+- **Bedrock**: Amazon Titan, Cohere models
+- **DeepSeek**: DeepSeek embeddings
 
 **Related ADRs:** [ADR-003](adrs/003-ollama-embeddings.md)
 
@@ -272,8 +274,8 @@ stateDiagram-v2
 Explore detailed architecture documentation:
 
 - **[Detailed Architecture](overview.md)** - Deep dive into system architecture, data flows, and performance characteristics
-- **[Two-Tier Memory System](two-tier-memory.md)** - Working memory and long-term memory design, eviction strategies, and context assembly
-- **[Hive Mind Architecture](hive-mind.md)** - Multi-robot shared memory, robot identification, and cross-robot knowledge sharing
+- **[Two-Tier Memory System](../robots/two-tier-memory.md)** - Working memory and long-term memory design, eviction strategies, and context assembly
+- **[Hive Mind Architecture](../robots/hive-mind.md)** - Multi-robot shared memory, robot identification, and cross-robot knowledge sharing
 
 ## Technology Stack
 
@@ -284,7 +286,7 @@ Explore detailed architecture documentation:
 | **Time-Series** | TimescaleDB | Hypertable partitioning, compression |
 | **Vector Search** | pgvector | Semantic similarity (HNSW) |
 | **Full-Text** | pg_trgm | Fuzzy text matching |
-| **Embeddings** | Ollama/OpenAI | Vector generation |
+| **Embeddings** | RubyLLM (multi-provider) | Vector generation |
 | **Connection Pool** | connection_pool gem | Database connection management |
 | **Testing** | Minitest | Test framework |
 
@@ -318,7 +320,7 @@ Explore detailed architecture documentation:
 
 - **Working Memory**: Limited by process RAM (~1-2GB for 128K tokens)
 - **Database**: PostgreSQL scales to TBs with proper indexing
-- **Embeddings**: Local models (Ollama) bounded by GPU/CPU
+- **Embeddings**: Local models (Ollama) bounded by GPU/CPU; cloud providers scale independently
 
 ### Horizontal Scaling
 

data/docs/architecture/overview.md

@@ -64,7 +64,7 @@ HTM implements a layered architecture with clear separation of concerns between
 - **Client-Side Generation**: Generate embeddings before database insertion
 - **Token Counting**: Estimate token counts for strings
 - **Model Management**: Handle different models per provider
-- **Provider Support**: Ollama (default) and OpenAI
+- **Multi-Provider Support**: Ollama (default), OpenAI, Anthropic, Gemini, Azure, Bedrock, DeepSeek via RubyLLM
 
 !!! info "Architecture Change (October 2025)"
     Embeddings are generated client-side in Ruby before database insertion. This provides reliable, cross-platform operation without complex database extension dependencies.
@@ -257,13 +257,17 @@ gem 'tiktoken_ruby', '~> 0.0.6'      # Token counting (OpenAI-compatible)
 
 ### Embedding Providers
 
-!!! info "Client-Side Generation"
-    Embeddings are generated client-side in Ruby before database insertion. This provides reliable, cross-platform operation.
+!!! info "Multi-Provider Support via RubyLLM"
+    HTM uses RubyLLM for embedding generation, supporting multiple providers. Choose based on your requirements for privacy, cost, and quality.
 
 | Provider | Models | Dimensions | Speed | Cost |
 |----------|--------|------------|-------|------|
-| **Ollama** (default) | nomic-embed-text, mxbai-embed-large, all-minilm | 384-1024 | Fast (local HTTP) | Free |
-| **OpenAI** | text-embedding-3-small, text-embedding-ada-002 | 1536 | Fast (API) | $0.0001/1K tokens |
+| **Ollama** (default) | nomic-embed-text, mxbai-embed-large | 384-1024 | Fast (local) | Free |
+| **OpenAI** | text-embedding-3-small, text-embedding-3-large | 1536-3072 | Fast (API) | $0.0001/1K tokens |
+| **Gemini** | text-embedding-004 | 768 | Fast (API) | Varies |
+| **Azure** | OpenAI models via Azure | 1536 | Fast (API) | Enterprise pricing |
+| **Bedrock** | Amazon Titan, Cohere | Varies | Fast (API) | AWS pricing |
+| **DeepSeek** | DeepSeek embeddings | Varies | Fast (API) | Competitive |
 
 ## Performance Characteristics
 
@@ -366,7 +370,7 @@ Based on typical production workloads with 10,000 nodes in long-term memory (cli
 ## Related Documentation
 
 - [Architecture Index](index.md) - Architecture overview and component summary
-- [Two-Tier Memory System](two-tier-memory.md) - Working memory and long-term memory deep dive
-- [Hive Mind Architecture](hive-mind.md) - Multi-robot shared memory design
+- [Two-Tier Memory System](../robots/two-tier-memory.md) - Working memory and long-term memory deep dive
+- [Hive Mind Architecture](../robots/hive-mind.md) - Multi-robot shared memory design
 - [API Reference](../api/htm.md) - Complete API documentation
 - [Architecture Decision Records](adrs/index.md) - Decision history

data/docs/assets/images/balanced-strategy-decay.svg

@@ -0,0 +1,41 @@
+<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">Balanced Strategy: Importance Decay Over Time</text>
+
+  <!-- Axes -->
+  <line x1="100" y1="350" x2="700" y2="350" stroke="#808080" stroke-width="2"/>
+  <line x1="100" y1="350" x2="100" y2="80" stroke="#808080" stroke-width="2"/>
+
+  <!-- X-axis labels -->
+  <text x="100" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">0h</text>
+  <text x="250" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">1h</text>
+  <text x="400" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">3h</text>
+  <text x="550" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">6h</text>
+  <text x="700" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">24h</text>
+  <text x="400" y="395" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Time Since Added (hours)</text>
+
+  <!-- Y-axis labels -->
+  <text x="85" y="355" text-anchor="end" fill="#B0B0B0" font-size="11">0</text>
+  <text x="85" y="280" text-anchor="end" fill="#B0B0B0" font-size="11">3</text>
+  <text x="85" y="205" text-anchor="end" fill="#B0B0B0" font-size="11">6</text>
+  <text x="85" y="130" text-anchor="end" fill="#B0B0B0" font-size="11">9</text>
+  <text x="85" y="85" text-anchor="end" fill="#B0B0B0" font-size="11">10</text>
+  <text x="40" y="220" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold" transform="rotate(-90 40 220)">Effective Score</text>
+
+  <!-- Decay curves for different importance levels -->
+  <!-- Importance 10.0 -->
+  <path d="M 100 80 Q 250 105 400 155 T 700 320" stroke="#4CAF50" stroke-width="3" fill="none"/>
+  <text x="710" y="320" fill="#4CAF50" font-size="11" font-weight="bold">Imp: 10.0</text>
+
+  <!-- Importance 5.0 -->
+  <path d="M 100 205 Q 250 230 400 255 T 700 335" stroke="#2196F3" stroke-width="3" fill="none"/>
+  <text x="710" y="335" fill="#2196F3" font-size="11" font-weight="bold">Imp: 5.0</text>
+
+  <!-- Importance 1.0 -->
+  <path d="M 100 330 Q 250 340 400 345 T 700 348" stroke="#FF9800" stroke-width="3" fill="none"/>
+  <text x="710" y="348" fill="#FF9800" font-size="11" font-weight="bold">Imp: 1.0</text>
+
+  <!-- Key insight -->
+  <rect x="150" y="50" width="500" height="25" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
+  <text x="400" y="68" text-anchor="middle" fill="#4CAF50" font-size="12">High-importance memories retain value longer, but recency still matters</text>
+</svg>

data/docs/assets/images/class-hierarchy.svg

@@ -43,7 +43,7 @@
   <text x="70" y="370" fill="#B0B0B0" font-size="10">• <tspan fill="#4CAF50" font-weight="bold">HTM</tspan>: Main API interface coordinating all components</text>
   <text x="70" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#2196F3" font-weight="bold">WorkingMemory</tspan>: Fast, token-limited in-memory cache</text>
   <text x="70" y="406" fill="#B0B0B0" font-size="10">• <tspan fill="#9C27B0" font-weight="bold">LongTermMemory</tspan>: Durable PostgreSQL storage with RAG search</text>
-  <text x="380" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#FF9800" font-weight="bold">EmbeddingService</tspan>: Vector generation via Ollama/OpenAI</text>
+  <text x="380" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#FF9800" font-weight="bold">EmbeddingService</tspan>: Vector generation via RubyLLM</text>
   <text x="380" y="406" fill="#B0B0B0" font-size="10">• <tspan fill="#FFC107" font-weight="bold">Database</tspan>: Schema management and connections</text>
 
   <!-- Markers -->

data/docs/assets/images/eviction-priority.svg

@@ -0,0 +1,43 @@
+<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">Eviction Priority (Lower → Higher retention)</text>
+
+  <!-- Priority bars -->
+  <rect x="50" y="80" width="150" height="50" fill="rgba(244, 67, 54, 0.6)" stroke="#F44336" stroke-width="2" rx="3"/>
+  <text x="125" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 1: Evict First</text>
+
+  <rect x="220" y="80" width="150" height="50" fill="rgba(255, 152, 0, 0.6)" stroke="#FF9800" stroke-width="2" rx="3"/>
+  <text x="295" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 2</text>
+
+  <rect x="390" y="80" width="150" height="50" fill="rgba(255, 193, 7, 0.6)" stroke="#FFC107" stroke-width="2" rx="3"/>
+  <text x="465" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 3</text>
+
+  <rect x="560" y="80" width="150" height="50" fill="rgba(76, 175, 80, 0.6)" stroke="#4CAF50" stroke-width="2" rx="3"/>
+  <text x="635" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 4: Keep Longest</text>
+
+  <!-- Details -->
+  <text x="125" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
+  <text x="125" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
+  <text x="125" y="200" text-anchor="middle" fill="#F44336" font-size="10" font-weight="bold">Low value, stale</text>
+
+  <text x="295" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
+  <text x="295" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
+  <text x="295" y="200" text-anchor="middle" fill="#FF9800" font-size="10" font-weight="bold">Low value, recent</text>
+
+  <text x="465" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
+  <text x="465" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
+  <text x="465" y="200" text-anchor="middle" fill="#FFC107" font-size="10" font-weight="bold">High value, older</text>
+
+  <text x="635" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
+  <text x="635" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
+  <text x="635" y="200" text-anchor="middle" fill="#4CAF50" font-size="10" font-weight="bold">High value, fresh</text>
+
+  <!-- Example scenario -->
+  <text x="50" y="250" fill="#E0E0E0" font-size="13" font-weight="bold">Example Eviction Scenario:</text>
+  <text x="50" y="280" fill="#B0B0B0" font-size="11">Working Memory: 127,500 / 128,000 tokens (99% full)</text>
+  <text x="50" y="300" fill="#B0B0B0" font-size="11">New memory to add: 5,000 tokens</text>
+  <text x="50" y="320" fill="#B0B0B0" font-size="11">Need to free: 4,500 tokens</text>
+
+  <text x="50" y="350" fill="#4CAF50" font-size="11">Eviction: Remove Tier 1 and Tier 2 nodes until 4,500+ tokens freed</text>
+  <text x="50" y="370" fill="#4CAF50" font-size="11">Result: Tier 3 and Tier 4 nodes preserved (high importance)</text>
+</svg>

data/docs/assets/images/exception-hierarchy.svg

@@ -13,9 +13,9 @@
   <path d="M 350 170 L 430 170 L 430 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
   <path d="M 350 170 L 580 170 L 580 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
 
-  <!-- Ollama connection failed -->
+  <!-- Provider connection failed -->
   <rect x="20" y="200" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
-  <text x="120" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Ollama connection failed"</text>
+  <text x="120" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Provider connection failed"</text>
 
   <!-- OpenAI API error -->
   <rect x="240" y="200" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>