robot_lab-durable 0.2.1 → 0.2.6

data/lib/robot_lab/durable/adapter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'htm'
+
+module RobotLab
+  module Durable
+    class Adapter
+      attr_reader :htm
+
+      def initialize(robot_name:)
+        @htm = HTM.new(robot_name: robot_name)
+      end
+
+      # Recall entries relevant to a query using HTM hybrid search.
+      #
+      # @param query [String] Natural-language search string
+      # @param limit [Integer] Maximum number of results
+      # @param strategy [Symbol] :vector, :fulltext, or :hybrid
+      # @return [Array<Entry>]
+      def recall(query:, limit: 20, strategy: :hybrid)
+        nodes = @htm.recall(query, limit: limit, strategy: strategy, raw: true)
+        nodes.map { |node| Entry.from_node(node) }
+      end
+
+      # Store content in HTM long-term memory.
+      #
+      # @param content [String]
+      # @param reasoning [String, nil] Why this is worth remembering
+      # @param category [String, Symbol] fact, preference, pattern, correction, or observation
+      # @return [Integer] HTM node_id
+      def record(content:, reasoning: nil, category: 'fact')
+        @htm.remember(
+          content,
+          metadata: {
+            'reasoning' => reasoning,
+            'category'  => category.to_s
+          }
+        )
+      end
+    end
+  end
+end

data/lib/robot_lab/durable/entry.rb

@@ -2,46 +2,15 @@
 
 module RobotLab
   module Durable
-    CONFIDENCE_INCREMENT = 0.1
-    MAX_CONFIDENCE       = 1.0
-
-    Entry = Data.define(:content, :reasoning, :category, :domain, :confidence, :use_count, :created_at, :updated_at) do
-      # Return a new Entry with confidence incremented and use_count bumped.
-      def confirm
-        new_confidence = [confidence + CONFIDENCE_INCREMENT, MAX_CONFIDENCE].min
-        with(
-          confidence: new_confidence.round(10),
-          use_count: use_count + 1,
-          updated_at: Time.now.iso8601
-        )
-      end
-
-      # Serialize to a plain Hash with string keys (safe for YAML round-trip).
-      def to_h
-        {
-          'content' => content,
-          'reasoning' => reasoning,
-          'category' => category.to_s,
-          'domain' => domain,
-          'confidence' => confidence,
-          'use_count' => use_count,
-          'created_at' => created_at,
-          'updated_at' => updated_at
-        }
-      end
-
-      # Deserialize from a Hash (string or symbol keys).
-      def self.from_h(hash)
-        h = hash.transform_keys(&:to_s)
+    Entry = Data.define(:node_id, :content, :reasoning, :category, :created_at) do
+      def self.from_node(node)
+        meta = node['metadata'] || {}
         new(
-          content: h['content'],
-          reasoning: h['reasoning'],
-          category: h['category']&.to_sym,
-          domain: h['domain'],
-          confidence: h['confidence'].to_f,
-          use_count: h['use_count'].to_i,
-          created_at: h['created_at'],
-          updated_at: h['updated_at']
+          node_id:    node['id'],
+          content:    node['content'],
+          reasoning:  meta['reasoning'],
+          category:   (meta['category'] || 'fact').to_sym,
+          created_at: node['created_at']
         )
       end
     end

data/lib/robot_lab/durable/hook.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Durable
+    class Hook < RobotLab::Hook
+      self.namespace = :durable
+
+      class << self
+        # Initialize an HTM-backed adapter for the robot and make it available
+        # thread-locally for the duration of the run, then tear it down.
+        def around_run(ctx, &block)
+          robot_name = ctx.robot.name || 'default'
+          set_adapter(Adapter.new(robot_name: robot_name))
+          block.call
+        ensure
+          clear_adapter
+        end
+
+        # Persist new session learnings to HTM long-term memory.
+        # HTM deduplicates by content hash, so double-writes from RecordKnowledge
+        # are harmless — the second call simply increments remember_count.
+        def on_learn(ctx)
+          return unless ctx.stored
+
+          adapter = current_adapter
+          return unless adapter
+
+          adapter.record(content: ctx.text, category: :observation)
+        end
+
+        # Returns the active durable adapter for the current thread, or nil.
+        def current_adapter
+          Thread.current[:robot_lab_durable_adapter]
+        end
+
+        private
+
+        def set_adapter(adapter)
+          Thread.current[:robot_lab_durable_adapter] = adapter
+        end
+
+        def clear_adapter
+          Thread.current[:robot_lab_durable_adapter] = nil
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/durable/version.rb

