htm 0.0.17 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 964868a160989db5a7f8baa524e89d82552166f5d065f30685a17597ddec627b
-  data.tar.gz: 963b4d21d30ee51d08c34af26a1d2d1284b17d03ac39734ad81be0d0b3cd1a45
+  metadata.gz: 73eb1c7c8727363608ac47f7c1afd26ebb47021a173c105e5bba364598bf143f
+  data.tar.gz: e9c6954e8bb6da65e26ea55878da3e817e59f28e3383d74f9b48a0501ebd882b
 SHA512:
-  metadata.gz: 2c061077debb17b3bcee1c70e1136cdf8d1248ca100815adb75eb522aa39c40ac1a8863c07684d89da36a7c8df37f6b22b3c98669939cfaf177ea37d51716435
-  data.tar.gz: 49b6ec15849051d17c85261d7529374d7d5f95be381b96415c10e0e883b08c3f52c5b3303c04ae850376dd23682dd4f387218eed1c6a5b1fab28c2f8eac2c183
+  metadata.gz: cb76637105f6033ba58d35f5fe3d73b41b990bd327069c7c526c196c787c62d2287e0fdac58261a2ee7b6d739af9f11bd58843c77b7ad6b486da95e02468665e
+  data.tar.gz: 9e4da2a308bfb5efe31a050406caee29e7a653e401a9665a271b3c094d540d50115663966f11f26b7b58a51f7a9354047ee6117ce69250e7dc5ffabb30469a48

data/.architecture/decisions/adrs/001-use-postgresql-timescaledb-storage.md

@@ -115,7 +115,7 @@ We will use **PostgreSQL with TimescaleDB** as the primary storage backend for H
 ### Connection Configuration
 ```ruby
 # Via environment variable (preferred)
-ENV['HTM_DBURL'] = "postgresql://user:pass@host:port/dbname?sslmode=require"
+ENV['HTM_DATABASE__URL'] = "postgresql://user:pass@host:port/dbname?sslmode=require"
 
 # Parsed into connection hash
 {

data/.architecture/decisions/adrs/011-database-side-embedding-generation-with-pgai.md

@@ -284,7 +284,7 @@ LIMIT $3;
 ruby enable_extensions.rb
 
 # 2. Run database schema with triggers
-psql $HTM_DBURL < sql/schema.sql
+psql $HTM_DATABASE__URL < sql/schema.sql
 
 # 3. Use HTM normally - embeddings automatic!
 ruby -r ./lib/htm -e "HTM.new(robot_name: 'Bot').add_node('test', 'value')"
@@ -294,16 +294,16 @@ ruby -r ./lib/htm -e "HTM.new(robot_name: 'Bot').add_node('test', 'value')"
 
 ```bash
 # 1. Backup database
-pg_dump $HTM_DBURL > htm_backup.sql
+pg_dump $HTM_DATABASE__URL > htm_backup.sql
 
 # 2. Enable pgai extension
 ruby enable_extensions.rb
 
 # 3. Apply new schema (adds triggers)
-psql $HTM_DBURL < sql/schema.sql
+psql $HTM_DATABASE__URL < sql/schema.sql
 
 # 4. (Optional) Regenerate embeddings with new model
-psql $HTM_DBURL -c "UPDATE nodes SET value = value;"
+psql $HTM_DATABASE__URL -c "UPDATE nodes SET value = value;"
 # This triggers embedding regeneration for all nodes
 ```
 

data/.architecture/decisions/adrs/012-llm-driven-ontology-topic-extraction.md

@@ -333,7 +333,7 @@ htm.add_node('memory_001', 'PostgreSQL with TimescaleDB handles time-series data
 HTM::Database.migrate
 
 # 2. (Optional) Re-extract topics for existing nodes
-psql $HTM_DBURL -c "UPDATE nodes SET value = value;"
+psql $HTM_DATABASE__URL -c "UPDATE nodes SET value = value;"
 # Triggers topic extraction for all existing nodes
 ```
 

