htm 0.0.18 → 0.0.30

data/docs/{architecture → robots}/two-tier-memory.md

@@ -6,64 +6,10 @@ HTM implements a sophisticated two-tier memory architecture that balances the co
 
 The two-tier architecture addresses a fundamental challenge in LLM-based applications: LLMs have limited context windows but need to maintain awareness across long conversations spanning days, weeks, or months.
 
-<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="18" font-weight="bold">Two-Tier Memory Architecture</text>
-
-  <!-- Working Memory (Hot Tier) -->
-  <rect x="50" y="80" width="300" height="180" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="5"/>
-  <text x="200" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Working Memory (Hot)</text>
-  <text x="80" y="140" fill="#B0B0B0" font-size="12">Capacity: Token-limited (128K)</text>
-  <text x="80" y="160" fill="#B0B0B0" font-size="12">Storage: In-memory Ruby Hash</text>
-  <text x="80" y="180" fill="#B0B0B0" font-size="12">Speed: O(1) lookups</text>
-  <text x="80" y="200" fill="#B0B0B0" font-size="12">Lifetime: Process lifetime</text>
-  <text x="80" y="220" fill="#B0B0B0" font-size="12">Eviction: Importance + Recency</text>
-  <text x="80" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Fast, Token-Aware, Volatile</text>
-
-  <!-- Long-Term Memory (Cold Tier) -->
-  <rect x="450" y="80" width="300" height="180" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3" rx="5"/>
-  <text x="600" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory (Cold)</text>
-  <text x="480" y="140" fill="#B0B0B0" font-size="12">Capacity: Unlimited</text>
-  <text x="480" y="160" fill="#B0B0B0" font-size="12">Storage: PostgreSQL + TimescaleDB</text>
-  <text x="480" y="180" fill="#B0B0B0" font-size="12">Speed: O(log n) with indexes</text>
-  <text x="480" y="200" fill="#B0B0B0" font-size="12">Lifetime: Permanent</text>
-  <text x="480" y="220" fill="#B0B0B0" font-size="12">Retrieval: RAG (semantic + temporal)</text>
-  <text x="480" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Durable, Searchable, Persistent</text>
-
-  <!-- Data Flow: Add Memory -->
-  <path d="M 200 280 L 200 320 L 400 320 L 400 280" stroke="#4CAF50" stroke-width="3" fill="none" marker-end="url(#arrow-green)"/>
-  <text x="300" y="310" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Add Memory</text>
-  <text x="300" y="330" text-anchor="middle" fill="#B0B0B0" font-size="10">(Stored in both tiers)</text>
-
-  <!-- Data Flow: Eviction -->
-  <path d="M 350 360 L 600 360" stroke="#FF9800" stroke-width="3" marker-end="url(#arrow-orange)"/>
-  <text x="475" y="350" text-anchor="middle" fill="#FF9800" font-size="12" font-weight="bold">Eviction</text>
-  <text x="475" y="380" text-anchor="middle" fill="#B0B0B0" font-size="10">(Token limit → move to LTM only)</text>
-
-  <!-- Data Flow: Recall -->
-  <path d="M 600 400 L 200 400" stroke="#9C27B0" stroke-width="3" marker-end="url(#arrow-purple)"/>
-  <text x="400" y="390" text-anchor="middle" fill="#9C27B0" font-size="12" font-weight="bold">Recall</text>
-  <text x="400" y="420" text-anchor="middle" fill="#B0B0B0" font-size="10">(RAG search → load back to WM)</text>
-
-  <!-- Never Forget Note -->
-  <rect x="150" y="450" width="500" height="40" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
-  <text x="400" y="475" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">Never Forget: Evicted memories stay in LTM forever (explicit deletion only)</text>
-
-  <defs>
-    <marker id="arrow-green" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
-    </marker>
-    <marker id="arrow-orange" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
-    </marker>
-    <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>
-</svg>
+![Two-Tier Memory Architecture](../assets/images/two-tier-memory-architecture.svg)
 
 !!! info "Related ADR"
-    See [ADR-002: Two-Tier Memory Architecture](adrs/002-two-tier-memory.md) for the complete architectural decision record.
+    See [ADR-002: Two-Tier Memory Architecture](../architecture/adrs/002-two-tier-memory.md) for the complete architectural decision record.
 
 ## Working Memory (Hot Tier)
 
@@ -209,55 +155,13 @@ Nodes are evicted in this order:
 3. **High importance, old** (e.g., importance: 9.0, age: 5 days)
 4. **High importance, recent** (e.g., importance: 9.0, age: 1 hour) ← **Kept longest**
 