@@ -2,6 +2,6 @@
 
 module RobotLab
   module Durable
-    VERSION = '0.2.1'
+    VERSION = '0.2.6'
   end
 end

data/lib/robot_lab/durable.rb

@@ -2,25 +2,23 @@
 
 require_relative 'durable/version'
 require_relative 'durable/entry'
-require_relative 'durable/store'
-require_relative 'durable/reflector'
-require_relative 'durable/learning'
+require_relative 'durable/adapter'
 
-# Minimal error stub so the storage layer works without robot_lab loaded.
+# Minimal error stub so the adapter layer works without robot_lab loaded.
 # When robot_lab is present its own RobotLab::Error takes precedence.
 module RobotLab
   Error = StandardError unless defined?(Error)
 end
 
-# When robot_lab is loaded, register the knowledge tools and hook the
-# Learning mixin into Robot so `learn: true` works in the constructor.
+if defined?(RobotLab::Hook)
+  require_relative 'durable/hook'
+end
+
 if defined?(RobotLab::Tool)
   require_relative 'recall_knowledge'
   require_relative 'record_knowledge'
 end
 
-RobotLab::Robot.include(RobotLab::Durable::Learning) if defined?(RobotLab::Robot)
-
 if defined?(RobotLab) && RobotLab.respond_to?(:register_extension)
   RobotLab.register_extension(:durable, RobotLab::Durable)
 end

data/lib/robot_lab/recall_knowledge.rb

@@ -7,22 +7,18 @@ module RobotLab
                 'to check if you have seen a similar situation before. ' \
                 'When in doubt and no relevant knowledge is found, skip the action.'
 
-    param :query,  type: 'string', desc: 'Natural language description of the decision you are about to make'
-    param :domain, type: 'string', desc: "Topic area to search (e.g. 'newsletter curation')", required: false
+    param :query, type: 'string', desc: 'Natural language description of the decision you are about to make'
 
-    def execute(query:, domain: nil)
-      store = robot&.durable_store
-      return 'No durable store configured on this robot.' unless store
+    def execute(query:)
+      adapter = RobotLab::Durable::Hook.current_adapter
+      return 'No durable session active on this robot.' unless adapter
 
-      entries = store.recall(query: query, domain: domain, min_confidence: 0.0)
+      entries = adapter.recall(query: query)
 
       if entries.empty?
         "No relevant past knowledge found for: #{query}. When in doubt, skip."
       else
-        lines = entries.map do |e|
-          "[#{e.category}/conf:#{format('%.1f', e.confidence)}] #{e.content} — #{e.reasoning}"
-        end
-
+        lines = entries.map { |e| "[#{e.category}] #{e.content} — #{e.reasoning}" }
         "Relevant past knowledge:\n#{lines.join("\n")}"
       end
     end

data/lib/robot_lab/record_knowledge.rb

@@ -11,26 +11,16 @@ module RobotLab
     param :reasoning, type: 'string',
                       desc: 'Why this is worth remembering — the observation or discussion that led to it'
     param :category,  type: 'string', desc: 'One of: fact, preference, pattern, correction'
-    param :domain,    type: 'string', desc: "Topic area this applies to (e.g. 'newsletter curation', 'ruby tooling')"
 
-    def execute(content:, reasoning:, category:, domain:)
-      store = robot&.durable_store
-      return 'No durable store configured on this robot.' unless store
+    def execute(content:, reasoning:, category:)
+      adapter = RobotLab::Durable::Hook.current_adapter
+      return 'No durable session active on this robot.' unless adapter
 
-      now = Time.now.iso8601
-      entry = Durable::Entry.new(
-        content:,
-        reasoning:,
-        category: category.to_sym,
-        domain:,
-        confidence: 0.1,
-        use_count: 0,
-        created_at: now,
-        updated_at: now
-      )
+      adapter.record(content: content, reasoning: reasoning, category: category)
 
