htm 0.0.15 → 0.0.18

data/docs/development/setup.md

@@ -187,11 +187,11 @@ Create or edit `~/.bashrc__tiger`:
 ```bash
 # TimescaleDB Connection Configuration
 export HTM_SERVICE_NAME="db-67977"  # Your service name
-export HTM_DBNAME="tsdb"
-export HTM_DBUSER="tsdbadmin"
-export HTM_DBPASS="your_password_here"
-export HTM_DBPORT="37807"  # Your port number
-export HTM_DBURL="postgres://tsdbadmin:your_password@host:port/tsdb?sslmode=require"
+export HTM_DATABASE__NAME="tsdb"
+export HTM_DATABASE__USER="tsdbadmin"
+export HTM_DATABASE__PASSWORD="your_password_here"
+export HTM_DATABASE__PORT="37807"  # Your port number
+export HTM_DATABASE__URL="postgres://tsdbadmin:your_password@host:port/tsdb?sslmode=require"
 ```
 
 Replace the placeholders with your actual connection details.
@@ -236,11 +236,11 @@ docker-compose up -d
 # Configure environment variables
 cat > ~/.bashrc__tiger <<'EOF'
 export HTM_SERVICE_NAME="local-dev"
-export HTM_DBNAME="tsdb"
-export HTM_DBUSER="tsdbadmin"
-export HTM_DBPASS="devpassword"
-export HTM_DBPORT="5432"
-export HTM_DBURL="postgres://tsdbadmin:devpassword@localhost:5432/tsdb?sslmode=disable"
+export HTM_DATABASE__NAME="tsdb"
+export HTM_DATABASE__USER="tsdbadmin"
+export HTM_DATABASE__PASSWORD="devpassword"
+export HTM_DATABASE__PORT="5432"
+export HTM_DATABASE__URL="postgres://tsdbadmin:devpassword@localhost:5432/tsdb?sslmode=disable"
 EOF
 
 source ~/.bashrc__tiger
@@ -364,7 +364,7 @@ You can also run the schema SQL directly:
 
 ```bash
 # Using psql
-psql $HTM_DBURL -f sql/schema.sql
+psql $HTM_DATABASE__URL -f sql/schema.sql
 
 # Or using Ruby
 ruby -r ./lib/htm -e "HTM::Database.setup"
@@ -478,11 +478,11 @@ HTM uses environment variables for configuration. Here's a complete reference:
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `HTM_DBURL` | Full PostgreSQL connection URL (preferred) | `postgres://user:pass@host:port/db?sslmode=require` |
-| `HTM_DBNAME` | Database name | `tsdb` |
-| `HTM_DBUSER` | Database username | `tsdbadmin` |
-| `HTM_DBPASS` | Database password | `your_password` |
-| `HTM_DBPORT` | Database port | `37807` |
+| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) | `postgres://user:pass@host:port/db?sslmode=require` |
+| `HTM_DATABASE__NAME` | Database name | `tsdb` |
+| `HTM_DATABASE__USER` | Database username | `tsdbadmin` |
+| `HTM_DATABASE__PASSWORD` | Database password | `your_password` |
+| `HTM_DATABASE__PORT` | Database port | `37807` |
 | `HTM_SERVICE_NAME` | Service identifier (informational) | `db-67977` |
 
 ### Ollama Variables
@@ -515,10 +515,10 @@ source ~/.bashrc__tiger
 
 ```bash
 # Verify environment variables are set
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 
 # Test connection directly with psql
-psql $HTM_DBURL
+psql $HTM_DATABASE__URL
 
 # Check if service is running (TimescaleDB Cloud)
 # Visit your Timescale Cloud dashboard
@@ -559,7 +559,7 @@ ollama pull gpt-oss
 ruby enable_extensions.rb
 
 # Check extension status
-psql $HTM_DBURL -c "SELECT extname, extversion FROM pg_extension ORDER BY extname"
+psql $HTM_DATABASE__URL -c "SELECT extname, extversion FROM pg_extension ORDER BY extname"
 
 # For TimescaleDB Cloud, extensions should be pre-installed
 # For local PostgreSQL, ensure you're using timescale/timescaledb-ha image
@@ -615,11 +615,11 @@ If you see SSL certificate errors:
 
 ```bash
 # Ensure sslmode is set in connection URL
-echo $HTM_DBURL | grep sslmode
+echo $HTM_DATABASE__URL | grep sslmode
 # Should show: sslmode=require
 
 # For local development without SSL
