htm 0.0.15 → 0.0.17

data/bin/htm_mcp

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# HTM MCP Server with CLI management commands
+#
+# Usage:
+#   htm_mcp              # Start MCP server (default)
+#   htm_mcp server       # Start MCP server (explicit)
+#   htm_mcp setup        # Initialize database
+#   htm_mcp init         # Initialize database (alias for setup)
+#   htm_mcp verify       # Verify database connection
+#   htm_mcp stats        # Show memory statistics
+#   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'
+
+# Handle CLI commands (exits if command handled)
+# Returns false if server should start
+unless HTM::MCP::CLI.run(ARGV) == false
+  exit 0
+end
+
+# Start MCP server
+require_relative '../lib/htm/mcp/server'
+HTM::MCP::Server.start

data/config/database.yml

@@ -9,15 +9,18 @@
 # Example HTM_DBURL format:
 #   postgresql://user:password@host:port/database?sslmode=require
 #
+# Environment detection priority:
+#   HTM_ENV > RAILS_ENV > RACK_ENV > 'development'
+#
 # Test database:
-#   Tests always use htm_test database (Rails convention).
-#   Set RAILS_ENV=test or RACK_ENV=test to use the test configuration.
+#   Tests always use htm_test database.
+#   Set HTM_ENV=test (or RAILS_ENV=test) to use the test configuration.
 
 <%
   require 'uri'
 
