htm 0.0.17 → 0.0.20

data/docs/guides/telemetry.md

@@ -0,0 +1,229 @@
+# Telemetry
+
+HTM includes optional OpenTelemetry-based metrics for observability. Telemetry is disabled by default with zero overhead when off.
+
+## Overview
+
+When enabled, HTM emits metrics for:
+
+- **Job execution** - Embedding generation and tag extraction jobs
+- **Latency tracking** - Operation timing for embeddings, tags, and search
+- **Cache effectiveness** - Hit/miss rates for query caching
+- **Search performance** - Query latency by strategy
+
+## Quick Start
+
+### Enable Telemetry
+
+```ruby
+HTM.configure do |config|
+  config.telemetry_enabled = true
+end
+```
+
+Or via environment variable:
+
+```bash
+export HTM_TELEMETRY_ENABLED=true
+```
+
+### Install Dependencies
+
+Telemetry uses optional OpenTelemetry gems (user installs if needed):
+
+```ruby
+# Add to Gemfile
+gem 'opentelemetry-sdk'
+gem 'opentelemetry-metrics-sdk'
+gem 'opentelemetry-exporter-otlp'  # For OTLP export
+```
+
+### Configure Export Destination
+
+```bash
+# Export to OTLP-compatible backend
+export OTEL_METRICS_EXPORTER="otlp"
+export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
+```
+
+## Available Metrics
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `htm.jobs` | Counter | job, status | Job execution counts (embedding, tags) |
+| `htm.embedding.latency` | Histogram | provider, status | Embedding generation time (ms) |
+| `htm.tag.latency` | Histogram | provider, status | Tag extraction time (ms) |
+| `htm.search.latency` | Histogram | strategy | Search operation time (ms) |
+| `htm.cache.operations` | Counter | operation (hit/miss) | Query cache effectiveness |
+
+## Compatible Backends
+
+HTM telemetry is OTLP-compatible and works with:
+
+### Open Source
+
+- **Jaeger** - Distributed tracing
+- **Prometheus + Grafana** - Metrics and visualization
+- **Grafana Tempo/Mimir** - Metrics and traces
+- **SigNoz** - Full-stack observability
+- **Uptrace** - APM with traces and metrics
+
+### Commercial
+
+- **Datadog**
+- **New Relic**
+- **Honeycomb**
+- **Splunk**
+- **Dynatrace**
+- **AWS X-Ray**
+- **Google Cloud Trace**
+- **Azure Monitor**
+
+## Prometheus + Grafana Setup
+
+### Install Services (macOS)
+
+```bash
+brew install prometheus grafana
+brew services start prometheus grafana
+```
+
+### Configure Prometheus Scrape
+
+Add to `/opt/homebrew/etc/prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: 'htm'
+    scrape_interval: 5s
+    static_configs:
+      - targets: ['localhost:9394']
+```
+
+### Expose Metrics Endpoint
+
+```ruby
+require 'prometheus/client'
+require 'webrick'
+
+# Create metrics endpoint
+server = WEBrick::HTTPServer.new(Port: 9394)
+server.mount_proc '/metrics' do |req, res|
+  res['Content-Type'] = 'text/plain'
+  res.body = Prometheus::Client::Formats::Text.marshal(
+    Prometheus::Client.registry
+  )
+end
+
+Thread.new { server.start }
+```
+
+### Grafana Dashboard
+
+A pre-configured dashboard is available at:
+`examples/telemetry/grafana/dashboards/htm-metrics.json`
+
+Import via Grafana UI:
+1. Go to Dashboards > Import
+2. Upload the JSON file
+3. Select your Prometheus data source
+
+## Design
+
+HTM uses the null object pattern for telemetry:
+
+- **Disabled**: All metric operations are no-ops with zero overhead
+- **SDK not installed**: Gracefully degrades with no errors
+- **Enabled**: Full metric collection and export
+
+```ruby
+# No-op when disabled
+HTM::Telemetry.record_job(:embedding, :success)  # Does nothing
+
+# Active when enabled
+HTM.configure { |c| c.telemetry_enabled = true }
+HTM::Telemetry.record_job(:embedding, :success)  # Records metric
+```
+
+## Observability Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    HTM Application                      │
+│                                                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
+│  │   remember  │  │    recall   │  │    jobs     │     │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
+│         │                │                │             │
+│         └────────────────┼────────────────┘             │
+│                          │                              │
+│              ┌───────────▼───────────┐                  │
+│              │  HTM::Observability   │                  │
+│              └───────────┬───────────┘                  │
+└──────────────────────────┼──────────────────────────────┘
+                           │
+                           ▼
+              ┌─────────────────────────┐
+              │   OpenTelemetry SDK     │
+              └───────────┬─────────────┘
+                          │
+           ┌──────────────┼──────────────┐
+           ▼              ▼              ▼
+      ┌─────────┐   ┌─────────┐   ┌─────────┐
+      │Prometheus│   │  Jaeger │   │ Datadog │
+      └─────────┘   └─────────┘   └─────────┘
+```
+
+## Example: Live Demo
+
+Run the included telemetry demo:
+
+```bash
+cd examples/telemetry
+ruby demo.rb
+```
+
+This will:
+1. Start Prometheus and Grafana services
+2. Run HTM operations in a loop
+3. Export metrics to Prometheus
+4. Open Grafana dashboard in your browser
+
+## Best Practices
+
+### Development
+
+```ruby
+# Disable telemetry in development (default)
+HTM.configure do |config|
+  config.telemetry_enabled = false
+end
+```
+
+### Production
+
+```ruby
+# Enable with OTLP export
+HTM.configure do |config|
+  config.telemetry_enabled = true
+end
+
+# Environment variables for backend
+ENV['OTEL_METRICS_EXPORTER'] = 'otlp'
+ENV['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'https://your-backend.com:4318'
+```
+
+### Testing
+
+```ruby
+# Always disable in tests
+HTM.configure do |config|
+  config.telemetry_enabled = false
+end
+```
+
+## See Also
+
+- [Telemetry Example](../examples/telemetry.md)
+- [Observability API](../api/yard/HTM/Observability.md)
+- [OpenTelemetry Ruby](https://opentelemetry.io/docs/languages/ruby/)

data/docs/index.md

@@ -1,15 +1,5 @@
 
 <div align="center">
-  <div style="background: linear-gradient(135deg, #ffd93d 0%, #f5c800 100%); border: 4px solid #e6b800; border-radius: 12px; padding: 20px; margin: 20px auto; max-width: 800px; box-shadow: 0 8px 16px rgba(230, 184, 0, 0.3);">
-    <p style="color: #000000; font-size: 42px; font-weight: bold; margin: 0;">
-      💣 CAUTION 💣
-    </p>
-    <p style="color: #000; font-size: 27px; font-weight: bold; margin: 10px 0 0 0; line-height: 1.6;">
-      This documentation may contain <strong>inaccuracies</strong>.<br/>
-      Verify critical details in the source code and example demos.
-    </p>
-  </div>
-
   <img src="assets/images/htm_demo.gif" alt="Tree of Knowledge" width="800">
 </div>
 
@@ -48,7 +38,7 @@ HTM follows a "never forget unless explicitly told" principle:
 
 HTM uses advanced Retrieval-Augmented Generation techniques:
 
-- **Vector Similarity Search**: Semantic search using pgvector with embeddings from Ollama
+- **Vector Similarity Search**: Semantic search using pgvector with embeddings via RubyLLM (multiple providers supported)
 - **Full-Text Search**: PostgreSQL full-text search for keyword matching
 - **Hybrid Search**: Combines both vector and full-text for best results
 - **Temporal Filtering**: Natural language time queries like "last week" or "yesterday"
@@ -79,12 +69,14 @@ Here's how simple it is to get started with HTM:
 ```ruby
 require 'htm'
 
-# Configure HTM globally (optional - uses Ollama by default)
+# Configure HTM globally (optional - defaults to Ollama for local development)
+# HTM uses RubyLLM which supports multiple providers:
+# :ollama (default), :openai, :anthropic, :gemini, :azure, :bedrock, :deepseek
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.embedding.provider = :ollama           # or :openai, etc.
+  config.embedding.model = 'nomic-embed-text'   # provider-specific model
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 # Initialize HTM for your robot
@@ -146,7 +138,7 @@ HTM consists of several key components working together:
 - **HTM API**: Main interface for all memory operations
 - **WorkingMemory**: Token-limited in-memory cache for immediate LLM use
 - **LongTermMemory**: PostgreSQL-backed durable storage
-- **EmbeddingService**: Generates vector embeddings via RubyLLM and Ollama
+- **EmbeddingService**: Generates vector embeddings via RubyLLM (supports Ollama, OpenAI, Anthropic, Gemini, Azure, Bedrock, DeepSeek, and more)
 - **Database**: Schema management and connection pooling
 
 ## Memory Types
@@ -166,7 +158,7 @@ Each type can have custom importance scores, tags, and relationships.
 
 Ready to add intelligent memory to your LLM application? Follow these steps:
 
-1. **[Installation](getting-started/installation.md)**: Set up HTM, PostgreSQL, TimescaleDB, and Ollama
+1. **[Installation](getting-started/installation.md)**: Set up HTM, PostgreSQL, and your preferred LLM provider
 2. **[Quick Start](getting-started/quick-start.md)**: Build your first HTM-powered application in 5 minutes
 3. **[User Guide](guides/getting-started.md)**: Deep dive into all HTM features
 4. **[API Reference](api/htm.md)**: Complete API documentation

data/docs/multi_framework_support.md

@@ -15,7 +15,7 @@ require 'htm'
 
 # Configure for CLI (synchronous execution)
 HTM.configure do |config|
-  config.job_backend = :inline  # Jobs run immediately
+  config.job.backend = :inline  # Jobs run immediately
 end
 
 htm = HTM.new(robot_name: "cli_assistant")
@@ -151,7 +151,7 @@ HTM.configuration.job_backend  # => :thread
 
 ```ruby
 HTM.configure do |config|
-  config.job_backend = :inline  # Force synchronous
+  config.job.backend = :inline  # Force synchronous
 end
 ```
 
@@ -177,7 +177,7 @@ export HTM_JOB_BACKEND=inline  # Override auto-detection
 ```ruby
 # Use inline backend
 HTM.configure do |config|
-  config.job_backend = :inline
+  config.job.backend = :inline
 
   # CLI-friendly logging
   config.logger.formatter = proc do |severity, datetime, progname, msg|
@@ -253,8 +253,8 @@ gem 'htm'
 
 # config/initializers/htm.rb (optional)
 HTM.configure do |config|
-  config.embedding_model = 'nomic-embed-text'
-  config.tag_model = 'llama3'
+  config.embedding.model = 'nomic-embed-text'
+  config.tag.model = 'llama3'
 end
 ```
 
@@ -397,8 +397,8 @@ bundle exec sidekiq
 ```ruby
 # Use faster/smaller models
 HTM.configure do |config|
-  config.embedding_model = 'all-minilm'  # Smaller, faster
-  config.tag_model = 'gemma2:2b'         # Smaller model
+  config.embedding.model = 'all-minilm'  # Smaller, faster
+  config.tag.model = 'gemma2:2b'         # Smaller model
 end
 
 # Or disable features
@@ -438,7 +438,7 @@ end
 
 # After (explicit inline):
 HTM.configure do |config|
-  config.job_backend = :inline
+  config.job.backend = :inline
 end
 # Jobs run synchronously, guaranteed to complete
 ```

data/docs/{architecture → robots}/hive-mind.md

@@ -6,61 +6,10 @@ HTM implements a "hive mind" architecture where multiple robots (AI agents) shar
 
 In the hive mind model, all robots access a single shared long-term memory database while maintaining independent working memory for process isolation. This design provides the best of both worlds: global knowledge sharing with local performance optimization.
 
-<svg viewBox="0 0 900 600" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="450" y="30" text-anchor="middle" fill="#E0E0E0" font-size="18" font-weight="bold">Hive Mind: Shared Long-Term Memory</text>
-
-  <!-- Central Database -->
-  <ellipse cx="450" cy="300" rx="180" ry="120" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3"/>
-  <text x="450" y="280" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory</text>
-  <text x="450" y="305" text-anchor="middle" fill="#B0B0B0" font-size="12">PostgreSQL</text>
-  <text x="450" y="325" text-anchor="middle" fill="#B0B0B0" font-size="12">Shared Global Database</text>
-  <text x="450" y="345" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">All Robots Access Here</text>
-
-  <!-- Robot 1: Code Helper -->
-  <rect x="50" y="80" width="200" height="100" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="2" rx="5"/>
-  <text x="150" y="110" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 1: Code Helper</text>
-  <text x="150" y="135" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-abc123</text>
-  <text x="150" y="155" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
-
-  <!-- Robot 2: Research Assistant -->
-  <rect x="650" y="80" width="200" height="100" fill="rgba(76, 175, 80, 0.2)" stroke="#4CAF50" stroke-width="2" rx="5"/>
-  <text x="750" y="110" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 2: Research Bot</text>
-  <text x="750" y="135" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-xyz789</text>
-  <text x="750" y="155" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
-
-  <!-- Robot 3: Chat Companion -->
-  <rect x="50" y="450" width="200" height="100" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="2" rx="5"/>
-  <text x="150" y="480" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 3: Chat Bot</text>
-  <text x="150" y="505" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-def456</text>
-  <text x="150" y="525" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
-
-  <!-- Robot 4: Design Assistant -->
-  <rect x="650" y="450" width="200" height="100" fill="rgba(244, 67, 54, 0.2)" stroke="#F44336" stroke-width="2" rx="5"/>
-  <text x="750" y="480" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 4: Designer</text>
-  <text x="750" y="505" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-ghi012</text>
-  <text x="750" y="525" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
-
-  <!-- Connections to central database -->
-  <line x1="150" y1="180" x2="320" y2="240" stroke="#2196F3" stroke-width="3"/>
-  <line x1="750" y1="180" x2="580" y2="240" stroke="#4CAF50" stroke-width="3"/>
-  <line x1="150" y1="450" x2="320" y2="360" stroke="#FF9800" stroke-width="3"/>
-  <line x1="750" y1="450" x2="580" y2="360" stroke="#F44336" stroke-width="3"/>
-
-  <!-- Labels on connections -->
-  <text x="235" y="210" fill="#2196F3" font-size="10">read/write</text>
-  <text x="650" y="210" fill="#4CAF50" font-size="10">read/write</text>
-  <text x="235" y="410" fill="#FF9800" font-size="10">read/write</text>
-  <text x="650" y="410" fill="#F44336" font-size="10">read/write</text>
-
-  <!-- Key benefit -->
-  <rect x="300" y="520" width="300" height="60" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="2" rx="5"/>
-  <text x="450" y="545" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">Knowledge Sharing:</text>
-  <text x="450" y="565" text-anchor="middle" fill="#B0B0B0" font-size="11">All robots see all memories</text>
-</svg>
+![Hive Mind: Shared Long-Term Memory](../assets/images/hive-mind-shared-memory.svg)
 
 !!! info "Related ADR"
-    See [ADR-004: Multi-Robot Shared Memory (Hive Mind)](adrs/004-hive-mind.md) for the complete architectural decision record.
+    See [ADR-004: Multi-Robot Shared Memory (Hive Mind)](../architecture/adrs/004-hive-mind.md) for the complete architectural decision record.
 
 ## Why Hive Mind?
 
@@ -96,59 +45,7 @@ HTM uses a hybrid memory topology:
 - **Long-Term Memory**: Shared globally across all robots
 - **Working Memory**: Per-robot, process-local
 
-<svg viewBox="0 0 800 500" 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">Memory Topology: Shared LTM + Local WM</text>
-
-  <!-- Legend -->
-  <rect x="50" y="50" width="20" height="20" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0"/>
-  <text x="80" y="65" fill="#B0B0B0" font-size="12">Shared (Global)</text>
-  <rect x="200" y="50" width="20" height="20" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3"/>
-  <text x="230" y="65" fill="#B0B0B0" font-size="12">Per-Robot (Local)</text>
-
-  <!-- Robot 1 -->
-  <g transform="translate(0, 100)">
-    <text x="150" y="0" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 1 (Process 1)</text>
-    <rect x="50" y="20" width="200" height="80" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="2" rx="5"/>
-    <text x="150" y="50" text-anchor="middle" fill="#E0E0E0" font-size="12">Working Memory</text>
-    <text x="150" y="70" text-anchor="middle" fill="#B0B0B0" font-size="10">In-memory, token-limited</text>
-    <text x="150" y="85" text-anchor="middle" fill="#B0B0B0" font-size="10">Independent</text>
-  </g>
-
-  <!-- Robot 2 -->
-  <g transform="translate(300, 100)">
-    <text x="150" y="0" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 2 (Process 2)</text>
-    <rect x="50" y="20" width="200" height="80" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="2" rx="5"/>
-    <text x="150" y="50" text-anchor="middle" fill="#E0E0E0" font-size="12">Working Memory</text>
-    <text x="150" y="70" text-anchor="middle" fill="#B0B0B0" font-size="10">In-memory, token-limited</text>
-    <text x="150" y="85" text-anchor="middle" fill="#B0B0B0" font-size="10">Independent</text>
-  </g>
-
-  <!-- Shared Long-Term Memory -->
-  <rect x="150" y="280" width="500" height="150" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3" rx="5"/>
-  <text x="400" y="310" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory (Shared)</text>
-  <text x="400" y="340" text-anchor="middle" fill="#B0B0B0" font-size="12">PostgreSQL</text>
-  <text x="400" y="365" text-anchor="middle" fill="#B0B0B0" font-size="12">All robots read/write here</text>
-  <text x="400" y="390" text-anchor="middle" fill="#B0B0B0" font-size="12">Memories attributed with robot_id</text>
-  <text x="400" y="410" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Single Source of Truth</text>
-
-  <!-- Connections -->
-  <line x1="150" y1="200" x2="300" y2="280" stroke="#9C27B0" stroke-width="2" marker-end="url(#arrow-purple)"/>
-  <line x1="450" y1="200" x2="400" y2="280" stroke="#9C27B0" stroke-width="2" marker-end="url(#arrow-purple)"/>
-
-  <text x="225" y="240" fill="#9C27B0" font-size="10">read/write</text>
-  <text x="425" y="240" fill="#9C27B0" font-size="10">read/write</text>
-
-  <defs>
-    <marker id="arrow-purple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
-    </marker>
-  </defs>
-
-  <!-- Key Point -->
-  <rect x="100" y="460" width="600" height="30" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
-  <text x="400" y="480" text-anchor="middle" fill="#4CAF50" font-size="12">Each robot has fast local cache (WM) + access to global knowledge (LTM)</text>
-</svg>
+![Memory Topology: Shared LTM + Local WM](../assets/images/memory-topology.svg)
 
 ### Why This Design?
 
@@ -248,7 +145,7 @@ end
 ```
 
 !!! info "Related ADR"
-    See [ADR-008: Robot Identification System](adrs/008-robot-identification.md) for detailed design decisions.
+    See [ADR-008: Robot Identification System](../architecture/adrs/008-robot-identification.md) for detailed design decisions.
 
 ## Memory Attribution and Deduplication
 
@@ -727,9 +624,9 @@ end
 
 ## Related Documentation
 
-- [Architecture Index](index.md) - System overview and component summary
-- [Architecture Overview](overview.md) - Detailed architecture and data flows
+- [Architecture Index](../architecture/index.md) - System overview and component summary
+- [Architecture Overview](../architecture/overview.md) - Detailed architecture and data flows
 - [Two-Tier Memory System](two-tier-memory.md) - Working memory and long-term memory design
-- [ADR-004: Multi-Robot Shared Memory (Hive Mind)](adrs/004-hive-mind.md)
-- [ADR-008: Robot Identification System](adrs/008-robot-identification.md)
+- [ADR-004: Multi-Robot Shared Memory (Hive Mind)](../architecture/adrs/004-hive-mind.md)
+- [ADR-008: Robot Identification System](../architecture/adrs/008-robot-identification.md)
 - [API Reference](../api/htm.md) - Complete API documentation

data/docs/robots/index.md

@@ -0,0 +1,73 @@
+# Robots
+
+HTM uses **robots** rather than the fashionable "agents" deliberately and thoughtfully. This section explains why, and how HTM's robot architecture enables intelligent memory management for LLM-based applications.
+
+## Section Overview
+
+| Document | Description |
+|----------|-------------|
+| [Why "Robots"?](why-robots.md) | The philosophical and practical reasons HTM uses "robot" terminology |
+| [Hive Mind](hive-mind.md) | How all robots share a common long-term memory |
+| [Two-Tier Memory](two-tier-memory.md) | The working memory and long-term storage architecture |
+| [Multi-Robot Systems](multi-robot.md) | Running multiple robots with shared knowledge |
+| [Robot Groups](robot-groups.md) | Organizing robots into collaborative groups |
+
+## The Robot Philosophy
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Shared Long-Term Memory            │
+│              (The Hive Mind / Collective)           │
+│                                                     │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
+│  │ Memory  │  │ Memory  │  │ Memory  │  ...         │
+│  └─────────┘  └─────────┘  └─────────┘              │
+└─────────────────────────────────────────────────────┘
+        ▲              ▲              ▲
+        │              │              │
+   ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+   │ Robot A │    │ Robot B │    │ Robot C │
+   │         │    │         │    │         │
+   │ Working │    │ Working │    │ Working │
+   │ Memory  │    │ Memory  │    │ Memory  │
+   └─────────┘    └─────────┘    └─────────┘
+```
+
+**Robots are workers**: They execute tasks, store memories, recall information.
+
+**Robots are individuals**: Each has its own name, identity, and working context.
+
+**Robots are collective**: They share knowledge, learn from each other's experiences.
+
+**Robots are persistent**: They're registered, tracked, and their contributions are attributed.
+
+## Quick Start
+
+```ruby
+# Create a robot
+htm = HTM.new(robot_name: "research_assistant")
+
+# Robot remembers information
+htm.remember("PostgreSQL supports vector search via pgvector")
+
+# Robot recalls relevant memories
+memories = htm.recall("database search capabilities", limit: 5)
+
+# Another robot can access the same memories
+htm2 = HTM.new(robot_name: "documentation_writer")
+memories = htm2.recall("vector search")  # Finds the first robot's memory
+```
+
+## Key Concepts
+
+- **Robot Identity**: Each robot has a unique name and ID, tracked in the `robots` table
+- **Working Memory**: Token-limited context for immediate use (per-robot)
+- **Long-Term Memory**: Durable PostgreSQL storage (shared across all robots)
+- **Hive Mind**: All robots contribute to and benefit from collective knowledge
+- **Never Forget**: Memories are never truly deleted, only soft-deleted
+
+## See Also
+
+- [Getting Started Guide](../getting-started/index.md)
+- [ADR-004: Hive Mind Architecture](../architecture/adrs/004-hive-mind.md)
+- [ADR-008: Robot Identification](../architecture/adrs/008-robot-identification.md)

data/docs/{guides → robots}/multi-robot.md

@@ -765,6 +765,6 @@ team.process_feature("oauth-integration")
 
 ## Next Steps
 
-- [**Context Assembly**](context-assembly.md) - Build context from multi-robot memories
-- [**Long-term Memory**](long-term-memory.md) - Understand the shared storage layer
-- [**Search Strategies**](search-strategies.md) - Find relevant memories across robots
+- [**Context Assembly**](../guides/context-assembly.md) - Build context from multi-robot memories
+- [**Long-term Memory**](../guides/long-term-memory.md) - Understand the shared storage layer
+- [**Search Strategies**](../guides/search-strategies.md) - Find relevant memories across robots

data/docs/{guides → robots}/robot-groups.md

@@ -1,6 +1,6 @@
 # Robot Groups: Coordinated Multi-Robot Systems
 
-Robot Groups extend HTM's [Hive Mind architecture](../architecture/hive-mind.md) by adding real-time coordination, shared working memory, and automatic failover capabilities. While the Hive Mind enables knowledge sharing through a shared long-term memory database, Robot Groups take this further by synchronizing active working memory across multiple robots in real-time.
+Robot Groups extend HTM's [Hive Mind architecture](hive-mind.md) by adding real-time coordination, shared working memory, and automatic failover capabilities. While the Hive Mind enables knowledge sharing through a shared long-term memory database, Robot Groups take this further by synchronizing active working memory across multiple robots in real-time.
 
 ## Overview
 
@@ -87,12 +87,13 @@ channel.stop_listening
 ```ruby
 require 'htm'
 
-# Configure HTM
+# Configure HTM (optional - uses Ollama by default)
+# Supports: :ollama, :openai, :anthropic, :gemini, :azure, :bedrock, :deepseek
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text'
-  config.tag_provider = :ollama
-  config.tag_model = 'llama3'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 # Create a robot group with active and passive members
@@ -384,10 +385,10 @@ require 'htm'
 worker_name = ARGV[0] || "worker-#{Process.pid}"
 group_name = 'distributed-service'
 
-# Configure HTM
+# Configure HTM (uses configured provider, defaults to Ollama)
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text'
+  config.embedding.provider = :ollama  # or :openai, :gemini, etc.
+  config.embedding.model = 'nomic-embed-text'
 end
 
 # Create HTM instance for this worker
@@ -573,7 +574,7 @@ Single-process demo showing:
 - Real-time sync via LISTEN/NOTIFY
 
 ```bash
-HTM_DBURL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/same_process.rb
+HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/same_process.rb
 ```
 
 ### multi_process.rb
@@ -585,7 +586,7 @@ Multi-process demo showing:
 - Dynamic scaling by spawning new processes
 
 ```bash
-HTM_DBURL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/multi_process.rb
+HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/multi_process.rb
 ```
 
 ### robot_worker.rb
@@ -597,8 +598,8 @@ Standalone worker process that:
 
 ## Related Documentation
 
-- [Hive Mind Architecture](../architecture/hive-mind.md) - Foundation for shared memory
+- [Hive Mind Architecture](hive-mind.md) - Foundation for shared memory
 - [Multi-Robot Usage](multi-robot.md) - Basic multi-robot patterns
-- [Working Memory](working-memory.md) - How working memory operates
+- [Working Memory](../guides/working-memory.md) - How working memory operates
 - [API Reference: RobotGroup](../api/yard/HTM/RobotGroup.md) - Complete API documentation
 - [API Reference: WorkingMemoryChannel](../api/yard/HTM/WorkingMemoryChannel.md) - Low-level pub/sub API