lex-working-memory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: edc8c24f643c909f8a668cf4f6912cca4b8fd080bd92627015b954fb58a12027
+  data.tar.gz: bd91d9be62389bff276be79db7074224d937ecd3cfcfb45abd1fd6366515c4ab
+SHA512:
+  metadata.gz: 56bae8720995069cdb1b4e54bd43045af761eeeacb1a82a3a67bc59c664b56caf730f5a475c1cffe51395290d038f49142965f7f81630e101798bd3be8731e81
+  data.tar.gz: 4f55b708fe07e3a954ce1f89b67a7d9e5906095888347824e224350da32533e1ac31d972b71c2ff642cdde70f4502aa4df3c1f1d2dd885370f6b193323ee4638

data/lib/legion/extensions/working_memory/client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      class Client
+        include Runners::WorkingMemory
+
+        attr_reader :buffer
+
+        def initialize(buffer: nil, **)
+          @buffer = buffer || Helpers::Buffer.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/working_memory/helpers/buffer.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      module Helpers
+        class Buffer
+          attr_reader :items
+
+          def initialize
+            @items = []
+          end
+
+          def store(content:, buffer_type: :episodic, priority: :normal, tags: [])
+            item = BufferItem.new(content: content, buffer_type: buffer_type, priority: priority, tags: tags)
+            @items << item
+            evict_if_over_capacity
+            item
+          end
+
+          def retrieve(id)
+            @items.find { |i| i.id == id }
+          end
+
+          def retrieve_by_tag(tag)
+            @items.select { |i| i.tags.include?(tag) }
+          end
+
+          def retrieve_by_type(buffer_type)
+            @items.select { |i| i.buffer_type == buffer_type }
+          end
+
+          def rehearse(id)
+            item = retrieve(id)
+            return nil unless item
+
+            item.rehearse
+            item
+          end
+
+          def remove(id)
+            @items.reject! { |i| i.id == id }
+          end
+
+          def tick_decay
+            @items.each(&:decay)
+            @items.reject!(&:expired?)
+          end
+
+          def consolidation_candidates
+            @items.select(&:consolidation_ready?)
+          end
+
+          def current_load
+            return 0.0 if capacity.zero?
+
+            (@items.size.to_f / capacity).clamp(0.0, 1.0)
+          end
+
+          def load_level
+            load = current_load
+            Constants::LOAD_LEVELS.each do |level, threshold|
+              return level if load >= threshold
+            end
+            :idle
+          end
+
+          def capacity
+            Constants::CAPACITY + chunk_bonus
+          end
+
+          def available_slots
+            [capacity - @items.size, 0].max
+          end
+
+          def full?
+            @items.size >= capacity
+          end
+
+          def clear
+            @items.clear
+          end
+
+          def size
+            @items.size
+          end
+
+          def to_h
+            {
+              size:       @items.size,
+              capacity:   capacity,
+              load:       current_load.round(4),
+              load_level: load_level,
+              by_type:    items_by_type,
+              available:  available_slots
+            }
+          end
+
+          private
+
+          def chunk_bonus
+            chunked = @items.group_by { |i| i.tags.first }.count { |_, group| group.size > 1 }
+            [chunked, Constants::CHUNK_BONUS].min
+          end
+
+          def evict_if_over_capacity
+            return unless @items.size > capacity
+
+            @items.sort_by!(&:activation)
+            @items.shift(@items.size - capacity)
+          end
+
+          def items_by_type
+            Constants::BUFFER_TYPES.to_h { |t| [t, @items.count { |i| i.buffer_type == t }] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/working_memory/helpers/buffer_item.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      module Helpers
+        class BufferItem
+          attr_reader :id, :content, :buffer_type, :priority, :tags, :created_at
+          attr_accessor :activation, :rehearsal_count, :age_ticks
+
+          def initialize(content:, buffer_type: :episodic, priority: :normal, tags: [])
+            @id              = SecureRandom.uuid
+            @content         = content
+            @buffer_type     = buffer_type
+            @priority        = priority
+            @tags            = tags
+            @activation      = Constants::PRIORITY_LEVELS[priority] || 0.5
+            @rehearsal_count = 0
+            @age_ticks       = 0
+            @created_at      = Time.now.utc
+          end
+
+          def rehearse
+            @rehearsal_count += 1
+            @activation = [@activation + Constants::REHEARSAL_BOOST, 1.0].min
+            @age_ticks = 0
+          end
+
+          def decay
+            @age_ticks += 1
+            @activation = [@activation - Constants::DECAY_RATE, 0.0].max
+          end
+
+          def expired?
+            @age_ticks >= Constants::MAX_AGE_TICKS || @activation <= 0.0
+          end
+
+          def consolidation_ready?
+            @activation >= Constants::CONSOLIDATION_THRESHOLD
+          end
+
+          def interferes_with?(other)
+            return false unless other.is_a?(BufferItem)
+            return false if @buffer_type != other.buffer_type
+
+            @tags.any? { |t| other.tags.include?(t) } && (@activation - other.activation).abs < Constants::INTERFERENCE_THRESHOLD
+          end
+
+          def to_h
+            {
+              id:                  @id,
+              content:             @content,
+              buffer_type:         @buffer_type,
+              priority:            @priority,
+              activation:          @activation.round(4),
+              rehearsal_count:     @rehearsal_count,
+              age_ticks:           @age_ticks,
+              expired:             expired?,
+              consolidation_ready: consolidation_ready?
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/working_memory/helpers/constants.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      module Helpers
+        module Constants
+          CAPACITY = 7
+
+          CHUNK_BONUS = 3
+
+          BUFFER_TYPES = %i[verbal spatial episodic].freeze
+
+          DECAY_RATE = 0.15
+
+          REHEARSAL_BOOST = 0.3
+
+          PRIORITY_LEVELS = {
+            critical:   1.0,
+            high:       0.75,
+            normal:     0.5,
+            low:        0.25,
+            background: 0.1
+          }.freeze
+
+          MAX_AGE_TICKS = 30
+
+          INTERFERENCE_THRESHOLD = 0.7
+
+          CONSOLIDATION_THRESHOLD = 0.8
+
+          LOAD_LEVELS = {
+            overloaded: 1.0,
+            high:       0.75,
+            moderate:   0.5,
+            low:        0.25,
+            idle:       0.0
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/working_memory/runners/working_memory.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      module Runners
+        module WorkingMemory
+          include Legion::Extensions::Helpers::Lex
+
+          def buffer
+            @buffer ||= Helpers::Buffer.new
+          end
+
+          def update_working_memory(**)
+            buffer.tick_decay
+            candidates = buffer.consolidation_candidates
+            Legion::Logging.debug "[working_memory] tick: size=#{buffer.size} load=#{buffer.load_level} candidates=#{candidates.size}"
+            { success: true, status: buffer.to_h, consolidation_candidates: candidates.map(&:to_h) }
+          end
+
+          def store_item(content:, buffer_type: :episodic, priority: :normal, tags: [], **)
+            Legion::Logging.debug '[working_memory] buffer full, eviction will occur' if buffer.full?
+
+            item = buffer.store(content: content, buffer_type: buffer_type, priority: priority, tags: tags)
+            Legion::Logging.debug "[working_memory] stored item=#{item.id} type=#{buffer_type} priority=#{priority}"
+            { success: true, item: item.to_h }
+          end
+
+          def retrieve_item(id:, **)
+            item = buffer.retrieve(id)
+            return { success: false, reason: :not_found } unless item
+
+            { success: true, item: item.to_h }
+          end
+
+          def rehearse_item(id:, **)
+            item = buffer.rehearse(id)
+            return { success: false, reason: :not_found } unless item
+
+            Legion::Logging.debug "[working_memory] rehearsed item=#{id} activation=#{item.activation.round(4)}"
+            { success: true, item: item.to_h }
+          end
+
+          def retrieve_by_tag(tag:, **)
+            items = buffer.retrieve_by_tag(tag)
+            { success: true, items: items.map(&:to_h), count: items.size }
+          end
+
+          def retrieve_by_type(buffer_type:, **)
+            items = buffer.retrieve_by_type(buffer_type)
+            { success: true, items: items.map(&:to_h), count: items.size }
+          end
+
+          def remove_item(id:, **)
+            buffer.remove(id)
+            Legion::Logging.debug "[working_memory] removed item=#{id}"
+            { success: true }
+          end
+
+          def buffer_status(**)
+            { success: true, status: buffer.to_h }
+          end
+
+          def consolidation_candidates(**)
+            candidates = buffer.consolidation_candidates
+            { success: true, candidates: candidates.map(&:to_h), count: candidates.size }
+          end
+
+          def working_memory_stats(**)
+            {
+              success:    true,
+              size:       buffer.size,
+              capacity:   buffer.capacity,
+              load:       buffer.current_load.round(4),
+              load_level: buffer.load_level,
+              full:       buffer.full?,
+              available:  buffer.available_slots
+            }
+          end
+
+          def clear_buffer(**)
+            buffer.clear
+            Legion::Logging.debug '[working_memory] buffer cleared'
+            { success: true }
+          end
+
+          def find_interference(id:, **)
+            item = buffer.retrieve(id)
+            return { success: false, reason: :not_found } unless item
+
+            interfering = buffer.items.select { |other| other.id != id && item.interferes_with?(other) }
+            { success: true, item_id: id, interfering: interfering.map(&:to_h), count: interfering.size }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/working_memory/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/working_memory.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'working_memory/version'
+require_relative 'working_memory/helpers/constants'
+require_relative 'working_memory/helpers/buffer_item'
+require_relative 'working_memory/helpers/buffer'
+require_relative 'working_memory/runners/working_memory'
+require_relative 'working_memory/client'
+
+module Legion
+  module Extensions
+    module WorkingMemory
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: lex-working-memory
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Short-term active maintenance of task-relevant information with capacity
+  limits, decay, and rehearsal
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/working_memory.rb
+- lib/legion/extensions/working_memory/client.rb
+- lib/legion/extensions/working_memory/helpers/buffer.rb
+- lib/legion/extensions/working_memory/helpers/buffer_item.rb
+- lib/legion/extensions/working_memory/helpers/constants.rb
+- lib/legion/extensions/working_memory/runners/working_memory.rb
+- lib/legion/extensions/working_memory/version.rb
+homepage: https://github.com/LegionIO/lex-working-memory
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Working memory buffer for LegionIO cognitive agents
+test_files: []