lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/echo_chamber/helpers/echo.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module EchoChamber
+          module Helpers
+            class Echo
+              include Constants
+
+              attr_reader :id, :content, :echo_type, :domain, :source_agent,
+                          :amplitude, :frequency, :original_amplitude, :created_at
+
+              def initialize(content:, echo_type: :belief, domain: :general,
+                             source_agent: nil, amplitude: DEFAULT_AMPLITUDE)
+                @id               = SecureRandom.uuid
+                @content          = content
+                @echo_type        = validate_type(echo_type)
+                @domain           = domain.to_sym
+                @source_agent     = source_agent
+                @amplitude        = amplitude.to_f.clamp(0.0, 1.0).round(10)
+                @original_amplitude = @amplitude
+                @frequency        = 1
+                @created_at       = Time.now.utc
+              end
+
+              def amplify!(rate = AMPLIFICATION_RATE)
+                @frequency += 1
+                @amplitude = (@amplitude + rate).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def dampen!(rate = DECAY_RATE)
+                @amplitude = (@amplitude - rate).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def resonate?
+                @amplitude >= DISRUPTION_THRESHOLD
+              end
+
+              def fading?
+                @amplitude <= POROUS_THRESHOLD
+              end
+
+              def silent?
+                @amplitude <= SILENT_THRESHOLD
+              end
+
+              def frequency_label
+                Constants.label_for(RESONANCE_LABELS, frequency_score)
+              end
+
+              def amplitude_label
+                Constants.label_for(AMPLIFICATION_LABELS, @amplitude)
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  content:            @content,
+                  echo_type:          @echo_type,
+                  domain:             @domain,
+                  source_agent:       @source_agent,
+                  amplitude:          @amplitude,
+                  original_amplitude: @original_amplitude,
+                  frequency:          @frequency,
+                  frequency_label:    frequency_label,
+                  amplitude_label:    amplitude_label,
+                  resonate:           resonate?,
+                  fading:             fading?,
+                  silent:             silent?,
+                  created_at:         @created_at
+                }
+              end
+
+              private
+
+              def validate_type(type)
+                sym = type.to_sym
+                ECHO_TYPES.include?(sym) ? sym : :belief
+              end
+
+              def frequency_score
+                [@frequency.to_f / 20.0, 1.0].min.round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/echo_chamber/runners/cognitive_echo_chamber.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module EchoChamber
+          module Runners
+            module CognitiveEchoChamber
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_echo(content:, echo_type: :belief, domain: :general,
+                              source_agent: nil, amplitude: 0.5, engine: nil, **)
+                raise ArgumentError, 'content cannot be empty' if content.to_s.strip.empty?
+
+                eng  = engine || default_engine
+                echo = eng.create_echo(
+                  content:      content,
+                  echo_type:    echo_type,
+                  domain:       domain,
+                  source_agent: source_agent,
+                  amplitude:    amplitude
+                )
+                Legion::Logging.debug "[cognitive_echo_chamber] echo created id=#{echo.id} type=#{echo_type} domain=#{domain}"
+                { success: true, echo: echo.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def create_chamber(label:, domain: :general, wall_thickness: 0.5, engine: nil, **)
+                raise ArgumentError, 'label cannot be empty' if label.to_s.strip.empty?
+
+                eng     = engine || default_engine
+                chamber = eng.create_chamber(label: label, domain: domain, wall_thickness: wall_thickness)
+                Legion::Logging.debug "[cognitive_echo_chamber] chamber created id=#{chamber.id} label=#{label}"
+                { success: true, chamber: chamber.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def amplify(echo_id:, rate: 0.1, engine: nil, **)
+                eng  = engine || default_engine
+                echo = eng.amplify_echo(echo_id: echo_id, rate: rate)
+                return { success: false, error: 'echo not found' } unless echo
+
+                Legion::Logging.debug "[cognitive_echo_chamber] amplified echo=#{echo_id} amplitude=#{echo.amplitude}"
+                { success: true, echo: echo.to_h }
+              end
+
+              def disrupt(chamber_id:, force:, engine: nil, **)
+                eng    = engine || default_engine
+                result = eng.disrupt_chamber(chamber_id: chamber_id, force: force)
+                Legion::Logging.debug "[cognitive_echo_chamber] disrupt chamber=#{chamber_id} success=#{result[:success]}"
+                result
+              end
+
+              def list_echoes(echo_type: nil, domain: nil, engine: nil, **)
+                eng    = engine || default_engine
+                echoes = if echo_type
+                           eng.echoes_by_type(echo_type: echo_type)
+                         else
+                           eng.active_echoes
+                         end
+                echoes = echoes.select { |e| e.domain == domain.to_sym } if domain
+                { success: true, echoes: echoes.map(&:to_h), count: echoes.size }
+              end
+
+              def chamber_status(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, **eng.echo_report }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::ChamberEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/echo_chamber/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module EchoChamber
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/echo_chamber.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'echo_chamber/version'
+require_relative 'echo_chamber/helpers/constants'
+require_relative 'echo_chamber/helpers/echo'
+require_relative 'echo_chamber/helpers/chamber'
+require_relative 'echo_chamber/helpers/chamber_engine'
+require_relative 'echo_chamber/runners/cognitive_echo_chamber'
+require_relative 'echo_chamber/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module EchoChamber
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/episodic/actors/decay.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Memory::Episodic::Runners::EpisodicBuffer
+              end
+
+              def runner_function
+                'update_episodic_buffer'
+              end
+
+              def time
+                15
+              end
+
+              def run_now?
+                false
+              end
+
+              def use_runner?
+                false
+              end
+
+              def check_subtask?
+                false
+              end
+
+              def generate_task?
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/episodic/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/episodic/runners/episodic_buffer'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          class Client
+            include Legion::Extensions::Agentic::Memory::Episodic::Runners::EpisodicBuffer
+
+            def initialize(store: nil, **)
+              @default_store = store || Helpers::EpisodicStore.new
+            end
+
+            private
+
+            attr_reader :default_store
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/episodic/helpers/constants.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          module Helpers
+            module Constants
+              MAX_EPISODES             = 30
+              MAX_BINDINGS_PER_EPISODE = 10
+              MAX_HISTORY              = 200
+              EPISODE_TTL              = 120
+              BINDING_STRENGTH_FLOOR   = 0.05
+              BINDING_DECAY            = 0.015
+              DEFAULT_BINDING_STRENGTH = 0.5
+              ATTENTION_BOOST          = 0.2
+              REHEARSAL_BOOST          = 0.15
+              INTEGRATION_THRESHOLD    = 0.4
+              RECENTLY_ACCESSED_WINDOW = 30
+
+              MODALITIES = %i[verbal visual spatial semantic emotional procedural temporal].freeze
+
+              COHERENCE_LABELS = {
+                (0.0...0.3)  => :fragmented,
+                (0.3...0.6)  => :partial,
+                (0.6...0.85) => :coherent,
+                (0.85..1.0)  => :vivid
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/episodic/helpers/episode.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          module Helpers
+            class Episode
+              include Constants
+
+              attr_reader :id, :bindings, :created_at, :last_accessed
+
+              def initialize
+                @id            = SecureRandom.uuid
+                @bindings      = {}
+                @created_at    = Time.now
+                @last_accessed = Time.now
+              end
+
+              def add_binding(modality:, content:, source:, strength: DEFAULT_BINDING_STRENGTH)
+                return { added: false, reason: :capacity_full } if @bindings.size >= MAX_BINDINGS_PER_EPISODE
+
+                binding = EpisodicBinding.new(modality: modality, content: content, source: source, strength: strength)
+                @bindings[binding.id] = binding
+                { added: true, binding_id: binding.id }
+              end
+
+              def remove_binding(binding_id:)
+                removed = !@bindings.delete(binding_id).nil?
+                { removed: removed, binding_id: binding_id }
+              end
+
+              def attend
+                @last_accessed = Time.now
+                @bindings.each_value { |b| b.strengthen(ATTENTION_BOOST) }
+              end
+
+              def rehearse
+                @last_accessed = Time.now
+                @bindings.each_value { |b| b.strengthen(REHEARSAL_BOOST) }
+              end
+
+              def modalities_present
+                @bindings.values.map(&:modality).uniq
+              end
+
+              def coherence
+                integrated = @bindings.values.select(&:integrated?)
+                return 0.0 if integrated.empty?
+
+                integrated.sum(&:strength) / integrated.size
+              end
+
+              def coherence_label
+                score = coherence
+                COHERENCE_LABELS.each do |range, label|
+                  return label if range.cover?(score)
+                end
+                :fragmented
+              end
+
+              def multimodal?
+                modalities_present.size >= 2
+              end
+
+              def expired?
+                age = Time.now - @created_at
+                age > EPISODE_TTL && !recently_accessed?
+              end
+
+              def decay_bindings
+                @bindings.each_value(&:decay)
+                @bindings.delete_if { |_, b| b.faded? }
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  bindings:        @bindings.transform_values(&:to_h),
+                  created_at:      @created_at,
+                  last_accessed:   @last_accessed,
+                  modalities:      modalities_present,
+                  coherence:       coherence,
+                  coherence_label: coherence_label,
+                  multimodal:      multimodal?,
+                  binding_count:   @bindings.size
+                }
+              end
+
+              private
+
+              def recently_accessed?
+                (Time.now - @last_accessed) <= RECENTLY_ACCESSED_WINDOW
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/episodic/helpers/episodic_binding.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          module Helpers
+            class EpisodicBinding
+              include Constants
+
+              attr_reader :id, :modality, :content, :source, :strength
+
+              def initialize(modality:, content:, source:, strength: DEFAULT_BINDING_STRENGTH)
+                raise ArgumentError, "invalid modality: #{modality}" unless MODALITIES.include?(modality.to_sym)
+
+                @id       = SecureRandom.uuid
+                @modality = modality.to_sym
+                @content  = content
+                @source   = source.to_sym
+                @strength = strength.to_f.clamp(0.0, 1.0)
+              end
+
+              def decay
+                @strength = [@strength - BINDING_DECAY, 0.0].max
+              end
+
+              def strengthen(amount)
+                @strength = [@strength + amount.to_f, 1.0].min
+              end
+
+              def integrated?
+                @strength >= INTEGRATION_THRESHOLD
+              end
+
+              def faded?
+                @strength <= BINDING_STRENGTH_FLOOR
+              end
+
+              def to_h
+                {
+                  id:       @id,
+                  modality: @modality,
+                  content:  @content,
+                  source:   @source,
+                  strength: @strength
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/episodic/helpers/episodic_store.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          module Helpers
+            class EpisodicStore
+              include Constants
+
+              attr_reader :episodes, :history
+
+              def initialize
+                @episodes = {}
+                @history  = []
+              end
+
+              def create_episode
+                evict_if_full
+                episode = Episode.new
+                @episodes[episode.id] = episode
+                record_history(:create, episode.id)
+                episode
+              end
+
+              def add_to_episode(episode_id:, modality:, content:, source:, strength: DEFAULT_BINDING_STRENGTH)
+                episode = @episodes[episode_id]
+                return { success: false, reason: :episode_not_found } unless episode
+
+                result = episode.add_binding(modality: modality, content: content, source: source, strength: strength)
+                record_history(:add_binding, episode_id) if result[:added]
+                result
+              end
+
+              def attend_episode(episode_id:)
+                episode = @episodes[episode_id]
+                return { success: false, reason: :episode_not_found } unless episode
+
+                episode.attend
+                record_history(:attend, episode_id)
+                { success: true, episode_id: episode_id }
+              end
+
+              def rehearse_episode(episode_id:)
+                episode = @episodes[episode_id]
+                return { success: false, reason: :episode_not_found } unless episode
+
+                episode.rehearse
+                record_history(:rehearse, episode_id)
+                { success: true, episode_id: episode_id }
+              end
+
+              def integrate(episode_id:)
+                episode = @episodes[episode_id]
+                return { integrated: false, reason: :episode_not_found } unless episode
+
+                coherence = episode.coherence
+                integrated = coherence >= INTEGRATION_THRESHOLD
+                {
+                  integrated:      integrated,
+                  episode_id:      episode_id,
+                  coherence:       coherence,
+                  coherence_label: episode.coherence_label
+                }
+              end
+
+              def retrieve_by_modality(modality:)
+                mod = modality.to_sym
+                @episodes.values.select { |ep| ep.modalities_present.include?(mod) }
+              end
+
+              def retrieve_multimodal
+                @episodes.values.select(&:multimodal?)
+              end
+
+              def most_coherent(limit: 5)
+                @episodes.values
+                         .sort_by { |ep| -ep.coherence }
+                         .first(limit)
+              end
+
+              def tick
+                expired_count = 0
+                @episodes.delete_if do |_, ep|
+                  ep.decay_bindings
+                  if ep.expired?
+                    expired_count += 1
+                    true
+                  else
+                    false
+                  end
+                end
+                { decayed: @episodes.size, expired: expired_count }
+              end
+
+              def count
+                @episodes.size
+              end
+
+              def to_h
+                {
+                  episode_count:    @episodes.size,
+                  history_size:     @history.size,
+                  multimodal_count: retrieve_multimodal.size,
+                  avg_coherence:    average_coherence
+                }
+              end
+
+              private
+
+              def evict_if_full
+                return unless @episodes.size >= MAX_EPISODES
+
+                expired = @episodes.values.select(&:expired?)
+                if expired.any?
+                  oldest = expired.min_by(&:created_at)
+                  @episodes.delete(oldest.id)
+                else
+                  lowest = @episodes.values.min_by(&:coherence)
+                  @episodes.delete(lowest.id) if lowest
+                end
+              end
+
+              def record_history(event, episode_id)
+                @history << { event: event, episode_id: episode_id, at: Time.now }
+                @history.shift if @history.size > MAX_HISTORY
+              end
+
+              def average_coherence
+                return 0.0 if @episodes.empty?
+
+                @episodes.values.sum(&:coherence) / @episodes.size
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end