data/.envrc

@@ -2,35 +2,22 @@
 
 export RR=`pwd`
 
-export RAILS_ENV=development
+export HTM_ENV=development
 export HTM_EXTRACT_PROPOSITIONS=true
 
 # Database connection - Localhost PostgreSQL
-export HTM_DBHOST=localhost
-export HTM_DBPORT=5432
-export HTM_DBNAME=htm_development
-export HTM_DBUSER=${USER}
-export HTM_DBPASS=
-export HTM_DBURL="postgresql://${HTM_DBUSER}@${HTM_DBHOST}:${HTM_DBPORT}/${HTM_DBNAME}?sslmode=disable"
-# export HTM_DBURL="postgresql://dewayne@localhost:5432/htm_development"
-
-# Uncomment if using TimescaleDB Cloud instead:
-# export HTM_SERVICE_NAME=$TIGER_SERVICE_NAME
-# export HTM_DBURL=$TIGER_DBURL
-# export HTM_DBNAME=$TIGER_DBNAME
-# export HTM_DBUSER=$TIGER_DBUSER
-# export HTM_DBPASS=$TIGER_DBPASS
-# export HTM_DBHOST=$TIGER_DBHOST
-# export HTM_DBPORT=$TIGER_DBPORT
+export HTM_DATABASE__HOST=localhost
+export HTM_DATABASE__PORT=5432
+export HTM_DATABASE__NAME=htm_development
+export HTM_DATABASE__USER=${USER}
+export HTM_DATABASE__PASSWORD=
+export HTM_DATABASE__URL="postgresql://${HTM_DATABASE__USER}@${HTM_DATABASE__HOST}:${HTM_DATABASE__PORT}/${HTM_DATABASE__NAME}?sslmode=disable"
 
 # Client-side embedding generation
-# HTM generates embeddings before inserting into database
-export HTM_EMBEDDINGS_PROVIDER=ollama
-export HTM_EMBEDDINGS_MODEL=embeddinggemma
-export HTM_EMBEDDINGS_BASE_URL=http://localhost:11434
-export HTM_EMBEDDINGS_DIMENSION=768
+export HTM_EMBEDDING__PROVIDER=ollama
+export HTM_EMBEDDING__MODEL=embeddinggemma
+export HTM_EMBEDDING__DIMENSIONS=768
 
 # Topic extraction (client-side)
-export HTM_TOPIC_PROVIDER=ollama
-export HTM_TOPIC_MODEL=phi4
-export HTM_TOPIC_BASE_URL=http://localhost:11434
+export HTM_TAG__PROVIDER=ollama
+export HTM_TAG__MODEL=phi4

data/.irbrc

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # HTM Interactive Development Console
-# Usage: HTM_DBURL="postgresql://user@localhost:5432/htm_development" irb
+# Usage: HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development" irb
 
 require_relative 'lib/htm'
 require 'debug_me'
@@ -21,12 +21,12 @@ end
 
 # Configure HTM with sensible defaults for interactive use
 HTM.configure do |config|
-  config.job_backend = :inline
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.embedding_dimensions = 768
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.job.backend = :inline
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.embedding.dimensions = 768
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
   config.reset_to_defaults
 end
 puts "✓ HTM configured (inline jobs, Ollama provider)"

data/.tbls.yml

@@ -1,9 +1,9 @@
 # tbls configuration for HTM database documentation
 # https://github.com/k1LoW/tbls
 
-# Database connection - uses HTM_DBURL environment variable
+# Database connection - uses HTM_DATABASE__URL environment variable
 # tbls expands environment variables with $VAR or ${VAR} syntax
-dsn: $HTM_DBURL
+dsn: $HTM_DATABASE__URL
 
 # Output documentation to docs/database directory
 docPath: docs/database

data/CHANGELOG.md

