lex-agentic-memory 0.1.0

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+          module Helpers
+            class PaleontologyEngine
+              def initialize
+                @fossils      = {}
+                @excavations  = {}
+                @extinction_log = []
+              end
+
+              def record_extinction(fossil_type:, domain:, content:,
+                                    extinction_cause:, stratum_depth: 0,
+                                    significance: nil, **)
+                validate_capacity!(:fossils, Constants::MAX_FOSSILS)
+                fossil = Fossil.new(
+                  fossil_type:      fossil_type,
+                  domain:           domain,
+                  content:          content,
+                  extinction_cause: extinction_cause,
+                  stratum_depth:    stratum_depth,
+                  significance:     significance
+                )
+                @fossils[fossil.id] = fossil
+                @extinction_log << { fossil_id: fossil.id, at: Time.now.utc }
+                fossil
+              end
+
+              def begin_excavation(target_stratum:)
+                validate_capacity!(:excavations, Constants::MAX_EXCAVATIONS)
+                exc = Excavation.new(target_stratum: target_stratum)
+                @excavations[exc.id] = exc
+                exc
+              end
+
+              def excavate!(excavation_id:)
+                exc = fetch_excavation!(excavation_id)
+                raise ArgumentError, 'excavation already completed' if exc.completed?
+
+                matching = stratum_fossils(exc.target_stratum)
+                return nil if matching.empty?
+
+                fossil = matching.sample
+                exc.record_find!(fossil)
+                fossil
+              end
+
+              def complete_excavation(excavation_id:)
+                exc = fetch_excavation!(excavation_id)
+                exc.complete!
+                exc
+              end
+
+              def erode_all!(rate: Constants::FOSSILIZATION_RATE)
+                @fossils.each_value { |f| f.erode!(rate: rate) }
+                prune_imprints!
+                @fossils.size
+              end
+
+              def link_lineage(fossil_id:, ancestor_id:)
+                fossil = fetch_fossil!(fossil_id)
+                fetch_fossil!(ancestor_id)
+                fossil.link_lineage(ancestor_id)
+                fossil
+              end
+
+              def fossils_by_type(fossil_type)
+                @fossils.values.select { |f| f.fossil_type == fossil_type.to_sym }
+              end
+
+              def fossils_by_cause(cause)
+                @fossils.values.select { |f| f.extinction_cause == cause.to_sym }
+              end
+
+              def fossils_by_era(era)
+                @fossils.values.select { |f| f.era == era.to_sym }
+              end
+
+              def keystone_fossils(limit: 10)
+                @fossils.values
+                        .select(&:keystone?)
+                        .sort_by { |f| -f.significance }
+                        .first(limit)
+              end
+
+              def extinction_timeline
+                @extinction_log.sort_by { |e| e[:at] }
+              end
+
+              def mass_extinction?(threshold: 5, window: 60)
+                cutoff = Time.now.utc - window
+                recent = @extinction_log.count { |e| e[:at] >= cutoff }
+                recent >= threshold
+              end
+
+              def all_fossils
+                @fossils.values
+              end
+
+              def all_excavations
+                @excavations.values
+              end
+
+              def paleontology_report
+                {
+                  total_fossils:     @fossils.size,
+                  total_excavations: @excavations.size,
+                  type_breakdown:    count_by(:fossil_type, Constants::FOSSIL_TYPES),
+                  cause_breakdown:   count_by(:extinction_cause, Constants::EXTINCTION_CAUSES),
+                  era_breakdown:     count_by(:era, Constants::ERA_NAMES),
+                  avg_preservation:  avg_field(:preservation),
+                  avg_significance:  avg_field(:significance),
+                  keystone_count:    @fossils.values.count(&:keystone?),
+                  imprint_count:     @fossils.values.count(&:imprint?),
+                  ancient_count:     @fossils.values.count(&:ancient?),
+                  mass_extinction:   mass_extinction?
+                }
+              end
+
+              private
+
+              def fetch_fossil!(id)
+                @fossils.fetch(id) do
+                  raise ArgumentError, "fossil not found: #{id.inspect}"
+                end
+              end
+
+              def fetch_excavation!(id)
+                @excavations.fetch(id) do
+                  raise ArgumentError, "excavation not found: #{id.inspect}"
+                end
+              end
+
+              def validate_capacity!(type, max)
+                collection = type == :fossils ? @fossils : @excavations
+                return if collection.size < max
+
+                raise ArgumentError, "#{type} capacity reached (max #{max})"
+              end
+
+              def stratum_fossils(depth)
+                @fossils.values.select { |f| f.stratum_depth == depth }
+              end
+
+              def prune_imprints!
+                @fossils.delete_if { |_, f| f.preservation <= 0.0 }
+              end
+
+              def count_by(attr, values)
+                values.to_h do |v|
+                  [v, @fossils.values.count { |f| f.public_send(attr) == v }]
+                end
+              end
+
+              def avg_field(field)
+                return 0.0 if @fossils.empty?
+
+                (@fossils.values.sum(&field) / @fossils.size).round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/paleontology/runners/cognitive_paleontology.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+          module Runners
+            module CognitivePaleontology
+              extend self
+
+              def record_extinction(fossil_type:, domain:, content:,
+                                    extinction_cause:, stratum_depth: 0,
+                                    significance: nil, engine: nil, **)
+                eng    = resolve_engine(engine)
+                fossil = eng.record_extinction(
+                  fossil_type: fossil_type, domain: domain, content: content,
+                  extinction_cause: extinction_cause,
+                  stratum_depth: stratum_depth, significance: significance
+                )
+                { success: true, fossil: fossil.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def begin_excavation(target_stratum:, engine: nil, **)
+                eng = resolve_engine(engine)
+                exc = eng.begin_excavation(target_stratum: target_stratum)
+                { success: true, excavation: exc.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def excavate(excavation_id:, engine: nil, **)
+                eng    = resolve_engine(engine)
+                fossil = eng.excavate!(excavation_id: excavation_id)
+                if fossil
+                  { success: true, fossil: fossil.to_h }
+                else
+                  { success: true, fossil: nil, message: 'no fossils at this stratum' }
+                end
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def complete_excavation(excavation_id:, engine: nil, **)
+                eng = resolve_engine(engine)
+                exc = eng.complete_excavation(excavation_id: excavation_id)
+                { success: true, excavation: exc.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_fossils(engine: nil, fossil_type: nil,
+                               extinction_cause: nil, **)
+                eng     = resolve_engine(engine)
+                results = filter_fossils(eng.all_fossils,
+                                         fossil_type:      fossil_type,
+                                         extinction_cause: extinction_cause)
+                { success: true, fossils: results.map(&:to_h),
+                  count: results.size }
+              end
+
+              def paleontology_status(engine: nil, **)
+                eng = resolve_engine(engine)
+                { success: true, report: eng.paleontology_report }
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              private
+
+              def filter_fossils(fossils, fossil_type:, extinction_cause:)
+                r = fossils
+                r = r.select { |f| f.fossil_type == fossil_type.to_sym } if fossil_type
+                r = r.select { |f| f.extinction_cause == extinction_cause.to_sym } if extinction_cause
+                r
+              end
+
+              def resolve_engine(engine)
+                engine || default_engine
+              end
+
+              def default_engine
+                @default_engine ||= Helpers::PaleontologyEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'paleontology/version'
+require_relative 'paleontology/helpers/constants'
+require_relative 'paleontology/helpers/fossil'
+require_relative 'paleontology/helpers/excavation'
+require_relative 'paleontology/helpers/paleontology_engine'
+require_relative 'paleontology/runners/cognitive_paleontology'
+require_relative 'paleontology/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Paleontology
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/agentic/memory/palimpsest/helpers/belief_layer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Palimpsest
+          module Helpers
+            class BeliefLayer
+              include Constants
+
+              attr_reader :id, :content, :confidence, :domain, :version, :author,
+                          :timestamp, :superseded_by
+
+              def initialize(content:, confidence: DEFAULT_CONFIDENCE, domain: :unknown,
+                             version: 1, author: :system)
+                @id            = ::SecureRandom.uuid
+                @content       = content
+                @confidence    = confidence.to_f.clamp(0.0, 1.0)
+                @domain        = domain
+                @version       = version
+                @author        = author
+                @timestamp     = ::Time.now.utc
+                @superseded_by = nil
+              end
+
+              def supersede!(next_layer_id)
+                @superseded_by = next_layer_id
+              end
+
+              def superseded?
+                !@superseded_by.nil?
+              end
+
+              def ghost?
+                superseded? && @confidence > GHOST_THRESHOLD
+              end
+
+              def dissipated?
+                superseded? && @confidence <= GHOST_THRESHOLD
+              end
+
+              def erode!(rate: EROSION_RATE)
+                @confidence = (@confidence - rate).clamp(0.0, 1.0).round(10)
+              end
+
+              def confidence_label
+                Constants.label_for(CONFIDENCE_LABELS, @confidence)
+              end
+
+              def ghost_label
+                return :not_ghost unless superseded?
+
+                Constants.label_for(GHOST_LABELS, @confidence)
+              end
+
+              def to_h
+                {
+                  id:            @id,
+                  content:       @content,
+                  confidence:    @confidence.round(4),
+                  domain:        @domain,
+                  version:       @version,
+                  author:        @author,
+                  timestamp:     @timestamp.iso8601,
+                  superseded_by: @superseded_by,
+                  superseded:    superseded?,
+                  ghost:         ghost?,
+                  label:         confidence_label
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Palimpsest
+          module Helpers
+            module Constants
+              MAX_PALIMPSESTS       = 200
+              MAX_LAYERS_PER_TOPIC  = 20
+              DEFAULT_CONFIDENCE    = 0.7
+              GHOST_THRESHOLD       = 0.1
+              EROSION_RATE          = 0.05
+              GHOST_DECAY           = 0.02
+
+              LAYER_DOMAINS = %i[
+                factual procedural normative identity
+                relational emotional strategic unknown
+              ].freeze
+
+              CONFIDENCE_LABELS = {
+                (0.9..)     => :certain,
+                (0.7...0.9) => :high,
+                (0.5...0.7) => :moderate,
+                (0.3...0.5) => :low,
+                (0.1...0.3) => :faint,
+                (..0.1)     => :ghost
+              }.freeze
+
+              GHOST_LABELS = {
+                (0.5..)     => :strong_ghost,
+                (0.3...0.5) => :moderate_ghost,
+                (0.1...0.3) => :faint_ghost,
+                (..0.1)     => :dissipated
+              }.freeze
+
+              DRIFT_LABELS = {
+                (0.7..)      => :radical,
+                (0.4...0.7)  => :major,
+                (0.2...0.4)  => :moderate,
+                (0.05...0.2) => :minor,
+                (..0.05)     => :stable
+              }.freeze
+
+              def self.label_for(labels_hash, value)
+                labels_hash.each { |range, label| return label if range.cover?(value) }
+                labels_hash.values.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/palimpsest/helpers/palimpsest.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Palimpsest
+          module Helpers
+            class Palimpsest
+              include Constants
+
+              attr_reader :id, :topic, :domain, :current_layer, :historical_layers,
+                          :created_at, :overwrite_count
+
+              def initialize(topic:, domain: :unknown)
+                @id                = ::SecureRandom.uuid
+                @topic             = topic
+                @domain            = domain
+                @current_layer     = nil
+                @historical_layers = []
+                @created_at        = ::Time.now.utc
+                @overwrite_count   = 0
+                @version_counter   = 0
+              end
+
+              def overwrite!(new_content, confidence: DEFAULT_CONFIDENCE, author: :system)
+                return false if at_layer_limit?
+
+                @version_counter += 1
+                new_layer = BeliefLayer.new(
+                  content:    new_content,
+                  confidence: confidence,
+                  domain:     @domain,
+                  version:    @version_counter,
+                  author:     author
+                )
+
+                if @current_layer
+                  @current_layer.supersede!(new_layer.id)
+                  @historical_layers << @current_layer
+                end
+
+                @current_layer = new_layer
+                @overwrite_count += 1
+                new_layer
+              end
+
+              def peek_through(depth: 1)
+                return [] if @historical_layers.empty?
+
+                @historical_layers.last([depth, @historical_layers.size].min).reverse
+              end
+
+              def erode_current!(rate: EROSION_RATE)
+                return nil unless @current_layer
+
+                @current_layer.erode!(rate: rate)
+                @current_layer.confidence
+              end
+
+              def ghost_layers
+                @historical_layers.select(&:ghost?)
+              end
+
+              def all_layers
+                layers = @historical_layers.dup
+                layers << @current_layer if @current_layer
+                layers
+              end
+
+              def restoration_strength
+                ghosts = ghost_layers
+                return 0.0 if ghosts.empty?
+
+                total = ghosts.sum(&:confidence)
+                (total / ghosts.size).round(10)
+              end
+
+              def belief_drift
+                return 0.0 unless @current_layer && @historical_layers.any?
+
+                origin = @historical_layers.first
+                (@current_layer.confidence - origin.confidence).abs.round(10)
+              end
+
+              def drift_label
+                Constants.label_for(DRIFT_LABELS, belief_drift)
+              end
+
+              def decay_ghosts!(rate: GHOST_DECAY)
+                @historical_layers.each { |layer| layer.erode!(rate: rate) if layer.superseded? }
+              end
+
+              def to_h
+                {
+                  id:                   @id,
+                  topic:                @topic,
+                  domain:               @domain,
+                  layer_count:          all_layers.size,
+                  overwrite_count:      @overwrite_count,
+                  ghost_count:          ghost_layers.size,
+                  restoration_strength: restoration_strength.round(4),
+                  belief_drift:         belief_drift.round(4),
+                  drift_label:          drift_label,
+                  current_layer:        @current_layer&.to_h,
+                  created_at:           @created_at.iso8601
+                }
+              end
+
+              private
+
+              def at_layer_limit?
+                all_layers.size >= MAX_LAYERS_PER_TOPIC
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/palimpsest/helpers/palimpsest_engine.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Palimpsest
+          module Helpers
+            class PalimpsestEngine
+              include Constants
+
+              attr_reader :palimpsests
+
+              def initialize
+                @palimpsests = {}
+              end
+
+              def create(topic:, domain: :unknown)
+                return nil if @palimpsests.size >= MAX_PALIMPSESTS
+                return nil if @palimpsests.key?(topic)
+
+                p = Palimpsest.new(topic: topic, domain: domain)
+                @palimpsests[topic] = p
+                p
+              end
+
+              def overwrite(topic:, content:, confidence: DEFAULT_CONFIDENCE, author: :system)
+                p = find_or_create(topic)
+                return nil unless p
+
+                p.overwrite!(content, confidence: confidence, author: author)
+              end
+
+              def peek_through(topic:, depth: 1)
+                p = @palimpsests[topic]
+                return [] unless p
+
+                p.peek_through(depth: depth).map(&:to_h)
+              end
+
+              def erode(topic:, rate: EROSION_RATE)
+                p = @palimpsests[topic]
+                return nil unless p
+
+                p.erode_current!(rate: rate)
+              end
+
+              def ghost_layers_for(topic:)
+                p = @palimpsests[topic]
+                return [] unless p
+
+                p.ghost_layers.map(&:to_h)
+              end
+
+              def all_ghost_layers
+                @palimpsests.flat_map { |_topic, p| p.ghost_layers.map(&:to_h) }
+              end
+
+              def domain_archaeology(domain:)
+                @palimpsests.each_with_object([]) do |(_topic, p), results|
+                  next unless p.domain == domain
+
+                  p.all_layers.each { |layer| results << layer.to_h.merge(topic: p.topic) }
+                end
+              end
+
+              def belief_drift(topic:)
+                p = @palimpsests[topic]
+                return nil unless p
+
+                { drift: p.belief_drift.round(4), label: p.drift_label }
+              end
+
+              def overwrite_frequency(topic:)
+                p = @palimpsests[topic]
+                return nil unless p
+
+                p.overwrite_count
+              end
+
+              def most_rewritten(limit: 10)
+                sorted = @palimpsests.values.sort_by { |p| -p.overwrite_count }
+                sorted.first(limit).map(&:to_h)
+              end
+
+              def decay_all!(ghost_rate: GHOST_DECAY)
+                @palimpsests.each_value { |p| p.decay_ghosts!(rate: ghost_rate) }
+              end
+
+              def palimpsest_report
+                total_ghosts = @palimpsests.values.sum { |p| p.ghost_layers.size }
+                avg_drift    = if @palimpsests.empty?
+                                 0.0
+                               else
+                                 total = @palimpsests.values.sum(&:belief_drift)
+                                 (total / @palimpsests.size).round(4)
+                               end
+                {
+                  palimpsest_count: @palimpsests.size,
+                  total_ghosts:     total_ghosts,
+                  average_drift:    avg_drift,
+                  most_rewritten:   most_rewritten(limit: 5)
+                }
+              end
+
+              private
+
+              def find_or_create(topic)
+                @palimpsests[topic] || create(topic: topic)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end