-<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>
+![Eviction Priority](../assets/images/eviction-priority.svg)
 
 !!! warning "Importance Matters"
     **Assign meaningful importance scores!** Low-importance memories (1.0-3.0) will be evicted first. Use higher scores (7.0-10.0) for critical information like architectural decisions, user preferences, and long-term facts.
 
 !!! info "Related ADR"
-    See [ADR-007: Working Memory Eviction Strategy](adrs/007-eviction-strategy.md) for detailed rationale and alternatives considered.
+    See [ADR-007: Working Memory Eviction Strategy](../architecture/adrs/007-eviction-strategy.md) for detailed rationale and alternatives considered.
 
 ### Context Assembly Strategies
 
@@ -352,50 +256,10 @@ context = htm.create_context(strategy: :balanced)
 # Recent debugging context + important architectural decisions
 ```
 
-<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>
+![Balanced Strategy: Importance Decay Over Time](../assets/images/balanced-strategy-decay.svg)
 
 !!! info "Related ADR"
-    See [ADR-006: Context Assembly Strategies](adrs/006-context-assembly.md) for detailed strategy analysis.
+    See [ADR-006: Context Assembly Strategies](../architecture/adrs/006-context-assembly.md) for detailed strategy analysis.
 
 ### Performance Characteristics
 
@@ -474,7 +338,7 @@ CREATE INDEX idx_nodes_value_gin ON nodes
 - Retention policies for data lifecycle
 
 !!! info "Related ADR"
-    See [ADR-001: Use PostgreSQL with TimescaleDB for Storage](adrs/001-postgresql-timescaledb.md) for complete rationale.
+    See [ADR-001: Use PostgreSQL with TimescaleDB for Storage](../architecture/adrs/001-postgresql-timescaledb.md) for complete rationale.
 
 ### Long-Term Memory Operations
 
@@ -560,7 +424,7 @@ end
 ```
 
 !!! info "Related ADR"
-    See [ADR-005: RAG-Based Retrieval with Hybrid Search](adrs/005-rag-retrieval.md) for search strategy details.
+    See [ADR-005: RAG-Based Retrieval with Hybrid Search](../architecture/adrs/005-rag-retrieval.md) for search strategy details.
 
 ### RAG-Based Retrieval
 
@@ -831,9 +695,9 @@ LIMIT 20;
 
 ## 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
 - [Hive Mind Architecture](hive-mind.md) - Multi-robot shared memory
-- [ADR-002: Two-Tier Memory Architecture](adrs/002-two-tier-memory.md)
-- [ADR-006: Context Assembly Strategies](adrs/006-context-assembly.md)
-- [ADR-007: Working Memory Eviction Strategy](adrs/007-eviction-strategy.md)
+- [ADR-002: Two-Tier Memory Architecture](../architecture/adrs/002-two-tier-memory.md)
+- [ADR-006: Context Assembly Strategies](../architecture/adrs/006-context-assembly.md)
+- [ADR-007: Working Memory Eviction Strategy](../architecture/adrs/007-eviction-strategy.md)

data/docs/robots/why-robots.md