@@ -7,6 +7,128 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.20] - 2025-12-22
+### Added
+- **Fiber-based job backend** - New `:fiber` backend for I/O-bound background jobs
+  - Uses `async` gem for cooperative concurrency
+  - Non-blocking execution ideal for LLM API calls
+  - `JobAdapter.enqueue_parallel(jobs)` for concurrent job execution
+  - Fiber backend runs jobs with `Async::Barrier` for parallel coordination
+- **RememberWorkflow using simple_flow** - Parallel processing pipeline for node enrichment
+  - Orchestrates save_node → (embedding, tags, propositions in parallel) → finalize
+  - Uses `SimpleFlow::Pipeline` with dependency-based step execution
+  - Configurable concurrency model (`:auto`, `:threads`, `:async`)
+  - Visualization support: `to_mermaid` and `execution_plan` methods
+
+### Changed
+- **async gem is now a required dependency** - Previously optional, now always available
+  - Enables fiber-based concurrency for all HTM installations
+  - `:fiber` is now the default job backend (was `:thread`)
+- **Default job backend changed from `:thread` to `:fiber`** - Better performance for I/O-bound LLM operations
+
+### Removed
+- **`JobAdapter.async_available?` method** - No longer needed since async is always available
+
+### Fixed
+- **`connection_timeout` default inconsistency** - Unified default to 60 seconds across all files
+  - `test/configuration_test.rb`, `docs/guides/configuration.md`, and `db/seeds.rb` now match `defaults.yml`
+
+### Dependencies
+- Added `async` (~> 2.0) as required runtime dependency
+- Added `simple_flow` for workflow orchestration
+
+## [0.0.19] - 2025-12-21
+
+### Changed
+- **Reorganized "Robots!" documentation** - Consolidated 5 robot-related docs into `docs/robots/` subdirectory
+  - Created `docs/robots/index.md` as section overview with navigation table and architecture diagram
+  - Moved `docs/robots.md` → `docs/robots/why-robots.md`
+  - Moved `docs/guides/multi-robot.md` → `docs/robots/multi-robot.md`
+  - Moved `docs/guides/robot-groups.md` → `docs/robots/robot-groups.md`
+  - Moved `docs/architecture/two-tier-memory.md` → `docs/robots/two-tier-memory.md`
+  - Moved `docs/architecture/hive-mind.md` → `docs/robots/hive-mind.md`
+  - Updated `mkdocs.yml` navigation with logical information flow
+  - Fixed 30+ broken relative links across documentation files
+- **Extracted inline SVG graphics to standalone files** - Improved documentation maintainability
+  - From `hive-mind.md`: `hive-mind-shared-memory.svg`, `memory-topology.svg`
+  - From `two-tier-memory.md`: `two-tier-memory-architecture.svg`, `eviction-priority.svg`, `balanced-strategy-decay.svg`
+  - All SVGs now in `docs/assets/images/` and referenced via markdown image syntax
+
+### Fixed
+- **ConfigSection.md unrecognized link warning** - Wrapped method signatures in backticks to prevent MkDocs interpreting bracket parameters as links
+
+## [0.0.18] - 2025-12-20
+### Added
+- **Anyway::Config-based configuration system** - Replaced custom Configuration class with robust multi-source config management
+  - **Multi-layer configuration loading** with priority (lowest to highest):
+    1. Bundled defaults (`lib/htm/config/defaults.yml`)
+    2. XDG user config (`~/.config/htm/htm.yml`)
+    3. Project config (`./config/htm.yml`)
+    4. Local overrides (`./config/htm.local.yml`) - gitignored for secrets
+    5. Environment variables (`HTM_*`)
+    6. Programmatic (`HTM.configure` block)
+  - **Nested configuration access**: `HTM.config.database.host`, `HTM.config.embedding.model`, etc.
+  - **Environment-specific overrides**: Different defaults for development, test, and production environments
+  - **Configuration source tracing**: Debug where each configuration value originated
+- **YAML-based prompt templates** - Tag and proposition extraction prompts now configurable via YAML
+  - Prompts use `%{placeholder}` syntax for runtime interpolation
+  - System and user prompts for tag extraction: `tag.system_prompt`, `tag.user_prompt_template`
+  - System and user prompts for proposition extraction: `proposition.system_prompt`, `proposition.user_prompt_template`
+  - Taxonomy context templates: `tag.taxonomy_context_existing`, `tag.taxonomy_context_empty`
+- **New loaders for configuration sources**:
+  - `HTM::Loaders::DefaultsLoader` - Loads bundled gem defaults from YAML
+  - `HTM::Loaders::XDGConfigLoader` - Loads XDG-compliant user configuration
+- **Configuration management example** - New `examples/config_file_example/` directory
+  - `show_config.rb` - Demonstrates configuration source tracing
+  - Sample configuration files showing override mechanisms
+  - Comprehensive README with configuration patterns
+
+### Changed
+- **BREAKING: Database environment variables renamed** - Migrate from `HTM_DBURL`/`HTM_DB*` to namespaced format
+  - `HTM_DBURL` → `HTM_DATABASE__URL`
+  - `HTM_DATABASE` → `HTM_DATABASE__NAME`
+  - `HTM_DB_USER` → `HTM_DATABASE__USER`
+  - `HTM_DB_PASSWORD` → `HTM_DATABASE__PASSWORD`
+  - `HTM_DB_HOST` → `HTM_DATABASE__HOST`
+  - `HTM_DB_PORT` → `HTM_DATABASE__PORT`
+  - Uses double underscore (`__`) for nested config (Anyway::Config convention)
+- **Configuration access patterns updated** - Direct attributes → nested configuration
+  - `config.embedding_provider` → `config.embedding.provider`
+  - `config.embedding_model` → `config.embedding.model`
+  - `config.tag_provider` → `config.tag.provider`
+  - `config.tag_model` → `config.tag.model`
+  - `config.chunk_size` → `config.chunking.size`
+  - `config.chunk_overlap` → `config.chunking.overlap`
+- **Removed `config/database.yml`** - Replaced by flexible YAML configuration files
+- **Prompt generation refactored** - Hardcoded prompt strings moved to `defaults.yml` templates
+- **MCP CLI enhanced** - Improved command handling and configuration output display
+
+### Removed
+- **`HTM::Configuration` class** - Replaced by `HTM::Config` using Anyway::Config
+- **Legacy database environment variable support** - Must use new `HTM_DATABASE__*` format
+
+### Dependencies
+- Added `anyway_config` gem for configuration management
+
+### Migration Guide
+Update your environment variables:
+```bash
+# Old format
+export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+
+# New format
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
+```
+
+Update configuration access:
+```ruby
+# Old pattern
+HTM.configuration.embedding_model
+
+# New pattern
+HTM.config.embedding.model
+```
+
 ## [0.0.17] - 2025-12-18
 
 ### Added
