htm 0.0.1 → 0.0.2

data/examples/cli_app/htm_cli.rb

@@ -59,6 +59,7 @@ class HTMCli
     puts "Commands:"
     puts "  remember <text>  - Store information"
     puts "  recall <topic>   - Search memories"
+    puts "  tags             - List all tags with linked nodes"
     puts "  stats            - Show memory statistics"
     puts "  help             - Show this help"
     puts "  exit             - Quit"
@@ -91,6 +92,8 @@ class HTMCli
       handle_remember(args)
     when 'recall'
       handle_recall(args)
+    when 'tags'
+      handle_tags(args)
     when 'stats'
       handle_stats
     when 'help'
@@ -113,7 +116,7 @@ class HTMCli
     puts "Processing..."
 
     start_time = Time.now
-    node_id = @htm.remember(text, source: 'cli_user')
+    node_id = @htm.remember(text)
     duration = ((Time.now - start_time) * 1000).round(2)
 
     puts "[✓] Stored as node #{node_id} (#{duration}ms)"
@@ -141,7 +144,15 @@ class HTMCli
     end
 
     puts "\nSearching for: \"#{topic}\""
-    puts "Strategy: hybrid (vector + fulltext)"
+    puts "Strategy: hybrid (vector + fulltext + tags)"
+
+    # Show which tags match the query
+    matching_tags = @htm.long_term_memory.find_query_matching_tags(topic)
+    if matching_tags.any?
+      puts "Matching tags: #{matching_tags.join(', ')}"
+    else
+      puts "Matching tags: (none found)"
+    end
 
     start_time = Time.now
     memories = @htm.recall(
@@ -161,15 +172,74 @@ class HTMCli
 
     memories.each_with_index do |memory, index|
       puts
-      puts "#{index + 1}. Node #{memory['id']} (#{memory['source']})"
+      puts "#{index + 1}. Node #{memory['id']}"
       puts "   Created: #{memory['created_at']}"
       puts "   Content: #{memory['content']}"
 
+      # Show scores from hybrid search
+      if memory['combined_score']
+        similarity = (memory['similarity'].to_f * 100).round(1)
+        tag_boost = (memory['tag_boost'].to_f * 100).round(1)
+        combined = (memory['combined_score'].to_f * 100).round(1)
+        puts "   Scores: similarity=#{similarity}%, tag_boost=#{tag_boost}%, combined=#{combined}%"
+      end
+
       # Show tags if any
       node = HTM::Models::Node.includes(:tags).find(memory['id'])
       if node.tags.any?
         puts "   Tags: #{node.tags.map(&:name).join(', ')}"
+      else
+        puts "   Tags: (none)"
+      end
+    end
+  end
+
+  def handle_tags(filter = nil)
+    puts "\nTags Overview:"
+    puts
+
+    # Get all tags with their nodes, optionally filtered by prefix
+    tags_query = HTM::Models::Tag.includes(:nodes).order(:name)
+    tags_query = tags_query.where("name LIKE ?", "#{filter}%") if filter && !filter.empty?
+
+    tags = tags_query.to_a
+
+    if tags.empty?
+      if filter
+        puts "[•] No tags found matching '#{filter}'"
+      else
+        puts "[•] No tags in database"
       end
+      return
+    end
+
+    puts "[✓] Found #{tags.length} tags#{filter ? " matching '#{filter}'" : ""}"
+    puts
+
+    tags.each do |tag|
+      nodes = tag.nodes.to_a
+      puts "━" * 60
+      puts "Tag: #{tag.name}"
+      puts "     Nodes: #{nodes.length}"
+      puts
+
+      if nodes.any?
+        nodes.each do |node|
+          content_preview = node.content.to_s[0..70]
+          content_preview += "..." if node.content.to_s.length > 70
+          puts "     [#{node.id}] #{content_preview}"
+        end
+      else
+        puts "     (no nodes linked)"
+      end
+      puts
+    end
+
+    # Show tag hierarchy summary
+    root_tags = tags.map { |t| t.name.split(':').first }.uniq.sort
+    if root_tags.length > 1
+      puts "━" * 60
+      puts "Root categories: #{root_tags.join(', ')}"
     end
   end
 
@@ -201,7 +271,7 @@ class HTMCli
     puts
 
     puts "Current Robot (#{@htm.robot_name}):"
-    robot_nodes = HTM::Models::Node.where(robot_id: @htm.robot_id).count
+    robot_nodes = HTM::Models::RobotNode.where(robot_id: @htm.robot_id).count
     puts "  Nodes: #{robot_nodes}"
   end
 
@@ -216,8 +286,17 @@ class HTMCli
     puts
     puts "  recall <topic>"
     puts "    Search for relevant memories using hybrid search"
-    puts "    Combines vector similarity and full-text search"
+    puts "    Combines vector similarity, full-text search, and tag matching"
+    puts "    Shows matching tags, scores (similarity, tag_boost, combined)"
     puts "    Example: recall PostgreSQL"
+    puts "    Example: recall database optimization"
+    puts
+    puts "  tags [prefix]"
+    puts "    List all tags with their linked node content"
+    puts "    Optionally filter by tag prefix"
+    puts "    Example: tags"
+    puts "    Example: tags database"
+    puts "    Example: tags ai:machine"
     puts
     puts "  stats"
     puts "    Show memory statistics and current state"
@@ -242,10 +321,9 @@ unless ENV['HTM_DBURL']
   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 "  export HTM_DBURL='postgresql://postgres@localhost:5432/htm_development'"
   puts
-  puts "Or source your environment configuration:"
-  puts "  source ~/.bashrc__tiger"
+  puts "See SETUP.md for database setup instructions."
   puts
   exit 1
 end

data/examples/custom_llm_configuration.rb

@@ -160,8 +160,7 @@ htm = HTM.new(robot_name: "IntegrationBot")
 # Remember information - will use custom LLM configuration
 puts "\nRemembering information in HTM..."
 node_id = htm.remember(
-  "PostgreSQL with pgvector enables efficient vector similarity search",
-  source: 'user'
+  "PostgreSQL with pgvector enables efficient vector similarity search"
 )
 
 puts "✓ Information remembered with node_id: #{node_id}"

data/examples/example_app/app.rb

@@ -72,18 +72,15 @@ class ExampleApp
     puts "(Tags will be auto-extracted by LLM in background)"
 
     node_1 = htm.remember(
-      "HTM provides intelligent memory management for LLM-based applications",
-      source: "assistant"
+      "HTM provides intelligent memory management for LLM-based applications"
     )
 
     node_2 = htm.remember(
-      "The two-tier architecture includes working memory and long-term storage",
-      source: "assistant"
+      "The two-tier architecture includes working memory and long-term storage"
     )
 
     node_3 = htm.remember(
-      "Can you explain how the working memory eviction algorithm works?",
-      source: "user"
+      "Can you explain how the working memory eviction algorithm works?"
     )
 
     puts "✓ Remembered 3 conversation messages (nodes #{node_1}, #{node_2}, #{node_3})"
@@ -132,8 +129,8 @@ class ExampleApp
       limit: 3
     )
     puts "Found #{fulltext_memories.length} memories:"
