htm 0.0.1

data/examples/basic_usage.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic usage example for HTM
+#
+# Prerequisites:
+# 1. Source environment variables: source ~/.bashrc__tiger
+# 2. Initialize database schema: ruby -r ./lib/htm -e "HTM::Database.setup"
+# 3. Install dependencies: bundle install
+
+require_relative '../lib/htm'
+
+puts "HTM Basic Usage Example"
+puts "=" * 60
+
+# Check environment
+unless ENV['HTM_DBURL']
+  puts "ERROR: HTM_DBURL not set. Please run: source ~/.bashrc__tiger"
+  exit 1
+end
+
+begin
+  # Configure HTM globally (uses RubyLLM with Ollama by default)
+  puts "\n1. Configuring HTM with Ollama provider..."
+  HTM.configure do |config|
+    config.embedding_provider = :ollama
+    config.embedding_model = 'nomic-embed-text'
+    config.embedding_dimensions = 768
+    config.tag_provider = :ollama
+    config.tag_model = 'llama3'
+    config.reset_to_defaults  # Apply settings
+  end
+  puts "✓ HTM configured with Ollama provider"
+
+  # Initialize HTM for 'Code Helper' robot
+  puts "\n2. Initializing HTM for 'Code Helper' robot..."
+  htm = HTM.new(
+    robot_name: "Code Helper",
+    working_memory_size: 128_000
+  )
+  puts "✓ HTM initialized"
+  puts "  Robot ID: #{htm.robot_id}"
+  puts "  Robot Name: #{htm.robot_name}"
+  puts "  Embedding Service: Ollama (#{HTM.configuration.embedding_model})"
+
+  # Remember some information
+  puts "\n3. Remembering information..."
+
+  node_id_1 = htm.remember(
+    "We decided to use PostgreSQL for HTM storage because it provides excellent time-series optimization and native vector search with pgvector.",
+    source: "architect"
+  )
+  puts "✓ Remembered decision about database choice (node #{node_id_1})"
+
+  node_id_2 = htm.remember(
+    "We chose RAG (Retrieval-Augmented Generation) for memory recall, combining temporal filtering with semantic vector search.",
+    source: "architect"
+  )
+  puts "✓ Remembered decision about RAG approach (node #{node_id_2})"
+
+  node_id_3 = htm.remember(
+    "The user's name is Dewayne and they prefer using debug_me for debugging instead of puts.",
+    source: "system"
+  )
+  puts "✓ Remembered fact about user preferences (node #{node_id_3})"
+
+  # Sleep briefly to allow async embedding/tag jobs to start
+  sleep 0.5
+
+  # Demonstrate recall
+  puts "\n4. Recalling memories about 'database'..."
+  memories = htm.recall(
+    "database",
+    timeframe: (Time.now - 3600)..Time.now,  # Last hour
+    limit: 5
+  )
+  puts "✓ Found #{memories.length} memories"
+  memories.each do |memory|
+    puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+  end
+
+  puts "\n" + "=" * 60
+  puts "✓ Example completed successfully!"
+  puts "\nThe HTM API provides 3 core methods:"
+  puts "  - htm.remember(content, source:) - Store information"
+  puts "  - htm.recall(timeframe:, topic:, ...) - Retrieve memories"
+  puts "  - htm.forget(node_id, confirm:) - Delete a memory"
+
+rescue => e
+  puts "\n✗ Error: #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+  exit 1
+end

data/examples/cli_app/README.md