@@ -618,7 +740,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Working memory size is user-configurable
 - See ADRs for detailed architectural decisions and rationale
 
-[Unreleased]: https://github.com/madbomber/htm/compare/v0.0.12...HEAD
+[Unreleased]: https://github.com/madbomber/htm/compare/v0.0.19...HEAD
+[0.0.19]: https://github.com/madbomber/htm/compare/v0.0.18...v0.0.19
+[0.0.18]: https://github.com/madbomber/htm/compare/v0.0.17...v0.0.18
+[0.0.17]: https://github.com/madbomber/htm/compare/v0.0.15...v0.0.17
+[0.0.15]: https://github.com/madbomber/htm/compare/v0.0.14...v0.0.15
+[0.0.14]: https://github.com/madbomber/htm/compare/v0.0.13...v0.0.14
+[0.0.13]: https://github.com/madbomber/htm/compare/v0.0.11...v0.0.13
+[0.0.11]: https://github.com/madbomber/htm/compare/v0.0.10...v0.0.11
 [0.0.12]: https://github.com/madbomber/htm/compare/v0.0.10...v0.0.12
 [0.0.10]: https://github.com/madbomber/htm/compare/v0.0.9...v0.0.10
 [0.0.9]: https://github.com/madbomber/htm/compare/v0.0.8...v0.0.9

