htm 0.0.15 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ae4db5f168c495f5afef19f740f16ee9b39136cd54403f54090921cb6952275
-  data.tar.gz: 454816f53e620a72efeae7bd8b6c0a30c459403b4f1b6a3d0ca7adf30f3cda7c
+  metadata.gz: 7379c23800bf3f00cc328be9725b14bcea06a9d2158eaf3b3bca80b11a6efb74
+  data.tar.gz: ec96095a72ab89fed1dd7df0ceaeb3888938f5ddbdea6fd3f3c06aa15b80bf67
 SHA512:
-  metadata.gz: 52adbf798f4004961936f9112878d245c6872bf812611efa47bc9b7808ba39510d79d0902f109db8169e1cd0d5420338094edd7719f995f67c1b3def07a2a4d2
-  data.tar.gz: 7ac9e6a8913b9b836ddfdfdb909857ac62bdd2c5d6c6c904c2a257224fc80499a118afd3d63a3a14d0daed838e11c02b2f2149eddb8c0385ebb2d5be9ab258f8
+  metadata.gz: 428b9c8f1db0f3a7a4be6e0b8bc4cc27f0bf058e7847c409cfca423c1bf9722a8efad92dbdd276d69844ab771670ea7cdc62e292018bec4705ed3f9f66255c16
+  data.tar.gz: af62a40339de40eac22f90b919a626b0f2d61a14440cdd5ca9e0aaf87ca088cc086cd35bc1eb4394d87a0646512c0a30d2fb47fdee7ec9ea2c4f11e469f2a44b

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,34 +2,22 @@
 
 export RR=`pwd`
 
+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

@@ -6,6 +6,144 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [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
+- **HTM_ENV environment variable** - Non-Rails users can now use `HTM_ENV` instead of `RAILS_ENV`
+  - Priority: `HTM_ENV` > `RAILS_ENV` > `RACK_ENV` > `'development'`
+  - `HTM.env` returns the current environment name
+  - `HTM.test?`, `HTM.development?`, `HTM.production?` helper methods
+  - Example: `HTM_ENV=test htm_mcp setup`
+- **MCP CLI subcommands** - `bin/htm_mcp` now supports multiple commands for database management
+  - `htm_mcp setup` / `htm_mcp init` - Initialize database schema
+  - `htm_mcp verify` - Verify database connection, extensions, and migration status
+  - `htm_mcp stats` - Show memory statistics including database size and file sources
+  - `htm_mcp version` - Show HTM version
+  - `htm_mcp help` - Comprehensive help with all environment variables
+  - `htm_mcp` / `htm_mcp server` / `htm_mcp stdio` - Start MCP server (default behavior)
+- **Migration status display** - `htm_mcp verify` now shows applied/pending migrations with +/- indicators
+- **Database size in stats** - `htm_mcp stats` displays database size via `pg_size_pretty`
+- **Error suggestions** - CLI provides helpful suggestions for common database errors (connection refused, missing database, auth failures, missing extensions)
+- **Rails demo application** - Full-featured web UI for exploring HTM capabilities
+  - Located in `examples/rails_app/` - minimal Rails 7.2 application
+  - **Dashboard** - Overview of memories, robots, tags, and files with quick stats
+  - **Memories** - Browse, create, edit, delete, and restore memories with tag filtering
+  - **Search** - Semantic search with vector/fulltext/hybrid strategies and strategy comparison mode
+  - **Tags** - Hierarchical tag browser with memory counts
+  - **Robots** - View robots, switch active robot, see memory associations
+  - **Files** - Load markdown files via path or native file picker, directory uploads, sync tracking
+  - Dark theme UI using Tailwind CSS
+  - Upload progress overlay with stage indicators
+  - Error handling with graceful degradation for search failures
+- **FileSource#needs_sync? default argument** - Now works without argument by reading file mtime from filesystem
+- **RobotGroup MCP tools** - 12 new tools for high-availability robot coordination
+  - `CreateGroupTool` - Create a new robot group with shared working memory
+  - `ListGroupsTool` - List all active robot groups in the session
+  - `GetGroupStatusTool` - Get detailed status of a robot group
+  - `JoinGroupTool` - Add a robot to an existing group
+  - `LeaveGroupTool` - Remove a robot from a group
+  - `GroupRememberTool` - Store memory shared across group members
+  - `GroupRecallTool` - Recall memories from a group's shared context
+  - `GetGroupWorkingMemoryTool` - Get a group's working memory contents
+  - `PromoteRobotTool` - Promote a passive robot to active role
+  - `FailoverTool` - Trigger failover to next available robot
+  - `SyncGroupTool` - Synchronize group state across members
+  - `ShutdownGroupTool` - Gracefully shutdown a robot group
+- **RobotGroups MCP resource** - `htm://groups` returns active robot groups and their status
+- **MCPGroupSession module** - Session state management for robot groups in MCP server
+- **MCP server test suite** - 59 tests with 174 assertions covering all tools and resources
+
+### Changed
+- **Renamed `bin/htm_mcp.rb` to `bin/htm_mcp`** - Cleaner executable name without extension
+- **MCP server refactored into modules** - Code moved from monolithic file to `lib/htm/mcp/`:
+  - `lib/htm/mcp/cli.rb` - CLI command handling
+  - `lib/htm/mcp/server.rb` - Server setup and lifecycle
+  - `lib/htm/mcp/tools.rb` - Individual MCP tools (11 tools)
+  - `lib/htm/mcp/group_tools.rb` - Robot group tools (12 tools)
+  - `lib/htm/mcp/resources.rb` - MCP resources (4 resources)
+- **README.md MCP section** - Reorganized tools by category (Session & Memory, Robot Group)
+- **docs/guides/mcp-server.md** - Comprehensive RobotGroup tools documentation with examples, updated for CLI commands
+
+### Fixed
+- **MCP server direct execution** - Added `require 'bundler/setup'` to `bin/htm_mcp` for execution without `bundle exec`
+  - Fixes timeout issues when MCP clients invoke the server directly
+  - Server now loads gems correctly from Gemfile when run as `./bin/htm_mcp`
+- **ontology_test.rb** - Added `configure_htm_with_mocks` to prevent real LLM calls during tests
+  - `test_node_creation_without_tags` and `test_empty_tag_array_no_topics` now pass
+- **job_adapter_test.rb** - Fixed environment detection test to properly handle `HTM_ENV` priority
+  - Test now saves and restores all relevant environment variables (`HTM_ENV`, `RAILS_ENV`, `RACK_ENV`)
 
 ## [0.0.15] - 2025-12-06