@@ -0,0 +1,317 @@
+# HTM CLI Application Example
+
+This example demonstrates using HTM in a command-line application with synchronous job execution.
+
+## Features
+
+- **Synchronous Execution**: Uses `:inline` job backend for immediate embedding/tag generation
+- **Interactive Interface**: Command-line REPL for remembering and recalling information
+- **Progress Feedback**: Real-time feedback on operations
+- **Database Persistence**: All memories stored in PostgreSQL
+- **Full HTM Features**: Vector search, tag extraction, hybrid search
+
+## Prerequisites
+
+1. **PostgreSQL Database**
+   ```bash
+   # Set database connection URL
+   export HTM_DBURL='postgresql://user:pass@host:port/dbname'
+
+   # Or use your existing config
+   source ~/.bashrc__tiger
+   ```
+
+2. **Ollama** (recommended but optional)
+   ```bash
+   # Install Ollama
+   curl https://ollama.ai/install.sh | sh
+
+   # Pull models
+   ollama pull nomic-embed-text  # For embeddings
+   ollama pull llama3            # For tag extraction
+   ```
+
+3. **Ruby Dependencies**
+   ```bash
+   # From HTM root directory
+   bundle install
+   ```
+
+## Usage
+
+### Run the CLI
+
+```bash
+# Make executable
+chmod +x htm_cli.rb
+
+# Run
+./htm_cli.rb
+# or
+ruby htm_cli.rb
+```
+
+### Commands
+
+**Store Information**
+```
+htm> remember PostgreSQL is great for time-series data
+```
+
+**Search Memories**
+```
+htm> recall PostgreSQL
+```
+
+**View Statistics**
+```
+htm> stats
+```
+
+**Show Help**
+```
+htm> help
+```
+
+**Exit**
+```
+htm> exit
+```
+
+## How It Works
+
+### Synchronous Job Execution
+
+Unlike web applications, CLI apps use `:inline` job backend:
+
+```ruby
+HTM.configure do |config|
+  config.job_backend = :inline  # Execute jobs synchronously
+end
+```
+
+This means:
+- `remember()` waits for embeddings and tags to be generated
+- Immediate feedback on completion
+- Simpler debugging and testing
+- No background job infrastructure needed
+
+### Job Backend Comparison
+
+| Backend | CLI | Web Apps | When to Use |
+|---------|-----|----------|-------------|
+| `:inline` | ✅ | ❌ | CLI tools, tests |
+| `:thread` | ⚠️ | ⚠️ | Simple standalone apps |
+| `:sidekiq` | ❌ | ✅ | Sinatra, microservices |
+| `:active_job` | ❌ | ✅ | Rails applications |
+
+## Example Session
+
+```
+$ ruby htm_cli.rb
+
+============================================================
+HTM CLI - Hierarchical Temporary Memory Assistant
+============================================================
+
+Job Backend: inline (synchronous execution)
+Robot: cli_assistant
+
+Commands:
+  remember <text>  - Store information
+  recall <topic>   - Search memories
+  stats            - Show memory statistics
+  help             - Show this help
+  exit             - Quit
+
+============================================================
+
+htm> remember PostgreSQL with pgvector enables semantic search
+
+Remembering: "PostgreSQL with pgvector enables semantic search"
+Processing...
+[✓] Stored as node 1 (1243.56ms)
+    Embedding: 768 dimensions
+    Tags: database:postgresql, search:semantic, ai:vector-search
+
+htm> remember TimescaleDB is built on PostgreSQL for time-series
+
+Remembering: "TimescaleDB is built on PostgreSQL for time-series"
+Processing...
+[✓] Stored as node 2 (1189.32ms)
+    Embedding: 768 dimensions
+    Tags: database:postgresql, database:timescaledb, time-series
+
+htm> recall PostgreSQL
+
+Searching for: "PostgreSQL"
+Strategy: hybrid (vector + fulltext)
+[✓] Found 2 memories (45.67ms)
+
+1. Node 1 (cli_user)
+   Created: 2025-11-09 14:23:15 UTC
+   Content: PostgreSQL with pgvector enables semantic search
+   Tags: database:postgresql, search:semantic, ai:vector-search
+
+2. Node 2 (cli_user)
+   Created: 2025-11-09 14:23:42 UTC
+   Content: TimescaleDB is built on PostgreSQL for time-series
+   Tags: database:postgresql, database:timescaledb, time-series
+
+htm> stats
+
+Memory Statistics:
+
+Nodes:
+  Total: 2
+  With embeddings: 2 (100.0%)
+  With tags: 2 (100.0%)
+
+Tags:
+  Total: 5
+  Average per node: 2.5
+
+Robots:
+  Total: 1
+
+Current Robot (cli_assistant):
+  Nodes: 2
+
+htm> exit
+
+Goodbye!
+```
+
+## Configuration Options
+
+### Custom Logger
+
+```ruby
+HTM.configure do |config|
+  config.logger = Logger.new('htm_cli.log')
+  config.logger.level = Logger::DEBUG
+end
+```
+
+### Custom Models
+
+```ruby
+HTM.configure do |config|
+  config.embedding_model = 'custom-embedding-model'
+  config.tag_model = 'custom-tag-model'
+end
+```
+
+### Timeouts
+
+```ruby
+HTM.configure do |config|
+  config.embedding_timeout = 60   # 1 minute
+  config.tag_timeout = 120        # 2 minutes
+end
+```
+
+## Performance Considerations
+
+### Synchronous Execution Trade-offs
+
+**Pros:**
+- Immediate feedback
+- Simple error handling
+- No background infrastructure needed
+- Predictable timing
+
+**Cons:**
+- Slower user-facing operations (1-3 seconds per remember)
+- Blocks on LLM API calls
+- Not suitable for high-throughput scenarios
+
+### Optimization Tips
+
+1. **Batch Operations**: Group multiple `remember()` calls
+2. **Caching**: Use query cache for repeated searches
+3. **Faster Models**: Use smaller embedding models for CLI
+4. **Selective Features**: Disable tags if not needed
+
+```ruby
+# Disable tag generation for faster CLI
+HTM.configure do |config|
+  config.tag_extractor = ->(_text, _ontology) { [] }
+end
+```
+
+## Troubleshooting
+
+### Database Connection Errors
+
+```bash
+# Verify database URL
+echo $HTM_DBURL
+
+# Test connection
+psql $HTM_DBURL -c "SELECT version();"
+
+# Initialize schema if needed
+cd ../.. && rake db_setup
+```
+
+### Ollama Connection Errors
+
+```bash
+# Check if Ollama is running
+curl http://localhost:11434/api/version
+
+# Start Ollama
+ollama serve
+
+# Verify models are pulled
+ollama list
+```
+
+### Slow Performance
+
+```bash
+# Use faster models
+export EMBEDDING_MODEL=all-minilm
+export TAG_MODEL=gemma2:2b
+
+# Or disable features
+# (modify htm_cli.rb to skip tag generation)
+```
+
+## Extending the CLI
+
+### Add New Commands
+
+```ruby
+# In htm_cli.rb, add to handle_command:
+when 'export'
+  handle_export(args)
+
+# Implement handler:
+def handle_export(filename)
+  nodes = HTM::Models::Node.all
+  File.write(filename, nodes.to_json)
+  puts "[✓] Exported #{nodes.count} nodes to #{filename}"
+end
+```
+
+### Custom Search Strategies
+
+```ruby
+def handle_recall(topic)
+  # Use different strategies
+  vector_results = @htm.recall(topic, strategy: :vector)
+  fulltext_results = @htm.recall(topic, strategy: :fulltext)
+  hybrid_results = @htm.recall(topic, strategy: :hybrid)
+
+  # Compare and choose best
+end
+```
+
+## See Also
+
+- [HTM README](../../README.md) - Main documentation
+- [Sinatra Example](../sinatra_app/README.md) - Web application example
+- [Rails Example](../rails_app/README.md) - Rails integration
+- [Job Backends Documentation](../../docs/job_backends.md) - Job backend guide