data/README.md

@@ -1,4 +1,16 @@
+
 <div align="center">
+  <div style="background: linear-gradient(135deg, #90EE90 0%, #32CD32 100%); border: 4px solid #228B22; border-radius: 12px; padding: 20px; margin: 20px auto; max-width: 800px; box-shadow: 0 8px 16px rgba(34, 139, 34, 0.3);">
+    <p style="color: #000000; font-size: 42px; font-weight: bold; margin: 0;">
+        🚀 v0.0.20 🚀
+    </p>
+    <p style="color: #000; font-size: 27px; font-weight: bold; margin: 10px 0 0 0; line-height: 1.6;">
+        <strong>Fiber-based concurrency</strong> is now the default.<br/>
+        Parallel embedding, tagging, and proposition extraction via simple_flow.
+    </p>
+  </div>
+
+
   <h1>HTM</h1>
   <img src="docs/assets/images/htm_demo.gif" alt="Tree of Knowledge is Growing" width="400">
 
@@ -39,7 +51,7 @@ HTM includes a Model Context Protocol server with 23 tools for memory management
   "mcpServers": {
     "htm": {
       "command": "htm_mcp",
-      "env": { "HTM_DBURL": "postgresql://localhost/htm" }
+      "env": { "HTM_DATABASE__URL": "postgresql://localhost/htm" }
     }
   }
 }

data/Rakefile

@@ -10,16 +10,21 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
-# Ensure test task runs with RAILS_ENV=test
+# Ensure test task runs with HTM_ENV=test (takes priority over RAILS_ENV/RACK_ENV)
 task :test do
-  ENV['RAILS_ENV'] = 'test'
+  ENV['HTM_ENV'] = 'test'
 end
 
 # Prepend environment setup before test runs
 Rake::Task[:test].enhance [:set_test_env]
 
 task :set_test_env do
-  ENV['RAILS_ENV'] = 'test'
+  ENV['HTM_ENV'] = 'test'
+  # Set database URL if not already configured
+  # Uses current system user for local PostgreSQL connection
+  unless ENV['HTM_DATABASE__URL']
+    ENV['HTM_DATABASE__URL'] = "postgresql://#{ENV['USER']}@localhost:5432/htm_test"
+  end
 end
 
 task default: :test

data/SETUP.md

@@ -60,10 +60,10 @@ psql htm_development -c "SELECT extname, extversion FROM pg_extension;"
 
 ```bash
 # Add to your ~/.bashrc or ~/.zshrc
-export HTM_DBURL="postgresql://postgres@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://postgres@localhost:5432/htm_development"
 
 # Or for a specific user with password
-export HTM_DBURL="postgresql://username:password@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://username:password@localhost:5432/htm_development"
 ```
 
 ### 5. Verify Connection
@@ -136,12 +136,12 @@ export OLLAMA_URL="http://custom-host:11434"
 
 | Variable | Description | Example Value |
 |----------|-------------|---------------|
