htm 0.0.1 → 0.0.2

data/lib/htm/models/working_memory_entry.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+class HTM
+  module Models
+    # WorkingMemoryEntry - Tracks which nodes are in each robot's working memory
+    #
+    # This provides optional database persistence for working memory state.
+    # Useful for:
+    # - Restoring working memory after process restart
+    # - Querying what nodes robots are actively working with
+    # - Debugging/monitoring working memory across robots
+    #
+    # Note: The in-memory WorkingMemory class remains the primary interface.
+    # This table is for persistence/observability, not required for operation.
+    #
+    class WorkingMemoryEntry < ActiveRecord::Base
+      self.table_name = 'working_memories'
+
+      belongs_to :robot, class_name: 'HTM::Models::Robot'
+      belongs_to :node, class_name: 'HTM::Models::Node'
+
+      validates :robot_id, presence: true
+      validates :node_id, presence: true
+      validates :robot_id, uniqueness: { scope: :node_id, message: 'already has this node in working memory' }
+
+      # Scopes
+      scope :by_robot, ->(robot_id) { where(robot_id: robot_id) }
+      scope :recent, -> { order(added_at: :desc) }
+
+      # Class methods
+
+      # Sync working memory state from in-memory hash to database
+      #
+      # @param robot_id [Integer] Robot ID
+      # @param node_entries [Hash] Hash of node_id => { token_count:, ... }
+      #
+      def self.sync_from_memory(robot_id, node_entries)
+        transaction do
+          # Clear existing entries for this robot
+          where(robot_id: robot_id).delete_all
+
+          # Insert current entries
+          node_entries.each do |node_id, data|
+            create!(
+              robot_id: robot_id,
+              node_id: node_id,
+              token_count: data[:token_count],
+              added_at: data[:added_at] || Time.current
+            )
+          end
+        end
+      end
+
+      # Load working memory state from database
+      #
+      # @param robot_id [Integer] Robot ID
+      # @return [Hash] Hash suitable for WorkingMemory restoration
+      #
+      def self.load_for_robot(robot_id)
+        by_robot(robot_id).includes(:node).each_with_object({}) do |entry, hash|
+          hash[entry.node_id] = {
+            content: entry.node.content,
+            token_count: entry.token_count,
+            added_at: entry.added_at,
+            access_count: entry.node.access_count
+          }
+        end
+      end
+
+      # Clear working memory for a robot
+      #
+      # @param robot_id [Integer] Robot ID
+      #
+      def self.clear_for_robot(robot_id)
+        where(robot_id: robot_id).delete_all
+      end
+
+      # Get total token count for a robot's working memory
+      #
+      # @param robot_id [Integer] Robot ID
+      # @return [Integer] Total tokens
+      #
+      def self.total_tokens_for_robot(robot_id)
+        where(robot_id: robot_id).sum(:token_count)
+      end
+    end
+  end
+end

data/lib/htm/tasks.rb

@@ -28,11 +28,15 @@
 #   rake htm:jobs:failed             # Show nodes with processing issues
 #   rake htm:jobs:clear_all          # Clear all embeddings and tags (testing)
 #
+# Tag tasks:
+#   rake htm:tags:tree               # Display tags as a hierarchical tree
+#
 
 if defined?(Rake)
   # Load the rake tasks
   load File.expand_path('../tasks/htm.rake', __dir__)
   load File.expand_path('../tasks/jobs.rake', __dir__)
+  load File.expand_path('../tasks/tags.rake', __dir__)
 else
   warn "HTM tasks not loaded: Rake is not available"
 end

data/lib/htm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class HTM
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/htm.rb

@@ -107,15 +107,14 @@ class HTM
   # @return [Integer] Database ID of the memory node
   #
   # @example Remember with source
-  #   node_id = htm.remember("PostgreSQL is great for HTM", source: "user")
+  #   node_id = htm.remember("PostgreSQL is great for HTM")
   #
   # @example Remember with manual tags
-  #   node_id = htm.remember("Time-series data", source: "user", tags: ["database:timescaledb"])
+  #   node_id = htm.remember("Time-series data", tags: ["database:timescaledb"])
   #
