lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/nostalgia/helpers/nostalgia_engine.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Nostalgia
+          module Helpers
+            class NostalgiaEngine
+              attr_reader :memories, :events
+
+              def initialize
+                @memories = []
+                @events   = []
+              end
+
+              def create_memory(content:, domain: :unknown, warmth: Constants::DEFAULT_WARMTH,
+                                original_valence: 0.5)
+                memory = NostalgicMemory.new(
+                  content:          content,
+                  domain:           domain,
+                  warmth:           warmth,
+                  original_valence: original_valence
+                )
+                @memories << memory
+                @memories.shift while @memories.size > Constants::MAX_MEMORIES
+                memory
+              end
+
+              def trigger_nostalgia(trigger:, domain: nil, intensity_hint: nil)
+                candidates = find_candidates(domain, trigger)
+                return [] if candidates.empty?
+
+                new_events = candidates.map do |memory|
+                  intensity = compute_intensity(memory, intensity_hint)
+                  next unless intensity >= Constants::TRIGGER_SENSITIVITY
+
+                  event = NostalgiaEvent.new(
+                    memory_id:      memory.id,
+                    trigger:        trigger,
+                    intensity:      intensity,
+                    effect_on_mood: compute_mood_effect(memory, intensity)
+                  )
+                  memory.warm!(intensity * 0.1)
+                  @events << event
+                  event
+                end.compact
+
+                @events.shift while @events.size > Constants::MAX_EVENTS
+                new_events
+              end
+
+              def age_all!
+                @memories.each(&:age!)
+              end
+
+              def warmth_by_domain
+                grouped = @memories.group_by(&:domain)
+                grouped.transform_values do |mems|
+                  total = mems.sum(&:warmth)
+                  (total / mems.size).round(10)
+                end
+              end
+
+              def rosy_retrospection_index
+                return 0.0 if @memories.empty?
+
+                rosy_count = @memories.count(&:rosy?)
+                inflation_sum = @memories.select(&:rosy?).sum do |m|
+                  m.warmth - m.original_valence
+                end
+
+                base = rosy_count.to_f / @memories.size
+                avg_inflation = rosy_count.positive? ? inflation_sum / rosy_count : 0.0
+                (base * avg_inflation).clamp(0.0, 1.0).round(10)
+              end
+
+              def nostalgia_proneness
+                return 0.0 if @memories.empty?
+
+                avg_warmth = @memories.sum(&:warmth) / @memories.size
+                event_density = [@events.size.to_f / Constants::MAX_EVENTS, 1.0].min
+                ((avg_warmth * 0.7) + (event_density * 0.3)).clamp(0.0, 1.0).round(10)
+              end
+
+              def most_nostalgic_domains
+                warmth_by_domain.sort_by { |_, v| -v }.map do |domain, avg_warmth|
+                  { domain: domain, avg_warmth: avg_warmth.round(10) }
+                end
+              end
+
+              def bittersweet_memories
+                @memories.select(&:bittersweet?).map(&:to_h)
+              end
+
+              def nostalgia_report
+                index = rosy_retrospection_index
+                proneness = nostalgia_proneness
+                {
+                  total_memories:           @memories.size,
+                  total_events:             @events.size,
+                  rosy_retrospection_index: index,
+                  retrospection_label:      Constants.label_for(Constants::RETROSPECTION_LABELS, index),
+                  nostalgia_proneness:      proneness,
+                  nostalgia_label:          Constants.label_for(Constants::NOSTALGIA_LABELS, proneness),
+                  most_nostalgic_domains:   most_nostalgic_domains,
+                  bittersweet_count:        bittersweet_memories.size,
+                  rosy_count:               @memories.count(&:rosy?)
+                }
+              end
+
+              private
+
+              def find_candidates(domain, trigger)
+                candidates = domain ? @memories.select { |m| m.domain == domain.to_sym } : @memories
+                return candidates.last(10) if trigger.nil?
+
+                by_content = candidates.select { |m| content_matches?(m.content, trigger) }
+                by_content.empty? ? candidates.last(5) : by_content
+              end
+
+              def content_matches?(content, trigger)
+                content.to_s.downcase.include?(trigger.to_s.downcase)
+              end
+
+              def compute_intensity(memory, hint)
+                base = memory.warmth * 0.6
+                temporal_boost = [memory.temporal_distance / 1000.0, 0.3].min
+                hint_value = hint ? hint.clamp(0.0, 1.0) * 0.2 : 0.0
+                (base + temporal_boost + hint_value).clamp(0.0, 1.0).round(10)
+              end
+
+              def compute_mood_effect(memory, intensity)
+                if memory.bittersweet?
+                  (intensity * 0.3).round(10)
+                elsif memory.rosy?
+                  (intensity * 0.6).round(10)
+                else
+                  (intensity * 0.4).round(10)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/nostalgia/helpers/nostalgia_event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Nostalgia
+          module Helpers
+            class NostalgiaEvent
+              attr_reader :id, :memory_id, :trigger, :intensity, :effect_on_mood, :occurred_at
+
+              def initialize(memory_id:, trigger:, intensity:, effect_on_mood: 0.0)
+                @id            = ::SecureRandom.uuid
+                @memory_id     = memory_id
+                @trigger       = trigger
+                @intensity     = intensity.clamp(0.0, 1.0)
+                @effect_on_mood = effect_on_mood.clamp(-1.0, 1.0)
+                @occurred_at = Time.now.utc
+              end
+
+              def nostalgia_label
+                Constants.label_for(Constants::NOSTALGIA_LABELS, @intensity)
+              end
+
+              def to_h
+                {
+                  id:              id,
+                  memory_id:       memory_id,
+                  trigger:         trigger,
+                  intensity:       @intensity,
+                  nostalgia_label: nostalgia_label,
+                  effect_on_mood:  @effect_on_mood,
+                  occurred_at:     occurred_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/nostalgia/helpers/nostalgic_memory.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Nostalgia
+          module Helpers
+            class NostalgicMemory
+              attr_reader :id, :content, :domain, :temporal_distance, :original_valence, :created_at
+
+              def initialize(content:, domain: :unknown, warmth: Constants::DEFAULT_WARMTH,
+                             original_valence: 0.5)
+                @id               = ::SecureRandom.uuid
+                @content          = content
+                @domain           = normalize_domain(domain)
+                @warmth           = warmth.clamp(0.0, Constants::WARMTH_CEILING)
+                @original_valence = original_valence.clamp(0.0, 1.0)
+                @current_valence  = @original_valence
+                @temporal_distance = 0
+                @created_at = Time.now.utc
+              end
+
+              def warmth
+                @warmth.round(10)
+              end
+
+              def current_valence
+                @current_valence.round(10)
+              end
+
+              def age!
+                @temporal_distance += 1
+                growth = Constants::WARMTH_GROWTH * temporal_distance_factor
+                @warmth = (@warmth + growth).clamp(0.0, Constants::WARMTH_CEILING)
+                self
+              end
+
+              def warm!(amount = Constants::WARMTH_GROWTH)
+                factor = 1.0 + (temporal_distance / 100.0)
+                @warmth = (@warmth + (amount.clamp(0.0, 1.0) * factor)).clamp(0.0, Constants::WARMTH_CEILING)
+                @current_valence = [@current_valence + (amount * 0.5), 1.0].min.round(10)
+                self
+              end
+
+              def cool!(amount = Constants::WARMTH_DECAY)
+                @warmth = (@warmth - amount.clamp(0.0, 1.0)).clamp(0.0, Constants::WARMTH_CEILING)
+                self
+              end
+
+              def rosy?
+                warmth > @original_valence
+              end
+
+              def bittersweet?
+                warmth >= Constants::BITTERSWEET_THRESHOLD && @original_valence < Constants::BITTERSWEET_THRESHOLD
+              end
+
+              def warmth_label
+                Constants.label_for(Constants::WARMTH_LABELS, warmth)
+              end
+
+              def to_h
+                {
+                  id:                id,
+                  content:           content,
+                  domain:            domain,
+                  warmth:            warmth,
+                  warmth_label:      warmth_label,
+                  temporal_distance: temporal_distance,
+                  original_valence:  @original_valence,
+                  current_valence:   current_valence,
+                  rosy:              rosy?,
+                  bittersweet:       bittersweet?,
+                  created_at:        created_at
+                }
+              end
+
+              private
+
+              def normalize_domain(domain)
+                sym = domain.to_sym
+                Constants::MEMORY_DOMAINS.include?(sym) ? sym : :unknown
+              end
+
+              def temporal_distance_factor
+                1.0 + (::Math.log(1 + @temporal_distance) * 0.1)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/nostalgia/runners/analysis.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Nostalgia
+          module Runners
+            module Analysis
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def warmth_by_domain(engine: nil, **)
+                eng = engine || nostalgia_engine
+                by_domain = eng.warmth_by_domain
+                Legion::Logging.debug "[cognitive_nostalgia] warmth_by_domain: #{by_domain.size} domains"
+                { success: true, warmth_by_domain: by_domain }
+              end
+
+              def rosy_retrospection_index(engine: nil, **)
+                eng = engine || nostalgia_engine
+                index = eng.rosy_retrospection_index
+                label = Helpers::Constants.label_for(Helpers::Constants::RETROSPECTION_LABELS, index)
+                Legion::Logging.debug "[cognitive_nostalgia] rosy_retrospection_index=#{index.round(2)} label=#{label}"
+                { success: true, index: index, label: label }
+              end
+
+              def nostalgia_proneness(engine: nil, **)
+                eng = engine || nostalgia_engine
+                proneness = eng.nostalgia_proneness
+                label = Helpers::Constants.label_for(Helpers::Constants::NOSTALGIA_LABELS, proneness)
+                Legion::Logging.debug "[cognitive_nostalgia] nostalgia_proneness=#{proneness.round(2)} label=#{label}"
+                { success: true, proneness: proneness, label: label }
+              end
+
+              def most_nostalgic_domains(engine: nil, **)
+                eng = engine || nostalgia_engine
+                domains = eng.most_nostalgic_domains
+                Legion::Logging.debug "[cognitive_nostalgia] most_nostalgic_domains: top=#{domains.first&.fetch(:domain, :none)}"
+                { success: true, domains: domains }
+              end
+
+              def bittersweet_memories(engine: nil, **)
+                eng = engine || nostalgia_engine
+                memories = eng.bittersweet_memories
+                Legion::Logging.debug "[cognitive_nostalgia] bittersweet_memories: count=#{memories.size}"
+                { success: true, memories: memories, count: memories.size }
+              end
+
+              private
+
+              def nostalgia_engine
+                @nostalgia_engine ||= Helpers::NostalgiaEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/nostalgia/runners/recall.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Nostalgia
+          module Runners
+            module Recall
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def store_memory(content:, domain: :unknown, warmth: Helpers::Constants::DEFAULT_WARMTH,
+                               original_valence: 0.5, engine: nil, **)
+                eng = engine || nostalgia_engine
+                memory = eng.create_memory(
+                  content:          content,
+                  domain:           domain,
+                  warmth:           warmth,
+                  original_valence: original_valence
+                )
+                Legion::Logging.debug "[cognitive_nostalgia] stored memory id=#{memory.id} domain=#{memory.domain} warmth=#{memory.warmth.round(2)}"
+                { success: true, memory: memory.to_h }
+              end
+
+              def trigger_nostalgia(trigger:, domain: nil, intensity_hint: nil, engine: nil, **)
+                eng = engine || nostalgia_engine
+                events = eng.trigger_nostalgia(trigger: trigger, domain: domain, intensity_hint: intensity_hint)
+                Legion::Logging.debug "[cognitive_nostalgia] triggered nostalgia: trigger=#{trigger} events=#{events.size}"
+                { success: true, events: events.map(&:to_h), count: events.size }
+              end
+
+              def age_memories(engine: nil, **)
+                eng = engine || nostalgia_engine
+                eng.age_all!
+                Legion::Logging.debug "[cognitive_nostalgia] aged #{eng.memories.size} memories"
+                { success: true, memory_count: eng.memories.size }
+              end
+
+              def nostalgia_report(engine: nil, **)
+                eng = engine || nostalgia_engine
+                report = eng.nostalgia_report
+                idx = report[:rosy_retrospection_index].round(2)
+                pro = report[:nostalgia_proneness].round(2)
+                Legion::Logging.debug "[cognitive_nostalgia] report: index=#{idx} proneness=#{pro}"
+                { success: true, **report }
+              end
+
+              private
+
+              def nostalgia_engine
+                @nostalgia_engine ||= Helpers::NostalgiaEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/nostalgia/version'
+require 'legion/extensions/agentic/memory/nostalgia/helpers/constants'
+require 'legion/extensions/agentic/memory/nostalgia/helpers/nostalgic_memory'
+require 'legion/extensions/agentic/memory/nostalgia/helpers/nostalgia_event'
+require 'legion/extensions/agentic/memory/nostalgia/helpers/nostalgia_engine'
+require 'legion/extensions/agentic/memory/nostalgia/runners/recall'
+require 'legion/extensions/agentic/memory/nostalgia/runners/analysis'
+require 'legion/extensions/agentic/memory/nostalgia/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Nostalgia
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/offloading/helpers/constants'
+require 'legion/extensions/agentic/memory/offloading/helpers/external_store'
+require 'legion/extensions/agentic/memory/offloading/helpers/offloaded_item'
+require 'legion/extensions/agentic/memory/offloading/helpers/offloading_engine'
+require 'legion/extensions/agentic/memory/offloading/runners/cognitive_offloading'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+          class Client
+            include Runners::CognitiveOffloading
+
+            def initialize(engine: nil, **)
+              @offloading_engine = engine || Helpers::OffloadingEngine.new
+            end
+
+            private
+
+            attr_reader :offloading_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+          module Helpers
+            module Constants
+              MAX_ITEMS         = 500
+              MAX_STORES        = 50
+              DEFAULT_STORE_TRUST = 0.7
+              TRUST_DECAY       = 0.02
+              TRUST_BOOST       = 0.05
+
+              ITEM_TYPES = %i[
+                fact procedure plan context delegation reminder calculation reference
+              ].freeze
+
+              STORE_TYPES = %i[
+                database file agent tool memory_aid external_service notes
+              ].freeze
+
+              TRUST_LABELS = {
+                (0.8..)     => :highly_trusted,
+                (0.6...0.8) => :trusted,
+                (0.4...0.6) => :cautious,
+                (0.2...0.4) => :distrusted,
+                (..0.2)     => :unreliable
+              }.freeze
+
+              IMPORTANCE_LABELS = {
+                (0.8..)     => :critical,
+                (0.6...0.8) => :important,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :trivial
+              }.freeze
+
+              OFFLOAD_LABELS = {
+                (0.8..)     => :heavily_offloaded,
+                (0.6...0.8) => :mostly_offloaded,
+                (0.4...0.6) => :balanced,
+                (0.2...0.4) => :mostly_internal,
+                (..0.2)     => :self_reliant
+              }.freeze
+
+              RETRIEVAL_SUCCESS_THRESHOLD = 0.7
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/offloading/helpers/external_store.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'constants'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+          module Helpers
+            class ExternalStore
+              include Constants
+
+              attr_reader :id, :name, :store_type, :trust, :items_stored,
+                          :successful_retrievals, :failed_retrievals, :created_at
+
+              def initialize(name:, store_type:)
+                @id                   = ::SecureRandom.uuid
+                @name                 = name
+                @store_type           = store_type
+                @trust                = DEFAULT_STORE_TRUST
+                @items_stored         = 0
+                @successful_retrievals = 0
+                @failed_retrievals     = 0
+                @created_at = Time.now.utc
+              end
+
+              def increment_items!
+                @items_stored += 1
+                self
+              end
+
+              def record_success!
+                @successful_retrievals += 1
+                @trust = (@trust + TRUST_BOOST).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def record_failure!
+                @failed_retrievals += 1
+                @trust = (@trust - TRUST_DECAY).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def retrieval_rate
+                total = @successful_retrievals + @failed_retrievals
+                return 0.0 if total.zero?
+
+                (@successful_retrievals.to_f / total).round(10)
+              end
+
+              def reliable?
+                @trust >= RETRIEVAL_SUCCESS_THRESHOLD
+              end
+
+              def trust_label
+                TRUST_LABELS.find { |range, _| range.cover?(@trust) }&.last || :unreliable
+              end
+
+              def to_h
+                {
+                  id:                    @id,
+                  name:                  @name,
+                  store_type:            @store_type,
+                  trust:                 @trust.round(10),
+                  trust_label:           trust_label,
+                  items_stored:          @items_stored,
+                  successful_retrievals: @successful_retrievals,
+                  failed_retrievals:     @failed_retrievals,
+                  retrieval_rate:        retrieval_rate,
+                  reliable:              reliable?,
+                  created_at:            @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/offloading/helpers/offloaded_item.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'constants'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+          module Helpers
+            class OffloadedItem
+              include Constants
+
+              attr_reader :id, :content, :item_type, :importance, :store_id,
+                          :offloaded_at, :retrieved_count, :last_retrieved_at
+
+              def initialize(content:, item_type:, importance:, store_id:)
+                @id               = ::SecureRandom.uuid
+                @content          = content
+                @item_type        = item_type
+                @importance       = importance.clamp(0.0, 1.0)
+                @store_id         = store_id
+                @offloaded_at     = Time.now.utc
+                @retrieved_count  = 0
+                @last_retrieved_at = nil
+              end
+
+              def retrieve!
+                @retrieved_count  += 1
+                @last_retrieved_at = Time.now.utc
+                self
+              end
+
+              def stale?(threshold_seconds: 3600)
+                return false if @last_retrieved_at.nil? && @retrieved_count.zero?
+
+                reference = @last_retrieved_at || @offloaded_at
+                (Time.now.utc - reference) > threshold_seconds
+              end
+
+              def importance_label
+                IMPORTANCE_LABELS.find { |range, _| range.cover?(@importance) }&.last || :trivial
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  content:           @content,
+                  item_type:         @item_type,
+                  importance:        @importance.round(10),
+                  importance_label:  importance_label,
+                  store_id:          @store_id,
+                  offloaded_at:      @offloaded_at,
+                  retrieved_count:   @retrieved_count,
+                  last_retrieved_at: @last_retrieved_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end