lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/semantic_satiation/runners/semantic_satiation.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticSatiation
+          module Runners
+            module SemanticSatiation
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def expose(label:, domain: :general, **)
+                result = satiation_engine.expose_by_label(label: label, domain: domain)
+                Legion::Logging.debug "[semantic_satiation] expose: label=#{label} domain=#{domain} " \
+                                      "fluency=#{result[:fluency]&.round(2)} satiated=#{result[:satiated]}"
+                result
+              end
+
+              def register(label:, domain: :general, **)
+                concept = satiation_engine.register_concept(label: label, domain: domain)
+                Legion::Logging.debug "[semantic_satiation] register: label=#{label} domain=#{domain} id=#{concept.id[0..7]}"
+                concept.to_h
+              end
+
+              def expose_by_id(concept_id:, **)
+                result = satiation_engine.expose_concept(concept_id: concept_id)
+                if result[:error]
+                  Legion::Logging.debug "[semantic_satiation] expose_by_id: not found id=#{concept_id[0..7]}"
+                else
+                  Legion::Logging.debug "[semantic_satiation] expose_by_id: id=#{concept_id[0..7]} " \
+                                        "fluency=#{result[:fluency]&.round(2)}"
+                end
+                result
+              end
+
+              def recover(amount: Helpers::Constants::RECOVERY_RATE, **)
+                result = satiation_engine.recover_all
+                Legion::Logging.debug "[semantic_satiation] recover: amount=#{amount} recovered=#{result[:recovered]}"
+                result
+              end
+
+              def satiation_status(**)
+                summary = satiation_engine.to_h
+                Legion::Logging.debug "[semantic_satiation] status: concepts=#{summary[:concept_count]} " \
+                                      "satiated=#{summary[:satiated_count]}"
+                summary
+              end
+
+              def domain_satiation(domain:, **)
+                avg_fluency = satiation_engine.domain_satiation(domain: domain)
+                Legion::Logging.debug "[semantic_satiation] domain_satiation: domain=#{domain} avg_fluency=#{avg_fluency.round(2)}"
+                { domain: domain, avg_fluency: avg_fluency }
+              end
+
+              def most_exposed(limit: 5, **)
+                concepts = satiation_engine.most_exposed(limit: limit)
+                Legion::Logging.debug "[semantic_satiation] most_exposed: limit=#{limit} found=#{concepts.size}"
+                { concepts: concepts.map(&:to_h), count: concepts.size }
+              end
+
+              def freshest_concepts(limit: 5, **)
+                concepts = satiation_engine.freshest(limit: limit)
+                Legion::Logging.debug "[semantic_satiation] freshest: limit=#{limit} found=#{concepts.size}"
+                { concepts: concepts.map(&:to_h), count: concepts.size }
+              end
+
+              def novelty_report(**)
+                report = satiation_engine.novelty_report
+                total = satiation_engine.concepts.size
+                Legion::Logging.debug "[semantic_satiation] novelty_report: total=#{total}"
+                { distribution: report, total: total }
+              end
+
+              def prune_saturated(**)
+                removed = satiation_engine.prune_saturated
+                Legion::Logging.debug "[semantic_satiation] prune_saturated: removed=#{removed}"
+                { removed: removed }
+              end
+
+              private
+
+              def satiation_engine
+                @satiation_engine ||= Helpers::SatiationEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/semantic_satiation/version'
+require 'legion/extensions/agentic/memory/semantic_satiation/helpers/constants'
+require 'legion/extensions/agentic/memory/semantic_satiation/helpers/concept'
+require 'legion/extensions/agentic/memory/semantic_satiation/helpers/satiation_engine'
+require 'legion/extensions/agentic/memory/semantic_satiation/runners/semantic_satiation'
+require 'legion/extensions/agentic/memory/semantic_satiation/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticSatiation
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+          module Actors
+            class Decay < Legion::Extensions::Actors::Every
+              def time
+                60
+              end
+
+              def use_runner?
+                false
+              end
+
+              def runner_function
+                :update_source_monitoring
+              end
+
+              def runner_class
+                Legion::Extensions::Agentic::Memory::SourceMonitoring::Runners::SourceMonitoring
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/source_monitoring/helpers/constants'
+require 'legion/extensions/agentic/memory/source_monitoring/helpers/source_record'
+require 'legion/extensions/agentic/memory/source_monitoring/helpers/source_tracker'
+require 'legion/extensions/agentic/memory/source_monitoring/runners/source_monitoring'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+          class Client
+            include Runners::SourceMonitoring
+
+            def initialize(tracker: nil, **)
+              @tracker = tracker || Helpers::SourceTracker.new
+            end
+
+            private
+
+            attr_reader :tracker
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+          module Helpers
+            module Constants
+              MAX_RECORDS       = 500
+              MAX_HISTORY       = 200
+              MAX_ATTRIBUTIONS  = 100
+
+              CONFIDENCE_FLOOR  = 0.1
+              CONFIDENCE_DECAY  = 0.01
+              CONFIDENCE_ALPHA  = 0.12
+
+              DEFAULT_CONFIDENCE = 0.6
+
+              # Source categories (Johnson & Raye reality monitoring)
+              SOURCES = %i[
+                external_perception
+                internal_generation
+                memory_retrieval
+                imagination
+                inference
+                instruction
+                dream
+                unknown
+              ].freeze
+
+              # Reality status — is this from the real world or internally generated?
+              REALITY_STATUS = {
+                external_perception: :real,
+                internal_generation: :constructed,
+                memory_retrieval:    :recalled,
+                imagination:         :imagined,
+                inference:           :derived,
+                instruction:         :received,
+                dream:               :dreamed,
+                unknown:             :uncertain
+              }.freeze
+
+              # Confusion pairs — common source monitoring errors
+              CONFUSION_PAIRS = [
+                %i[external_perception memory_retrieval],
+                %i[internal_generation memory_retrieval],
+                %i[imagination external_perception],
+                %i[inference external_perception],
+                %i[dream memory_retrieval]
+              ].freeze
+
+              CONFIDENCE_LABELS = {
+                (0.8..)     => :certain,
+                (0.6...0.8) => :confident,
+                (0.4...0.6) => :uncertain,
+                (0.2...0.4) => :doubtful,
+                (..0.2)     => :guessing
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/source_monitoring/helpers/source_record.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+          module Helpers
+            class SourceRecord
+              include Constants
+
+              attr_reader :id, :content_id, :source, :domain, :context, :recorded_at
+              attr_accessor :confidence, :verified
+
+              def initialize(id:, content_id:, source:, domain: :general, confidence: DEFAULT_CONFIDENCE, context: {})
+                @id          = id
+                @content_id  = content_id
+                @source      = source
+                @domain      = domain
+                @confidence  = confidence.to_f.clamp(0.0, 1.0)
+                @context     = context
+                @verified    = false
+                @recorded_at = Time.now.utc
+                @corrections = []
+              end
+
+              def reality_status
+                REALITY_STATUS.fetch(@source, :uncertain)
+              end
+
+              def external?
+                @source == :external_perception
+              end
+
+              def internal?
+                %i[internal_generation imagination dream].include?(@source)
+              end
+
+              def verify
+                @verified = true
+                @confidence = [@confidence + 0.15, 1.0].min
+              end
+
+              def correct(new_source:)
+                @corrections << { from: @source, to: new_source, at: Time.now.utc }
+                @source = new_source
+                @confidence = [@confidence * 0.8, CONFIDENCE_FLOOR].max
+              end
+
+              def correction_count
+                @corrections.size
+              end
+
+              def confused?
+                CONFUSION_PAIRS.any? { |pair| pair.include?(@source) } && @confidence < 0.5
+              end
+
+              def decay
+                @confidence = [@confidence - CONFIDENCE_DECAY, CONFIDENCE_FLOOR].max
+              end
+
+              def faded?
+                @confidence <= CONFIDENCE_FLOOR && !@verified
+              end
+
+              def confidence_label
+                CONFIDENCE_LABELS.each { |range, lbl| return lbl if range.cover?(@confidence) }
+                :guessing
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  content_id:       @content_id,
+                  source:           @source,
+                  domain:           @domain,
+                  reality_status:   reality_status,
+                  confidence:       @confidence.round(4),
+                  confidence_label: confidence_label,
+                  verified:         @verified,
+                  external:         external?,
+                  internal:         internal?,
+                  confused:         confused?,
+                  corrections:      correction_count,
+                  recorded_at:      @recorded_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/source_monitoring/helpers/source_tracker.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+          module Helpers
+            class SourceTracker
+              include Constants
+
+              attr_reader :records, :attribution_log
+
+              def initialize
+                @records         = {}
+                @attribution_log = []
+                @record_counter  = 0
+                @accuracy_hits   = 0
+                @accuracy_total  = 0
+              end
+
+              def record_source(content_id:, source:, domain: :general, confidence: DEFAULT_CONFIDENCE, context: {})
+                return nil unless SOURCES.include?(source)
+                return nil if @records.size >= MAX_RECORDS
+
+                @record_counter += 1
+                rec_id = :"src_#{@record_counter}"
+                rec = SourceRecord.new(
+                  id: rec_id, content_id: content_id, source: source,
+                  domain: domain, confidence: confidence, context: context
+                )
+                @records[rec_id] = rec
+                rec
+              end
+
+              def attribute(content_id:)
+                @records.values.select { |r| r.content_id == content_id }.sort_by { |r| -r.confidence }
+              end
+
+              def verify_source(record_id:)
+                rec = @records[record_id]
+                return nil unless rec
+
+                rec.verify
+                @accuracy_hits += 1
+                @accuracy_total += 1
+                log_attribution(record_id, :verified)
+                rec
+              end
+
+              def correct_source(record_id:, new_source:)
+                rec = @records[record_id]
+                return nil unless rec
+                return nil unless SOURCES.include?(new_source)
+
+                old = rec.source
+                rec.correct(new_source: new_source)
+                @accuracy_total += 1
+                log_attribution(record_id, :corrected, from: old, to: new_source)
+                rec
+              end
+
+              def reality_check(content_id:)
+                records = attribute(content_id: content_id)
+                return { status: :unknown, confidence: 0.0 } if records.empty?
+
+                best = records.first
+                { status: best.reality_status, confidence: best.confidence, source: best.source, verified: best.verified }
+              end
+
+              def confused_records
+                @records.values.select(&:confused?).map(&:to_h)
+              end
+
+              def records_by_source(source:)
+                @records.values.select { |r| r.source == source }.map(&:to_h)
+              end
+
+              def records_in_domain(domain:)
+                @records.values.select { |r| r.domain == domain }.map(&:to_h)
+              end
+
+              def attribution_accuracy
+                return 0.0 if @accuracy_total.zero?
+
+                @accuracy_hits.to_f / @accuracy_total
+              end
+
+              def decay_all
+                @records.each_value(&:decay)
+                @records.reject! { |_, r| r.faded? }
+              end
+
+              def to_h
+                source_dist = SOURCES.to_h { |s| [s, @records.values.count { |r| r.source == s }] }
+                {
+                  total_records:        @records.size,
+                  verified_count:       @records.values.count(&:verified),
+                  confused_count:       @records.values.count(&:confused?),
+                  accuracy:             attribution_accuracy.round(4),
+                  source_distribution:  source_dist,
+                  attribution_log_size: @attribution_log.size
+                }
+              end
+
+              private
+
+              def log_attribution(record_id, action, **extra)
+                entry = { record_id: record_id, action: action, at: Time.now.utc }.merge(extra)
+                @attribution_log << entry
+                @attribution_log.shift while @attribution_log.size > MAX_ATTRIBUTIONS
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/source_monitoring/runners/source_monitoring.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+          module Runners
+            module SourceMonitoring
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def record_source(content_id:, source:, domain: :general, confidence: nil, context: {}, **)
+                conf = confidence || Helpers::Constants::DEFAULT_CONFIDENCE
+                Legion::Logging.debug "[source_monitoring] record: content=#{content_id} source=#{source}"
+                rec = tracker.record_source(
+                  content_id: content_id, source: source.to_sym,
+                  domain: domain, confidence: conf, context: context
+                )
+                if rec
+                  { success: true, record: rec.to_h }
+                else
+                  { success: false, reason: :invalid_or_full }
+                end
+              end
+
+              def attribute_source(content_id:, **)
+                records = tracker.attribute(content_id: content_id)
+                Legion::Logging.debug "[source_monitoring] attribute: content=#{content_id} found=#{records.size}"
+                { success: true, records: records.map(&:to_h), count: records.size }
+              end
+
+              def verify_source(record_id:, **)
+                Legion::Logging.debug "[source_monitoring] verify: #{record_id}"
+                rec = tracker.verify_source(record_id: record_id.to_sym)
+                if rec
+                  { success: true, record: rec.to_h }
+                else
+                  { success: false, reason: :not_found }
+                end
+              end
+
+              def correct_source(record_id:, new_source:, **)
+                Legion::Logging.debug "[source_monitoring] correct: #{record_id} -> #{new_source}"
+                rec = tracker.correct_source(record_id: record_id.to_sym, new_source: new_source.to_sym)
+                if rec
+                  { success: true, record: rec.to_h }
+                else
+                  { success: false, reason: :not_found_or_invalid }
+                end
+              end
+
+              def reality_check(content_id:, **)
+                result = tracker.reality_check(content_id: content_id)
+                Legion::Logging.debug "[source_monitoring] reality_check: #{content_id} => #{result[:status]}"
+                { success: true, **result }
+              end
+
+              def confused_sources(**)
+                confused = tracker.confused_records
+                { success: true, confused: confused, count: confused.size }
+              end
+
+              def sources_by_type(source:, **)
+                records = tracker.records_by_source(source: source.to_sym)
+                { success: true, records: records, count: records.size }
+              end
+
+              def attribution_accuracy(**)
+                { success: true, accuracy: tracker.attribution_accuracy.round(4) }
+              end
+
+              def update_source_monitoring(**)
+                Legion::Logging.debug '[source_monitoring] tick'
+                tracker.decay_all
+                { success: true, records: tracker.records.size }
+              end
+
+              def source_monitoring_stats(**)
+                Legion::Logging.debug '[source_monitoring] stats'
+                { success: true, stats: tracker.to_h }
+              end
+
+              private
+
+              def tracker
+                @tracker ||= Helpers::SourceTracker.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/source_monitoring/version'
+require 'legion/extensions/agentic/memory/source_monitoring/helpers/constants'
+require 'legion/extensions/agentic/memory/source_monitoring/helpers/source_record'
+require 'legion/extensions/agentic/memory/source_monitoring/helpers/source_tracker'
+require 'legion/extensions/agentic/memory/source_monitoring/runners/source_monitoring'
+require 'legion/extensions/agentic/memory/source_monitoring/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SourceMonitoring
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/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 Trace
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidation
+              end
+
+              def runner_function
+                'decay_cycle'
+              end
+
+              def time
+                60
+              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/trace/actors/tier_migration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Actor
+            class TierMigration < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidation
+              end
+
+              def runner_function
+                'migrate_tier'
+              end
+
+              def time
+                300
+              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