-| `HTM_DBURL` | Full PostgreSQL connection URL (preferred) | `postgresql://postgres@localhost:5432/htm_development` |
-| `HTM_DBNAME` | Database name (fallback) | `htm_development` |
-| `HTM_DBUSER` | Database user (fallback) | `postgres` |
-| `HTM_DBPASS` | Database password (fallback) | `` |
-| `HTM_DBHOST` | Database host (fallback) | `localhost` |
-| `HTM_DBPORT` | Database port (fallback) | `5432` |
+| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) | `postgresql://postgres@localhost:5432/htm_development` |
+| `HTM_DATABASE__NAME` | Database name (fallback) | `htm_development` |
+| `HTM_DATABASE__USER` | Database user (fallback) | `postgres` |
+| `HTM_DATABASE__PASSWORD` | Database password (fallback) | `` |
+| `HTM_DATABASE__HOST` | Database host (fallback) | `localhost` |
+| `HTM_DATABASE__PORT` | Database port (fallback) | `5432` |
 | `OLLAMA_URL` | Ollama server URL | `http://localhost:11434` |
 
 ## Development Workflow
@@ -150,7 +150,7 @@ export OLLAMA_URL="http://custom-host:11434"
 
 ```bash
 # 1. Set database URL (if not in shell config)
-export HTM_DBURL="postgresql://postgres@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://postgres@localhost:5432/htm_development"
 
 # 2. Install dependencies
 bundle install
@@ -196,7 +196,7 @@ HTM/
 │   │   ├── configuration.rb      # Multi-provider LLM config
 │   │   └── version.rb            # Version constant
 ├── config/
-│   └── database.yml              # Database configuration
+│   └── defaults.yml              # Default configuration values
 ├── db/
 │   └── schema.sql                # Database schema
 ├── test/
@@ -248,10 +248,10 @@ If you get connection errors:
 
 ```bash
 # Verify environment variable is set
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 
 # Test connection manually
-psql $HTM_DBURL -c "SELECT 1"
+psql $HTM_DATABASE__URL -c "SELECT 1"
 
 # Check PostgreSQL is running
 brew services list | grep postgresql  # macOS

data/bin/htm_mcp

@@ -13,10 +13,6 @@
 #   htm_mcp version      # Show HTM version
 #   htm_mcp help         # Show help and environment variables
 
-# Setup bundler to load gems from Gemfile
-# This allows running the script directly without `bundle exec`
-require 'bundler/setup'
-
 require_relative '../lib/htm'
 require_relative '../lib/htm/mcp/cli'
 

data/db/seed_data/README.md

@@ -23,8 +23,8 @@ The seeding process uses environment variables for configuration. All settings h
 
 ### Database Settings
 
-- `HTM_DBURL` - Full PostgreSQL connection URL (required)
-- Or individual settings: `HTM_DBHOST`, `HTM_DBPORT`, `HTM_DBNAME`, `HTM_DBUSER`, `HTM_DBPASS`
+- `HTM_DATABASE__URL` - Full PostgreSQL connection URL (required)
+- Or individual settings: `HTM_DATABASE__HOST`, `HTM_DATABASE__PORT`, `HTM_DATABASE__NAME`, `HTM_DATABASE__USER`, `HTM_DATABASE__PASSWORD`
 
 ### Other Settings
 

data/db/seeds.rb

@@ -15,7 +15,7 @@
 #   HTM_EMBEDDING_TIMEOUT - Embedding generation timeout in seconds (default: 120)
 #   HTM_TAG_TIMEOUT - Tag generation timeout in seconds (default: 180)
 #   HTM_CONNECTION_TIMEOUT - LLM connection timeout in seconds (default: 30)
-#   HTM_DBURL - Database connection URL
+#   HTM_DATABASE__URL - Database connection URL
 #
 # Usage:
 #   rake htm:db:seed
@@ -37,7 +37,7 @@ tag_provider = (ENV['HTM_TAG_PROVIDER'] || 'ollama').to_sym
 tag_model = ENV['HTM_TAG_MODEL'] || 'gemma3'
 embedding_timeout = (ENV['HTM_EMBEDDING_TIMEOUT'] || '120').to_i
 tag_timeout = (ENV['HTM_TAG_TIMEOUT'] || '180').to_i
