robot_lab-durable 0.1.0

data/lib/robot_lab/durable/reflector.rb

@@ -0,0 +1,47 @@
+# 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

@@ -0,0 +1,119 @@
+# 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.read(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.read(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

data/lib/robot_lab/durable/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Durable
+    VERSION = "0.1.0"
+  end
+end

data/lib/robot_lab/durable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "durable/version"
+require_relative "durable/entry"
+require_relative "durable/store"
+require_relative "durable/reflector"
+require_relative "durable/learning"
+
+# Minimal error stub so the storage 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::Tool)
+  require_relative "recall_knowledge"
+  require_relative "record_knowledge"
+end
+
+if defined?(RobotLab::Robot)
+  RobotLab::Robot.include(RobotLab::Durable::Learning)
+end

data/lib/robot_lab/recall_knowledge.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class RecallKnowledge < Tool
+    description "Recall relevant knowledge from past sessions before making a decision. " \
+                "Use this when uncertain whether to include or skip content, or when you want " \
+                "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
+
+    def execute(query:, domain: nil)
+      store = robot&.durable_store
+      return "No durable store configured on this robot." unless store
+
+      entries = store.recall(query: query, domain: domain, min_confidence: 0.0)
+
+      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
+
+        "Relevant past knowledge:\n#{lines.join("\n")}"
+      end
+    end
+  end
+end

data/lib/robot_lab/record_knowledge.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class RecordKnowledge < Tool
+    description "Record a piece of knowledge learned during this session. " \
+                "Use after a decision or discussion reveals something worth remembering: " \
+                "a user preference, a reliable pattern, or a factual insight. " \
+                "Recorded knowledge persists across future sessions."
+
+    param :content,   type: "string", desc: "The knowledge to record, in plain language (one clear statement)"
+    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
+
+      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
+      )
+
+      store.record(entry)
+      robot.learn("#{content} (#{domain})")
+
+      "Recorded: #{content}"
+    end
+  end
+end

data/mkdocs.yml

@@ -0,0 +1,116 @@
+site_name: robot_lab-durable
+site_description: Cross-session durable learning for the RobotLab LLM agent framework
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/robot_lab-durable
+copyright: Copyright © 2025 Dewayne VanHoozer
+
+repo_name: MadBomber/robot_lab-durable
+repo_url: https://github.com/MadBomber/robot_lab-durable
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: green
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: green
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/brain
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: robot_lab-durable
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/robot_lab-durable
+      name: robot_lab-durable on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/robot_lab-durable
+      name: robot_lab-durable on RubyGems
+
+nav:
+  - Home: index.md
+  - Design & Planning:
+      - Implementation Plan: superpowers/plans/2026-05-06-durable-learning.md
+      - Design Spec: superpowers/specs/2026-05-06-durable-learning-design.md

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: robot_lab-durable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dewayne VanHoozer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: robot_lab
+  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 — 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
+  tools that integrate directly into Robot when robot_lab is present.
+email:
+- dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- 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
+- lib/robot_lab/durable.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/version.rb
+- lib/robot_lab/recall_knowledge.rb
+- lib/robot_lab/record_knowledge.rb
+- mkdocs.yml
+homepage: https://github.com/MadBomber/robot_lab-durable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MadBomber/robot_lab-durable
+  source_code_uri: https://github.com/MadBomber/robot_lab-durable
+  changelog_uri: https://github.com/MadBomber/robot_lab-durable/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Cross-session durable learning for RobotLab agents
+test_files: []