lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/nostalgia/helpers/nostalgia_engine_spec.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgiaEngine do
+  subject(:engine) { described_class.new }
+
+  let(:memory_attrs) do
+    { content: 'childhood home', domain: :place, original_valence: 0.4 }
+  end
+
+  describe '#create_memory' do
+    it 'creates and stores a NostalgicMemory' do
+      memory = engine.create_memory(**memory_attrs)
+      expect(memory).to be_a(Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgicMemory)
+      expect(engine.memories.size).to eq(1)
+    end
+
+    it 'returns memory with correct content' do
+      memory = engine.create_memory(**memory_attrs)
+      expect(memory.content).to eq('childhood home')
+    end
+
+    it 'enforces MAX_MEMORIES cap' do
+      (Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::Constants::MAX_MEMORIES + 5).times do |i|
+        engine.create_memory(content: "memory #{i}")
+      end
+      expect(engine.memories.size).to eq(Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::Constants::MAX_MEMORIES)
+    end
+  end
+
+  describe '#trigger_nostalgia' do
+    before do
+      engine.create_memory(content: 'old friend from school', domain: :relationship,
+                           warmth: 0.7, original_valence: 0.5)
+      engine.create_memory(content: 'school lunchroom', domain: :place,
+                           warmth: 0.6, original_valence: 0.4)
+    end
+
+    context 'when memories match the trigger' do
+      it 'returns events for matching memories' do
+        events = engine.trigger_nostalgia(trigger: 'school')
+        expect(events).to all(be_a(Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgiaEvent))
+      end
+
+      it 'stores events internally' do
+        engine.trigger_nostalgia(trigger: 'school')
+        expect(engine.events).not_to be_empty
+      end
+    end
+
+    context 'when domain is specified' do
+      it 'filters candidates by domain' do
+        events = engine.trigger_nostalgia(trigger: 'school', domain: :place)
+        event_memory_ids = events.map(&:memory_id)
+        place_memory = engine.memories.find { |m| m.domain == :place }
+        expect(event_memory_ids).to include(place_memory.id) if place_memory && events.any?
+      end
+    end
+
+    context 'when no memories exist' do
+      it 'returns empty array' do
+        events = described_class.new.trigger_nostalgia(trigger: 'anything')
+        expect(events).to eq([])
+      end
+    end
+  end
+
+  describe '#age_all!' do
+    it 'increments temporal_distance on all memories' do
+      engine.create_memory(content: 'memory 1')
+      engine.create_memory(content: 'memory 2')
+      engine.age_all!
+      engine.memories.each do |m|
+        expect(m.temporal_distance).to eq(1)
+      end
+    end
+  end
+
+  describe '#warmth_by_domain' do
+    before do
+      engine.create_memory(content: 'beach vacation', domain: :place, warmth: 0.7)
+      engine.create_memory(content: 'mountain hike', domain: :place, warmth: 0.5)
+      engine.create_memory(content: 'first job', domain: :achievement, warmth: 0.8)
+    end
+
+    it 'returns average warmth per domain' do
+      result = engine.warmth_by_domain
+      expect(result[:place]).to be_within(0.01).of(0.6)
+      expect(result[:achievement]).to be_within(0.01).of(0.8)
+    end
+
+    it 'returns a hash' do
+      expect(engine.warmth_by_domain).to be_a(Hash)
+    end
+  end
+
+  describe '#rosy_retrospection_index' do
+    context 'with no memories' do
+      it 'returns 0.0' do
+        expect(engine.rosy_retrospection_index).to eq(0.0)
+      end
+    end
+
+    context 'with rosy memories' do
+      before do
+        engine.create_memory(content: 'good times', warmth: 0.9, original_valence: 0.3)
+        engine.create_memory(content: 'average times', warmth: 0.4, original_valence: 0.4)
+      end
+
+      it 'returns a value in [0, 1]' do
+        expect(engine.rosy_retrospection_index).to be_between(0.0, 1.0)
+      end
+    end
+  end
+
+  describe '#nostalgia_proneness' do
+    context 'with no memories' do
+      it 'returns 0.0' do
+        expect(engine.nostalgia_proneness).to eq(0.0)
+      end
+    end
+
+    context 'with highly warm memories' do
+      before do
+        5.times { |i| engine.create_memory(content: "memory #{i}", warmth: 0.8) }
+      end
+
+      it 'returns a higher proneness' do
+        expect(engine.nostalgia_proneness).to be > 0.3
+      end
+    end
+  end
+
+  describe '#most_nostalgic_domains' do
+    before do
+      engine.create_memory(content: 'beach', domain: :place, warmth: 0.9)
+      engine.create_memory(content: 'win', domain: :achievement, warmth: 0.5)
+    end
+
+    it 'returns domains sorted by avg warmth descending' do
+      result = engine.most_nostalgic_domains
+      expect(result.first[:domain]).to eq(:place)
+      expect(result.map { |d| d[:domain] }).to include(:place, :achievement)
+    end
+
+    it 'includes avg_warmth key' do
+      result = engine.most_nostalgic_domains
+      expect(result.first).to have_key(:avg_warmth)
+    end
+  end
+
+  describe '#bittersweet_memories' do
+    before do
+      engine.create_memory(content: 'painful but warm', warmth: 0.7, original_valence: 0.2)
+      engine.create_memory(content: 'purely pleasant', warmth: 0.8, original_valence: 0.8)
+    end
+
+    it 'returns only bittersweet memories' do
+      result = engine.bittersweet_memories
+      expect(result).not_to be_empty
+      result.each do |m|
+        expect(m[:bittersweet]).to be true
+      end
+    end
+  end
+
+  describe '#nostalgia_report' do
+    before do
+      engine.create_memory(content: 'memory a', domain: :place, warmth: 0.7, original_valence: 0.3)
+      engine.create_memory(content: 'memory b', domain: :achievement, warmth: 0.5, original_valence: 0.6)
+    end
+
+    it 'includes all expected keys' do
+      report = engine.nostalgia_report
+      expect(report).to include(
+        :total_memories,
+        :total_events,
+        :rosy_retrospection_index,
+        :retrospection_label,
+        :nostalgia_proneness,
+        :nostalgia_label,
+        :most_nostalgic_domains,
+        :bittersweet_count,
+        :rosy_count
+      )
+    end
+
+    it 'has correct total_memories' do
+      expect(engine.nostalgia_report[:total_memories]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/nostalgia/helpers/nostalgia_event_spec.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgiaEvent do
+  subject(:event) do
+    described_class.new(
+      memory_id:      'abc-123',
+      trigger:        'old song',
+      intensity:      0.7,
+      effect_on_mood: 0.4
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores memory_id' do
+      expect(event.memory_id).to eq('abc-123')
+    end
+
+    it 'stores trigger' do
+      expect(event.trigger).to eq('old song')
+    end
+
+    it 'clamps intensity to [0, 1]' do
+      e = described_class.new(memory_id: 'x', trigger: 't', intensity: 1.8)
+      expect(e.intensity).to eq(1.0)
+    end
+
+    it 'clamps effect_on_mood to [-1, 1]' do
+      e = described_class.new(memory_id: 'x', trigger: 't', intensity: 0.5, effect_on_mood: 2.0)
+      expect(e.effect_on_mood).to eq(1.0)
+    end
+
+    it 'defaults effect_on_mood to 0.0' do
+      e = described_class.new(memory_id: 'x', trigger: 't', intensity: 0.5)
+      expect(e.effect_on_mood).to eq(0.0)
+    end
+  end
+
+  describe '#nostalgia_label' do
+    it 'returns a symbol' do
+      expect(event.nostalgia_label).to be_a(Symbol)
+    end
+
+    it 'returns :vivid for intensity 0.7' do
+      expect(event.nostalgia_label).to eq(:vivid)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      h = event.to_h
+      expect(h).to include(:id, :memory_id, :trigger, :intensity, :nostalgia_label,
+                           :effect_on_mood, :occurred_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/nostalgia/helpers/nostalgic_memory_spec.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgicMemory do
+  subject(:memory) { described_class.new(content: 'summer camp', domain: :place, original_valence: 0.6) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(memory.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(memory.content).to eq('summer camp')
+    end
+
+    it 'normalizes domain' do
+      expect(memory.domain).to eq(:place)
+    end
+
+    it 'defaults temporal_distance to 0' do
+      expect(memory.temporal_distance).to eq(0)
+    end
+
+    it 'clamps unknown domain to :unknown' do
+      m = described_class.new(content: 'test', domain: :bogus)
+      expect(m.domain).to eq(:unknown)
+    end
+
+    it 'clamps warmth to WARMTH_CEILING' do
+      m = described_class.new(content: 'test', warmth: 1.5)
+      expect(m.warmth).to be <= Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::Constants::WARMTH_CEILING
+    end
+  end
+
+  describe '#age!' do
+    it 'increments temporal_distance' do
+      memory.age!
+      expect(memory.temporal_distance).to eq(1)
+    end
+
+    it 'increases warmth' do
+      original = memory.warmth
+      memory.age!
+      expect(memory.warmth).to be > original
+    end
+
+    it 'returns self for chaining' do
+      expect(memory.age!).to eq(memory)
+    end
+
+    it 'does not exceed WARMTH_CEILING after many ages' do
+      100.times { memory.age! }
+      expect(memory.warmth).to be <= Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::Constants::WARMTH_CEILING
+    end
+  end
+
+  describe '#warm!' do
+    it 'increases warmth' do
+      original = memory.warmth
+      memory.warm!(0.1)
+      expect(memory.warmth).to be > original
+    end
+
+    it 'returns self for chaining' do
+      expect(memory.warm!).to eq(memory)
+    end
+
+    it 'does not exceed WARMTH_CEILING' do
+      50.times { memory.warm!(0.5) }
+      expect(memory.warmth).to be <= Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::Constants::WARMTH_CEILING
+    end
+  end
+
+  describe '#cool!' do
+    it 'decreases warmth' do
+      memory.warm!(0.3)
+      before = memory.warmth
+      memory.cool!(0.1)
+      expect(memory.warmth).to be < before
+    end
+
+    it 'does not go below 0' do
+      m = described_class.new(content: 'test', warmth: 0.0)
+      m.cool!(1.0)
+      expect(m.warmth).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(memory.cool!).to eq(memory)
+    end
+  end
+
+  describe '#rosy?' do
+    it 'returns false when warmth equals original_valence' do
+      m = described_class.new(content: 'test', warmth: 0.5, original_valence: 0.5)
+      expect(m.rosy?).to be false
+    end
+
+    it 'returns true when warmth exceeds original_valence' do
+      m = described_class.new(content: 'test', warmth: 0.8, original_valence: 0.3)
+      expect(m.rosy?).to be true
+    end
+  end
+
+  describe '#bittersweet?' do
+    it 'returns true for high warmth but low original valence' do
+      m = described_class.new(content: 'test', warmth: 0.7, original_valence: 0.2)
+      expect(m.bittersweet?).to be true
+    end
+
+    it 'returns false for high warmth and high original valence' do
+      m = described_class.new(content: 'test', warmth: 0.8, original_valence: 0.8)
+      expect(m.bittersweet?).to be false
+    end
+
+    it 'returns false for low warmth' do
+      m = described_class.new(content: 'test', warmth: 0.2, original_valence: 0.1)
+      expect(m.bittersweet?).to be false
+    end
+  end
+
+  describe '#warmth_label' do
+    it 'returns a symbol' do
+      expect(memory.warmth_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all key fields' do
+      h = memory.to_h
+      expect(h).to include(:id, :content, :domain, :warmth, :warmth_label, :temporal_distance,
+                           :original_valence, :current_valence, :rosy, :bittersweet, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/nostalgia/runners/analysis_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Nostalgia::Runners::Analysis do
+  let(:engine) { Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgiaEngine.new }
+
+  let(:client) do
+    Class.new do
+      include Legion::Extensions::Agentic::Memory::Nostalgia::Runners::Analysis
+    end.new
+  end
+
+  before do
+    engine.create_memory(content: 'great vacation', domain: :place, warmth: 0.8, original_valence: 0.4)
+    engine.create_memory(content: 'promotion day', domain: :achievement, warmth: 0.6, original_valence: 0.7)
+    engine.create_memory(content: 'tough breakup', domain: :relationship, warmth: 0.7, original_valence: 0.2)
+  end
+
+  describe '#warmth_by_domain' do
+    it 'returns success: true' do
+      result = client.warmth_by_domain(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns warmth_by_domain hash' do
+      result = client.warmth_by_domain(engine: engine)
+      expect(result[:warmth_by_domain]).to be_a(Hash)
+      expect(result[:warmth_by_domain]).to have_key(:place)
+    end
+  end
+
+  describe '#rosy_retrospection_index' do
+    it 'returns success: true' do
+      result = client.rosy_retrospection_index(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns index in [0, 1]' do
+      result = client.rosy_retrospection_index(engine: engine)
+      expect(result[:index]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns a retrospection label' do
+      result = client.rosy_retrospection_index(engine: engine)
+      expect(result[:label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#nostalgia_proneness' do
+    it 'returns success: true' do
+      result = client.nostalgia_proneness(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns proneness in [0, 1]' do
+      result = client.nostalgia_proneness(engine: engine)
+      expect(result[:proneness]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns a nostalgia label' do
+      result = client.nostalgia_proneness(engine: engine)
+      expect(result[:label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#most_nostalgic_domains' do
+    it 'returns success: true' do
+      result = client.most_nostalgic_domains(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns sorted domains' do
+      result = client.most_nostalgic_domains(engine: engine)
+      domains = result[:domains]
+      expect(domains).to be_an(Array)
+      expect(domains.first[:avg_warmth]).to be >= domains.last[:avg_warmth]
+    end
+  end
+
+  describe '#bittersweet_memories' do
+    it 'returns success: true' do
+      result = client.bittersweet_memories(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns only bittersweet memories' do
+      result = client.bittersweet_memories(engine: engine)
+      expect(result[:memories]).to be_an(Array)
+      expect(result[:count]).to eq(result[:memories].size)
+    end
+
+    it 'identifies the tough breakup as bittersweet' do
+      result = client.bittersweet_memories(engine: engine)
+      contents = result[:memories].map { |m| m[:content] }
+      expect(contents).to include('tough breakup')
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/nostalgia/runners/recall_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Nostalgia::Runners::Recall do
+  let(:engine) { Legion::Extensions::Agentic::Memory::Nostalgia::Helpers::NostalgiaEngine.new }
+
+  let(:client) do
+    Class.new do
+      include Legion::Extensions::Agentic::Memory::Nostalgia::Runners::Recall
+    end.new
+  end
+
+  describe '#store_memory' do
+    it 'returns success: true' do
+      result = client.store_memory(content: 'old school', engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes memory hash' do
+      result = client.store_memory(content: 'old school', engine: engine)
+      expect(result[:memory]).to include(:id, :content, :domain, :warmth)
+    end
+
+    it 'stores memory in engine' do
+      client.store_memory(content: 'test memory', domain: :place, engine: engine)
+      expect(engine.memories.size).to eq(1)
+    end
+  end
+
+  describe '#trigger_nostalgia' do
+    before do
+      engine.create_memory(content: 'summer in the park', domain: :place, original_valence: 0.5)
+    end
+
+    it 'returns success: true' do
+      result = client.trigger_nostalgia(trigger: 'summer', engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes events array' do
+      result = client.trigger_nostalgia(trigger: 'summer', engine: engine)
+      expect(result[:events]).to be_an(Array)
+    end
+
+    it 'includes count' do
+      result = client.trigger_nostalgia(trigger: 'summer', engine: engine)
+      expect(result[:count]).to eq(result[:events].size)
+    end
+  end
+
+  describe '#age_memories' do
+    before do
+      engine.create_memory(content: 'memory')
+    end
+
+    it 'returns success: true' do
+      result = client.age_memories(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes memory_count' do
+      result = client.age_memories(engine: engine)
+      expect(result[:memory_count]).to eq(1)
+    end
+  end
+
+  describe '#nostalgia_report' do
+    before do
+      engine.create_memory(content: 'report memory', warmth: 0.6, original_valence: 0.3)
+    end
+
+    it 'returns success: true' do
+      result = client.nostalgia_report(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes report fields' do
+      result = client.nostalgia_report(engine: engine)
+      expect(result).to include(:total_memories, :rosy_retrospection_index, :nostalgia_proneness)
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/offloading/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Offloading::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:register_store)
+    expect(client).to respond_to(:offload_item)
+    expect(client).to respond_to(:retrieve_item)
+    expect(client).to respond_to(:report_retrieval_failure)
+    expect(client).to respond_to(:items_in_store)
+    expect(client).to respond_to(:items_by_type)
+    expect(client).to respond_to(:most_important_offloaded)
+    expect(client).to respond_to(:offloading_status)
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::Agentic::Memory::Offloading::Helpers::OffloadingEngine.new
+    c = described_class.new(engine: engine)
+    result = c.register_store(name: 'test', store_type: :file)
+    expect(result[:success]).to be true
+  end
+
+  it 'creates its own engine when none injected' do
+    result = client.register_store(name: 'auto', store_type: :notes)
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/agentic/memory/offloading/helpers/constants_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Offloading::Helpers::Constants do
+  subject(:constants) { described_class }
+
+  it 'defines MAX_ITEMS as 500' do
+    expect(constants::MAX_ITEMS).to eq(500)
+  end
+
+  it 'defines MAX_STORES as 50' do
+    expect(constants::MAX_STORES).to eq(50)
+  end
+
+  it 'defines DEFAULT_STORE_TRUST as 0.7' do
+    expect(constants::DEFAULT_STORE_TRUST).to eq(0.7)
+  end
+
+  it 'defines TRUST_DECAY as 0.02' do
+    expect(constants::TRUST_DECAY).to eq(0.02)
+  end
+
+  it 'defines TRUST_BOOST as 0.05' do
+    expect(constants::TRUST_BOOST).to eq(0.05)
+  end
+
+  it 'defines RETRIEVAL_SUCCESS_THRESHOLD as 0.7' do
+    expect(constants::RETRIEVAL_SUCCESS_THRESHOLD).to eq(0.7)
+  end
+
+  it 'defines ITEM_TYPES as frozen array of symbols' do
+    expect(constants::ITEM_TYPES).to include(:fact, :procedure, :plan, :context, :delegation,
+                                             :reminder, :calculation, :reference)
+    expect(constants::ITEM_TYPES).to be_frozen
+  end
+
+  it 'defines STORE_TYPES as frozen array of symbols' do
+    expect(constants::STORE_TYPES).to include(:database, :file, :agent, :tool, :memory_aid,
+                                              :external_service, :notes)
+    expect(constants::STORE_TYPES).to be_frozen
+  end
+
+  it 'maps high trust to :highly_trusted' do
+    label = constants::TRUST_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:highly_trusted)
+  end
+
+  it 'maps moderate trust to :trusted' do
+    label = constants::TRUST_LABELS.find { |range, _| range.cover?(0.7) }&.last
+    expect(label).to eq(:trusted)
+  end
+
+  it 'maps low trust to :unreliable' do
+    label = constants::TRUST_LABELS.find { |range, _| range.cover?(0.1) }&.last
+    expect(label).to eq(:unreliable)
+  end
+
+  it 'maps high importance to :critical' do
+    label = constants::IMPORTANCE_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:critical)
+  end
+
+  it 'maps high offloading ratio to :heavily_offloaded' do
+    label = constants::OFFLOAD_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:heavily_offloaded)
+  end
+
+  it 'maps low offloading ratio to :self_reliant' do
+    label = constants::OFFLOAD_LABELS.find { |range, _| range.cover?(0.1) }&.last
+    expect(label).to eq(:self_reliant)
+  end
+end