@@ -0,0 +1,85 @@
+# Why "Robots" Instead of "Agents"?
+
+> "What's in a name? That which we call a rose
+> By any other name would smell as sweet."
+> — Shakespeare, *Romeo and Juliet*
+
+Shakespeare argues names are arbitrary. In software, we respectfully disagree—names shape expectations and understanding. The words we choose frame how we think about systems, what we expect from them, and how we architect their capabilities.
+
+HTM uses **robots** rather than the fashionable "agents" deliberately and thoughtfully.
+
+## The Problem with "Agent"
+
+The term "agent" carries philosophical baggage it cannot support:
+
+- **Semantic overload**: User agents, software agents, real estate agents, secret agents, FBI agents, travel agents. The word means everything and therefore nothing. When you say "AI agent," what mental model does your listener construct?
+
+- **False autonomy**: "Agent" implies genuine decision-making, independent action, perhaps even free will. These systems follow instructions. They predict the next token. They don't have *agency* in any meaningful philosophical sense. Calling them agents sets expectations the technology cannot meet.
+
+- **The hype cycle problem**: "AI Agent" and "Agentic AI" became buzzwords in 2023-2024, often meaning nothing more than "LLM with a prompt and a while loop." We prefer terminology that will age gracefully rather than become an embarrassing artifact of a particular moment's enthusiasm.
+
+- **Implementation reality**: Look under the hood of popular "agent" frameworks. You'll often find a system prompt, a for-loop, and some JSON parsing. Calling that an "agent" is marketing, not engineering.
+
+## The Case for "Robot"
+
+"Robot" has heritage, honesty, and heart:
+
+- **Rich literary tradition**: The word comes from Karel Čapek's 1920 play *R.U.R.* (Rossum's Universal Robots), derived from Czech *robota*, meaning forced labor or drudgery. Isaac Asimov gave us the Three Laws of Robotics and decades of thoughtful exploration of robot ethics, identity, and purpose. There's a century of serious thinking about what robots are and how they should behave. "Agent" has no comparable intellectual foundation.
+
+- **Honest about the relationship**: Robots work for us. They're tireless, reliable, and purpose-built. They don't pretend to have goals independent of their creators. This honesty about the master-worker relationship is healthier than the ambiguity of "agent."
+
+- **Cultural resonance**: Robots are endearing. R2-D2. Wall-E. Bender. Data. The Iron Giant. Baymax. We've spent a century telling stories about robots, developing affection for them, and exploring their place alongside humanity. "Agent" has no such cultural weight—it's the language of bureaucracy and espionage.
+
+- **Technical precision**: In HTM, each robot has an identity (`robot_id`), a name, and a history of contributions. Robots are registered in a table. They're tracked. They're *things* with identity and persistence. "Agent" suggests ephemerality; "robot" suggests durability.
+
+## Robots in the Hive Mind
+
+HTM's architecture reinforces the robot metaphor in a specific way: **all robots share a common long-term memory**.
+
+This is the *hive mind* pattern. Individual robots have their own working memory—their own immediate context and focus—but they draw from and contribute to a shared pool of knowledge. Like worker bees serving a hive, each robot is both individual and part of something larger.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Shared Long-Term Memory            │
+│              (The Hive Mind / Collective)           │
+│                                                     │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
+│  │ Memory  │  │ Memory  │  │ Memory  │  ...         │
+│  └─────────┘  └─────────┘  └─────────┘              │
+└─────────────────────────────────────────────────────┘
+        ▲              ▲              ▲
+        │              │              │
+   ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+   │ Robot A │    │ Robot B │    │ Robot C │
+   │         │    │         │    │         │
+   │ Working │    │ Working │    │ Working │
+   │ Memory  │    │ Memory  │    │ Memory  │
+   └─────────┘    └─────────┘    └─────────┘
+```
+
+This architecture maps naturally to the robot metaphor:
+
+- **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
+
+"Agent" suggests independence and autonomy. "Robot" suggests collaboration and purpose. HTM's robots work together, building collective intelligence. That's what the terminology should convey.
+
+## Robots Never Forget
+
+HTM follows a **never-forget philosophy** (see [ADR-009](../architecture/adrs/009-never-forget.md)). Memories are never truly deleted—only soft-deleted, always recoverable. This aligns with the robot metaphor:
+
+A good robot doesn't lose your data. A good robot remembers what you told it, years later if necessary. A good robot is *reliable* in a way that ephemeral "agents" are not.
+
+When you tell an HTM robot something important, it stores that information in the collective memory. Other robots can access it. Future robots can learn from it. The knowledge persists, attributed to the robot that first contributed it.
+
+This is robot memory done right: durable, shared, and faithful.
+
+## Honest Terminology, Clear Thinking
+
+Language shapes thought. When we call these systems "agents," we prime ourselves to expect agency—goals, autonomy, perhaps even consciousness. When we call them "robots," we remind ourselves what they actually are: sophisticated tools, tireless workers, faithful servants of the instructions we give them.
+
+HTM helps robots do their job better: remember perfectly, recall intelligently, share knowledge generously, and serve reliably. That's not agency. That's good engineering.
+
+These are robots. Let's call them what they are.

data/examples/.envrc

@@ -0,0 +1,6 @@
+# htm/examples/.envrc
+
+source_up
+
+export HTM_ENV=examples
+export HTM_DATABASE__URL="postgresql://dewayne@localhost:5432/htm_$HTM_ENV"

data/examples/.gitignore

@@ -0,0 +1,2 @@
+*.log
+*.log.0

data/examples/00_create_examples_db.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Creates and sets up the htm_examples database
+#
+# This script should be run before any other examples to ensure
+# the examples database exists and has the correct schema.
+#
+# Run via:
+#   ruby examples/00_create_examples_db.rb
+#   # or
+#   ./examples/00_create_examples_db.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+# Set examples environment BEFORE loading HTM
+ENV['HTM_ENV'] = 'examples'
+
+service_name = ENV['HTM_SERVICE__NAME'] || 'htm'
+db_name = "#{service_name}_examples"
+db_url = "postgresql://#{ENV['USER']}@localhost:5432/#{db_name}"
+
+ENV['HTM_DATABASE__URL'] = db_url
+
+puts <<~HEADER
+
+  ==========================================
+  == HTM Examples Database Setup ==
+  ==========================================
+
+  Database: #{db_name}
+
+HEADER
+
+# Step 1: Create database if it doesn't exist
+puts "1. Checking if database exists..."
+
+check_cmd = "psql -lqt | cut -d \\| -f 1 | grep -qw #{db_name}"
+db_exists = system(check_cmd)
+
+if db_exists
+  puts "   Database '#{db_name}' already exists."
+else
+  puts "   Creating database '#{db_name}'..."
+  unless system("createdb #{db_name}")
+    abort "   ERROR: Failed to create database '#{db_name}'"
+  end
+  puts "   Database created."
+end
+
+# Step 2: Enable extensions
+puts "\n2. Enabling PostgreSQL extensions..."
+
+extensions_sql = <<~SQL
+  CREATE EXTENSION IF NOT EXISTS vector;
+  CREATE EXTENSION IF NOT EXISTS pg_trgm;
+SQL
+
+unless system("psql -d #{db_name} -c \"#{extensions_sql}\" > /dev/null 2>&1")
+  abort "   ERROR: Failed to enable extensions"
+end
+puts "   Extensions enabled (pgvector, pg_trgm)."
+
+# Step 3: Run migrations
+puts "\n3. Running schema migrations..."
+
+require "htm"
+
+HTM.configure do |config|
+  config.job.backend = :inline
+  config.log_level = :info
+  config.telemetry_enabled = false
+end
+
+begin
+  HTM::SequelConfig.establish_connection!
+  HTM::Database.setup
+  puts "   Schema setup complete."
+rescue => e
+  abort "   ERROR: #{e.message}"
+end
+
+puts <<~FOOTER
+
+  ==========================================
+  Examples database is ready!
+
+  You can now run examples:
+    ruby examples/basic_usage.rb
+    rake examples:basic
+    rake examples:all
+  ==========================================
+
+FOOTER

data/examples/{basic_usage.rb → 01_basic_usage.rb}

@@ -4,25 +4,21 @@
 # Basic usage example for HTM
 #
 # Prerequisites:
-# 1. Configure database via environment or config file:
-#    - HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
-#    - Or individual vars: HTM_DATABASE__HOST, HTM_DATABASE__NAME, etc.
-# 2. Initialize database schema: rake htm:db:setup
-# 3. Install dependencies: bundle install
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: bundle install
+#
+# Run via:
+#   rake examples:basic
+#   # or
+#   ruby examples/basic_usage.rb
 
-require_relative '../lib/htm'
+require_relative 'examples_helper'
 
-puts "HTM Basic Usage Example"
-puts "=" * 60
+ExamplesHelper.section "HTM Basic Usage Example"
+ExamplesHelper.print_environment
 
-# Check database configuration using the config system
-unless HTM.config.database_configured?
-  puts "ERROR: Database not configured. Set one of:"
-  puts "  export HTM_DATABASE__URL=\"postgresql://user@localhost:5432/htm_development\""
-  puts "  Or configure in ~/.config/htm/htm.yml"
-  puts "Run 'bin/htm_mcp help' for all configuration options."
-  exit 1
-end
+# Verify database is available
+ExamplesHelper.require_database!
 
 begin
   # Configure HTM globally (uses Ollama by default from defaults.yml)

data/examples/{custom_llm_configuration.rb → 03_custom_llm_configuration.rb}

@@ -5,11 +5,21 @@
 #
 # This example demonstrates how to configure HTM with custom LLM methods
 # for embedding generation and tag extraction, as well as using defaults.
+#
+# Prerequisites:
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: bundle install
+#
+# Run via:
+#   ruby examples/custom_llm_configuration.rb
 
-require_relative '../lib/htm'
+require_relative 'examples_helper'
 
-puts "HTM Custom LLM Configuration Example"
-puts "=" * 50
+ExamplesHelper.section "HTM Custom LLM Configuration Example"
+ExamplesHelper.print_environment
+
+# Verify database is available
+ExamplesHelper.require_database!
 
 # Example 1: Use Default Configuration (RubyLLM with Ollama)
 puts "\n1. Using Default Configuration (RubyLLM + Ollama)"

data/examples/{file_loader_usage.rb → 04_file_loader_usage.rb}

@@ -10,24 +10,21 @@
 # - Unloading files
 #
 # Prerequisites:
-# 1. Set HTM_DATABASE__URL environment variable (see SETUP.md)
-# 2. Initialize database schema: rake db_setup
-# 3. Install dependencies: bundle install
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: bundle install
+#
+# Run via:
+#   ruby examples/file_loader_usage.rb
 
-require_relative '../lib/htm'
+require_relative 'examples_helper'
 require 'tempfile'
 require 'fileutils'
 
-puts "HTM File Loader Example"
-puts "=" * 60
+ExamplesHelper.section "HTM File Loader Example"
+ExamplesHelper.print_environment
 
-# Check environment
-unless ENV['HTM_DATABASE__URL']
-  puts "ERROR: HTM_DATABASE__URL not set. Please set it:"
-  puts "  export HTM_DATABASE__URL=\"postgresql://postgres@localhost:5432/htm_development\""
-  puts "See SETUP.md for details."
-  exit 1
-end
+# Verify database is available
+ExamplesHelper.require_database!
 
 begin
   # Configure HTM globally (uses Ollama by default)
@@ -102,7 +99,7 @@ begin
   puts "   Skipped: #{result[:skipped]}"
 
   # Access the file source to show frontmatter
-  source = HTM::Models::FileSource.find(result[:file_source_id])
+  source = HTM::Models::FileSource[result[:file_source_id]]
   puts "   Frontmatter title: #{source.title}"
   puts "   Frontmatter author: #{source.author}"
   puts "   Frontmatter tags: #{source.frontmatter_tags.join(', ')}"

data/examples/{timeframe_demo.rb → 05_timeframe_demo.rb}

@@ -3,10 +3,17 @@
 
 # Timeframe Demo - Demonstrates the various ways to use timeframes with recall
 #
-# Run with:
-#   HTM_DATABASE__URL="postgresql://localhost/htm_development" ruby examples/timeframe_demo.rb
+# Prerequisites:
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: bundle install
+#
+# Run via:
+#   rake examples:basic  # runs basic_usage.rb
+#   ruby examples/timeframe_demo.rb
+
+require_relative 'examples_helper'
 
-require_relative "../lib/htm"
+ExamplesHelper.require_database!
 
 puts <<~HEADER
   ╔══════════════════════════════════════════════════════════════════╗

data/examples/{example_app → 06_example_app}/app.rb

@@ -2,27 +2,27 @@
 # Example HTM Application
 #
 # This demonstrates a simple application using the HTM gem with full RubyLLM integration.
+#
+# Prerequisites:
+# 1. Set up examples database: rake examples:setup
+# 2. Install dependencies: bundle install
+#
+# Run via:
+#   ruby examples/example_app/app.rb
 
-require_relative '../../lib/htm'
+require_relative '../examples_helper'
 require 'ruby_llm'
 require 'logger'
 
 class ExampleApp
   def self.run
     puts "\n=== HTM Full-Featured Example Application ==="
-    puts "\nChecking database connection..."
-
-    # Check if database is configured
-    config = HTM::Database.default_config
-    unless config
-      puts "\n⚠ Database not configured!"
-      puts "Set HTM_DATABASE__URL environment variable:"
-      puts "  export HTM_DATABASE__URL='postgresql://user:pass@host:port/dbname'"
-      puts "\nOr run: rake app:bootstrap"
-      return
-    end
+    ExamplesHelper.print_environment
+
+    # Verify database is available
+    ExamplesHelper.require_database!
 
-    puts "✓ Database configured: #{config[:dbname]} @ #{config[:host]}"
+    puts "Database configured: #{HTM.config.actual_database_name}"
 
     # Configure HTM with RubyLLM for embeddings and tag generation
     puts "\nConfiguring HTM with RubyLLM..."
@@ -95,7 +95,7 @@ class ExampleApp
     # Check what was generated
     puts "\n--- Generated Tags ---"
     [node_1, node_2, node_3].each do |node_id|
-      node = HTM::Models::Node.includes(:tags).find(node_id)
+      node = HTM::Models::Node[node_id]
       if node.tags.any?
         puts "Node #{node_id}:"
         node.tags.each { |tag| puts "  - #{tag.name}" }
@@ -107,7 +107,7 @@ class ExampleApp
     # Check embeddings
     puts "\n--- Embedding Status ---"
     [node_1, node_2, node_3].each do |node_id|
-      node = HTM::Models::Node.find(node_id)
+      node = HTM::Models::Node[node_id]
       if node.embedding
         dimensions = node.embedding.is_a?(Array) ? node.embedding.size : node.embedding_dimension
         status = "✓ Generated (#{dimensions} dimensions)"