-      store.record(entry)
-      robot.learn("#{content} (#{domain})")
+      # Update session memory so subsequent LLM calls in this run see the fact.
+      # HTM deduplicates by content hash, so the on_learn callback that follows is safe.
+      robot.learn(content)
 
       "Recorded: #{content}"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab-durable
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -23,10 +23,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.2.0
-description: Provides RobotLab::Durable — a YAML-backed knowledge store that lets
-  robot_lab agents accumulate and recall observations across sessions. Includes Entry
-  (immutable value object with confidence scoring), Store (file-locked per-domain
-  persistence), Reflector (end-of-session promoter), and the Learning mixin with RecallKnowledge/RecordKnowledge
+- !ruby/object:Gem::Dependency
+  name: htm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides RobotLab::Durable — an adapter between robot_lab and the HTM
+  gem (Hierarchical Temporal Memory). Replaces the former YAML store with PostgreSQL-backed
+  long-term memory featuring vector embeddings, hybrid semantic search, hierarchical
+  tagging, and multi-robot federation. Includes RecallKnowledge and RecordKnowledge
   tools that integrate directly into Robot when robot_lab is present.
 email:
 - dvanhoozer@gmail.com
@@ -36,8 +50,11 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -45,13 +62,13 @@ files:
 - docs/index.md
 - docs/superpowers/plans/2026-05-06-durable-learning.md
 - docs/superpowers/specs/2026-05-06-durable-learning-design.md
-- examples/33_stock_generator.rb
-- examples/33_stock_predictor.rb
+- examples/01_day_trader.rb
+- examples/day_trader_lib/generator.rb
+- examples/day_trader_lib/predictor.rb
 - lib/robot_lab/durable.rb
+- lib/robot_lab/durable/adapter.rb
 - lib/robot_lab/durable/entry.rb
-- lib/robot_lab/durable/learning.rb
-- lib/robot_lab/durable/reflector.rb
-- lib/robot_lab/durable/store.rb
+- lib/robot_lab/durable/hook.rb
 - lib/robot_lab/durable/version.rb
 - lib/robot_lab/recall_knowledge.rb
 - lib/robot_lab/record_knowledge.rb
@@ -78,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.17
 specification_version: 4
-summary: Cross-session durable learning for RobotLab agents
+summary: HTM-backed long-term memory for RobotLab agents
 test_files: []

data/lib/robot_lab/durable/learning.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module Durable
-    module Learning
-      # Configure durable learning on a robot after initialization.
-      #
-      # @param domain [String] topic area for this robot's knowledge
-      # @param store_path [String, nil] override default ~/.robot_lab/durable path
-      def setup_durable_learning(domain:, store_path: nil)
-        @learn_domain  = domain.to_s
-        opts           = store_path ? { path: store_path } : {}
-        @durable_store = Store.new(**opts)
-
-        seed_from_store
-        @local_tools = (@local_tools + [RecallKnowledge, RecordKnowledge]).uniq
-      end
-
-      # Run the end-of-session reflection pass.
-      # Called automatically from Robot#run when durable learning is active.
-      def run_reflector
-        return unless @durable_store && @learn_domain && @learnings&.any?
-
-        Reflector.new(store: @durable_store, domain: @learn_domain).reflect(@learnings)
-      end
-
-      private
-
-      def seed_from_store
-        return unless @durable_store && @learn_domain
-
-        entries = @durable_store.recall(query: @learn_domain, domain: @learn_domain, min_confidence: 0.0)
-        entries.each do |e|
-          learn("[#{e.category}] #{e.content}: #{e.reasoning}")
-        end
-      end
-    end
-  end
-end

data/lib/robot_lab/durable/reflector.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  module Durable
-    class Reflector
-      def initialize(store:, domain:)
-        @store  = store
-        @domain = domain.to_s
-      end
-
-      # Examine plain-text learnings accumulated during a session and promote
-      # any that are not already represented in the store.
-      #
-      # @param learnings [Array<String>] robot.learnings from the completed session
-      def reflect(learnings)
-        Array(learnings).each do |text|
-          next if text.nil? || text.strip.empty?
-
-          text = text.strip
-          next if already_stored?(text)
-
-          now = Time.now.iso8601
-          @store.record(
-            Entry.new(
-              content: text,
-              reasoning: 'Observed during session (auto-promoted by Reflector)',
-              category: :pattern,
-              domain: @domain,
-              confidence: 0.1,
-              use_count: 0,
-              created_at: now,
-              updated_at: now
-            )
-          )
-        end
-      end
-
-      private
-
-      def already_stored?(text)
-        @store.recall(query: text, domain: @domain, min_confidence: 0.0).any? do |e|
-          e.content.downcase == text.downcase
-        end
-      end
-    end
-  end
-end