-  # Determine current environment
-  current_env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+  # Determine current environment (HTM_ENV takes priority for non-Rails users)
+  current_env = ENV['HTM_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
 
   # Parse connection from HTM_DBURL or use individual variables
   if ENV['HTM_DBURL']

data/docs/getting-started/installation.md

@@ -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:

data/docs/guides/mcp-server.md

@@ -4,7 +4,7 @@ HTM includes a Model Context Protocol (MCP) server that exposes memory capabilit
 
 ## Overview
 
-The MCP server (`bin/htm_mcp.rb`) uses [FastMCP](https://github.com/yjacket/fast-mcp) to expose HTM's memory operations as MCP tools and resources. Any MCP-compatible client can connect to the server and use HTM's memory capabilities.
+The MCP server (`bin/htm_mcp`) uses [FastMCP](https://github.com/yjacket/fast-mcp) to expose HTM's memory operations as MCP tools and resources. Any MCP-compatible client can connect to the server and use HTM's memory capabilities.
 
 ### Key Features
 
@@ -13,6 +13,7 @@ The MCP server (`bin/htm_mcp.rb`) uses [FastMCP](https://github.com/yjacket/fast
 - **Session restore**: Restore previous session context from working memory
 - **Fuzzy search**: Typo-tolerant tag and topic search
 - **Resource access**: Query statistics, tag hierarchy, and recent memories
+- **Robot Groups (High-Availability)**: Coordinate multiple robots with shared working memory, failover, and real-time sync
 
 ## Prerequisites
 
@@ -26,7 +27,7 @@ Before using the MCP server, ensure you have:
 2. **PostgreSQL database set up**
    ```bash
    export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
-   rake htm:db:setup
+   htm_mcp setup
    ```
 
 3. **Ollama running** (for embeddings and tag extraction)
@@ -38,14 +39,60 @@ Before using the MCP server, ensure you have:
 
 ## Starting the Server
 
-The MCP server uses STDIO transport which is compatible with most MCP clients.  When you do a `gem install htm` the htm_mcp.rb executable is placed on your $PATH.
+The MCP server uses STDIO transport which is compatible with most MCP clients. When you do a `gem install htm`, the `htm_mcp` executable is placed on your $PATH.
 
 ```bash
-htm_mcp.rb
+htm_mcp
 ```
 
 The server logs to STDERR to avoid corrupting the JSON-RPC protocol on STDOUT.
 
+## CLI Commands
+
+The `htm_mcp` executable includes management commands for database setup and diagnostics:
+
+| Command | Description |
+|---------|-------------|
+| `htm_mcp` | Start the MCP server (default) |
+| `htm_mcp server` | Start the MCP server (explicit) |
+| `htm_mcp setup` | Initialize database schema and run migrations |
+| `htm_mcp init` | Alias for setup |
+| `htm_mcp verify` | Verify database connection, extensions, and migration status |
+| `htm_mcp stats` | Show memory statistics (nodes, tags, robots, database size) |
+| `htm_mcp version` | Show HTM version |
+| `htm_mcp help` | Show help with all environment variables |
+
+### First-Time Setup
+
+```bash
+# Set your database URL
+export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+
+# Initialize the database
+htm_mcp setup
+
+# Verify everything is working
+htm_mcp verify
+
+# Check memory statistics
+htm_mcp stats
+```
+
+### Migration Status
+
+The `verify` command shows migration status with `+` (applied) and `-` (pending) indicators:
+
+```
+Migration Status
+--------------------------------------------------------------------------------
+  + 20250101000001_create_schema_migrations
+  + 20250101000002_create_robots
+  + 20250101000003_create_nodes
+  - 20250612000001_add_new_feature
+--------------------------------------------------------------------------------
+  3 applied, 1 pending
+```
+
 ## Tools Reference
 
 ### SetRobotTool
@@ -335,6 +382,291 @@ Get statistics about HTM memory usage.
 }
 ```
 
+## Robot Group Tools
+
+Robot Groups enable high-availability configurations with multiple robots sharing working memory. Groups support active/passive roles, automatic failover, and real-time synchronization via PostgreSQL LISTEN/NOTIFY.
+
+### CreateGroupTool
+
+Create a new robot group with shared working memory.
+
+**Parameters:**
+- `name` (String, required): Unique name for the group
+- `sync_interval` (Integer, optional): Sync interval in seconds (default: 30)
+- `max_members` (Integer, optional): Maximum group members (default: 10)
+- `token_budget` (Integer, optional): Shared working memory token limit (default: 4000)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "sync_interval": 30,
+  "max_members": 10,
+  "token_budget": 4000,
+  "message": "Robot group 'research-team' created successfully"
+}
+```
+
+---
+
+### ListGroupsTool
+
+List all active robot groups in the current MCP session.
+
+**Parameters:** None
+
+**Returns:**
+```json
+{
+  "success": true,
+  "count": 2,
+  "groups": [
+    {
+      "name": "research-team",
+      "member_count": 3,
+      "active_robot": "researcher-1"
+    },
+    {
+      "name": "support-team",
+      "member_count": 2,
+      "active_robot": "support-bot"
+    }
+  ]
+}
+```
+
+---
+
+### GetGroupStatusTool
+
+Get detailed status of a robot group.
+
+**Parameters:**
+- `name` (String, required): The group name
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "status": {
+    "active_robot": "researcher-1",
+    "member_count": 3,
+    "members": [
+      { "name": "researcher-1", "role": "active", "last_seen": "2024-01-15T10:30:00Z" },
+      { "name": "researcher-2", "role": "passive", "last_seen": "2024-01-15T10:29:55Z" },
+      { "name": "researcher-3", "role": "passive", "last_seen": "2024-01-15T10:29:50Z" }
+    ],
+    "working_memory_tokens": 2500,
+    "token_budget": 4000,
+    "sync_interval": 30
+  }
+}
+```
+
+---
+
+### JoinGroupTool
+
+Add a robot to an existing group.
+
+**Parameters:**
+- `group_name` (String, required): The group to join
+- `robot_name` (String, required): The robot name to add
+- `role` (String, optional): `"active"` or `"passive"` (default: `"passive"`)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "robot_name": "researcher-4",
+  "role": "passive",
+  "message": "Robot 'researcher-4' joined group 'research-team' as passive"
+}
+```
+
+---
+
+### LeaveGroupTool
+
+Remove a robot from a group.
+
+**Parameters:**
+- `group_name` (String, required): The group to leave
+- `robot_name` (String, required): The robot to remove
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "robot_name": "researcher-4",
+  "message": "Robot 'researcher-4' left group 'research-team'"
+}
+```
+
+---
+
+### GroupRememberTool
+
+Store memory shared across all group members. Only the active robot can write to group memory.
+
+**Parameters:**
+- `group_name` (String, required): The target group
+- `content` (String, required): The content to remember
+- `tags` (Array<String>, optional): Tags for categorization
+- `metadata` (Hash, optional): Key-value metadata
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "node_id": 789,
+  "content": "Found relevant paper on embeddings",
+  "tags": ["research:papers", "ai:embeddings"],
+  "message": "Memory stored in group working memory"
+}
+```
+
+---
+
+### GroupRecallTool
+
+Recall memories from a group's shared context.
+
+**Parameters:**
+- `group_name` (String, required): The target group
+- `query` (String, required): Search query
+- `limit` (Integer, optional): Maximum results (default: 10)
+- `strategy` (String, optional): `"vector"`, `"fulltext"`, or `"hybrid"` (default: `"hybrid"`)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "query": "embeddings",
+  "count": 3,
+  "results": [
+    {
+      "id": 789,
+      "content": "Found relevant paper on embeddings",
+      "tags": ["research:papers", "ai:embeddings"],
+      "score": 0.92
+    }
+  ]
+}
+```
+
+---
+
+### GetGroupWorkingMemoryTool
+
+Get a group's working memory contents.
+
+**Parameters:**
+- `group_name` (String, required): The target group
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "token_usage": 2500,
+  "token_budget": 4000,
+  "count": 15,
+  "working_memory": [
+    {
+      "id": 789,
+      "content": "Found relevant paper on embeddings",
+      "tags": ["research:papers"],
+      "added_at": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### PromoteRobotTool
+
+Promote a passive robot to active role. The current active robot becomes passive.
+
+**Parameters:**
+- `group_name` (String, required): The target group
+- `robot_name` (String, required): The robot to promote
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "promoted_robot": "researcher-2",
+  "previous_active": "researcher-1",
+  "message": "Robot 'researcher-2' is now active. 'researcher-1' is now passive."
+}
+```
+
+---
+
+### FailoverTool
+
+Trigger failover to the next available robot in the group.
+
+**Parameters:**
+- `group_name` (String, required): The target group
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "new_active": "researcher-2",
+  "previous_active": "researcher-1",
+  "message": "Failover complete. 'researcher-2' is now active."
+}
+```
+
+---
+
+### SyncGroupTool
+
+Manually synchronize group state across all members.
+
+**Parameters:**
+- `group_name` (String, required): The target group
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "synced_members": 3,
+  "message": "Group state synchronized across 3 members"
+}
+```
+
+---
+
+### ShutdownGroupTool
+
+Gracefully shutdown a robot group, removing all members.
+
+**Parameters:**
+- `group_name` (String, required): The group to shutdown
+
+**Returns:**
+```json
+{
+  "success": true,
+  "group_name": "research-team",
+  "message": "Robot group 'research-team' has been shut down"
+}
+```
+
 ## Resources Reference
 
 ### htm://statistics