-export HTM_DBURL="postgres://user:pass@localhost:5432/tsdb?sslmode=disable"
+export HTM_DATABASE__URL="postgres://user:pass@localhost:5432/tsdb?sslmode=disable"
 ```
 
 ### Ruby Version Issues

data/docs/development/testing.md

@@ -244,7 +244,7 @@ Testing with real database:
 ```ruby
 class DatabaseIntegrationTest < Minitest::Test
   def setup
-    skip "Database not configured" unless ENV['HTM_DBURL']
+    skip "Database not configured" unless ENV['HTM_DATABASE__URL']
 
     @htm = HTM.new(
       robot_name: "Test Robot",

data/docs/getting-started/installation.md

@@ -103,24 +103,24 @@ CREATE EXTENSION IF NOT EXISTS pg_trgm;
 
 ```bash
 # Add to ~/.bashrc or your preferred config file
-export HTM_DBURL="postgres://username:password@localhost:5432/htm_db"
-export HTM_DBNAME="htm_db"
-export HTM_DBUSER="your_username"
-export HTM_DBPASS="your_password"
-export HTM_DBPORT="5432"
-export HTM_DBHOST="localhost"
+export HTM_DATABASE__URL="postgres://username:password@localhost:5432/htm_db"
+export HTM_DATABASE__NAME="htm_db"
+export HTM_DATABASE__USER="your_username"
+export HTM_DATABASE__PASSWORD="your_password"
+export HTM_DATABASE__PORT="5432"
+export HTM_DATABASE__HOST="localhost"
 
 # Load the configuration
 source ~/.bashrc
 ```
 
 !!! tip "Environment Configuration"
-    HTM automatically uses the `HTM_DBURL` environment variable if available. You can also pass database configuration directly to `HTM.new()`.
+    HTM automatically uses the `HTM_DATABASE__URL` environment variable if available. You can also pass database configuration directly to `HTM.new()`.
 
 Set environment variable:
 
 ```bash
-export HTM_DBURL="postgres://localhost/htm_db"
+export HTM_DATABASE__URL="postgres://localhost/htm_db"
 ```
 
 ## Step 3: Enable PostgreSQL Extensions
@@ -139,7 +139,7 @@ Test your database connection and verify extensions:
 cd /path/to/your/project
 ruby -e "
 require 'pg'
-conn = PG.connect(ENV['HTM_DBURL'])
+conn = PG.connect(ENV['HTM_DATABASE__URL'])
 result = conn.exec('SELECT extname, extversion FROM pg_extension ORDER BY extname')
 result.each { |row| puts \"✓ #{row['extname']}: Version #{row['extversion']}\" }
 conn.close
@@ -232,7 +232,17 @@ export OLLAMA_URL="http://custom-host:11434"
 
 Run the database setup to create HTM's tables and schema:
 
-### Option A: Using Ruby
+### Option A: Using htm_mcp CLI (Recommended)
+
+```bash
+# Initialize the database schema
+htm_mcp setup
+
+# Verify the setup
+htm_mcp verify
+```
+
+### Option B: Using Ruby
 
 ```ruby
 require 'htm'
@@ -241,29 +251,39 @@ require 'htm'
 HTM::Database.setup
 ```
 
-### Option B: Using Command Line
-
-```bash
-ruby -r ./lib/htm -e "HTM::Database.setup"
-```
-
 ### Option C: Using Rake Task (if available)
 
 ```bash
-rake db:setup
+rake htm:db:setup
 ```
 
 This creates the following tables:
 
 - **`nodes`**: Main memory storage with vector embeddings
-- **`relationships`**: Knowledge graph connections
-- **`tags`**: Flexible categorization
+- **`tags`**: Hierarchical categorization
 - **`robots`**: Robot registry
-- **`operations_log`**: Audit trail
+- **`file_sources`**: Source file metadata for loaded documents
 
 !!! success "Schema Created"
     You'll see confirmation messages as each table and index is created.
 
+### htm_mcp CLI Commands
+
+The `htm_mcp` executable provides commands for database management:
+
+| Command | Description |
+|---------|-------------|
+| `htm_mcp setup` | Initialize database schema |
+| `htm_mcp verify` | Verify connection, extensions, and migrations |
+| `htm_mcp stats` | Show memory statistics |
+| `htm_mcp help` | Show all commands and environment variables |
+| `htm_mcp` | Start the MCP server |
+
+```bash
+# Check statistics after setup
+htm_mcp stats
+```
+
 ## Step 6: Verify Installation
 
 Create a test script to verify everything works:
@@ -332,11 +352,11 @@ HTM uses the following environment variables:
 
 | Variable | Description | Default | Required |
 |----------|-------------|---------|----------|
-| `HTM_DBURL` | PostgreSQL connection URL | - | Yes |
-| `HTM_DBNAME` | Database name | `htm_db` | No |
-| `HTM_DBUSER` | Database user | `postgres` | No |
-| `HTM_DBPASS` | Database password | - | No |
-| `HTM_DBPORT` | Database port | `5432` | No |
+| `HTM_DATABASE__URL` | PostgreSQL connection URL | - | Yes |
+| `HTM_DATABASE__NAME` | Database name | `htm_db` | No |
+| `HTM_DATABASE__USER` | Database user | `postgres` | No |
+| `HTM_DATABASE__PASSWORD` | Database password | - | No |
+| `HTM_DATABASE__PORT` | Database port | `5432` | No |
 | `OLLAMA_URL` | Ollama API URL | `http://localhost:11434` | No |
 
 ### Example Configuration File
@@ -345,7 +365,7 @@ Create a configuration file for easy loading:
 
 ```bash
 # ~/.bashrc__htm
-export HTM_DBURL="postgres://user:pass@host:port/db?sslmode=require"
+export HTM_DATABASE__URL="postgres://user:pass@host:port/db?sslmode=require"
 export OLLAMA_URL="http://localhost:11434"
 ```
 
@@ -365,11 +385,11 @@ source ~/.bashrc__htm
 **Solutions**:
 
 ```bash
-# 1. Verify HTM_DBURL is set
-echo $HTM_DBURL
+# 1. Verify HTM_DATABASE__URL is set
+echo $HTM_DATABASE__URL
 
 # 2. Test connection manually
-psql $HTM_DBURL
+psql $HTM_DATABASE__URL
 
 # 3. Check if PostgreSQL is running (local installs)
 pg_ctl status
@@ -413,7 +433,7 @@ make
 sudo make install
 
 # Enable in database
-psql $HTM_DBURL -c "CREATE EXTENSION IF NOT EXISTS pgvector;"
+psql $HTM_DATABASE__URL -c "CREATE EXTENSION IF NOT EXISTS pgvector;"
 ```
 
 ### Ruby Version Issues
@@ -442,7 +462,7 @@ ruby --version
 
 ```bash
 # Ensure your database user has necessary permissions
-psql $HTM_DBURL -c "
+psql $HTM_DATABASE__URL -c "
   GRANT ALL PRIVILEGES ON DATABASE your_db TO your_user;
   GRANT ALL ON ALL TABLES IN SCHEMA public TO your_user;
 "

data/docs/getting-started/quick-start.md

@@ -125,10 +125,10 @@ Create an HTM instance for your robot:
 ```ruby
 # Configure HTM globally (optional - uses Ollama by default)
 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
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 # Initialize HTM with a robot name
@@ -338,10 +338,10 @@ puts "=" * 60
 
 # Step 1: Configure and initialize HTM
 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
+  config.embedding.model = 'nomic-embed-text:latest'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 htm = HTM.new(
@@ -522,8 +522,8 @@ htm = HTM.new(
 
 # Try different embedding models via configure
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'llama3:latest'  # Use Llama3
+  config.embedding.provider = :ollama
+  config.embedding.model = 'llama3:latest'  # Use Llama3
 end
 
 # Try different recall strategies
@@ -606,10 +606,10 @@ curl http://localhost:11434/api/version
 
 ### Issue: "Database connection failed"
 
-**Solution**: Verify your `HTM_DBURL` is set:
+**Solution**: Verify your `HTM_DATABASE__URL` is set:
 
 ```bash
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 # Should show your connection string
 ```
 

data/docs/guides/getting-started.md

@@ -55,10 +55,10 @@ HTM requires a TimescaleDB database. Set your database connection:
 
 ```bash
 # Add to your .bashrc or .zshrc
-export HTM_DBURL="postgresql://user:password@host:port/database"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/database"
 
 # Or create a config file
-echo "export HTM_DBURL='your-connection-string'" > ~/.bashrc__tiger
+echo "export HTM_DATABASE__URL='your-connection-string'" > ~/.bashrc__tiger
 source ~/.bashrc__tiger
 ```
 

data/docs/guides/long-term-memory.md

@@ -803,7 +803,7 @@ begin
   conn.close
 rescue PG::Error => e
   puts "Connection failed: #{e.message}"
-  puts "Check HTM_DBURL environment variable"
+  puts "Check HTM_DATABASE__URL environment variable"
 end
 ```