data/lib/robot_lab/durable/store.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-require 'fileutils'
-
-module RobotLab
-  module Durable
-    class Store
-      DEFAULT_PATH = File.join(Dir.home, '.robot_lab', 'durable')
-
-      MIN_WORD_LENGTH = 3
-
-      def initialize(path: DEFAULT_PATH)
-        @path = path
-        FileUtils.mkdir_p(@path)
-      end
-
-      # Return entries matching query keywords, sorted by descending confidence.
-      #
-      # @param query [String] natural-language search string
-      # @param domain [String, nil] restrict to one domain file; nil searches all
-      # @param min_confidence [Float] exclude entries below this threshold
-      # @return [Array<Entry>]
-      def recall(query:, domain: nil, min_confidence: 0.0)
-        entries = domain ? load_domain(domain) : load_all
-        words   = tokenize(query)
-
-        entries
-          .select { |e| e.confidence >= min_confidence }
-          .select { |e| matches?(e, words) }
-          .sort_by { |e| -e.confidence }
-      end
-
-      # Persist a new entry. If an entry with the same content already exists
-      # in the domain file, increment its confidence and use_count instead.
-      #
-      # @param entry [Entry]
-      # @return [Entry] the stored entry (may differ if an existing one was updated)
-      def record(entry)
-        with_domain_lock(entry.domain) do
-          entries = load_domain(entry.domain)
-          idx     = entries.find_index { |e| e.content.downcase == entry.content.downcase }
-
-          if idx
-            entries[idx] = entries[idx].confirm
-          else
-            entries << entry
-          end
-
-          save_domain(entry.domain, entries)
-          entries[idx || -1]
-        end
-      end
-
-      # Increment confidence and use_count on a stored entry.
-      #
-      # @param entry [Entry]
-      # @return [Entry] the updated entry
-      def confirm(entry)
-        updated = entry.confirm
-        record_exact(updated)
-        updated
-      end
-
-      private
-
-      def matches?(entry, words)
-        text = "#{entry.content} #{entry.domain}".downcase
-        words.any? { |w| text.include?(w) }
-      end
-
-      def tokenize(str)
-        str.downcase.split(/\s+/).reject { |w| w.length < MIN_WORD_LENGTH }
-      end
-
-      def load_domain(domain)
-        file = domain_file(domain)
-        return [] unless File.exist?(file)
-
-        raw = Array(YAML.safe_load_file(file) || [])
-        raw.map { |h| Entry.from_h(h) }
-      end
-
-      def load_all
-        Dir.glob(File.join(@path, '*.yaml')).flat_map do |file|
-          raw = Array(YAML.safe_load_file(file) || [])
-          raw.map { |h| Entry.from_h(h) }
-        end
-      end
-
-      def save_domain(domain, entries)
-        File.write(domain_file(domain), YAML.dump(entries.map(&:to_h)))
-      end
-
-      def record_exact(entry)
-        with_domain_lock(entry.domain) do
-          entries = load_domain(entry.domain)
-          idx     = entries.find_index { |e| e.content.downcase == entry.content.downcase }
-          raise RobotLab::Error, "Cannot confirm: entry not found in domain '#{entry.domain}'" unless idx
-
-          entries[idx] = entry
-          save_domain(entry.domain, entries)
-        end
-      end
-
-      def domain_file(domain)
-        safe = domain.to_s.downcase.gsub(/[^a-z0-9]+/, '_').delete_prefix('_').delete_suffix('_')
-        File.join(@path, "#{safe}.yaml")
-      end
-
-      def with_domain_lock(domain, &block)
-        lock_path = "#{domain_file(domain)}.lock"
-        File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |f|
-          f.flock(File::LOCK_EX)
-          block.call
-        end
-      end
-    end
-  end
-end