lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/transfer/helpers/domain_knowledge.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Transfer
+          module Helpers
+            class DomainKnowledge
+              attr_reader :id, :domain, :proficiency, :learn_count, :transfer_count
+
+              PROFICIENCY_LABELS = [
+                [0.0, 0.2,  'novice'],
+                [0.2, 0.4,  'beginner'],
+                [0.4, 0.6,  'intermediate'],
+                [0.6, 0.8,  'advanced'],
+                [0.8, 1.01, 'expert']
+              ].freeze
+
+              def initialize(domain:)
+                @id             = SecureRandom.uuid
+                @domain         = domain
+                @proficiency    = 0.0
+                @learn_count    = 0
+                @transfer_count = 0
+              end
+
+              def learn!(amount:)
+                @proficiency = (@proficiency + amount).clamp(0.0, 1.0).round(10)
+                @learn_count += 1
+                self
+              end
+
+              def record_transfer!
+                @transfer_count += 1
+                self
+              end
+
+              def apply_boost!(amount)
+                @proficiency = (@proficiency + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def apply_penalty!(amount)
+                @proficiency = (@proficiency - amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def proficiency_label
+                PROFICIENCY_LABELS.each do |low, high, label|
+                  return label if @proficiency >= low && @proficiency < high
+                end
+                'novice'
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  domain:            @domain,
+                  proficiency:       @proficiency.round(10),
+                  proficiency_label: proficiency_label,
+                  learn_count:       @learn_count,
+                  transfer_count:    @transfer_count
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/transfer/helpers/transfer_engine.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Transfer
+          module Helpers
+            class TransferEngine
+              include Constants
+
+              attr_reader :domains, :similarities, :transfer_history
+
+              def initialize
+                @domains          = {}
+                @similarities     = {}
+                @transfer_history = []
+              end
+
+              def set_similarity(domain_a:, domain_b:, similarity:)
+                sim = similarity.clamp(0.0, 1.0).round(10)
+                @similarities[similarity_key(domain_a, domain_b)] = sim
+                sim
+              end
+
+              def learn_domain(domain:, amount:)
+                check_domain_limit!
+                entry = get_or_create_domain(domain)
+                entry.learn!(amount: amount.clamp(0.0, 1.0))
+                entry.to_h
+              end
+
+              def attempt_transfer(from_domain:, to_domain:)
+                source = @domains[from_domain]
+                return { status: :source_not_found, from_domain: from_domain } unless source
+
+                check_domain_limit!
+                target   = get_or_create_domain(to_domain)
+                sim      = similarity_between(from_domain, to_domain)
+                type     = transfer_type(sim)
+                distance = transfer_distance(sim)
+                effect   = apply_transfer_effect!(target, source, type)
+                source.record_transfer!
+                record_history!(from_domain, to_domain, sim, type, distance, effect)
+                build_transfer_result(from_domain, to_domain, sim, type, distance, effect, target)
+              end
+
+              def transfer_effectiveness(from_domain:, to_domain:)
+                sim = similarity_between(from_domain, to_domain)
+                build_effectiveness(from_domain, to_domain, sim, transfer_type(sim),
+                                    @domains[from_domain], @domains[to_domain])
+              end
+
+              def most_transferable(target_domain:, limit: 5)
+                candidates = candidate_rows(target_domain)
+                candidates.select { |r| r[:type] == :positive }
+                          .sort_by { |r| -r[:similarity] }
+                          .first(limit)
+              end
+
+              def interference_risks(target_domain:)
+                candidate_rows(target_domain)
+                  .select { |r| r[:type] == :interference }
+                  .sort_by { |r| -r[:similarity] }
+              end
+
+              def transfer_report
+                {
+                  total_transfers:     @transfer_history.size,
+                  positive_transfers:  @transfer_history.count { |h| h[:type] == :positive },
+                  negative_transfers:  @transfer_history.count { |h| h[:type] == :negative },
+                  neutral_transfers:   @transfer_history.count { |h| h[:type] == :neutral },
+                  interference_events: @transfer_history.count { |h| h[:type] == :interference },
+                  domain_count:        @domains.size,
+                  similarity_pairs:    @similarities.size
+                }
+              end
+
+              def to_h
+                {
+                  domains:          @domains.transform_values(&:to_h),
+                  similarities:     @similarities.dup,
+                  transfer_history: @transfer_history.dup,
+                  report:           transfer_report
+                }
+              end
+
+              private
+
+              def get_or_create_domain(name)
+                @domains[name] ||= DomainKnowledge.new(domain: name)
+              end
+
+              def similarity_key(domain_a, domain_b)
+                [domain_a, domain_b].sort.join(':')
+              end
+
+              def similarity_between(domain_a, domain_b)
+                @similarities[similarity_key(domain_a, domain_b)] || 0.0
+              end
+
+              def transfer_type(similarity)
+                if similarity >= POSITIVE_TRANSFER_THRESHOLD then :positive
+                elsif similarity >= NEGATIVE_TRANSFER_THRESHOLD then :interference
+                elsif similarity > 0.0 then :negative
+                else :neutral
+                end
+              end
+
+              def transfer_distance(similarity)
+                if similarity >= POSITIVE_TRANSFER_THRESHOLD then :near
+                elsif similarity >= NEGATIVE_TRANSFER_THRESHOLD then :moderate
+                else :far
+                end
+              end
+
+              def apply_transfer_effect!(target, source, type)
+                case type
+                when :positive
+                  scaled = (source.proficiency * TRANSFER_BOOST).round(10)
+                  target.apply_boost!(scaled)
+                  scaled
+                when :interference
+                  penalty = (source.proficiency * INTERFERENCE_PENALTY).round(10)
+                  target.apply_penalty!(penalty)
+                  -penalty
+                else
+                  0.0
+                end
+              end
+
+              def record_history!(from_domain, to_domain, sim, type, distance, effect)
+                @transfer_history << {
+                  from_domain: from_domain,
+                  to_domain:   to_domain,
+                  similarity:  sim.round(10),
+                  type:        type,
+                  distance:    distance,
+                  effect:      effect,
+                  at:          Time.now.utc
+                }
+              end
+
+              def check_domain_limit!
+                raise "domain limit of #{MAX_DOMAINS} reached" if @domains.size >= MAX_DOMAINS
+              end
+
+              def candidate_rows(target_domain)
+                @domains.reject { |name, _| name == target_domain }.map do |name, entry|
+                  sim  = similarity_between(name, target_domain)
+                  type = transfer_type(sim)
+                  { domain: name, proficiency: entry.proficiency.round(10), similarity: sim.round(10), type: type }
+                end
+              end
+
+              def build_transfer_result(from_domain, to_domain, sim, type, distance, effect, target)
+                {
+                  status:      :ok,
+                  from_domain: from_domain,
+                  to_domain:   to_domain,
+                  similarity:  sim.round(10),
+                  type:        type,
+                  distance:    distance,
+                  effect:      effect,
+                  proficiency: target.proficiency.round(10)
+                }
+              end
+
+              def build_effectiveness(from_domain, to_domain, sim, type, source, target)
+                {
+                  from_domain:        from_domain,
+                  to_domain:          to_domain,
+                  similarity:         sim.round(10),
+                  type:               type,
+                  type_label:         TRANSFER_LABELS[type],
+                  distance:           transfer_distance(sim),
+                  distance_label:     DISTANCE_LABELS[transfer_distance(sim)],
+                  source_proficiency: source&.proficiency&.round(10) || 0.0,
+                  target_proficiency: target&.proficiency&.round(10) || 0.0
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/transfer/runners/transfer_learning.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Transfer
+          module Runners
+            module TransferLearning
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def learn_domain(domain:, amount:, **)
+                result = transfer_engine.learn_domain(domain: domain, amount: amount)
+                Legion::Logging.info "[transfer_learning] learn: domain=#{domain} amount=#{amount} proficiency=#{result[:proficiency]}"
+                result
+              end
+
+              def attempt_transfer(from_domain:, to_domain:, **)
+                result = transfer_engine.attempt_transfer(from_domain: from_domain, to_domain: to_domain)
+                Legion::Logging.info "[transfer_learning] transfer: from=#{from_domain} to=#{to_domain} type=#{result[:type]} effect=#{result[:effect]}"
+                result
+              end
+
+              def set_similarity(domain_a:, domain_b:, similarity:, **)
+                sim = transfer_engine.set_similarity(domain_a: domain_a, domain_b: domain_b, similarity: similarity)
+                Legion::Logging.debug "[transfer_learning] similarity set: #{domain_a}<->#{domain_b} similarity=#{sim}"
+                { domain_a: domain_a, domain_b: domain_b, similarity: sim }
+              end
+
+              def transfer_effectiveness(from_domain:, to_domain:, **)
+                result = transfer_engine.transfer_effectiveness(from_domain: from_domain, to_domain: to_domain)
+                Legion::Logging.debug "[transfer_learning] effectiveness: from=#{from_domain} to=#{to_domain} type=#{result[:type]}"
+                result
+              end
+
+              def most_transferable(target_domain:, limit: 5, **)
+                candidates = transfer_engine.most_transferable(target_domain: target_domain, limit: limit)
+                Legion::Logging.debug "[transfer_learning] most_transferable: target=#{target_domain} found=#{candidates.size}"
+                { target_domain: target_domain, candidates: candidates, count: candidates.size }
+              end
+
+              def interference_risks(target_domain:, **)
+                risks = transfer_engine.interference_risks(target_domain: target_domain)
+                Legion::Logging.debug "[transfer_learning] interference_risks: target=#{target_domain} risks=#{risks.size}"
+                { target_domain: target_domain, risks: risks, count: risks.size }
+              end
+
+              def transfer_report(**)
+                report = transfer_engine.transfer_report
+                Legion::Logging.debug "[transfer_learning] report: domains=#{report[:domain_count]} transfers=#{report[:total_transfers]}"
+                report
+              end
+
+              def get_domain(domain:, **)
+                entry = transfer_engine.domains[domain]
+                if entry
+                  Legion::Logging.debug "[transfer_learning] get_domain: domain=#{domain} proficiency=#{entry.proficiency}"
+                  { found: true, domain: entry.to_h }
+                else
+                  Legion::Logging.debug "[transfer_learning] get_domain: domain=#{domain} not found"
+                  { found: false, domain: domain }
+                end
+              end
+
+              private
+
+              def transfer_engine
+                @transfer_engine ||= Helpers::TransferEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/transfer/version'
+require 'legion/extensions/agentic/memory/transfer/helpers/constants'
+require 'legion/extensions/agentic/memory/transfer/helpers/domain_knowledge'
+require 'legion/extensions/agentic/memory/transfer/helpers/transfer_engine'
+require 'legion/extensions/agentic/memory/transfer/runners/transfer_learning'
+require 'legion/extensions/agentic/memory/transfer/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Transfer
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'memory/version'
+require_relative 'memory/archaeology'
+require_relative 'memory/paleontology'
+require_relative 'memory/palimpsest'
+require_relative 'memory/compression'
+require_relative 'memory/hologram'
+require_relative 'memory/offloading'
+require_relative 'memory/nostalgia'
+require_relative 'memory/echo'
+require_relative 'memory/echo_chamber'
+require_relative 'memory/immune_memory'
+require_relative 'memory/reserve'
+require_relative 'memory/trace'
+require_relative 'memory/episodic'
+require_relative 'memory/semantic'
+require_relative 'memory/semantic_priming'
+require_relative 'memory/semantic_satiation'
+require_relative 'memory/source_monitoring'
+require_relative 'memory/transfer'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+        def remote_invocable?
+          false
+        end
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/archaeology/client_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology::Client do
+  let(:client) { described_class.new }
+
+  it 'creates with default engine' do
+    expect(client).to respond_to(:create_site)
+  end
+
+  describe '#create_site' do
+    it 'delegates to runner' do
+      result = client.create_site(domain: :cognitive)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#excavate' do
+    it 'delegates to runner' do
+      site_result = client.create_site(domain: :cognitive)
+      result = client.excavate(site_id: site_result[:site][:id])
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#list_artifacts' do
+    it 'returns empty list' do
+      result = client.list_artifacts
+      expect(result[:count]).to eq 0
+    end
+  end
+
+  describe '#archaeology_status' do
+    it 'returns report' do
+      result = client.archaeology_status
+      expect(result[:report]).to be_a Hash
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/archaeology/cognitive_archaeology_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology do
+  it 'has a version number' do
+    expect(described_class::VERSION).to eq '0.1.0'
+  end
+end

data/spec/legion/extensions/agentic/memory/archaeology/helpers/archaeology_engine_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology::Helpers::ArchaeologyEngine do
+  let(:engine) { described_class.new }
+
+  describe '#create_site' do
+    it 'creates a site with the given domain' do
+      site = engine.create_site(domain: :cognitive)
+      expect(site.domain).to eq :cognitive
+    end
+
+    it 'tracks site in all_sites' do
+      engine.create_site(domain: :cognitive)
+      expect(engine.all_sites.size).to eq 1
+    end
+
+    it 'raises on invalid domain' do
+      expect { engine.create_site(domain: :bogus) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#dig' do
+    let(:site) { engine.create_site(domain: :cognitive) }
+
+    it 'returns hash with site survey and dug status' do
+      result = engine.dig(site_id: site.id)
+      expect(result[:dug]).to be true
+      expect(result[:site]).to be_a Hash
+    end
+
+    it 'raises for unknown site_id' do
+      expect { engine.dig(site_id: 'bad') }.to raise_error(ArgumentError, /site not found/)
+    end
+  end
+
+  describe '#excavate' do
+    let(:site) { engine.create_site(domain: :cognitive) }
+
+    it 'returns an Artifact' do
+      expect(engine.excavate(site_id: site.id)).to be_a(
+        Legion::Extensions::Agentic::Memory::Archaeology::Helpers::Artifact
+      )
+    end
+
+    it 'tracks artifact in all_artifacts' do
+      engine.excavate(site_id: site.id)
+      expect(engine.all_artifacts.size).to eq 1
+    end
+  end
+
+  describe '#restore_artifact' do
+    it 'boosts preservation' do
+      site = engine.create_site(domain: :cognitive)
+      a = engine.excavate(site_id: site.id)
+      a.decay!(rate: 0.3)
+      original = a.preservation
+      engine.restore_artifact(artifact_id: a.id, boost: 0.2)
+      expect(a.preservation).to be > original
+    end
+
+    it 'raises for unknown artifact_id' do
+      expect { engine.restore_artifact(artifact_id: 'bad') }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#decay_all!' do
+    it 'reduces preservation on all artifacts' do
+      site = engine.create_site(domain: :cognitive)
+      a = engine.excavate(site_id: site.id)
+      original = a.preservation
+      engine.decay_all!
+      expect(a.preservation).to be < original
+    end
+
+    it 'prunes artifacts that reach 0.0' do
+      site = engine.create_site(domain: :cognitive)
+      a = engine.excavate(site_id: site.id)
+      a.instance_variable_set(:@preservation_quality, 0.01)
+      engine.decay_all!(rate: 0.5)
+      expect(engine.all_artifacts).not_to include(a)
+    end
+
+    it 'returns remaining artifact count' do
+      site = engine.create_site(domain: :cognitive)
+      engine.excavate(site_id: site.id)
+      expect(engine.decay_all!).to be_a Integer
+    end
+  end
+
+  describe '#artifacts_by_type' do
+    it 'filters by artifact_type' do
+      site = engine.create_site(domain: :cognitive)
+      3.times { engine.excavate(site_id: site.id) }
+      first_type = engine.all_artifacts.first.artifact_type
+      results = engine.artifacts_by_type(first_type)
+      expect(results).to all(have_attributes(artifact_type: first_type))
+    end
+  end
+
+  describe '#artifacts_by_domain' do
+    it 'returns matching artifacts' do
+      site = engine.create_site(domain: :cognitive)
+      engine.excavate(site_id: site.id)
+      expect(engine.artifacts_by_domain(:cognitive).size).to eq 1
+    end
+
+    it 'returns empty for non-matching domain' do
+      site = engine.create_site(domain: :cognitive)
+      engine.excavate(site_id: site.id)
+      expect(engine.artifacts_by_domain(:emotional)).to be_empty
+    end
+  end
+
+  describe '#best_preserved' do
+    it 'returns artifacts sorted by preservation descending' do
+      site = engine.create_site(domain: :cognitive)
+      5.times { engine.excavate(site_id: site.id) }
+      best = engine.best_preserved(limit: 3)
+      preservations = best.map(&:preservation)
+      expect(preservations).to eq preservations.sort.reverse
+    end
+  end
+
+  describe '#most_fragile' do
+    it 'returns only fragments' do
+      site = engine.create_site(domain: :cognitive)
+      3.times { engine.excavate(site_id: site.id) }
+      engine.all_artifacts.first.instance_variable_set(:@preservation_quality, 0.1)
+      fragile = engine.most_fragile
+      expect(fragile).to all(be_fragment)
+    end
+  end
+
+  describe '#site_report' do
+    it 'returns site data with artifacts' do
+      site = engine.create_site(domain: :cognitive)
+      engine.excavate(site_id: site.id)
+      report = engine.site_report(site_id: site.id)
+      expect(report).to have_key(:artifacts)
+    end
+  end
+
+  describe '#archaeology_report' do
+    it 'returns comprehensive report' do
+      site = engine.create_site(domain: :cognitive)
+      engine.excavate(site_id: site.id)
+      report = engine.archaeology_report
+      %i[total_artifacts total_sites type_breakdown domain_breakdown
+         depth_breakdown avg_preservation avg_integrity fragment_count
+         ancient_count sites].each do |key|
+        expect(report).to have_key(key)
+      end
+    end
+
+    it 'returns correct counts' do
+      site = engine.create_site(domain: :cognitive)
+      3.times { engine.excavate(site_id: site.id) }
+      expect(engine.archaeology_report[:total_artifacts]).to eq 3
+    end
+
+    it 'works empty' do
+      expect(engine.archaeology_report[:total_artifacts]).to eq 0
+    end
+  end
+end