data/examples/cli_app/htm_cli.rb

@@ -0,0 +1,270 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# HTM CLI Application Example
+#
+# Demonstrates using HTM in a command-line application with:
+# - Synchronous job execution (inline mode)
+# - Interactive command interface
+# - Progress feedback
+# - Database persistence
+#
+# Usage:
+#   ruby htm_cli.rb
+#
+# Environment:
+#   HTM_DBURL - PostgreSQL connection URL (required)
+#   OLLAMA_URL - Ollama server URL (default: http://localhost:11434)
+#
+
+require_relative '../../lib/htm'
+require 'io/console'
+
+class HTMCli
+  def initialize
+    # Configure HTM for CLI usage
+    HTM.configure do |config|
+      # Use inline mode for synchronous execution
+      config.job_backend = :inline
+
+      # CLI-friendly logging
+      config.logger.level = Logger::INFO
+      config.logger.formatter = proc do |severity, datetime, progname, msg|
+        case severity
+        when 'INFO'
+          "[✓] #{msg}\n"
+        when 'WARN'
+          "[⚠] #{msg}\n"
+        when 'ERROR'
+          "[✗] #{msg}\n"
+        else
+          "[•] #{msg}\n"
+        end
+      end
+    end
+
+    # Initialize HTM instance
+    @htm = HTM.new(robot_name: "cli_assistant")
+  end
+
+  def run
+    puts
+    puts "=" * 60
+    puts "HTM CLI - Hierarchical Temporary Memory Assistant"
+    puts "=" * 60
+    puts
+    puts "Job Backend: #{HTM.configuration.job_backend} (synchronous execution)"
+    puts "Robot: #{@htm.robot_name}"
+    puts
+    puts "Commands:"
+    puts "  remember <text>  - Store information"
+    puts "  recall <topic>   - Search memories"
+    puts "  stats            - Show memory statistics"
+    puts "  help             - Show this help"
+    puts "  exit             - Quit"
+    puts
+    puts "=" * 60
+    puts
+
+    loop do
+      print "\nhtm> "
+      input = gets&.chomp
+      break if input.nil? || input == 'exit'
+
+      handle_command(input)
+    end
+
+    puts "\nGoodbye!"
+  end
+
+  private
+
+  def handle_command(input)
+    return if input.empty?
+
+    parts = input.split(' ', 2)
+    command = parts[0]
+    args = parts[1]
+
+    case command
+    when 'remember'
+      handle_remember(args)
+    when 'recall'
+      handle_recall(args)
+    when 'stats'
+      handle_stats
+    when 'help'
+      handle_help
+    else
+      puts "Unknown command: #{command}. Type 'help' for available commands."
+    end
+  rescue StandardError => e
+    puts "[✗] Error: #{e.message}"
+    puts "    #{e.class}: #{e.backtrace.first}"
+  end
+
+  def handle_remember(text)
+    unless text && !text.empty?
+      puts "Usage: remember <text>"
+      return
+    end
+
+    puts "\nRemembering: \"#{text}\""
+    puts "Processing..."
+
+    start_time = Time.now
+    node_id = @htm.remember(text, source: 'cli_user')
+    duration = ((Time.now - start_time) * 1000).round(2)
+
+    puts "[✓] Stored as node #{node_id} (#{duration}ms)"
+
+    # Show what was generated (inline mode, so already complete)
+    node = HTM::Models::Node.includes(:tags).find(node_id)
+
+    if node.embedding
+      puts "    Embedding: #{node.embedding_dimension} dimensions"
+    else
+      puts "    Embedding: Not generated"
+    end
+
+    if node.tags.any?
+      puts "    Tags: #{node.tags.map(&:name).join(', ')}"
+    else
+      puts "    Tags: None"
+    end
+  end
+
+  def handle_recall(topic)
+    unless topic && !topic.empty?
+      puts "Usage: recall <topic>"
+      return
+    end
+
+    puts "\nSearching for: \"#{topic}\""
+    puts "Strategy: hybrid (vector + fulltext)"
+
+    start_time = Time.now
+    memories = @htm.recall(
+      topic,
+      limit: 10,
+      strategy: :hybrid,
+      raw: true
+    )
+    duration = ((Time.now - start_time) * 1000).round(2)
+
+    if memories.empty?
+      puts "[•] No memories found (#{duration}ms)"
+      return
+    end
+
+    puts "[✓] Found #{memories.length} memories (#{duration}ms)\n"
+
+    memories.each_with_index do |memory, index|
+      puts
+      puts "#{index + 1}. Node #{memory['id']} (#{memory['source']})"
+      puts "   Created: #{memory['created_at']}"
+      puts "   Content: #{memory['content']}"
+
+      # Show tags if any
+      node = HTM::Models::Node.includes(:tags).find(memory['id'])
+      if node.tags.any?
+        puts "   Tags: #{node.tags.map(&:name).join(', ')}"
+      end
+    end
+  end
+
+  def handle_stats
+    puts "\nMemory Statistics:"
+    puts
+
+    total_nodes = HTM::Models::Node.count
+    nodes_with_embeddings = HTM::Models::Node.where.not(embedding: nil).count
+    nodes_with_tags = HTM::Models::Node.joins(:tags).distinct.count
+    total_tags = HTM::Models::Tag.count
+    total_robots = HTM::Models::Robot.count
+
+    puts "Nodes:"
+    puts "  Total: #{total_nodes}"
+    puts "  With embeddings: #{nodes_with_embeddings} (#{percentage(nodes_with_embeddings, total_nodes)})"
+    puts "  With tags: #{nodes_with_tags} (#{percentage(nodes_with_tags, total_nodes)})"
+    puts
+
+    puts "Tags:"
+    puts "  Total: #{total_tags}"
+    if total_tags > 0
+      puts "  Average per node: #{(total_tags.to_f / total_nodes).round(2)}"
+    end
+    puts
+
+    puts "Robots:"
+    puts "  Total: #{total_robots}"
+    puts
+
+    puts "Current Robot (#{@htm.robot_name}):"
+    robot_nodes = HTM::Models::Node.where(robot_id: @htm.robot_id).count
+    puts "  Nodes: #{robot_nodes}"
+  end
+
+  def handle_help
+    puts
+    puts "HTM CLI Commands:"
+    puts
+    puts "  remember <text>"
+    puts "    Store information in long-term memory"
+    puts "    Embeddings and tags are generated synchronously"
+    puts "    Example: remember PostgreSQL is great for time-series data"
+    puts
+    puts "  recall <topic>"
+    puts "    Search for relevant memories using hybrid search"
+    puts "    Combines vector similarity and full-text search"
+    puts "    Example: recall PostgreSQL"
+    puts
+    puts "  stats"
+    puts "    Show memory statistics and current state"
+    puts
+    puts "  help"
+    puts "    Show this help message"
+    puts
+    puts "  exit"
+    puts "    Quit the CLI"
+    puts
+  end
+
+  def percentage(part, total)
+    return "0%" if total.zero?
+    "#{((part.to_f / total) * 100).round(1)}%"
+  end
+end
+
+# Check database configuration
+unless ENV['HTM_DBURL']
+  puts
+  puts "[✗] Error: HTM_DBURL environment variable not set"
+  puts
+  puts "Please set your database connection URL:"
+  puts "  export HTM_DBURL='postgresql://user:pass@host:port/dbname'"
+  puts
+  puts "Or source your environment configuration:"
+  puts "  source ~/.bashrc__tiger"
+  puts
+  exit 1
+end
+
+# Check Ollama connection (optional but recommended)
+begin
+  require 'net/http'
+  uri = URI(ENV['OLLAMA_URL'] || 'http://localhost:11434')
+  response = Net::HTTP.get_response(uri)
+rescue StandardError => e
+  puts
+  puts "[⚠] Warning: Cannot connect to Ollama (#{e.message})"
+  puts "    Embeddings and tags will not be generated"
+  puts "    Install Ollama: https://ollama.ai"
+  puts
+  puts "Continue anyway? (y/n) "
+  answer = gets.chomp.downcase
+  exit unless answer == 'y' || answer == 'yes'
+end
+
+# Run CLI
+HTMCli.new.run