-  def remember(content, source: "", tags: [])
+  def remember(content, tags: [])
     # Convert nil to empty string
     content = content.to_s
-    source = source.to_s
 
     # If content is empty, return the last node ID without creating a new entry
     if content.empty?
@@ -126,22 +125,35 @@ class HTM
     # Calculate token count using configured counter
     token_count = HTM.count_tokens(content)
 
-    # Store in long-term memory immediately (without embedding)
-    # Embedding and tags will be generated asynchronously
-    node_id = @long_term_memory.add(
+    # Store in long-term memory (with deduplication)
+    # Returns { node_id:, is_new:, robot_node: }
+    result = @long_term_memory.add(
       content: content,
-      source: source,
       token_count: token_count,
       robot_id: @robot_id,
       embedding: nil  # Will be generated in background
     )
 
-    HTM.logger.info "Node #{node_id} created for robot #{@robot_name} (#{token_count} tokens)"
+    node_id = result[:node_id]
+    is_new = result[:is_new]
 
-    # Enqueue background jobs for embedding and tag generation
-    # Both jobs run in parallel with equal priority
-    enqueue_embedding_job(node_id)
-    enqueue_tags_job(node_id, manual_tags: tags)
+    if is_new
+      HTM.logger.info "Node #{node_id} created for robot #{@robot_name} (#{token_count} tokens)"
+
+      # Enqueue background jobs for embedding and tag generation
+      # Only for NEW nodes - existing nodes already have embeddings/tags
+      enqueue_embedding_job(node_id)
+      enqueue_tags_job(node_id, manual_tags: tags)
+    else
+      HTM.logger.info "Node #{node_id} already exists, linked to robot #{@robot_name} (remember_count: #{result[:robot_node].remember_count})"
+
+      # For existing nodes, only add manual tags if provided
+      if tags.any?
+        node = HTM::Models::Node.find(node_id)
+        node.add_tags(tags)
+        HTM.logger.info "Added #{tags.length} manual tags to existing node #{node_id}"
+      end
+    end
 
     # Add to working memory (access_count starts at 0)
     @working_memory.add(node_id, content, token_count: token_count, access_count: 0)
@@ -385,6 +397,15 @@ class HTM
     when /last (\d+) days?/
       days = $1.to_i
       (now - days * 24 * 3600)..now
+    when /last (\d+) seconds?/
+      seconds = $1.to_i
+      (now - seconds)..now
+    when /last (\d+) minutes?/
+      minutes = $1.to_i
+      (now - minutes * 60)..now
+    when /last (\d+) hours?/
+      hours = $1.to_i
+      (now - hours * 3600)..now
     when /this month/
       start_of_month = Time.new(now.year, now.month, 1)
       start_of_month..now

data/lib/tasks/htm.rake

@@ -138,10 +138,41 @@ namespace :htm do
       end
     end
 
+  end
+
+  namespace :doc do
     desc "Generate/update database documentation in dbdoc/"
-    task :doc do
+    task :db do
+      unless system("which tbls > /dev/null 2>&1")
+        puts "Error: 'tbls' is not installed."
+        puts "Install it with: brew install tbls"
+        exit 1
+      end
       require 'htm'
       HTM::Database.generate_docs
     end
+
+    desc "Build documentation site with MkDocs"
+    task :build do
+      unless system("which mkdocs > /dev/null 2>&1")
+        puts "Error: 'mkdocs' is not installed."
+        puts "Install it with: brew install mkdocs"
+        exit 1
+      end
+      sh "mkdocs build"
+    end
+
+    desc "Serve documentation site locally with MkDocs"
+    task :serve do
+      unless system("which mkdocs > /dev/null 2>&1")
+        puts "Error: 'mkdocs' is not installed."
+        puts "Install it with: brew install mkdocs"
+        exit 1
+      end
+      sh "mkdocs serve"
+    end
+
+    desc "Generate DB docs, build site, and serve locally"
+    task :all => [:db, :build, :serve]
   end
 end

data/lib/tasks/jobs.rake

@@ -42,9 +42,13 @@ namespace :htm do
       # Tags by depth
       if total_tags > 0
         puts "\nTag hierarchy breakdown:"
-        HTM::Models::Tag.all.each do |tag|
-          depth = tag.name.count(':')
-          puts "  Depth #{depth}: #{tag.name.count(':', depth)} tags" if depth <= 3
+        depth_counts = Hash.new(0)
+        HTM::Models::Tag.pluck(:name).each do |name|
+          depth = name.count(':')
+          depth_counts[depth] += 1
+        end
+        depth_counts.keys.sort.each do |depth|
+          puts "  Depth #{depth}: #{depth_counts[depth]} tags"
         end
       end
 

data/lib/tasks/tags.rake

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# HTM Tag Management Tasks
+#
+# These tasks are available to any application using the HTM gem.
+# Add to your application's Rakefile:
+#
+#   require 'htm/tasks'
+#
+
+namespace :htm do
+  namespace :tags do
+    desc "Display tags as a hierarchical tree"
+    task :tree do
+      require 'htm'
+
+      # Ensure database connection
+      HTM::ActiveRecordConfig.establish_connection!
+
+      count = HTM::Models::Tag.count
+
+      if count.zero?
+        puts "No tags found in database."
+        next
+      end
+
+      # Display tree using Tag model method
+      puts "\nHTM Tags Tree"
+      puts "=" * 40
+      print HTM::Models::Tag.all.tree_string
+      puts "\nTotal tags: #{count}"
+    end
+  end
+end

data/mkdocs.yml

@@ -13,21 +13,21 @@ edit_uri: edit/main/docs/
 # Configuration
 theme:
   name: material
-  
+
   # Color scheme - Default to light mode
   palette:
     # Palette toggle for light mode (default)
     - scheme: default
-      primary: blue
-      accent: blue
+      primary: indigo
+      accent: deep purple
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
-    
+
     # Palette toggle for dark mode
     - scheme: slate
-      primary: blue
-      accent: blue
+      primary: indigo
+      accent: deep purple
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
@@ -37,6 +37,10 @@ theme:
     text: Roboto
     code: Roboto Mono
 
+  # Logo and icon
+  icon:
+    repo: fontawesome/brands/github
+
   # Theme features
   features:
     # Navigation
@@ -48,6 +52,7 @@ theme:
     - navigation.path
     - navigation.indexes
     - navigation.top
+    - navigation.footer
 
     # Table of contents
     - toc.follow
@@ -72,6 +77,7 @@ theme:
 plugins:
   - search:
       separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
 
 # Extensions
 markdown_extensions:
@@ -82,6 +88,7 @@ markdown_extensions:
   - def_list
   - footnotes
   - md_in_html
+  - tables
   - toc:
       permalink: true
       title: On this page
@@ -92,6 +99,7 @@ markdown_extensions:
   - pymdownx.betterem:
       smart_enable: all
   - pymdownx.caret
+  - pymdownx.critic
   - pymdownx.details
   - pymdownx.emoji:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
@@ -108,6 +116,8 @@ markdown_extensions:
       repo: htm
   - pymdownx.mark
   - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -138,11 +148,28 @@ extra:
       link: https://rubygems.org/gems/htm
       name: HTM on RubyGems
 
+  analytics:
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >-
+            Thanks for your feedback! Help us improve by creating an issue.
+
 # Navigation
 nav:
   - Home: index.md
-  - Installation: installation.md
-  - Quick Start: quick-start.md
+  - Getting Started:
+      - getting-started/index.md
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
   - Architecture:
     - architecture/index.md
     - Overview: architecture/overview.md
@@ -184,7 +211,27 @@ nav:
     - Testing: development/testing.md
     - Contributing: development/contributing.md
     - Database Schema: development/schema.md
+    - Database Tables:
+      - database/README.md
+      - Core Tables:
+        - Robots: database/public.robots.md
+        - Nodes: database/public.nodes.md
+        - Tags: database/public.tags.md
+        - Working Memories: database/public.working_memories.md
+      - Join Tables:
+        - Node Tags: database/public.node_tags.md
+        - Nodes Tags (Legacy): database/public.nodes_tags.md
+        - Robot Nodes: database/public.robot_nodes.md
+      - Views & Stats:
+        - Node Stats: database/public.node_stats.md
+        - Robot Activity: database/public.robot_activity.md
+        - Topic Relationships: database/public.topic_relationships.md
+        - Ontology Structure: database/public.ontology_structure.md
+        - Relationships: database/public.relationships.md
+      - System:
+        - Operations Log: database/public.operations_log.md
+        - Schema Migrations: database/public.schema_migrations.md
     - Multi-Framework Support: multi_framework_support.md
     - Database Rake Tasks: database_rake_tasks.md
     - Using Rake Tasks: using_rake_tasks_in_your_app.md
-    - Setup Local Database: setup_local_database.md
+    - Setup Local Database: setup_local_database.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: htm
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -182,6 +182,7 @@ files:
 - ".architecture/reviews/initial-system-analysis.md"
 - ".envrc"
 - ".irbrc"
+- ".tbls.yml"
 - CHANGELOG.md
 - COMMITS.md
 - LICENSE
@@ -194,38 +195,16 @@ files:
 - db/migrate/20250101000003_create_nodes.rb
 - db/migrate/20250101000005_create_tags.rb
 - db/migrate/20250101000007_add_node_vector_indexes.rb
+- db/migrate/20250125000001_add_content_hash_to_nodes.rb
+- db/migrate/20250125000002_create_robot_nodes.rb
+- db/migrate/20250125000003_remove_source_and_robot_id_from_nodes.rb
+- db/migrate/20250126000001_create_working_memories.rb
+- db/migrate/20250126000002_remove_unused_columns.rb
 - db/schema.sql
 - db/seed_data/README.md
 - db/seed_data/presidents.md
 - db/seed_data/states.md
 - db/seeds.rb
-- dbdoc/README.md
-- dbdoc/public.node_stats.md
-- dbdoc/public.node_stats.svg
-- dbdoc/public.node_tags.md
-- dbdoc/public.node_tags.svg
-- dbdoc/public.nodes.md
-- dbdoc/public.nodes.svg
-- dbdoc/public.nodes_tags.md
-- dbdoc/public.nodes_tags.svg
-- dbdoc/public.ontology_structure.md
-- dbdoc/public.ontology_structure.svg
-- dbdoc/public.operations_log.md
-- dbdoc/public.operations_log.svg
-- dbdoc/public.relationships.md
-- dbdoc/public.relationships.svg
-- dbdoc/public.robot_activity.md
-- dbdoc/public.robot_activity.svg
-- dbdoc/public.robots.md
-- dbdoc/public.robots.svg
-- dbdoc/public.schema_migrations.md
-- dbdoc/public.schema_migrations.svg
-- dbdoc/public.tags.md
-- dbdoc/public.tags.svg
-- dbdoc/public.topic_relationships.md
-- dbdoc/public.topic_relationships.svg
-- dbdoc/schema.json
-- dbdoc/schema.svg
 - docs/api/database.md
 - docs/api/embedding-service.md
 - docs/api/htm.md
@@ -249,23 +228,71 @@ files:
 - docs/architecture/overview.md
 - docs/architecture/two-tier-memory.md
 - docs/assets/css/custom.css
+- docs/assets/images/adr-010-current-architecture.svg
+- docs/assets/images/adr-010-proposed-architecture.svg
+- docs/assets/images/adr-dependency-tree.svg
+- docs/assets/images/class-hierarchy.svg
+- docs/assets/images/exception-hierarchy.svg
+- docs/assets/images/htm-architecture-overview.svg
+- docs/assets/images/htm-complete-memory-flow.svg
+- docs/assets/images/htm-context-assembly-flow.svg
 - docs/assets/images/htm-core-components.svg
 - docs/assets/images/htm-database-schema.svg
+- docs/assets/images/htm-eviction-process.svg
 - docs/assets/images/htm-hive-mind-architecture.svg
 - docs/assets/images/htm-importance-scoring-framework.svg
 - docs/assets/images/htm-layered-architecture.svg
 - docs/assets/images/htm-long-term-memory-architecture.svg
+- docs/assets/images/htm-memory-addition-flow.svg
+- docs/assets/images/htm-memory-recall-flow.svg
+- docs/assets/images/htm-node-states.svg
 - docs/assets/images/htm-working-memory-architecture.svg
 - docs/assets/images/htm.jpg
 - docs/assets/images/htm_demo.gif
+- docs/assets/images/project-structure.svg
+- docs/assets/images/test-directory-structure.svg
 - docs/assets/js/mathjax.js
 - docs/assets/videos/htm_video.mp4
+- docs/database/README.md
+- docs/database/public.node_stats.md
+- docs/database/public.node_stats.svg
+- docs/database/public.node_tags.md
+- docs/database/public.node_tags.svg
+- docs/database/public.nodes.md
+- docs/database/public.nodes.svg
+- docs/database/public.nodes_tags.md
+- docs/database/public.nodes_tags.svg
+- docs/database/public.ontology_structure.md
+- docs/database/public.ontology_structure.svg
+- docs/database/public.operations_log.md
+- docs/database/public.operations_log.svg
+- docs/database/public.relationships.md
+- docs/database/public.relationships.svg
+- docs/database/public.robot_activity.md
+- docs/database/public.robot_activity.svg
+- docs/database/public.robot_nodes.md
+- docs/database/public.robot_nodes.svg
+- docs/database/public.robots.md
+- docs/database/public.robots.svg
+- docs/database/public.schema_migrations.md
+- docs/database/public.schema_migrations.svg
+- docs/database/public.tags.md
+- docs/database/public.tags.svg
+- docs/database/public.topic_relationships.md
+- docs/database/public.topic_relationships.svg
+- docs/database/public.working_memories.md
+- docs/database/public.working_memories.svg
+- docs/database/schema.json
+- docs/database/schema.svg
 - docs/database_rake_tasks.md
 - docs/development/contributing.md
 - docs/development/index.md
 - docs/development/schema.md
 - docs/development/setup.md
 - docs/development/testing.md
+- docs/getting-started/index.md
+- docs/getting-started/installation.md
+- docs/getting-started/quick-start.md
 - docs/guides/adding-memories.md
 - docs/guides/context-assembly.md
 - docs/guides/getting-started.md
@@ -275,10 +302,9 @@ files:
 - docs/guides/recalling-memories.md
 - docs/guides/search-strategies.md
 - docs/guides/working-memory.md
+- docs/images/htm-er-diagram.svg
 - docs/index.md
-- docs/installation.md
 - docs/multi_framework_support.md
-- docs/quick-start.md
 - docs/setup_local_database.md
 - docs/using_rake_tasks_in_your_app.md
 - examples/basic_usage.rb
@@ -288,6 +314,7 @@ files:
 - examples/example_app/Rakefile
 - examples/example_app/app.rb
 - examples/sinatra_app/Gemfile
+- examples/sinatra_app/Gemfile.lock
 - examples/sinatra_app/app.rb
 - lib/htm.rb
 - lib/htm/active_record_config.rb
@@ -295,6 +322,7 @@ files:
 - lib/htm/database.rb
 - lib/htm/embedding_service.rb
 - lib/htm/errors.rb
+- lib/htm/integrations/sinatra.rb
 - lib/htm/job_adapter.rb
 - lib/htm/jobs/generate_embedding_job.rb
 - lib/htm/jobs/generate_tags_job.rb
@@ -302,9 +330,10 @@ files:
 - lib/htm/models/node.rb
 - lib/htm/models/node_tag.rb
 - lib/htm/models/robot.rb
+- lib/htm/models/robot_node.rb
 - lib/htm/models/tag.rb
+- lib/htm/models/working_memory_entry.rb
 - lib/htm/railtie.rb
-- lib/htm/sinatra.rb
 - lib/htm/tag_service.rb
 - lib/htm/tasks.rb
 - lib/htm/version.rb
@@ -312,6 +341,7 @@ files:
 - lib/tasks/db.rake
 - lib/tasks/htm.rake
 - lib/tasks/jobs.rake
+- lib/tasks/tags.rake
 - mkdocs.yml
 - scripts/install_local_database.sh
 homepage: https://github.com/madbomber/htm