htm 0.0.17 → 0.0.18

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/setup_local_database.md

@@ -63,12 +63,12 @@ Update your `.envrc` file (already done):
 
 ```bash
 # 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=prefer"
+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=prefer"
 
 # Client-side embedding generation
 export HTM_EMBEDDINGS_PROVIDER=ollama
@@ -209,7 +209,7 @@ ollama serve
 **Solution:**
 ```bash
 direnv allow
-echo $HTM_DBURL  # Verify it's set
+echo $HTM_DATABASE__URL  # Verify it's set
 ```
 
 ## Switching Back to TimescaleDB Cloud
@@ -218,21 +218,21 @@ To switch back to TimescaleDB Cloud (production), edit `.envrc`:
 
 ```bash
 # Comment out localhost config
-# 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=prefer"
+# 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=prefer"
 
 # Uncomment TimescaleDB Cloud config
 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__URL=$TIGER_DBURL
+export HTM_DATABASE__NAME=$TIGER_DBNAME
+export HTM_DATABASE__USER=$TIGER_DBUSER
+export HTM_DATABASE__PASSWORD=$TIGER_DBPASS
+export HTM_DATABASE__HOST=$TIGER_DBHOST
+export HTM_DATABASE__PORT=$TIGER_DBPORT
 ```
 
 Then reload:

data/docs/using_rake_tasks_in_your_app.md

@@ -63,14 +63,14 @@ Create a `.envrc` file in your application's root:
 
 ```bash
 # .envrc
-export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=require"
 
 # Or use individual parameters
-export HTM_DBHOST="your-host.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="your-host.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"
 
 # Embedding configuration
 export HTM_EMBEDDINGS_PROVIDER=ollama
@@ -93,7 +93,7 @@ direnv allow
 ### Option 2: Export in Shell
 
 ```bash
-export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=require"
 rake htm:db:info
 ```
 
@@ -103,7 +103,7 @@ rake htm:db:info
 # Rakefile
 
 # Set environment variables programmatically
-ENV['HTM_DBURL'] = "postgresql://user:password@host:port/dbname?sslmode=require"
+ENV['HTM_DATABASE__URL'] = "postgresql://user:password@host:port/dbname?sslmode=require"
 
 # Then load tasks
 require 'htm/tasks'
@@ -122,7 +122,7 @@ require 'htm/tasks'
 
 ```bash
 # .env
-HTM_DBURL=postgresql://user:password@host:port/dbname?sslmode=require
+HTM_DATABASE__URL=postgresql://user:password@host:port/dbname?sslmode=require
 ```
 
 ## Real-World Example
@@ -297,13 +297,13 @@ jobs:
 
       - name: Setup database
         env:
-          HTM_DBURL: postgresql://postgres:postgres@localhost:5432/test
+          HTM_DATABASE__URL: postgresql://postgres:postgres@localhost:5432/test
         run: |
           bundle exec rake htm:db:setup
 
       - name: Run tests
         env:
-          HTM_DBURL: postgresql://postgres:postgres@localhost:5432/test
+          HTM_DATABASE__URL: postgresql://postgres:postgres@localhost:5432/test
         run: |
           bundle exec rake test
 ```
@@ -317,7 +317,7 @@ services:
   app:
     build: .
     environment:
-      - HTM_DBURL=postgresql://postgres:postgres@db:5432/myapp
+      - HTM_DATABASE__URL=postgresql://postgres:postgres@db:5432/myapp
     depends_on:
       - db
     command: bash -c "rake htm:db:setup && rake app:start"
@@ -347,10 +347,10 @@ rake -T
 Error: Database configuration not found
 ```
 
-Solution: Set `HTM_DBURL` environment variable
+Solution: Set `HTM_DATABASE__URL` environment variable
 
 ```bash
-export HTM_DBURL="postgresql://user:password@host:port/dbname"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname"
 rake htm:db:info
 ```
 

data/examples/README.md

@@ -8,12 +8,12 @@ All examples require:
 
 1. **PostgreSQL Database** with pgvector extension:
    ```bash
-   export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+   export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
    ```
 
    > **Note**: Database selection now respects `RAILS_ENV`. If `RAILS_ENV` is set,
-   > HTM extracts the base name from `HTM_DBURL` and appends the environment suffix.
-   > For example, with `HTM_DBURL=...htm_development` and `RAILS_ENV=test`, HTM
+   > HTM extracts the base name from `HTM_DATABASE__URL` and appends the environment suffix.
+   > For example, with `HTM_DATABASE__URL=...htm_development` and `HTM_ENV=test`, HTM
    > connects to `htm_test`. When `RAILS_ENV` is unset (typical for examples),
    > behavior is unchanged.
 
@@ -32,6 +32,43 @@ All examples require:
 
 ## Standalone Scripts
 
