lex-agentic-memory 0.1.0

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+require_relative 'external_store'
+require_relative 'offloaded_item'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+          module Helpers
+            class OffloadingEngine
+              include Constants
+
+              attr_reader :items, :stores
+
+              def initialize
+                @items  = {}
+                @stores = {}
+              end
+
+              def register_store(name:, store_type:)
+                return nil if @stores.size >= MAX_STORES
+
+                store = ExternalStore.new(name: name, store_type: store_type)
+                @stores[store.id] = store
+                store
+              end
+
+              def offload(content:, item_type:, importance:, store_id:)
+                return nil if @items.size >= MAX_ITEMS
+                return nil unless @stores.key?(store_id)
+
+                item = OffloadedItem.new(
+                  content:    content,
+                  item_type:  item_type,
+                  importance: importance,
+                  store_id:   store_id
+                )
+                @items[item.id] = item
+                @stores[store_id].increment_items!
+                item
+              end
+
+              def retrieve(item_id:)
+                item = @items[item_id]
+                return nil unless item
+
+                store = @stores[item.store_id]
+                store&.record_success!
+                item.retrieve!
+                item
+              end
+
+              def retrieve_failed(item_id:)
+                item = @items[item_id]
+                return nil unless item
+
+                store = @stores[item.store_id]
+                store&.record_failure!
+                item
+              end
+
+              def items_in_store(store_id:)
+                @items.values.select { |i| i.store_id == store_id }
+              end
+
+              def items_by_type(item_type:)
+                @items.values.select { |i| i.item_type == item_type }
+              end
+
+              def most_important_offloaded(limit: 10)
+                @items.values
+                      .sort_by { |i| -i.importance }
+                      .first(limit)
+              end
+
+              def offloading_ratio
+                return 0.0 if MAX_ITEMS.zero?
+
+                (@items.size.to_f / MAX_ITEMS).round(10)
+              end
+
+              def overall_store_trust
+                return 0.0 if @stores.empty?
+
+                total = @stores.values.sum(&:trust)
+                (total / @stores.size).round(10)
+              end
+
+              def most_trusted_store
+                @stores.values.max_by(&:trust)
+              end
+
+              def least_trusted_store
+                @stores.values.min_by(&:trust)
+              end
+
+              def offloading_report
+                {
+                  total_items:         @items.size,
+                  total_stores:        @stores.size,
+                  offloading_ratio:    offloading_ratio,
+                  offloading_label:    offloading_label,
+                  overall_store_trust: overall_store_trust,
+                  most_trusted_store:  most_trusted_store&.to_h,
+                  least_trusted_store: least_trusted_store&.to_h,
+                  items_by_type:       items_type_summary,
+                  stores_summary:      @stores.values.map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  items:  @items.transform_values(&:to_h),
+                  stores: @stores.transform_values(&:to_h)
+                }
+              end
+
+              private
+
+              def offloading_label
+                OFFLOAD_LABELS.find { |range, _| range.cover?(offloading_ratio) }&.last || :self_reliant
+              end
+
+              def items_type_summary
+                ITEM_TYPES.to_h do |type|
+                  [type, @items.values.count { |i| i.item_type == type }]
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/offloading/runners/cognitive_offloading.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+          module Runners
+            module CognitiveOffloading
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_store(name:, store_type:, engine: nil, **)
+                eng = engine || offloading_engine
+                store = eng.register_store(name: name, store_type: store_type)
+                if store
+                  Legion::Logging.info "[cognitive_offloading] registered store name=#{name} type=#{store_type} id=#{store.id}"
+                  { success: true, store: store.to_h }
+                else
+                  Legion::Logging.warn '[cognitive_offloading] register_store failed: limit reached or invalid store_type'
+                  { success: false, reason: :limit_reached }
+                end
+              end
+
+              def offload_item(content:, item_type:, importance:, store_id:, engine: nil, **)
+                eng = engine || offloading_engine
+                item = eng.offload(content: content, item_type: item_type, importance: importance, store_id: store_id)
+                if item
+                  Legion::Logging.info "[cognitive_offloading] offloaded item=#{item.id} type=#{item_type} importance=#{importance.round(2)} store=#{store_id}"
+                  { success: true, item: item.to_h }
+                else
+                  Legion::Logging.warn "[cognitive_offloading] offload failed: limit reached or store not found store_id=#{store_id}"
+                  { success: false, reason: :offload_failed }
+                end
+              end
+
+              def retrieve_item(item_id:, engine: nil, **)
+                eng = engine || offloading_engine
+                item = eng.retrieve(item_id: item_id)
+                if item
+                  Legion::Logging.debug "[cognitive_offloading] retrieved item=#{item_id} count=#{item.retrieved_count}"
+                  { success: true, item: item.to_h }
+                else
+                  Legion::Logging.warn "[cognitive_offloading] retrieve failed: item not found item_id=#{item_id}"
+                  { success: false, reason: :not_found }
+                end
+              end
+
+              def report_retrieval_failure(item_id:, engine: nil, **)
+                eng = engine || offloading_engine
+                item = eng.retrieve_failed(item_id: item_id)
+                if item
+                  store = eng.stores[item.store_id]
+                  trust = store&.trust&.round(2)
+                  Legion::Logging.warn "[cognitive_offloading] retrieval failure item=#{item_id} store_trust=#{trust}"
+                  { success: true, item_id: item_id, store_trust: trust }
+                else
+                  { success: false, reason: :not_found }
+                end
+              end
+
+              def items_in_store(store_id:, engine: nil, **)
+                eng = engine || offloading_engine
+                items = eng.items_in_store(store_id: store_id)
+                Legion::Logging.debug "[cognitive_offloading] items_in_store store=#{store_id} count=#{items.size}"
+                { success: true, items: items.map(&:to_h), count: items.size }
+              end
+
+              def items_by_type(item_type:, engine: nil, **)
+                eng = engine || offloading_engine
+                items = eng.items_by_type(item_type: item_type)
+                Legion::Logging.debug "[cognitive_offloading] items_by_type type=#{item_type} count=#{items.size}"
+                { success: true, items: items.map(&:to_h), count: items.size }
+              end
+
+              def most_important_offloaded(limit: 10, engine: nil, **)
+                eng = engine || offloading_engine
+                items = eng.most_important_offloaded(limit: limit)
+                Legion::Logging.debug "[cognitive_offloading] most_important limit=#{limit} count=#{items.size}"
+                { success: true, items: items.map(&:to_h), count: items.size }
+              end
+
+              def offloading_status(engine: nil, **)
+                eng = engine || offloading_engine
+                report = eng.offloading_report
+                ratio = report[:offloading_ratio]
+                Legion::Logging.debug "[cognitive_offloading] status items=#{report[:total_items]} stores=#{report[:total_stores]} ratio=#{ratio}"
+                { success: true, report: report }
+              end
+
+              private
+
+              def offloading_engine
+                @offloading_engine ||= Helpers::OffloadingEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/offloading/version'
+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'
+require 'legion/extensions/agentic/memory/offloading/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Offloading
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+          class Client
+            include Runners::CognitivePaleontology
+
+            def initialize(engine: nil)
+              @default_engine = engine || Helpers::PaleontologyEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+          module Helpers
+            module Constants
+              MAX_FOSSILS      = 500
+              MAX_STRATA       = 20
+              MAX_EXCAVATIONS  = 100
+              FOSSILIZATION_RATE = 0.02
+              MIN_FOSSIL_AGE = 300
+
+              FOSSIL_TYPES = %i[
+                strategy pattern belief heuristic
+                association routine assumption framework
+              ].freeze
+
+              EXTINCTION_CAUSES = %i[
+                obsolescence contradiction displacement
+                energy_cost irrelevance environmental_shift
+              ].freeze
+
+              ERA_NAMES = %i[
+                primordial archaic classical medieval
+                renaissance industrial modern contemporary
+              ].freeze
+
+              PRESERVATION_STATES = %i[
+                pristine mineralized fragmented trace imprint
+              ].freeze
+
+              PRESERVATION_LABELS = [
+                [0.8..1.0, :pristine],
+                [0.6..0.8, :mineralized],
+                [0.4..0.6, :fragmented],
+                [0.2..0.4, :trace],
+                [0.0..0.2, :imprint]
+              ].freeze
+
+              SIGNIFICANCE_LABELS = [
+                [0.8..1.0, :keystone],
+                [0.6..0.8, :significant],
+                [0.4..0.6, :notable],
+                [0.2..0.4, :minor],
+                [0.0..0.2, :trivial]
+              ].freeze
+
+              STRATUM_LABELS = {
+                0 => 'Surface (contemporary)',
+                1 => 'Shallow (recent history)',
+                2 => 'Mid (established patterns)',
+                3 => 'Deep (foundational layers)',
+                4 => 'Bedrock (primordial cognition)'
+              }.freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/paleontology/helpers/excavation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+          module Helpers
+            class Excavation
+              attr_reader :id, :target_stratum, :fossils_found,
+                          :started_at, :completed_at, :status
+
+              def initialize(target_stratum:)
+                @id             = SecureRandom.uuid
+                @target_stratum = target_stratum.to_i.clamp(0, 4)
+                @fossils_found  = []
+                @started_at     = Time.now.utc
+                @completed_at   = nil
+                @status         = :in_progress
+              end
+
+              def record_find!(fossil)
+                @fossils_found << fossil
+              end
+
+              def complete!
+                return false if @status == :completed
+
+                @completed_at = Time.now.utc
+                @status       = :completed
+                true
+              end
+
+              def completed?
+                @status == :completed
+              end
+
+              def yield_rate
+                return 0.0 if @fossils_found.empty?
+
+                @fossils_found.sum(&:significance) / @fossils_found.size
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  target_stratum: @target_stratum,
+                  stratum_label:  Constants::STRATUM_LABELS[@target_stratum],
+                  fossils_count:  @fossils_found.size,
+                  yield_rate:     yield_rate.round(10),
+                  status:         @status,
+                  started_at:     @started_at,
+                  completed_at:   @completed_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/paleontology/helpers/fossil.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+          module Helpers
+            class Fossil
+              attr_reader :id, :fossil_type, :domain, :content,
+                          :extinction_cause, :era, :stratum_depth,
+                          :discovered_at, :extinct_at, :lineage_ids
+              attr_accessor :preservation, :significance
+
+              def initialize(fossil_type:, domain:, content:, extinction_cause:,
+                             era: nil, stratum_depth: 0, preservation: nil,
+                             significance: nil)
+                validate_type!(fossil_type)
+                validate_cause!(extinction_cause)
+                assign_core(fossil_type, domain, content, extinction_cause)
+                assign_metadata(era, stratum_depth, preservation, significance)
+              end
+
+              def erode!(rate: Constants::FOSSILIZATION_RATE)
+                @preservation = (@preservation - rate.abs).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def reinforce!(boost: 0.1)
+                @significance = (@significance + boost.abs).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def imprint?
+                @preservation < 0.2
+              end
+
+              def keystone?
+                @significance >= 0.8
+              end
+
+              def ancient?
+                (Time.now.utc - @extinct_at) > 5_000_000
+              end
+
+              def preservation_label
+                Constants.label_for(Constants::PRESERVATION_LABELS, @preservation)
+              end
+
+              def significance_label
+                Constants.label_for(Constants::SIGNIFICANCE_LABELS, @significance)
+              end
+
+              def link_lineage(other_id)
+                @lineage_ids << other_id unless @lineage_ids.include?(other_id)
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  fossil_type:        @fossil_type,
+                  domain:             @domain,
+                  content:            @content,
+                  extinction_cause:   @extinction_cause,
+                  era:                @era,
+                  stratum_depth:      @stratum_depth,
+                  preservation:       @preservation,
+                  preservation_label: preservation_label,
+                  significance:       @significance,
+                  significance_label: significance_label,
+                  discovered_at:      @discovered_at,
+                  extinct_at:         @extinct_at,
+                  lineage_ids:        @lineage_ids,
+                  imprint:            imprint?,
+                  keystone:           keystone?,
+                  ancient:            ancient?
+                }
+              end
+
+              private
+
+              def assign_core(fossil_type, domain, content, extinction_cause)
+                @id               = SecureRandom.uuid
+                @fossil_type      = fossil_type.to_sym
+                @domain           = domain.to_sym
+                @content          = content.to_s
+                @extinction_cause = extinction_cause.to_sym
+              end
+
+              def assign_metadata(era, stratum_depth, preservation, significance)
+                @era           = (era || assign_era(stratum_depth)).to_sym
+                @stratum_depth = stratum_depth.to_i.clamp(0, 4)
+                @preservation  = (preservation || 0.8).to_f.clamp(0.0, 1.0).round(10)
+                @significance  = (significance || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @discovered_at = Time.now.utc
+                @extinct_at    = Time.now.utc - rand(100..10_000_000)
+                @lineage_ids   = []
+              end
+
+              def validate_type!(val)
+                return if Constants::FOSSIL_TYPES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown fossil type: #{val.inspect}; " \
+                      "must be one of #{Constants::FOSSIL_TYPES.inspect}"
+              end
+
+              def validate_cause!(val)
+                return if Constants::EXTINCTION_CAUSES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown extinction cause: #{val.inspect}; " \
+                      "must be one of #{Constants::EXTINCTION_CAUSES.inspect}"
+              end
+
+              def assign_era(depth)
+                Constants::ERA_NAMES[depth.to_i.clamp(0, Constants::ERA_NAMES.size - 1)]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end