-connection_timeout = (ENV['HTM_CONNECTION_TIMEOUT'] || '30').to_i
+connection_timeout = (ENV['HTM_CONNECTION_TIMEOUT'] || '60').to_i
 
 puts "Configuration:"
 puts "  Embedding Provider: #{embedding_provider}"
@@ -64,7 +64,7 @@ end
 puts "✓ HTM configured"
 puts
 
-# Create HTM instance (uses default database config from ENV['HTM_DBURL'])
+# Create HTM instance (uses default database config from ENV['HTM_DATABASE__URL'])
 htm = HTM.new(robot_name: ENV['HTM_ROBOT_NAME'] || "Seed Robot")
 
 # Add sample conversation messages

data/docs/api/database.md

@@ -38,7 +38,7 @@ HTM::Database.setup(db_url = nil)
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `db_url` | String, nil | `ENV['HTM_DBURL']` | Database connection URL |
+| `db_url` | String, nil | `ENV['HTM_DATABASE__URL']` | Database connection URL |
 
 #### Returns
 
@@ -170,25 +170,25 @@ HTM::Database.parse_connection_params()
 #### Returns
 
 - `Hash` - Connection configuration
-- `nil` - If `ENV['HTM_DBNAME']` not set
+- `nil` - If `ENV['HTM_DATABASE__NAME']` not set
 
 #### Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HTM_DBHOST` | Database hostname | `'cw7rxj91bm.srbbwwxn56.tsdb.cloud.timescale.com'` |
-| `HTM_DBPORT` | Database port | `37807` |
-| `HTM_DBNAME` | Database name | *required* |
-| `HTM_DBUSER` | Database user | *required* |
-| `HTM_DBPASS` | Database password | *required* |
+| `HTM_DATABASE__HOST` | Database hostname | `'cw7rxj91bm.srbbwwxn56.tsdb.cloud.timescale.com'` |
+| `HTM_DATABASE__PORT` | Database port | `37807` |
+| `HTM_DATABASE__NAME` | Database name | *required* |
+| `HTM_DATABASE__USER` | Database user | *required* |
+| `HTM_DATABASE__PASSWORD` | Database password | *required* |
 
 #### Examples
 
 ```ruby
 # Set environment variables
-ENV['HTM_DBNAME'] = 'tsdb'
-ENV['HTM_DBUSER'] = 'tsdbadmin'
-ENV['HTM_DBPASS'] = 'secret'
+ENV['HTM_DATABASE__NAME'] = 'tsdb'
+ENV['HTM_DATABASE__USER'] = 'tsdbadmin'
+ENV['HTM_DATABASE__PASSWORD'] = 'secret'
 
 config = HTM::Database.parse_connection_params()
 # => {
@@ -201,14 +201,14 @@ config = HTM::Database.parse_connection_params()
 # }
 
 # Custom host and port
-ENV['HTM_DBHOST'] = 'localhost'
-ENV['HTM_DBPORT'] = '5432'
+ENV['HTM_DATABASE__HOST'] = 'localhost'
+ENV['HTM_DATABASE__PORT'] = '5432'
 
 config = HTM::Database.parse_connection_params()
 # => { host: "localhost", port: 5432, ... }
 
-# Without HTM_DBNAME
-ENV.delete('HTM_DBNAME')
+# Without HTM_DATABASE__NAME
+ENV.delete('HTM_DATABASE__NAME')
 config = HTM::Database.parse_connection_params()
 # => nil
 ```
@@ -230,29 +230,29 @@ HTM::Database.default_config()
 
 #### Priority Order
 