+### config_file_example/
+
+**Configuration management with source tracing.**
+
+Demonstrates how HTM uses `anyway_config` for layered configuration from multiple sources, with source tracing to show where each value originated.
+
+```bash
+cd examples/config_file_example
+ruby show_config.rb
+```
+
+**Features:**
+- Configuration priority order (defaults → XDG → project → local → env vars)
+- Source tracing showing origin of each config value
+- `HTM_CONF` environment variable for custom config file paths
+- Environment-specific configuration (`HTM_ENV`)
+- Generating config templates with `htm_mcp config`
+
+**Usage examples:**
+```bash
+# Basic - loads ./config/htm.local.yml automatically
+ruby show_config.rb
+
+# Use custom config file
+HTM_CONF=./custom_config.yml ruby show_config.rb
+
+# Override with environment variables
+HTM_EMBEDDING__MODEL=mxbai-embed-large ruby show_config.rb
+
+# Different environment
+HTM_ENV=production ruby show_config.rb
+```
+
+See [config_file_example/README.md](config_file_example/README.md) for detailed documentation.
+
+---
+
 ### basic_usage.rb
 
 **Getting started with HTM fundamentals.**
@@ -184,7 +221,7 @@ ruby examples/mcp_server.rb
       "command": "ruby",
       "args": ["/path/to/htm/examples/mcp_server.rb"],
       "env": {
-        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -260,7 +297,7 @@ ollama pull gpt-oss  # Or your preferred model
 ```
 
 **Environment Variables:**
-- `HTM_DBURL` - PostgreSQL connection (required)
+- `HTM_DATABASE__URL` - PostgreSQL connection (required)
 - `OLLAMA_URL` - Ollama server URL (default: http://localhost:11434)
 - `OLLAMA_MODEL` - Model to use (default: gpt-oss:latest)
 - `HTM_ROBOT_NAME` - Robot name (optional, prompts if not set)
@@ -313,7 +350,7 @@ bundle exec ruby app.rb
 - Tag tree visualization
 
 **Environment Variables:**
-- `HTM_DBURL` - PostgreSQL connection (required)
+- `HTM_DATABASE__URL` - PostgreSQL connection (required)
 - `REDIS_URL` - Redis for Sidekiq (default: redis://localhost:6379/0)
 - `SESSION_SECRET` - Session encryption key
 
@@ -405,6 +442,12 @@ examples/
 ├── custom_llm_configuration.rb    # LLM integration patterns
 ├── file_loader_usage.rb           # Document loading
 ├── timeframe_demo.rb              # Time-based filtering
+├── config_file_example/
+│   ├── show_config.rb             # Config source tracing demo
+│   ├── custom_config.yml          # Example for HTM_CONF
+│   ├── README.md                  # Configuration documentation
+│   └── config/
+│       └── htm.local.yml          # Auto-loaded local overrides
 ├── telemetry/
 │   ├── demo.rb                    # Live Grafana metrics dashboard
 │   ├── README.md
@@ -438,6 +481,7 @@ examples/
 | Use Case | Example |
 |----------|---------|
 | Learning HTM basics | `basic_usage.rb` |
+| Configuration management | `config_file_example/` |
 | Custom LLM integration | `custom_llm_configuration.rb` |
 | Loading documents/files | `file_loader_usage.rb` |
 | Time-based queries | `timeframe_demo.rb` |

data/examples/basic_usage.rb

@@ -4,8 +4,10 @@
 # Basic usage example for HTM
 #
 # Prerequisites:
-# 1. Set HTM_DBURL environment variable (see SETUP.md)
-# 2. Initialize database schema: rake db_setup
+# 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
 
 require_relative '../lib/htm'
@@ -13,26 +15,31 @@ require_relative '../lib/htm'
 puts "HTM Basic Usage Example"
 puts "=" * 60
 
-# Check environment
-unless ENV['HTM_DBURL']
-  puts "ERROR: HTM_DBURL not set. Please set it:"
-  puts "  export HTM_DBURL=\"postgresql://postgres@localhost:5432/htm_development\""
-  puts "See SETUP.md for details."
+# 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
 
 begin
-  # Configure HTM globally (uses Ollama by default)
+  # Configure HTM globally (uses Ollama by default from defaults.yml)
   puts "\n1. Configuring HTM with Ollama provider..."
   HTM.configure do |config|
-    config.embedding_provider = :ollama
-    config.embedding_model = 'nomic-embed-text:latest'  # Ollama models need :tag suffix
-    config.embedding_dimensions = 768
-    config.tag_provider = :ollama
-    config.tag_model = 'gemma3:latest'  # Ollama models need :tag suffix
-    config.reset_to_defaults  # Apply settings
+    config.embedding.provider = :ollama
+    config.embedding.model = 'nomic-embed-text:latest'
+    config.embedding.dimensions = 768
+    config.tag.provider = :ollama
+    config.tag.model = 'gemma3:latest'
+    # Use inline job backend for synchronous execution in examples
+    # (In production, use :thread or :sidekiq for async processing)
+    config.job.backend = :inline
+    # Quiet the logs for cleaner output
+    config.log_level = :warn
   end
-  puts "✓ HTM configured with Ollama provider"
+  puts "✓ HTM configured with Ollama provider (inline job backend)"
 
   # Initialize HTM for 'Code Helper' robot
   puts "\n2. Initializing HTM for 'Code Helper' robot..."
@@ -43,7 +50,7 @@ begin
   puts "✓ HTM initialized"
   puts "  Robot ID: #{htm.robot_id}"
   puts "  Robot Name: #{htm.robot_name}"
-  puts "  Embedding Service: Ollama (#{HTM.configuration.embedding_model})"
+  puts "  Embedding Service: #{HTM.config.embedding.provider} (#{HTM.config.embedding.model})"
 
   # Remember some information
   puts "\n3. Remembering information..."
@@ -63,15 +70,18 @@ begin
   )
   puts "✓ Remembered fact about user preferences (node #{node_id_3})"
 
-  # Sleep briefly to allow async embedding/tag jobs to start
-  sleep 0.5
+  # With inline backend, embeddings and tags are generated synchronously
+  # No sleep needed - memories are immediately searchable
 
-  # Demonstrate recall
-  puts "\n4. Recalling memories about 'database'..."
+  # Demonstrate recall using fulltext search (keyword matching)
+  # Note: hybrid search requires fulltext matches first, so search terms
+  # must appear in the stored content. Use fulltext for keyword matching.
+  puts "\n4. Recalling memories about 'PostgreSQL'..."
   memories = htm.recall(
-    "database",
+    "PostgreSQL",  # This word appears in the stored content
     timeframe: (Time.now - 3600)..Time.now,  # Last hour
     limit: 5,
+    strategy: :fulltext,  # Keyword matching (words must appear in content)
     raw: true  # Return full node data (id, content, etc.)
   )
   puts "✓ Found #{memories.length} memories"

data/examples/cli_app/README.md

@@ -15,7 +15,7 @@ This example demonstrates using HTM in a command-line application with synchrono
 1. **PostgreSQL Database**
    ```bash
    # Set database connection URL
-   export HTM_DBURL='postgresql://user:pass@host:port/dbname'
+   export HTM_DATABASE__URL='postgresql://user:pass@host:port/dbname'
 
    # Or use your existing config
    source ~/.bashrc__tiger
@@ -86,7 +86,7 @@ Unlike web applications, CLI apps use `:inline` job backend:
 
 ```ruby
 HTM.configure do |config|
-  config.job_backend = :inline  # Execute jobs synchronously
+  config.job.backend = :inline  # Execute jobs synchronously
 end
 ```
 
@@ -197,8 +197,8 @@ end
 
 ```ruby
 HTM.configure do |config|
-  config.embedding_model = 'custom-embedding-model'
-  config.tag_model = 'custom-tag-model'
+  config.embedding.model = 'custom-embedding-model'
+  config.tag.model = 'custom-tag-model'
 end
 ```
 
@@ -206,8 +206,8 @@ end
 
 ```ruby
 HTM.configure do |config|
-  config.embedding_timeout = 60   # 1 minute
-  config.tag_timeout = 120        # 2 minutes
+  config.embedding.timeout = 60   # 1 minute
+  config.tag.timeout = 120        # 2 minutes
 end
 ```
 
@@ -246,10 +246,10 @@ end
 
 ```bash
 # Verify database URL
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 
 # Test connection
-psql $HTM_DBURL -c "SELECT version();"
+psql $HTM_DATABASE__URL -c "SELECT version();"
 
 # Initialize schema if needed
 cd ../.. && rake db_setup

data/examples/cli_app/htm_cli.rb

@@ -13,7 +13,7 @@
 #   ruby htm_cli.rb
 #
 # Environment:
-#   HTM_DBURL - PostgreSQL connection URL (required)
+#   HTM_DATABASE__URL - PostgreSQL connection URL (required)
 #   OLLAMA_URL - Ollama server URL (default: http://localhost:11434)
 #
 
@@ -39,7 +39,7 @@ class HTMCli
     # Configure HTM for CLI usage
     HTM.configure do |config|
       # Use inline mode for synchronous execution
-      config.job_backend = :inline
+      config.job.backend = :inline
 
       # CLI-friendly logging
       config.logger.level = Logger::INFO
@@ -376,12 +376,12 @@ class HTMCli
 end
 
 # Check database configuration
-unless ENV['HTM_DBURL']
+unless ENV['HTM_DATABASE__URL']
   puts
-  puts "[✗] Error: HTM_DBURL environment variable not set"
+  puts "[✗] Error: HTM_DATABASE__URL environment variable not set"
   puts
   puts "Please set your database connection URL:"
-  puts "  export HTM_DBURL='postgresql://postgres@localhost:5432/htm_development'"
+  puts "  export HTM_DATABASE__URL='postgresql://postgres@localhost:5432/htm_development'"
   puts
   puts "See SETUP.md for database setup instructions."
   puts