lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/palimpsest/runners/cognitive_palimpsest.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Palimpsest
+          module Runners
+            module CognitivePalimpsest
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_palimpsest(topic:, domain: :unknown, engine: nil, **)
+                p = resolve_engine(engine).create(topic: topic, domain: domain)
+                return { success: false, reason: :limit_or_duplicate } unless p
+
+                { success: true, id: p.id, topic: p.topic, domain: p.domain }
+              end
+
+              def overwrite_belief(topic:, content:, confidence: DEFAULT_CONFIDENCE,
+                                   author: :system, engine: nil, **)
+                layer = resolve_engine(engine).overwrite(
+                  topic:      topic,
+                  content:    content,
+                  confidence: confidence,
+                  author:     author
+                )
+                return { success: false, reason: :limit_reached } unless layer
+
+                { success: true, layer_id: layer.id, version: layer.version,
+                  confidence: layer.confidence.round(4) }
+              end
+
+              def peek_through_belief(topic:, depth: 1, engine: nil, **)
+                layers = resolve_engine(engine).peek_through(topic: topic, depth: depth)
+                { success: true, layers: layers, count: layers.size }
+              end
+
+              def erode_belief(topic:, rate: EROSION_RATE, engine: nil, **)
+                result = resolve_engine(engine).erode(topic: topic, rate: rate)
+                return { success: false, reason: :not_found } if result.nil?
+
+                { success: true, topic: topic, confidence: result.round(4) }
+              end
+
+              def ghost_layers(topic:, engine: nil, **)
+                layers = resolve_engine(engine).ghost_layers_for(topic: topic)
+                { success: true, layers: layers, count: layers.size }
+              end
+
+              def all_ghost_layers(engine: nil, **)
+                layers = resolve_engine(engine).all_ghost_layers
+                { success: true, layers: layers, count: layers.size }
+              end
+
+              def domain_archaeology(domain:, engine: nil, **)
+                layers = resolve_engine(engine).domain_archaeology(domain: domain)
+                { success: true, layers: layers, count: layers.size }
+              end
+
+              def belief_drift(topic:, engine: nil, **)
+                result = resolve_engine(engine).belief_drift(topic: topic)
+                return { success: false, reason: :not_found } unless result
+
+                { success: true }.merge(result)
+              end
+
+              def overwrite_frequency(topic:, engine: nil, **)
+                count = resolve_engine(engine).overwrite_frequency(topic: topic)
+                return { success: false, reason: :not_found } if count.nil?
+
+                { success: true, topic: topic, overwrite_count: count }
+              end
+
+              def most_rewritten(limit: 10, engine: nil, **)
+                palimpsests = resolve_engine(engine).most_rewritten(limit: limit)
+                { success: true, palimpsests: palimpsests, count: palimpsests.size }
+              end
+
+              def decay_all_ghosts(ghost_rate: GHOST_DECAY, engine: nil, **)
+                resolve_engine(engine).decay_all!(ghost_rate: ghost_rate)
+                { success: true }
+              end
+
+              def palimpsest_report(engine: nil, **)
+                report = resolve_engine(engine).palimpsest_report
+                { success: true }.merge(report)
+              end
+
+              private
+
+              def resolve_engine(engine)
+                engine || default_engine
+              end
+
+              def default_engine
+                @default_engine ||= Helpers::PalimpsestEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'palimpsest/version'
+require_relative 'palimpsest/helpers/constants'
+require_relative 'palimpsest/helpers/belief_layer'
+require_relative 'palimpsest/helpers/palimpsest_engine'
+require_relative 'palimpsest/helpers/palimpsest'
+require_relative 'palimpsest/runners/cognitive_palimpsest'
+require_relative 'palimpsest/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Palimpsest
+          # Sub-module for cognitive palimpsest: layered memory overwriting and recovery
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Reserve
+          class Client
+            include Runners::CognitiveReserve
+
+            def initialize(engine: nil)
+              @engine = engine
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Reserve
+          module Helpers
+            module Constants
+              # Maximum tracked pathways
+              MAX_PATHWAYS = 100
+
+              # Maximum tracked compensations
+              MAX_COMPENSATIONS = 200
+
+              # Maximum event history
+              MAX_HISTORY = 300
+
+              # Default pathway capacity (0..1)
+              DEFAULT_CAPACITY = 1.0
+
+              # Capacity bounds
+              CAPACITY_FLOOR   = 0.0
+              CAPACITY_CEILING = 1.0
+
+              # Threshold below which a pathway is considered degraded
+              DEGRADED_THRESHOLD = 0.5
+
+              # Threshold below which a pathway is considered failed
+              FAILED_THRESHOLD = 0.1
+
+              # Compensation efficiency — how much of lost capacity a backup restores
+              COMPENSATION_EFFICIENCY = 0.7
+
+              # Recovery rate per tick
+              RECOVERY_RATE = 0.02
+
+              # Decay rate for unused compensatory pathways
+              COMPENSATION_DECAY = 0.01
+
+              # Reserve levels based on overall reserve ratio
+              RESERVE_LABELS = {
+                (0.8..)     => :robust,
+                (0.6...0.8) => :adequate,
+                (0.4...0.6) => :reduced,
+                (0.2...0.4) => :vulnerable,
+                (..0.2)     => :critical
+              }.freeze
+
+              # Pathway states
+              PATHWAY_STATES = %i[healthy degraded compensating failed].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/reserve/helpers/pathway.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Reserve
+          module Helpers
+            class Pathway
+              include Constants
+
+              attr_reader :id, :domain, :function, :capacity, :backup_ids,
+                          :damage_count, :compensation_count, :created_at, :updated_at
+
+              def initialize(id:, function:, domain: :general, capacity: DEFAULT_CAPACITY)
+                @id                 = id
+                @function           = function
+                @domain             = domain
+                @capacity           = capacity.clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+                @backup_ids         = []
+                @damage_count       = 0
+                @compensation_count = 0
+                @created_at         = Time.now.utc
+                @updated_at         = @created_at
+              end
+
+              def damage(amount:)
+                @capacity = (@capacity - amount.abs).clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+                @damage_count += 1
+                @updated_at = Time.now.utc
+                self
+              end
+
+              def recover(amount: RECOVERY_RATE)
+                @capacity = (@capacity + amount.abs).clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+                @updated_at = Time.now.utc
+                self
+              end
+
+              def add_backup(pathway_id:)
+                return self if @backup_ids.include?(pathway_id)
+
+                @backup_ids << pathway_id
+                @updated_at = Time.now.utc
+                self
+              end
+
+              def remove_backup(pathway_id:)
+                @backup_ids.delete(pathway_id)
+                @updated_at = Time.now.utc
+                self
+              end
+
+              def compensate!
+                @compensation_count += 1
+                @updated_at = Time.now.utc
+              end
+
+              def state
+                return :failed if @capacity <= FAILED_THRESHOLD
+                return :compensating if @capacity <= DEGRADED_THRESHOLD && !@backup_ids.empty?
+                return :degraded if @capacity <= DEGRADED_THRESHOLD
+
+                :healthy
+              end
+
+              def healthy?
+                state == :healthy
+              end
+
+              def degraded?
+                @capacity <= DEGRADED_THRESHOLD
+              end
+
+              def failed?
+                @capacity <= FAILED_THRESHOLD
+              end
+
+              def effective_capacity(backup_capacities: [])
+                return @capacity if @capacity > DEGRADED_THRESHOLD || backup_capacities.empty?
+
+                deficit = DEGRADED_THRESHOLD - @capacity
+                compensation = backup_capacities.sum(0.0) * COMPENSATION_EFFICIENCY
+                (@capacity + [compensation, deficit].min).clamp(CAPACITY_FLOOR, CAPACITY_CEILING)
+              end
+
+              def redundancy
+                @backup_ids.size
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  function:           @function,
+                  domain:             @domain,
+                  capacity:           @capacity.round(4),
+                  state:              state,
+                  backup_count:       @backup_ids.size,
+                  backup_ids:         @backup_ids.dup,
+                  damage_count:       @damage_count,
+                  compensation_count: @compensation_count,
+                  created_at:         @created_at,
+                  updated_at:         @updated_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/reserve/helpers/reserve_engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Reserve
+          module Helpers
+            class ReserveEngine
+              include Constants
+
+              attr_reader :pathways, :history
+
+              def initialize
+                @pathways      = {}
+                @pathway_count = 0
+                @history       = []
+              end
+
+              def add_pathway(function:, domain: :general, capacity: DEFAULT_CAPACITY)
+                return nil if @pathways.size >= MAX_PATHWAYS
+
+                @pathway_count += 1
+                pathway = Pathway.new(
+                  id:       :"path_#{@pathway_count}",
+                  function: function,
+                  domain:   domain,
+                  capacity: capacity
+                )
+                @pathways[pathway.id] = pathway
+                record_event(:add_pathway, pathway_id: pathway.id)
+                pathway
+              end
+
+              def link_backup(primary_id:, backup_id:)
+                primary = @pathways[primary_id]
+                backup  = @pathways[backup_id]
+                return nil unless primary && backup
+
+                primary.add_backup(pathway_id: backup_id)
+                record_event(:link_backup, primary_id: primary_id, backup_id: backup_id)
+                primary
+              end
+
+              def damage_pathway(pathway_id:, amount:)
+                pathway = @pathways[pathway_id]
+                return nil unless pathway
+
+                pathway.damage(amount: amount)
+                activate_compensation(pathway) if pathway.degraded?
+                record_event(:damage, pathway_id: pathway_id, amount: amount, state: pathway.state)
+                pathway
+              end
+
+              def recover_pathway(pathway_id:, amount: RECOVERY_RATE)
+                pathway = @pathways[pathway_id]
+                return nil unless pathway
+
+                pathway.recover(amount: amount)
+                record_event(:recover, pathway_id: pathway_id)
+                pathway
+              end
+
+              def effective_capacity(pathway_id:)
+                pathway = @pathways[pathway_id]
+                return nil unless pathway
+
+                backup_caps = pathway.backup_ids.filter_map { |bid| @pathways[bid]&.capacity }
+                pathway.effective_capacity(backup_capacities: backup_caps)
+              end
+
+              def overall_reserve
+                return DEFAULT_CAPACITY if @pathways.empty?
+
+                caps = @pathways.values.map do |p|
+                  backup_caps = p.backup_ids.filter_map { |bid| @pathways[bid]&.capacity }
+                  p.effective_capacity(backup_capacities: backup_caps)
+                end
+                caps.sum / caps.size.to_f
+              end
+
+              def reserve_label
+                ratio = overall_reserve
+                RESERVE_LABELS.find { |range, _| range.cover?(ratio) }&.last || :critical
+              end
+
+              def degraded_pathways
+                @pathways.values.select(&:degraded?).map(&:to_h)
+              end
+
+              def failed_pathways
+                @pathways.values.select(&:failed?).map(&:to_h)
+              end
+
+              def healthy_pathways
+                @pathways.values.select(&:healthy?).map(&:to_h)
+              end
+
+              def domain_reserve(domain:)
+                relevant = @pathways.values.select { |p| p.domain == domain }
+                return DEFAULT_CAPACITY if relevant.empty?
+
+                caps = relevant.map do |p|
+                  backup_caps = p.backup_ids.filter_map { |bid| @pathways[bid]&.capacity }
+                  p.effective_capacity(backup_capacities: backup_caps)
+                end
+                caps.sum / caps.size.to_f
+              end
+
+              def most_vulnerable(limit: 5)
+                @pathways.values
+                         .sort_by(&:capacity)
+                         .first(limit)
+                         .map(&:to_h)
+              end
+
+              def most_redundant(limit: 5)
+                @pathways.values
+                         .sort_by { |p| -p.redundancy }
+                         .first(limit)
+                         .map(&:to_h)
+              end
+
+              def recover_all
+                @pathways.each_value { |p| p.recover unless p.failed? }
+              end
+
+              def to_h
+                {
+                  pathway_count:   @pathways.size,
+                  overall_reserve: overall_reserve.round(4),
+                  reserve_label:   reserve_label,
+                  healthy_count:   @pathways.values.count(&:healthy?),
+                  degraded_count:  @pathways.values.count(&:degraded?),
+                  failed_count:    @pathways.values.count(&:failed?),
+                  history_size:    @history.size
+                }
+              end
+
+              private
+
+              def activate_compensation(pathway)
+                pathway.backup_ids.each do |backup_id|
+                  backup = @pathways[backup_id]
+                  next unless backup&.healthy?
+
+                  pathway.compensate!
+                  record_event(:compensate, pathway_id: pathway.id, backup_id: backup_id)
+                  break
+                end
+              end
+
+              def record_event(type, **details)
+                @history << { type: type, at: Time.now.utc }.merge(details)
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/reserve/runners/cognitive_reserve.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Reserve
+          module Runners
+            module CognitiveReserve
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def add_cognitive_pathway(function:, domain: :general, capacity: DEFAULT_CAPACITY, **)
+                pathway = engine.add_pathway(function: function, domain: domain, capacity: capacity)
+                return { success: false, reason: :limit_reached } unless pathway
+
+                { success: true, pathway_id: pathway.id, capacity: pathway.capacity }
+              end
+
+              def link_backup_pathway(primary_id:, backup_id:, **)
+                result = engine.link_backup(primary_id: primary_id, backup_id: backup_id)
+                return { success: false, reason: :not_found } unless result
+
+                { success: true, primary_id: primary_id, backup_id: backup_id, backup_count: result.backup_ids.size }
+              end
+
+              def damage_cognitive_pathway(pathway_id:, amount:, **)
+                pathway = engine.damage_pathway(pathway_id: pathway_id, amount: amount)
+                return { success: false, reason: :not_found } unless pathway
+
+                {
+                  success:            true,
+                  pathway_id:         pathway_id,
+                  capacity:           pathway.capacity.round(4),
+                  state:              pathway.state,
+                  effective_capacity: engine.effective_capacity(pathway_id: pathway_id)&.round(4)
+                }
+              end
+
+              def recover_cognitive_pathway(pathway_id:, amount: RECOVERY_RATE, **)
+                pathway = engine.recover_pathway(pathway_id: pathway_id, amount: amount)
+                return { success: false, reason: :not_found } unless pathway
+
+                { success: true, pathway_id: pathway_id, capacity: pathway.capacity.round(4), state: pathway.state }
+              end
+
+              def cognitive_reserve_assessment(**)
+                {
+                  success:         true,
+                  overall_reserve: engine.overall_reserve.round(4),
+                  reserve_label:   engine.reserve_label,
+                  most_vulnerable: engine.most_vulnerable,
+                  degraded:        engine.degraded_pathways,
+                  failed:          engine.failed_pathways
+                }
+              end
+
+              def domain_cognitive_reserve(domain:, **)
+                {
+                  success:       true,
+                  domain:        domain,
+                  reserve:       engine.domain_reserve(domain: domain).round(4),
+                  pathway_count: engine.pathways.values.count { |p| p.domain == domain }
+                }
+              end
+
+              def most_redundant_pathways(**)
+                pathways = engine.most_redundant
+                { success: true, pathways: pathways, count: pathways.size }
+              end
+
+              def update_cognitive_reserve(**)
+                engine.recover_all
+                { success: true }.merge(engine.to_h)
+              end
+
+              def cognitive_reserve_stats(**)
+                { success: true }.merge(engine.to_h)
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::ReserveEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'reserve/version'
+require_relative 'reserve/helpers/constants'
+require_relative 'reserve/helpers/pathway'
+require_relative 'reserve/helpers/reserve_engine'
+require_relative 'reserve/runners/cognitive_reserve'
+require_relative 'reserve/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Reserve
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic/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 Semantic
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Memory::Semantic::Runners::SemanticMemory
+              end
+
+              def runner_function
+                'update_semantic_memory'
+              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

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/semantic/helpers/constants'
+require 'legion/extensions/agentic/memory/semantic/helpers/concept'
+require 'legion/extensions/agentic/memory/semantic/helpers/knowledge_store'
+require 'legion/extensions/agentic/memory/semantic/runners/semantic_memory'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+          class Client
+            include Runners::SemanticMemory
+
+            def initialize(knowledge_store: nil, **)
+              @knowledge_store = knowledge_store || Helpers::KnowledgeStore.new
+            end
+
+            private
+
+            attr_reader :knowledge_store
+          end
+        end
+      end
+    end
+  end
+end