lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/episodic/runners/episodic_buffer.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+          module Runners
+            module EpisodicBuffer
+              def create_episode(**)
+                store = default_store
+                episode = store.create_episode
+                Legion::Logging.debug "[episodic_buffer] created episode id=#{episode.id[0..7]}"
+                { success: true, episode_id: episode.id, created_at: episode.created_at }
+              end
+
+              def add_binding(episode_id:, modality:, content:, source:,
+                              strength: Helpers::Constants::DEFAULT_BINDING_STRENGTH, **)
+                raise ArgumentError, "invalid modality: #{modality}" unless Helpers::Constants::MODALITIES.include?(modality.to_sym)
+
+                store  = default_store
+                result = store.add_to_episode(
+                  episode_id: episode_id,
+                  modality:   modality.to_sym,
+                  content:    content,
+                  source:     source,
+                  strength:   strength
+                )
+
+                if result[:added]
+                  Legion::Logging.debug "[episodic_buffer] add_binding ep=#{episode_id[0..7]} mod=#{modality}"
+                  { success: true, episode_id: episode_id, binding_id: result[:binding_id] }
+                else
+                  Legion::Logging.debug "[episodic_buffer] add_binding failed ep=#{episode_id[0..7]} r=#{result[:reason]}"
+                  { success: false, episode_id: episode_id, reason: result[:reason] }
+                end
+              end
+
+              def attend_episode(episode_id:, **)
+                store  = default_store
+                result = store.attend_episode(episode_id: episode_id)
+                Legion::Logging.debug "[episodic_buffer] attend ep=#{episode_id[0..7]} success=#{result[:success]}"
+                result.merge(success: result[:success])
+              end
+
+              def rehearse_episode(episode_id:, **)
+                store  = default_store
+                result = store.rehearse_episode(episode_id: episode_id)
+                Legion::Logging.debug "[episodic_buffer] rehearse ep=#{episode_id[0..7]} success=#{result[:success]}"
+                result.merge(success: result[:success])
+              end
+
+              def check_integration(episode_id:, **)
+                store  = default_store
+                result = store.integrate(episode_id: episode_id)
+                Legion::Logging.debug "[episodic_buffer] check_integration ep=#{episode_id[0..7]} ok=#{result[:integrated]}"
+                result.merge(success: true)
+              end
+
+              def retrieve_by_modality(modality:, **)
+                store    = default_store
+                episodes = store.retrieve_by_modality(modality: modality.to_sym)
+                Legion::Logging.debug "[episodic_buffer] retrieve_by_modality mod=#{modality} count=#{episodes.size}"
+                { success: true, modality: modality, count: episodes.size, episodes: episodes.map(&:to_h) }
+              end
+
+              def retrieve_multimodal(**)
+                store    = default_store
+                episodes = store.retrieve_multimodal
+                Legion::Logging.debug "[episodic_buffer] retrieve_multimodal count=#{episodes.size}"
+                { success: true, count: episodes.size, episodes: episodes.map(&:to_h) }
+              end
+
+              def most_coherent(limit: 5, **)
+                store    = default_store
+                episodes = store.most_coherent(limit: limit)
+                Legion::Logging.debug "[episodic_buffer] most_coherent limit=#{limit} returned=#{episodes.size}"
+                { success: true, count: episodes.size, episodes: episodes.map(&:to_h) }
+              end
+
+              def update_episodic_buffer(**)
+                store  = default_store
+                result = store.tick
+                Legion::Logging.debug "[episodic_buffer] tick decayed=#{result[:decayed]} expired=#{result[:expired]}"
+                { success: true }.merge(result)
+              end
+
+              def episodic_buffer_stats(**)
+                store = default_store
+                stats = store.to_h
+                Legion::Logging.debug "[episodic_buffer] stats episodes=#{stats[:episode_count]}"
+                { success: true }.merge(stats)
+              end
+
+              private
+
+              def default_store
+                @default_store ||= Helpers::EpisodicStore.new
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/episodic/version'
+require 'legion/extensions/agentic/memory/episodic/helpers/constants'
+require 'legion/extensions/agentic/memory/episodic/helpers/episodic_binding'
+require 'legion/extensions/agentic/memory/episodic/helpers/episode'
+require 'legion/extensions/agentic/memory/episodic/helpers/episodic_store'
+require 'legion/extensions/agentic/memory/episodic/runners/episodic_buffer'
+require 'legion/extensions/agentic/memory/episodic/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Episodic
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+          class Client
+            include Runners::CognitiveHologram
+
+            def initialize(engine: nil, **)
+              @default_engine = engine || Helpers::HologramEngine.new
+            end
+
+            private
+
+            attr_reader :default_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+          module Helpers
+            module Constants
+              # Resolution levels for holographic recall quality
+              RESOLUTION_LEVELS = %i[perfect high medium low fragmentary].freeze
+
+              # Maximum number of holograms retained in the engine
+              MAX_HOLOGRAMS = 100
+
+              # Per-cycle decay applied to fragment fidelity
+              INTERFERENCE_DECAY = 0.03
+
+              # Minimum completeness for a fragment to contribute to reconstruction
+              RECONSTRUCTION_THRESHOLD = 0.3
+
+              # Fragment labels based on completeness range
+              FRAGMENT_LABELS = [
+                [(0.9..),       :intact],
+                [(0.7...0.9),   :substantial],
+                [(0.5...0.7),   :partial],
+                [(0.3...0.5),   :degraded],
+                [(..0.3),       :fragmentary]
+              ].freeze
+
+              # Resolution labels mapping hologram resolution to symbol
+              RESOLUTION_LABELS = [
+                [(0.9..),       :perfect],
+                [(0.7...0.9),   :high],
+                [(0.5...0.7),   :medium],
+                [(0.3...0.5),   :low],
+                [(..0.3),       :fragmentary]
+              ].freeze
+
+              # Fidelity labels for individual fragments
+              FIDELITY_LABELS = [
+                [(0.8..),       :pristine],
+                [(0.6...0.8),   :clear],
+                [(0.4...0.6),   :hazy],
+                [(0.2...0.4),   :clouded],
+                [(..0.2),       :corrupted]
+              ].freeze
+
+              # Interference strength labels
+              INTERFERENCE_LABELS = [
+                [(0.7..),       :strong],
+                [(0.4...0.7),   :moderate],
+                [(0.1...0.4),   :weak],
+                [(..0.1),       :negligible]
+              ].freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+          module Helpers
+            class Hologram
+              include Constants
+
+              attr_reader :id, :domain, :content, :fragments, :created_at
+
+              def initialize(domain:, content:)
+                @id         = SecureRandom.uuid
+                @domain     = domain.to_sym
+                @content    = content
+                @fragments  = []
+                @created_at = Time.now.utc
+              end
+
+              def resolution
+                return 0.0 if @fragments.empty?
+
+                sufficient = @fragments.select(&:sufficient?)
+                return 0.0 if sufficient.empty?
+
+                avg_completeness = sufficient.sum(&:completeness).round(10) / sufficient.size
+                avg_fidelity     = sufficient.sum(&:fidelity).round(10) / sufficient.size
+                ((avg_completeness + avg_fidelity) / 2.0).round(10)
+              end
+
+              def fragment!(count)
+                count = count.clamp(1, 20)
+                new_fragments = (1..count).map do |i|
+                  completeness = ((1.0 / count) + (rand * 0.2)).clamp(0.0, 1.0)
+                  fidelity     = (1.0 - ((i - 1).to_f / (count * 2))).clamp(0.0, 1.0)
+                  HolographicFragment.new(
+                    content:            @content,
+                    parent_hologram_id: @id,
+                    completeness:       completeness,
+                    fidelity:           fidelity
+                  )
+                end
+                @fragments.concat(new_fragments)
+                new_fragments
+              end
+
+              def reconstruct(fragments)
+                sufficient = Array(fragments).select(&:sufficient?)
+                return { success: false, reason: :insufficient_fragments, resolution: 0.0 } if sufficient.empty?
+
+                avg_completeness = sufficient.sum(&:completeness).round(10) / sufficient.size
+                avg_fidelity     = sufficient.sum(&:fidelity).round(10) / sufficient.size
+                reconstructed_resolution = ((avg_completeness + avg_fidelity) / 2.0).round(10)
+
+                {
+                  success:         true,
+                  resolution:      reconstructed_resolution,
+                  label:           resolution_label(reconstructed_resolution),
+                  fragment_count:  sufficient.size,
+                  total_fragments: fragments.size
+                }
+              end
+
+              def add_fragment(fragment)
+                @fragments << fragment
+                fragment
+              end
+
+              def resolution_label(res = nil)
+                value = res || resolution
+                Constants.label_for(Constants::RESOLUTION_LABELS, value)
+              end
+
+              def interference_with(other_hologram)
+                return 0.0 if other_hologram.nil? || other_hologram.id == @id
+
+                self_words  = tokenize(@content)
+                other_words = tokenize(other_hologram.content)
+
+                return 0.0 if self_words.empty? || other_words.empty?
+
+                shared = (self_words & other_words).size
+                total  = (self_words | other_words).size
+                return 0.0 if total.zero?
+
+                (shared.to_f / total).round(10)
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  domain:           @domain,
+                  content:          @content,
+                  resolution:       resolution,
+                  resolution_label: resolution_label,
+                  fragment_count:   @fragments.size,
+                  fragments:        @fragments.map(&:to_h),
+                  created_at:       @created_at.iso8601
+                }
+              end
+
+              private
+
+              def tokenize(text)
+                text.to_s.downcase.scan(/\w+/).uniq
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/hologram/helpers/hologram_engine.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+          module Helpers
+            class HologramEngine
+              include Constants
+
+              def initialize
+                @holograms = {}
+              end
+
+              def create_hologram(domain:, content:)
+                prune! if @holograms.size >= Constants::MAX_HOLOGRAMS
+
+                hologram = Hologram.new(domain: domain, content: content)
+                @holograms[hologram.id] = hologram
+                hologram
+              end
+
+              def fragment_hologram(hologram_id:, count: 4)
+                hologram = @holograms[hologram_id]
+                return nil unless hologram
+
+                hologram.fragment!(count)
+              end
+
+              def reconstruct_from_fragments(fragment_ids:, hologram_id:)
+                hologram = @holograms[hologram_id]
+                return { success: false, reason: :hologram_not_found } unless hologram
+
+                fragments = hologram.fragments.select { |f| fragment_ids.include?(f.id) }
+                hologram.reconstruct(fragments)
+              end
+
+              def measure_interference(hologram_id_a:, hologram_id_b:)
+                holo_a = @holograms[hologram_id_a]
+                holo_b = @holograms[hologram_id_b]
+
+                return { interference: 0.0, label: :negligible, reason: :hologram_not_found } unless holo_a && holo_b
+
+                score = holo_a.interference_with(holo_b)
+                {
+                  interference: score,
+                  label:        Constants.label_for(Constants::INTERFERENCE_LABELS, score),
+                  hologram_a:   hologram_id_a,
+                  hologram_b:   hologram_id_b
+                }
+              end
+
+              def degrade_all!
+                @holograms.each_value do |hologram|
+                  hologram.fragments.each(&:degrade!)
+                end
+              end
+
+              def best_preserved(limit: 5)
+                @holograms.values
+                          .select { |h| h.fragments.any? }
+                          .sort_by { |h| -h.resolution }
+                          .first(limit)
+              end
+
+              def most_fragmented(limit: 5)
+                @holograms.values
+                          .select { |h| h.fragments.any? }
+                          .sort_by(&:resolution)
+                          .first(limit)
+              end
+
+              def hologram_report
+                total = @holograms.size
+                with_fragments = @holograms.values.count { |h| h.fragments.any? }
+                avg_resolution = resolution_average
+
+                {
+                  total_holograms:       total,
+                  holograms_with_frags:  with_fragments,
+                  average_resolution:    avg_resolution,
+                  resolution_label:      Constants.label_for(Constants::RESOLUTION_LABELS, avg_resolution),
+                  best_preserved_count:  best_preserved(limit: 3).size,
+                  most_fragmented_count: most_fragmented(limit: 3).size
+                }
+              end
+
+              def holograms
+                @holograms.values
+              end
+
+              def get(hologram_id)
+                @holograms[hologram_id]
+              end
+
+              private
+
+              def resolution_average
+                return 0.0 if @holograms.empty?
+
+                values = @holograms.values.map(&:resolution)
+                (values.sum.round(10) / values.size).round(10)
+              end
+
+              def prune!
+                worst = most_fragmented(limit: 10)
+                to_remove = worst.size.positive? ? worst : [@holograms.values.first]
+                to_remove.each { |h| @holograms.delete(h.id) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/hologram/helpers/holographic_fragment.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+          module Helpers
+            class HolographicFragment
+              include Constants
+
+              attr_reader :id, :parent_hologram_id, :content, :created_at
+              attr_accessor :completeness, :fidelity
+
+              def initialize(content:, parent_hologram_id:, completeness: 1.0, fidelity: 1.0)
+                @id                = SecureRandom.uuid
+                @content           = content
+                @parent_hologram_id = parent_hologram_id
+                @completeness      = completeness.clamp(0.0, 1.0)
+                @fidelity          = fidelity.clamp(0.0, 1.0)
+                @created_at        = Time.now.utc
+              end
+
+              def degrade!(rate = Constants::INTERFERENCE_DECAY)
+                @completeness = (@completeness - rate).round(10).clamp(0.0, 1.0)
+                @fidelity     = (@fidelity - rate).round(10).clamp(0.0, 1.0)
+                self
+              end
+
+              def enhance!(boost = 0.1)
+                @completeness = (@completeness + boost).round(10).clamp(0.0, 1.0)
+                @fidelity     = (@fidelity + boost).round(10).clamp(0.0, 1.0)
+                self
+              end
+
+              def sufficient?
+                @completeness > Constants::RECONSTRUCTION_THRESHOLD
+              end
+
+              def completeness_label
+                Constants.label_for(Constants::FRAGMENT_LABELS, @completeness)
+              end
+
+              def fidelity_label
+                Constants.label_for(Constants::FIDELITY_LABELS, @fidelity)
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  parent_hologram_id: @parent_hologram_id,
+                  content:            @content,
+                  completeness:       @completeness,
+                  fidelity:           @fidelity,
+                  completeness_label: completeness_label,
+                  fidelity_label:     fidelity_label,
+                  sufficient:         sufficient?,
+                  created_at:         @created_at.iso8601
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/hologram/runners/cognitive_hologram.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+          module Runners
+            module CognitiveHologram
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create(domain: :general, content: '', engine: nil, **)
+                raise ArgumentError, 'content cannot be empty' if content.to_s.strip.empty?
+
+                target_engine = engine || default_engine
+                hologram = target_engine.create_hologram(domain: domain, content: content)
+
+                Legion::Logging.debug "[cognitive_hologram] created hologram: domain=#{domain} id=#{hologram.id}"
+
+                { success: true, hologram: hologram.to_h }
+              rescue StandardError => e
+                Legion::Logging.error "[cognitive_hologram] create failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def fragment(hologram_id:, count: 4, engine: nil, **)
+                target_engine = engine || default_engine
+                fragments = target_engine.fragment_hologram(hologram_id: hologram_id, count: count)
+
+                unless fragments
+                  Legion::Logging.warn "[cognitive_hologram] fragment: hologram not found id=#{hologram_id}"
+                  return { success: false, reason: :hologram_not_found }
+                end
+
+                Legion::Logging.debug "[cognitive_hologram] fragmented hologram id=#{hologram_id} count=#{fragments.size}"
+                { success: true, fragment_count: fragments.size, fragments: fragments.map(&:to_h) }
+              rescue StandardError => e
+                Legion::Logging.error "[cognitive_hologram] fragment failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def reconstruct(hologram_id:, fragment_ids: [], engine: nil, **)
+                target_engine = engine || default_engine
+                result = target_engine.reconstruct_from_fragments(
+                  hologram_id:  hologram_id,
+                  fragment_ids: fragment_ids
+                )
+
+                Legion::Logging.debug "[cognitive_hologram] reconstruct hologram=#{hologram_id} " \
+                                      "fragments=#{fragment_ids.size} success=#{result[:success]}"
+
+                result.merge(success: result[:success])
+              rescue StandardError => e
+                Legion::Logging.error "[cognitive_hologram] reconstruct failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def list_holograms(limit: 20, engine: nil, **)
+                target_engine = engine || default_engine
+                holograms = target_engine.holograms.first(limit)
+
+                Legion::Logging.debug "[cognitive_hologram] list_holograms: count=#{holograms.size} limit=#{limit}"
+                { success: true, holograms: holograms.map(&:to_h), count: holograms.size }
+              rescue StandardError => e
+                Legion::Logging.error "[cognitive_hologram] list_holograms failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def interference_check(hologram_id_a:, hologram_id_b:, engine: nil, **)
+                target_engine = engine || default_engine
+                result = target_engine.measure_interference(
+                  hologram_id_a: hologram_id_a,
+                  hologram_id_b: hologram_id_b
+                )
+
+                Legion::Logging.debug '[cognitive_hologram] interference_check: ' \
+                                      "a=#{hologram_id_a} b=#{hologram_id_b} score=#{result[:interference]}"
+
+                result.merge(success: true)
+              rescue StandardError => e
+                Legion::Logging.error "[cognitive_hologram] interference_check failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def hologram_status(engine: nil, **)
+                target_engine = engine || default_engine
+                report = target_engine.hologram_report
+
+                Legion::Logging.debug "[cognitive_hologram] status: total=#{report[:total_holograms]} " \
+                                      "avg_resolution=#{report[:average_resolution].round(2)}"
+
+                { success: true, report: report }
+              rescue StandardError => e
+                Legion::Logging.error "[cognitive_hologram] hologram_status failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::HologramEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'hologram/version'
+require_relative 'hologram/helpers/constants'
+require_relative 'hologram/helpers/holographic_fragment'
+require_relative 'hologram/helpers/hologram'
+require_relative 'hologram/helpers/hologram_engine'
+require_relative 'hologram/runners/cognitive_hologram'
+require_relative 'hologram/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Hologram
+        end
+      end
+    end
+  end
+end