-    fulltext_memories.each do |memory|
-      puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+    fulltext_memories.each do |content|
+      puts "  - #{content[0..60]}..."
     end
 
     # 2. Vector search (requires embeddings)
@@ -146,8 +143,8 @@ class ExampleApp
         limit: 3
       )
       puts "Found #{vector_memories.length} memories:"
-      vector_memories.each do |memory|
-        puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+      vector_memories.each do |content|
+        puts "  - #{content[0..60]}..."
       end
     rescue StandardError => e
       puts "  ⚠ Vector search error: #{e.message}"
@@ -164,8 +161,8 @@ class ExampleApp
         limit: 3
       )
       puts "Found #{hybrid_memories.length} memories:"
-      hybrid_memories.each do |memory|
-        puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+      hybrid_memories.each do |content|
+        puts "  - #{content[0..60]}..."
       end
     rescue StandardError => e
       puts "  ⚠ Hybrid search error: #{e.message}"
@@ -177,12 +174,12 @@ class ExampleApp
     puts "✓ Demo Complete!"
     puts "="*60
     puts "\nThe HTM API provides 3 core methods:"
-    puts "  1. htm.remember(content, source:)"
+    puts "  1. htm.remember(content, tags: [])"
     puts "     - Stores information in long-term memory"
     puts "     - Adds to working memory for immediate use"
     puts "     - Generates embeddings and tags in background"
     puts ""
