lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/archaeology/runners/cognitive_archaeology.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+          module Runners
+            module CognitiveArchaeology
+              extend self
+
+              def create_site(domain:, engine: nil, **)
+                eng  = resolve_engine(engine)
+                site = eng.create_site(domain: domain)
+                { success: true, site: site.survey }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def dig(site_id:, engine: nil, **)
+                eng    = resolve_engine(engine)
+                result = eng.dig(site_id: site_id)
+                { success: true }.merge(result)
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def excavate(site_id:, engine: nil, **)
+                eng      = resolve_engine(engine)
+                artifact = eng.excavate(site_id: site_id)
+                { success: true, artifact: artifact.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def restore_artifact(artifact_id:, boost: 0.15, engine: nil, **)
+                eng      = resolve_engine(engine)
+                artifact = eng.restore_artifact(
+                  artifact_id: artifact_id, boost: boost
+                )
+                { success: true, artifact: artifact.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_artifacts(engine: nil, type: nil, domain: nil,
+                                 depth_level: nil, **)
+                eng     = resolve_engine(engine)
+                results = filter_results(eng.all_artifacts,
+                                         type: type, domain: domain,
+                                         depth_level: depth_level)
+                { success: true, artifacts: results.map(&:to_h),
+                  count: results.size }
+              end
+
+              def archaeology_status(engine: nil, **)
+                eng = resolve_engine(engine)
+                { success: true, report: eng.archaeology_report }
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              private
+
+              def filter_results(artifacts, type:, domain:, depth_level:)
+                r = artifacts
+                r = r.select { |a| a.artifact_type == type.to_sym } if type
+                r = r.select { |a| a.domain == domain.to_sym } if domain
+                r = r.select { |a| a.depth_level == depth_level.to_sym } if depth_level
+                r
+              end
+
+              def resolve_engine(engine)
+                engine || default_engine
+              end
+
+              def default_engine
+                @default_engine ||= Helpers::ArchaeologyEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'archaeology/version'
+require_relative 'archaeology/helpers/constants'
+require_relative 'archaeology/helpers/artifact'
+require_relative 'archaeology/helpers/excavation_site'
+require_relative 'archaeology/helpers/archaeology_engine'
+require_relative 'archaeology/runners/cognitive_archaeology'
+require_relative 'archaeology/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Compression
+          class Client
+            include Runners::CognitiveCompression
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/compression/helpers/compression_engine.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Compression
+          module Helpers
+            class CompressionEngine
+              include Constants
+
+              def initialize
+                @chunks       = {}
+                @abstractions = {}
+              end
+
+              def store_chunk(label:, chunk_type: :semantic, original_size: 1.0)
+                prune_chunks_if_needed
+                chunk = InformationChunk.new(label: label, chunk_type: chunk_type,
+                                             original_size: original_size)
+                @chunks[chunk.id] = chunk
+                chunk
+              end
+
+              def compress_chunk(chunk_id:, amount: COMPRESSION_RATE)
+                chunk = @chunks[chunk_id]
+                return nil unless chunk
+
+                chunk.compress!(amount: amount)
+              end
+
+              def decompress_chunk(chunk_id:, amount: COMPRESSION_RATE)
+                chunk = @chunks[chunk_id]
+                return nil unless chunk
+
+                chunk.decompress!(amount: amount)
+              end
+
+              def abstract_chunks(chunk_ids:, abstraction_label:)
+                prune_abstractions_if_needed
+                chunks = chunk_ids.filter_map { |id| @chunks[id] }
+                return nil if chunks.empty?
+
+                combined_size = chunks.sum(&:compressed_size)
+                abstraction = InformationChunk.new(
+                  label:         abstraction_label,
+                  chunk_type:    :abstract,
+                  original_size: combined_size
+                )
+                avg_fidelity = (chunks.sum(&:fidelity) / chunks.size).round(10)
+                abstraction.compress!(amount: DEFAULT_COMPRESSION_RATIO)
+                @abstractions[abstraction.id] = {
+                  chunk:      abstraction,
+                  source_ids: chunk_ids,
+                  fidelity:   avg_fidelity
+                }
+                abstraction
+              end
+
+              def compress_all(amount: COMPRESSION_RATE)
+                @chunks.each_value { |c| c.compress!(amount: amount) }
+                @chunks.size
+              end
+
+              def chunks_by_type(chunk_type:)
+                ct = chunk_type.to_sym
+                @chunks.values.select { |c| c.chunk_type == ct }
+              end
+
+              def highly_compressed_chunks
+                @chunks.values.select(&:highly_compressed?)
+              end
+
+              def average_compression_ratio
+                return 0.0 if @chunks.empty?
+
+                ratios = @chunks.values.map(&:compression_ratio)
+                (ratios.sum / ratios.size).round(10)
+              end
+
+              def average_fidelity
+                return 1.0 if @chunks.empty?
+
+                fids = @chunks.values.map(&:fidelity)
+                (fids.sum / fids.size).round(10)
+              end
+
+              def total_original_size
+                @chunks.values.sum(&:original_size).round(10)
+              end
+
+              def total_compressed_size
+                @chunks.values.sum(&:compressed_size).round(10)
+              end
+
+              def overall_compression_ratio
+                return 0.0 if total_original_size.zero?
+
+                (1.0 - (total_compressed_size / total_original_size)).clamp(0.0, 1.0).round(10)
+              end
+
+              def compression_report
+                {
+                  total_chunks:              @chunks.size,
+                  total_abstractions:        @abstractions.size,
+                  average_compression_ratio: average_compression_ratio,
+                  overall_compression_ratio: overall_compression_ratio,
+                  average_fidelity:          average_fidelity,
+                  total_original_size:       total_original_size,
+                  total_compressed_size:     total_compressed_size,
+                  highly_compressed_count:   highly_compressed_chunks.size
+                }
+              end
+
+              def to_h
+                {
+                  total_chunks:              @chunks.size,
+                  total_abstractions:        @abstractions.size,
+                  average_compression_ratio: average_compression_ratio,
+                  average_fidelity:          average_fidelity
+                }
+              end
+
+              private
+
+              def prune_chunks_if_needed
+                return if @chunks.size < MAX_CHUNKS
+
+                oldest = @chunks.values.min_by(&:created_at)
+                @chunks.delete(oldest.id) if oldest
+              end
+
+              def prune_abstractions_if_needed
+                return if @abstractions.size < MAX_ABSTRACTIONS
+
+                oldest_key = @abstractions.min_by { |_, v| v[:chunk].created_at }&.first
+                @abstractions.delete(oldest_key) if oldest_key
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Compression
+          module Helpers
+            module Constants
+              MAX_CHUNKS = 500
+              MAX_ABSTRACTIONS = 200
+
+              DEFAULT_COMPRESSION_RATIO = 0.5
+              COMPRESSION_RATE = 0.1
+              FIDELITY_LOSS_RATE = 0.02
+              MIN_FIDELITY = 0.1
+
+              COMPRESSION_LABELS = {
+                (0.8..)     => :highly_compressed,
+                (0.6...0.8) => :compressed,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :detailed,
+                (..0.2)     => :raw
+              }.freeze
+
+              FIDELITY_LABELS = {
+                (0.8..)     => :pristine,
+                (0.6...0.8) => :faithful,
+                (0.4...0.6) => :approximate,
+                (0.2...0.4) => :lossy,
+                (..0.2)     => :degraded
+              }.freeze
+
+              CHUNK_TYPES = %i[
+                episodic semantic procedural sensory
+                emotional abstract relational
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/compression/helpers/information_chunk.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Compression
+          module Helpers
+            class InformationChunk
+              include Constants
+
+              attr_reader :id, :label, :chunk_type, :original_size, :compressed_size,
+                          :fidelity, :compression_count, :created_at
+
+              def initialize(label:, chunk_type: :semantic, original_size: 1.0)
+                @id                = SecureRandom.uuid
+                @label             = label
+                @chunk_type        = chunk_type.to_sym
+                @original_size     = [original_size.to_f, 0.01].max
+                @compressed_size   = @original_size
+                @fidelity          = 1.0
+                @compression_count = 0
+                @created_at        = Time.now.utc
+              end
+
+              def compression_ratio
+                return 0.0 if @original_size.zero?
+
+                (1.0 - (@compressed_size / @original_size)).clamp(0.0, 1.0).round(10)
+              end
+
+              def compress!(amount: COMPRESSION_RATE)
+                @compressed_size = (@compressed_size * (1.0 - amount)).clamp(0.01, @original_size).round(10)
+                @fidelity = (@fidelity - FIDELITY_LOSS_RATE).clamp(MIN_FIDELITY, 1.0).round(10)
+                @compression_count += 1
+                self
+              end
+
+              def decompress!(amount: COMPRESSION_RATE)
+                @compressed_size = (@compressed_size / (1.0 - amount)).clamp(0.01, @original_size).round(10)
+                self
+              end
+
+              def highly_compressed?
+                compression_ratio >= 0.8
+              end
+
+              def compression_label
+                match = COMPRESSION_LABELS.find { |range, _| range.cover?(compression_ratio) }
+                match ? match.last : :raw
+              end
+
+              def fidelity_label
+                match = FIDELITY_LABELS.find { |range, _| range.cover?(@fidelity) }
+                match ? match.last : :degraded
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  label:             @label,
+                  chunk_type:        @chunk_type,
+                  original_size:     @original_size,
+                  compressed_size:   @compressed_size,
+                  compression_ratio: compression_ratio,
+                  compression_label: compression_label,
+                  fidelity:          @fidelity,
+                  fidelity_label:    fidelity_label,
+                  compression_count: @compression_count,
+                  created_at:        @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/compression/runners/cognitive_compression.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Compression
+          module Runners
+            module CognitiveCompression
+              include Helpers::Constants
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def store_chunk(label:, engine: nil, chunk_type: :semantic, original_size: 1.0, **)
+                eng = engine || default_engine
+                chunk = eng.store_chunk(label: label, chunk_type: chunk_type, original_size: original_size)
+                { success: true, chunk: chunk.to_h }
+              end
+
+              def compress_chunk(chunk_id:, engine: nil, amount: COMPRESSION_RATE, **)
+                eng = engine || default_engine
+                result = eng.compress_chunk(chunk_id: chunk_id, amount: amount)
+                return { success: false, error: 'chunk not found' } unless result
+
+                { success: true, chunk: result.to_h }
+              end
+
+              def decompress_chunk(chunk_id:, engine: nil, amount: COMPRESSION_RATE, **)
+                eng = engine || default_engine
+                result = eng.decompress_chunk(chunk_id: chunk_id, amount: amount)
+                return { success: false, error: 'chunk not found' } unless result
+
+                { success: true, chunk: result.to_h }
+              end
+
+              def abstract_chunks(chunk_ids:, abstraction_label:, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.abstract_chunks(chunk_ids: chunk_ids, abstraction_label: abstraction_label)
+                return { success: false, error: 'no valid chunks' } unless result
+
+                { success: true, abstraction: result.to_h }
+              end
+
+              def compress_all(engine: nil, amount: COMPRESSION_RATE, **)
+                eng = engine || default_engine
+                count = eng.compress_all(amount: amount)
+                { success: true, compressed_count: count }
+              end
+
+              def average_fidelity(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, fidelity: eng.average_fidelity }
+              end
+
+              def overall_compression_ratio(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, ratio: eng.overall_compression_ratio }
+              end
+
+              def compression_report(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, report: eng.compression_report }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::CompressionEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'compression/version'
+require_relative 'compression/helpers/constants'
+require_relative 'compression/helpers/information_chunk'
+require_relative 'compression/helpers/compression_engine'
+require_relative 'compression/runners/cognitive_compression'
+require_relative 'compression/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Compression
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Echo
+          module Helpers
+            module Constants
+              MAX_ECHOES        = 300
+              MAX_INTERACTIONS  = 500
+              DEFAULT_INTENSITY = 0.8
+              ECHO_DECAY        = 0.1
+              REINFORCEMENT     = 0.15
+              INTERFERENCE_THRESHOLD = 0.4
+              PRIMING_THRESHOLD = 0.3
+              SILENT_THRESHOLD  = 0.05
+
+              ECHO_TYPES = %i[
+                thought emotion decision observation
+                prediction error success failure
+              ].freeze
+
+              INTENSITY_LABELS = {
+                (0.8..)     => :reverberating,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :fading,
+                (..0.2)     => :whisper
+              }.freeze
+
+              EFFECT_LABELS = {
+                (0.6..)     => :dominant,
+                (0.3...0.6) => :influential,
+                (0.1...0.3) => :subtle,
+                (..0.1)     => :negligible
+              }.freeze
+
+              CHAMBER_LABELS = {
+                (0.8..)     => :echo_chamber,
+                (0.6...0.8) => :resonant,
+                (0.4...0.6) => :balanced,
+                (0.2...0.4) => :diverse,
+                (..0.2)     => :scattered
+              }.freeze
+
+              def self.label_for(labels, value)
+                match = labels.find { |range, _| range.cover?(value) }
+                match&.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Echo
+          module Helpers
+            class Echo
+              include Constants
+
+              attr_reader :id, :content, :echo_type, :domain, :intensity,
+                          :original_intensity, :decay_count, :created_at
+
+              def initialize(content:, echo_type: :thought, domain: :general, intensity: DEFAULT_INTENSITY)
+                @id                 = SecureRandom.uuid
+                @content            = content
+                @echo_type          = validate_type(echo_type)
+                @domain             = domain.to_sym
+                @intensity          = intensity.to_f.clamp(0.0, 1.0).round(10)
+                @original_intensity = @intensity
+                @decay_count        = 0
+                @created_at         = Time.now.utc
+              end
+
+              def decay!
+                @decay_count += 1
+                @intensity = (@intensity - ECHO_DECAY).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def reinforce!(amount = REINFORCEMENT)
+                @intensity = (@intensity + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def silent?
+                @intensity <= SILENT_THRESHOLD
+              end
+
+              def active?
+                @intensity > SILENT_THRESHOLD
+              end
+
+              def priming?
+                @intensity >= PRIMING_THRESHOLD
+              end
+
+              def interfering?
+                @intensity >= INTERFERENCE_THRESHOLD
+              end
+
+              def persistence
+                return 0.0 if @original_intensity.zero?
+
+                (@intensity / @original_intensity).clamp(0.0, 1.0).round(10)
+              end
+
+              def intensity_label = Constants.label_for(INTENSITY_LABELS, @intensity)
+              def effect_label = Constants.label_for(EFFECT_LABELS, @intensity)
+
+              def to_h
+                {
+                  id:                 @id,
+                  content:            @content,
+                  echo_type:          @echo_type,
+                  domain:             @domain,
+                  intensity:          @intensity,
+                  original_intensity: @original_intensity,
+                  intensity_label:    intensity_label,
+                  effect_label:       effect_label,
+                  priming:            priming?,
+                  interfering:        interfering?,
+                  silent:             silent?,
+                  persistence:        persistence,
+                  decay_count:        @decay_count,
+                  created_at:         @created_at
+                }
+              end
+
+              private
+
+              def validate_type(type)
+                sym = type.to_sym
+                ECHO_TYPES.include?(sym) ? sym : :thought
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end