@@ -375,6 +707,32 @@ ai
 
 Last 20 memories as JSON array.
 
+### htm://groups
+
+Active robot groups and their status:
+
+```json
+{
+  "count": 2,
+  "groups": [
+    {
+      "name": "research-team",
+      "member_count": 3,
+      "active_robot": "researcher-1",
+      "token_usage": 2500,
+      "token_budget": 4000
+    },
+    {
+      "name": "support-team",
+      "member_count": 2,
+      "active_robot": "support-bot",
+      "token_usage": 1200,
+      "token_budget": 4000
+    }
+  ]
+}
+```
+
 ## Client Configuration
 
 ### Claude Desktop
@@ -385,8 +743,22 @@ Add to `~/.config/claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%
 {
   "mcpServers": {
     "htm-memory": {
-      "command": "ruby",
-      "args": ["/absolute/path/to/htm/bin/htm_mcp.rb"],
+      "command": "htm_mcp",
+      "env": {
+        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+      }
+    }
+  }
+}
+```
+
+If `htm_mcp` is not in your PATH, use the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "htm-memory": {
+      "command": "/path/to/htm_mcp",
       "env": {
         "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
       }
@@ -408,8 +780,7 @@ Add to `~/.claude/claude_code_config.json`:
 {
   "mcpServers": {
     "htm-memory": {
-      "command": "ruby",
-      "args": ["/absolute/path/to/htm/bin/htm_mcp.rb"],
+      "command": "htm_mcp",
       "env": {
         "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
       }
@@ -439,9 +810,7 @@ Add to `~/.config/aia/config.yml`:
 ```yaml
 mcp_servers:
   htm-memory:
-    command: ruby
-    args:
-      - /absolute/path/to/htm/bin/htm_mcp.rb
+    command: htm_mcp
     env:
       HTM_DBURL: postgresql://user@localhost:5432/htm_development
 ```
@@ -451,9 +820,7 @@ For project-specific configuration, add to `.aia/config.yml` in your project roo
 ```yaml
 mcp_servers:
   htm-memory:
-    command: ruby
-    args:
-      - /absolute/path/to/htm/bin/htm_mcp.rb
+    command: htm_mcp
     env:
       HTM_DBURL: postgresql://user@localhost:5432/my_project_htm
 ```
@@ -515,6 +882,41 @@ Remember that project B uses Vue with JavaScript
 
 Each robot has its own working memory but shares the global long-term memory (hive mind).
 
+### Using Robot Groups
+
+Robot Groups enable high-availability configurations where multiple robots share working memory:
+
+1. **Create a group**:
+   ```
+   Create a robot group called "research-team" with 3 max members
+   ```
+
+2. **Join robots to the group**:
+   ```
+   Join robot "researcher-1" to group "research-team" as active
+   Join robot "researcher-2" to group "research-team" as passive
+   ```
+
+3. **Store shared memories**:
+   ```
+   Remember in group "research-team" that we found a relevant paper on embeddings
+   ```
+
+4. **Recall from group context**:
+   ```
+   Recall from group "research-team" what we know about embeddings
+   ```
+
+5. **Handle failover**:
+   ```
+   Trigger failover for group "research-team"
+   ```
+
+6. **Check group status**:
+   ```
+   Show status of group "research-team"
+   ```
+
 ### Searching with Typo Tolerance
 
 Use fuzzy search when you're not sure of exact tag names:
@@ -573,7 +975,7 @@ psql htm_development -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
 
 **Claude Desktop doesn't show HTM tools:**
 1. Verify the config file path is correct for your OS
-2. Check that the path to `htm_mcp.rb` is absolute
+2. Check that `htm_mcp` is in your PATH or use an absolute path
 3. Restart Claude Desktop completely
 4. Check Claude Desktop logs for errors
 
@@ -596,18 +998,51 @@ psql htm_development -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
 
 Enable verbose logging by checking STDERR output:
 ```bash
-ruby bin/htm_mcp.rb 2>&1 | tee mcp_debug.log
+htm_mcp 2>&1 | tee mcp_debug.log
 ```
 
 The server logs all tool calls and errors to STDERR.
 
 ## Environment Variables
 
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `HTM_DBURL` | PostgreSQL connection URL | Yes |
-| `OLLAMA_URL` | Ollama server URL (default: `http://localhost:11434`) | No |
-| `HTM_ROBOT_NAME` | Default robot name for clients | No |
+Run `htm_mcp help` for a complete list. Key variables:
+
+### Database (required)
+
+| Variable | Description |
+|----------|-------------|
+| `HTM_DBURL` | PostgreSQL connection URL (e.g., `postgresql://user:pass@localhost:5432/htm_development`) |
+
+### Database (alternative to HTM_DBURL)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HTM_DBNAME` | Database name | - |
+| `HTM_DBHOST` | Database host | `localhost` |
+| `HTM_DBPORT` | Database port | `5432` |
+| `HTM_DBUSER` | Database username | - |
+| `HTM_DBPASS` | Database password | - |
+| `HTM_DBSSLMODE` | SSL mode | `prefer` |
+
+### LLM Providers
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HTM_EMBEDDING_PROVIDER` | Embedding provider | `ollama` |
+| `HTM_EMBEDDING_MODEL` | Embedding model | `nomic-embed-text:latest` |
+| `HTM_TAG_PROVIDER` | Tag extraction provider | `ollama` |
+| `HTM_TAG_MODEL` | Tag model | `gemma3:latest` |
+| `HTM_OLLAMA_URL` | Ollama server URL | `http://localhost:11434` |
+
+### Other Providers (set API keys as needed)
+
+| Variable | Description |
+|----------|-------------|
+| `HTM_OPENAI_API_KEY` | OpenAI API key |
+| `HTM_ANTHROPIC_API_KEY` | Anthropic API key |
+| `HTM_GEMINI_API_KEY` | Google Gemini API key |
+| `HTM_AZURE_API_KEY` | Azure OpenAI API key |
+| `HTM_AZURE_ENDPOINT` | Azure OpenAI endpoint |
 
 ## Next Steps
 

data/docs/multi_framework_support.md

@@ -131,8 +131,8 @@ node_id = htm.remember("text")  # ~15ms
 HTM automatically detects the appropriate backend:
 
 ```ruby
-# Test environment → :inline
-ENV['RAILS_ENV'] = 'test'
+# Test environment → :inline (uses HTM.env which checks HTM_ENV > RAILS_ENV > RACK_ENV)
+ENV['HTM_ENV'] = 'test'
 HTM.configuration.job_backend  # => :inline
 
 # Rails app → :active_job