-    puts "  2. htm.recall(timeframe:, topic:, strategy:, limit:)"
+    puts "  2. htm.recall(topic, timeframe:, strategy:, limit:)"
     puts "     - Retrieves relevant memories"
     puts "     - Strategies: :fulltext, :vector, :hybrid"
     puts "     - Results added to working memory"

data/examples/sinatra_app/Gemfile

@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 # Web framework
 gem 'sinatra', '~> 3.0'
+gem 'sinatra-contrib', '~> 3.0'
 gem 'puma', '~> 6.0'
 
 # Background jobs

data/examples/sinatra_app/Gemfile.lock

@@ -0,0 +1,166 @@
+PATH
+  remote: ../..
+  specs:
+    htm (0.0.2)
+      activerecord
+      lru_redux
+      neighbor
+      pg (>= 1.5.0)
+      ruby_llm
+      tiktoken_ruby
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (8.1.1)
+      activesupport (= 8.1.1)
+    activerecord (8.1.1)
+      activemodel (= 8.1.1)
+      activesupport (= 8.1.1)
+      timeout (>= 0.4.0)
+    activesupport (8.1.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.5)
+    drb (2.2.3)
+    event_stream_parser (1.0.0)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-multipart (1.1.1)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    json (2.16.0)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    lru_redux (1.1.0)
+    marcel (1.1.0)
+    minitest (5.26.2)
+    multi_json (1.17.0)
+    multipart-post (2.4.1)
+    mustermann (3.0.4)
+      ruby2_keywords (~> 0.0.1)
+    neighbor (0.6.0)
+      activerecord (>= 7.1)
+    net-http (0.8.0)
+      uri (>= 0.11.1)
+    nio4r (2.7.5)
+    pg (1.6.2)
+    pg (1.6.2-aarch64-linux)
+    pg (1.6.2-aarch64-linux-musl)
+    pg (1.6.2-arm64-darwin)
+    pg (1.6.2-x86_64-darwin)
+    pg (1.6.2-x86_64-linux)
+    pg (1.6.2-x86_64-linux-musl)
+    puma (6.6.1)
+      nio4r (~> 2.0)
+    rack (2.2.21)
+    rack-protection (3.2.0)
+      base64 (>= 0.1.0)
+      rack (~> 2.2, >= 2.2.4)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.26.1)
+      connection_pool
+    rerun (0.14.0)
+      listen (~> 3.0)
+    ruby2_keywords (0.0.5)
+    ruby_llm (1.9.1)
+      base64
+      event_stream_parser (~> 1)
+      faraday (>= 1.10.0)
+      faraday-multipart (>= 1)
+      faraday-net_http (>= 1)
+      faraday-retry (>= 1)
+      marcel (~> 1.0)
+      ruby_llm-schema (~> 0.2.1)
+      zeitwerk (~> 2)
+    ruby_llm-schema (0.2.5)
+    securerandom (0.4.1)
+    sidekiq (7.3.9)
+      base64
+      connection_pool (>= 2.3.0)
+      logger
+      rack (>= 2.2.4)
+      redis-client (>= 0.22.2)
+    sinatra (3.2.0)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.2.0)
+      tilt (~> 2.0)
+    sinatra-contrib (3.2.0)
+      multi_json (>= 0.0.2)
+      mustermann (~> 3.0)
+      rack-protection (= 3.2.0)
+      sinatra (= 3.2.0)
+      tilt (~> 2.0)
+    tiktoken_ruby (0.0.13-aarch64-linux)
+    tiktoken_ruby (0.0.13-arm-linux)
+    tiktoken_ruby (0.0.13-arm64-darwin)
+    tiktoken_ruby (0.0.13-x86_64-darwin)
+    tiktoken_ruby (0.0.13-x86_64-linux)
+    tiktoken_ruby (0.0.13-x86_64-linux-musl)
+    tilt (2.6.1)
+    timeout (0.4.4)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  htm!
+  multi_json
+  puma (~> 6.0)
+  redis (~> 5.0)
+  rerun
+  sidekiq (~> 7.0)
+  sinatra (~> 3.0)
+  sinatra-contrib (~> 3.0)
+
+BUNDLED WITH
+   2.7.2