htm 0.0.15 → 0.0.18

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
 
@@ -25,8 +26,8 @@ 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
+   export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
+   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_DATABASE__URL="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,10 +743,24 @@ 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_DATABASE__URL": "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"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -408,10 +780,9 @@ 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"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -439,11 +810,9 @@ 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
+      HTM_DATABASE__URL: postgresql://user@localhost:5432/htm_development
 ```
 
 For project-specific configuration, add to `.aia/config.yml` in your project root:
@@ -451,11 +820,9 @@ 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
+      HTM_DATABASE__URL: postgresql://user@localhost:5432/my_project_htm
 ```
 
 ## Usage Examples
@@ -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:
@@ -550,9 +952,9 @@ This will find `database:postgresql` even with the typo.
 gem install fast-mcp
 ```
 
-**Error: `HTM_DBURL not set`**
+**Error: `HTM_DATABASE__URL not set`**
 ```bash
-export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
 ```
 
 ### Database Connection Issues
@@ -573,14 +975,14 @@ 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
 
 **Claude Code doesn't recognize tools:**
 1. Run `/mcp` to refresh MCP connections
 2. Verify config is valid JSON
-3. Check that HTM_DBURL is set in the env section
+3. Check that HTM_DATABASE__URL is set in the env section
 
 ### Embedding/Tag 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_DATABASE__URL` | PostgreSQL connection URL (e.g., `postgresql://user:pass@localhost:5432/htm_development`) |
+
+### Database (alternative to HTM_DATABASE__URL)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HTM_DATABASE__NAME` | Database name | - |
+| `HTM_DATABASE__HOST` | Database host | `localhost` |
+| `HTM_DATABASE__PORT` | Database port | `5432` |
+| `HTM_DATABASE__USER` | Database username | - |
+| `HTM_DATABASE__PASSWORD` | 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/guides/robot-groups.md

@@ -89,10 +89,10 @@ require 'htm'
 
 # Configure HTM
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text'
-  config.tag_provider = :ollama
-  config.tag_model = 'llama3'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
+  config.tag.provider = :ollama
+  config.tag.model = 'llama3'
 end
 
 # Create a robot group with active and passive members
@@ -386,8 +386,8 @@ group_name = 'distributed-service'
 
 # Configure HTM
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
 end
 
 # Create HTM instance for this worker
@@ -573,7 +573,7 @@ Single-process demo showing:
 - Real-time sync via LISTEN/NOTIFY
 
 ```bash
-HTM_DBURL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/same_process.rb
+HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/same_process.rb
 ```
 
 ### multi_process.rb
@@ -585,7 +585,7 @@ Multi-process demo showing:
 - Dynamic scaling by spawning new processes
 
 ```bash
-HTM_DBURL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/multi_process.rb
+HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_dev" ruby examples/robot_groups/multi_process.rb
 ```
 
 ### robot_worker.rb

data/docs/index.md

@@ -81,10 +81,10 @@ require 'htm'
 
 # 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 for your robot