-1. `ENV['HTM_DBURL']` - Parse connection URL
-2. `ENV['HTM_DBNAME']` - Parse individual params
+1. `ENV['HTM_DATABASE__URL']` - Parse connection URL
+2. `ENV['HTM_DATABASE__NAME']` - Parse individual params
 3. `nil` - No configuration available
 
 #### Examples
 
 ```ruby
-# Using HTM_DBURL
-ENV['HTM_DBURL'] = 'postgresql://user:pass@host/db'
+# Using HTM_DATABASE__URL
+ENV['HTM_DATABASE__URL'] = 'postgresql://user:pass@host/db'
 config = HTM::Database.default_config
 # => Parsed from URL
 
-# Using HTM_DBNAME
-ENV.delete('HTM_DBURL')
-ENV['HTM_DBNAME'] = 'mydb'
-ENV['HTM_DBUSER'] = 'user'
-ENV['HTM_DBPASS'] = 'pass'
+# Using HTM_DATABASE__NAME
+ENV.delete('HTM_DATABASE__URL')
+ENV['HTM_DATABASE__NAME'] = 'mydb'
+ENV['HTM_DATABASE__USER'] = 'user'
+ENV['HTM_DATABASE__PASSWORD'] = 'pass'
 config = HTM::Database.default_config
 # => Parsed from params
 
 # No configuration
-ENV.delete('HTM_DBURL')
-ENV.delete('HTM_DBNAME')
+ENV.delete('HTM_DATABASE__URL')
+ENV.delete('HTM_DATABASE__NAME')
 config = HTM::Database.default_config
 # => nil
 
@@ -341,33 +341,33 @@ Using URL (recommended):
 
 ```bash
 # In ~/.bashrc__tiger
-export HTM_DBURL='postgresql://tsdbadmin:PASSWORD@SERVICE.tsdb.cloud.timescale.com:37807/tsdb?sslmode=require'
+export HTM_DATABASE__URL='postgresql://tsdbadmin:PASSWORD@SERVICE.tsdb.cloud.timescale.com:37807/tsdb?sslmode=require'
 ```
 
 Using individual variables:
 
 ```bash
 # In ~/.bashrc__tiger
-export HTM_DBHOST='xxx.tsdb.cloud.timescale.com'
-export HTM_DBPORT=37807
-export HTM_DBNAME='tsdb'
-export HTM_DBUSER='tsdbadmin'
-export HTM_DBPASS='your_password'
+export HTM_DATABASE__HOST='xxx.tsdb.cloud.timescale.com'
+export HTM_DATABASE__PORT=37807
+export HTM_DATABASE__NAME='tsdb'
+export HTM_DATABASE__USER='tsdbadmin'
+export HTM_DATABASE__PASSWORD='your_password'
 ```
 
 ### Local PostgreSQL
 
 ```bash
-export HTM_DBURL='postgresql://localhost/htm_dev'
+export HTM_DATABASE__URL='postgresql://localhost/htm_dev'
 
 # Or with auth
-export HTM_DBURL='postgresql://user:pass@localhost:5432/htm_dev'
+export HTM_DATABASE__URL='postgresql://user:pass@localhost:5432/htm_dev'
 ```
 
 ### Docker PostgreSQL
 
 ```bash
-export HTM_DBURL='postgresql://postgres:postgres@localhost:5432/htm'
+export HTM_DATABASE__URL='postgresql://postgres:postgres@localhost:5432/htm'
 ```
 
 ---
@@ -402,7 +402,7 @@ if config
   puts "Port: #{config[:port]}"
 else
   puts "No database configuration found"
-  puts "Please set HTM_DBURL or HTM_DBNAME environment variables"
+  puts "Please set HTM_DATABASE__URL or HTM_DATABASE__NAME environment variables"
 end
 
 # Test connection
@@ -493,7 +493,7 @@ pg_isready -h localhost -p 5432
 psql -h localhost -U user -d dbname
 
 # Verify environment
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 ```
 
 ### Permission Denied
@@ -576,7 +576,7 @@ end
 config = HTM::Database.default_config
 
 unless config
-  raise "Database not configured. Please set HTM_DBURL environment variable. " \
+  raise "Database not configured. Please set HTM_DATABASE__URL environment variable. " \
         "See README.md for configuration instructions."
 end
 ```