lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/episodic/helpers/episode_spec.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Episodic::Helpers::Episode do
+  let(:episode) { described_class.new }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(episode.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'starts with empty bindings' do
+      expect(episode.bindings).to be_empty
+    end
+
+    it 'sets created_at' do
+      expect(episode.created_at).to be_a(Time)
+    end
+
+    it 'sets last_accessed' do
+      expect(episode.last_accessed).to be_a(Time)
+    end
+  end
+
+  describe '#add_binding' do
+    it 'adds a binding successfully' do
+      result = episode.add_binding(modality: :verbal, content: 'test', source: :phonological_loop)
+      expect(result[:added]).to be true
+      expect(result[:binding_id]).not_to be_nil
+    end
+
+    it 'stores binding in the bindings hash' do
+      result = episode.add_binding(modality: :verbal, content: 'test', source: :phonological_loop)
+      expect(episode.bindings).to have_key(result[:binding_id])
+    end
+
+    it 'rejects binding when at capacity' do
+      10.times { |i| episode.add_binding(modality: :verbal, content: "item #{i}", source: :test) }
+      result = episode.add_binding(modality: :visual, content: 'overflow', source: :test)
+      expect(result[:added]).to be false
+      expect(result[:reason]).to eq(:capacity_full)
+    end
+
+    it 'accepts all modalities' do
+      %i[verbal visual spatial semantic emotional procedural temporal].each_with_index do |mod, idx|
+        result = episode.add_binding(modality: mod, content: "content #{idx}", source: :test)
+        expect(result[:added]).to be true
+      end
+    end
+  end
+
+  describe '#remove_binding' do
+    it 'removes an existing binding' do
+      result = episode.add_binding(modality: :verbal, content: 'test', source: :test)
+      remove_result = episode.remove_binding(binding_id: result[:binding_id])
+      expect(remove_result[:removed]).to be true
+    end
+
+    it 'returns false for unknown binding' do
+      result = episode.remove_binding(binding_id: 'nonexistent-id')
+      expect(result[:removed]).to be false
+    end
+  end
+
+  describe '#attend' do
+    it 'updates last_accessed' do
+      before = episode.last_accessed
+      sleep(0.01)
+      episode.attend
+      expect(episode.last_accessed).to be >= before
+    end
+
+    it 'boosts all binding strengths' do
+      episode.add_binding(modality: :verbal, content: 'test', source: :test, strength: 0.3)
+      initial_strengths = episode.bindings.values.map(&:strength)
+      episode.attend
+      episode.bindings.values.each_with_index do |b, i|
+        expect(b.strength).to be > initial_strengths[i]
+      end
+    end
+  end
+
+  describe '#rehearse' do
+    it 'updates last_accessed' do
+      before = episode.last_accessed
+      sleep(0.01)
+      episode.rehearse
+      expect(episode.last_accessed).to be >= before
+    end
+
+    it 'boosts bindings by REHEARSAL_BOOST' do
+      episode.add_binding(modality: :verbal, content: 'test', source: :test, strength: 0.3)
+      initial = episode.bindings.values.first.strength
+      episode.rehearse
+      expect(episode.bindings.values.first.strength).to be_within(0.001).of(initial + 0.15)
+    end
+  end
+
+  describe '#modalities_present' do
+    it 'returns empty array for empty episode' do
+      expect(episode.modalities_present).to eq([])
+    end
+
+    it 'returns unique modalities' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test)
+      episode.add_binding(modality: :visual, content: 'b', source: :test)
+      episode.add_binding(modality: :verbal, content: 'c', source: :test)
+      expect(episode.modalities_present).to contain_exactly(:verbal, :visual)
+    end
+  end
+
+  describe '#coherence' do
+    it 'returns 0.0 for empty episode' do
+      expect(episode.coherence).to eq(0.0)
+    end
+
+    it 'returns 0.0 when no bindings are integrated' do
+      episode.add_binding(modality: :verbal, content: 'x', source: :test, strength: 0.1)
+      expect(episode.coherence).to eq(0.0)
+    end
+
+    it 'returns average strength of integrated bindings' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test, strength: 0.6)
+      episode.add_binding(modality: :visual, content: 'b', source: :test, strength: 0.8)
+      expected = (0.6 + 0.8) / 2.0
+      expect(episode.coherence).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#coherence_label' do
+    it 'returns :fragmented for low coherence' do
+      episode.add_binding(modality: :verbal, content: 'x', source: :test, strength: 0.1)
+      expect(episode.coherence_label).to eq(:fragmented)
+    end
+
+    it 'returns coherence label for integrated bindings' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test, strength: 0.7)
+      episode.add_binding(modality: :visual, content: 'b', source: :test, strength: 0.7)
+      expect(episode.coherence_label).to eq(:coherent)
+    end
+  end
+
+  describe '#multimodal?' do
+    it 'returns false for single modality' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test)
+      expect(episode.multimodal?).to be false
+    end
+
+    it 'returns true for 2+ modalities' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test)
+      episode.add_binding(modality: :visual, content: 'b', source: :test)
+      expect(episode.multimodal?).to be true
+    end
+  end
+
+  describe '#expired?' do
+    it 'returns false for fresh episode' do
+      expect(episode.expired?).to be false
+    end
+  end
+
+  describe '#decay_bindings' do
+    it 'decays all binding strengths' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test, strength: 0.5)
+      initial = episode.bindings.values.first.strength
+      episode.decay_bindings
+      expect(episode.bindings.values.first.strength).to be < initial
+    end
+
+    it 'removes faded bindings' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test, strength: 0.04)
+      episode.decay_bindings
+      expect(episode.bindings).to be_empty
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = episode.to_h
+      expect(h.keys).to include(:id, :bindings, :created_at, :last_accessed, :modalities)
+      expect(h.keys).to include(:coherence, :coherence_label, :multimodal, :binding_count)
+    end
+
+    it 'reflects current binding count' do
+      episode.add_binding(modality: :verbal, content: 'a', source: :test)
+      expect(episode.to_h[:binding_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/episodic/helpers/episodic_binding_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Episodic::Helpers::EpisodicBinding do
+  let(:binding) { described_class.new(modality: :verbal, content: 'hello world', source: :phonological_loop) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(binding.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns modality as symbol' do
+      expect(binding.modality).to eq(:verbal)
+    end
+
+    it 'assigns content' do
+      expect(binding.content).to eq('hello world')
+    end
+
+    it 'assigns source as symbol' do
+      expect(binding.source).to eq(:phonological_loop)
+    end
+
+    it 'defaults strength to DEFAULT_BINDING_STRENGTH' do
+      expect(binding.strength).to eq(0.5)
+    end
+
+    it 'accepts custom strength' do
+      b = described_class.new(modality: :visual, content: 'image', source: :visuospatial, strength: 0.8)
+      expect(b.strength).to eq(0.8)
+    end
+
+    it 'clamps strength to 0..1' do
+      b = described_class.new(modality: :visual, content: 'x', source: :perception, strength: 1.5)
+      expect(b.strength).to eq(1.0)
+    end
+
+    it 'raises ArgumentError for invalid modality' do
+      expect do
+        described_class.new(modality: :invalid_mod, content: 'x', source: :test)
+      end.to raise_error(ArgumentError, /invalid modality/)
+    end
+
+    it 'accepts all valid modalities' do
+      %i[verbal visual spatial semantic emotional procedural temporal].each do |mod|
+        expect { described_class.new(modality: mod, content: 'x', source: :test) }.not_to raise_error
+      end
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces strength by BINDING_DECAY' do
+      initial = binding.strength
+      binding.decay
+      expect(binding.strength).to be_within(0.001).of(initial - 0.015)
+    end
+
+    it 'does not go below 0.0' do
+      b = described_class.new(modality: :verbal, content: 'x', source: :test, strength: 0.01)
+      b.decay
+      expect(b.strength).to be >= 0.0
+    end
+  end
+
+  describe '#strengthen' do
+    it 'increases strength by the given amount' do
+      initial = binding.strength
+      binding.strengthen(0.1)
+      expect(binding.strength).to be_within(0.001).of(initial + 0.1)
+    end
+
+    it 'clamps at 1.0' do
+      b = described_class.new(modality: :verbal, content: 'x', source: :test, strength: 0.95)
+      b.strengthen(0.5)
+      expect(b.strength).to eq(1.0)
+    end
+  end
+
+  describe '#integrated?' do
+    it 'returns true when strength >= INTEGRATION_THRESHOLD' do
+      b = described_class.new(modality: :verbal, content: 'x', source: :test, strength: 0.5)
+      expect(b.integrated?).to be true
+    end
+
+    it 'returns false when strength < INTEGRATION_THRESHOLD' do
+      b = described_class.new(modality: :verbal, content: 'x', source: :test, strength: 0.3)
+      expect(b.integrated?).to be false
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns true when strength <= BINDING_STRENGTH_FLOOR' do
+      b = described_class.new(modality: :verbal, content: 'x', source: :test, strength: 0.04)
+      expect(b.faded?).to be true
+    end
+
+    it 'returns false when strength is above floor' do
+      expect(binding.faded?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = binding.to_h
+      expect(h).to include(:id, :modality, :content, :source, :strength)
+    end
+
+    it 'contains correct values' do
+      h = binding.to_h
+      expect(h[:modality]).to eq(:verbal)
+      expect(h[:content]).to eq('hello world')
+      expect(h[:source]).to eq(:phonological_loop)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/episodic/helpers/episodic_store_spec.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Episodic::Helpers::EpisodicStore do
+  let(:store) { described_class.new }
+
+  def add_multimodal_episode(the_store)
+    ep = the_store.create_episode
+    the_store.add_to_episode(episode_id: ep.id, modality: :verbal, content: 'a', source: :test)
+    the_store.add_to_episode(episode_id: ep.id, modality: :visual, content: 'b', source: :test)
+    ep
+  end
+
+  describe '#initialize' do
+    it 'starts with empty episodes' do
+      expect(store.episodes).to be_empty
+    end
+
+    it 'starts with empty history' do
+      expect(store.history).to be_empty
+    end
+  end
+
+  describe '#create_episode' do
+    it 'returns an Episode' do
+      ep = store.create_episode
+      expect(ep).to be_a(Legion::Extensions::Agentic::Memory::Episodic::Helpers::Episode)
+    end
+
+    it 'stores the episode' do
+      ep = store.create_episode
+      expect(store.episodes).to have_key(ep.id)
+    end
+
+    it 'records history' do
+      store.create_episode
+      expect(store.history.last[:event]).to eq(:create)
+    end
+
+    it 'evicts oldest expired episode when at capacity' do
+      stub_const('Legion::Extensions::Agentic::Memory::Episodic::Helpers::Constants::MAX_EPISODES', 2)
+      e1 = store.create_episode
+      e2 = store.create_episode
+      expect(store.count).to eq(2)
+      allow(e1).to receive(:expired?).and_return(true)
+      allow(e2).to receive(:expired?).and_return(false)
+      store.create_episode
+      expect(store.count).to eq(2)
+    end
+  end
+
+  describe '#add_to_episode' do
+    let(:ep) { store.create_episode }
+
+    it 'adds binding to existing episode' do
+      result = store.add_to_episode(
+        episode_id: ep.id, modality: :verbal, content: 'hello', source: :phonological_loop
+      )
+      expect(result[:added]).to be true
+    end
+
+    it 'returns failure for missing episode' do
+      result = store.add_to_episode(
+        episode_id: 'nonexistent', modality: :verbal, content: 'x', source: :test
+      )
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:episode_not_found)
+    end
+  end
+
+  describe '#attend_episode' do
+    it 'returns success for existing episode' do
+      ep = store.create_episode
+      result = store.attend_episode(episode_id: ep.id)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for missing episode' do
+      result = store.attend_episode(episode_id: 'missing')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#rehearse_episode' do
+    it 'returns success for existing episode' do
+      ep = store.create_episode
+      result = store.rehearse_episode(episode_id: ep.id)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for missing episode' do
+      result = store.rehearse_episode(episode_id: 'missing')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#integrate' do
+    let(:ep) { store.create_episode }
+
+    it 'returns integrated: false for low-coherence episode' do
+      store.add_to_episode(episode_id: ep.id, modality: :verbal, content: 'x', source: :test, strength: 0.1)
+      result = store.integrate(episode_id: ep.id)
+      expect(result[:integrated]).to be false
+    end
+
+    it 'returns integrated: true for high-coherence episode' do
+      store.add_to_episode(episode_id: ep.id, modality: :verbal, content: 'a', source: :test, strength: 0.9)
+      store.add_to_episode(episode_id: ep.id, modality: :visual, content: 'b', source: :test, strength: 0.9)
+      result = store.integrate(episode_id: ep.id)
+      expect(result[:integrated]).to be true
+    end
+
+    it 'returns failure for missing episode' do
+      result = store.integrate(episode_id: 'missing')
+      expect(result[:integrated]).to be false
+      expect(result[:reason]).to eq(:episode_not_found)
+    end
+
+    it 'includes coherence label' do
+      store.add_to_episode(episode_id: ep.id, modality: :verbal, content: 'a', source: :test, strength: 0.9)
+      result = store.integrate(episode_id: ep.id)
+      expect(result[:coherence_label]).not_to be_nil
+    end
+  end
+
+  describe '#retrieve_by_modality' do
+    it 'returns episodes containing that modality' do
+      add_multimodal_episode(store)
+      results = store.retrieve_by_modality(modality: :verbal)
+      expect(results.size).to eq(1)
+    end
+
+    it 'returns empty array when no match' do
+      expect(store.retrieve_by_modality(modality: :temporal)).to be_empty
+    end
+  end
+
+  describe '#retrieve_multimodal' do
+    it 'returns episodes with 2+ modalities' do
+      add_multimodal_episode(store)
+      expect(store.retrieve_multimodal.size).to eq(1)
+    end
+
+    it 'excludes single-modality episodes' do
+      ep = store.create_episode
+      store.add_to_episode(episode_id: ep.id, modality: :verbal, content: 'x', source: :test)
+      expect(store.retrieve_multimodal).to be_empty
+    end
+  end
+
+  describe '#most_coherent' do
+    it 'returns episodes sorted by coherence descending' do
+      ep1 = store.create_episode
+      store.add_to_episode(episode_id: ep1.id, modality: :verbal, content: 'a', source: :test, strength: 0.9)
+      ep2 = store.create_episode
+      store.add_to_episode(episode_id: ep2.id, modality: :visual, content: 'b', source: :test, strength: 0.5)
+
+      results = store.most_coherent(limit: 2)
+      expect(results.first.id).to eq(ep1.id)
+    end
+
+    it 'respects limit' do
+      3.times { store.create_episode }
+      expect(store.most_coherent(limit: 2).size).to be <= 2
+    end
+  end
+
+  describe '#tick' do
+    it 'returns a hash with decayed and expired counts' do
+      store.create_episode
+      result = store.tick
+      expect(result).to include(:decayed, :expired)
+    end
+
+    it 'removes episodes with faded bindings that are also expired' do
+      ep = store.create_episode
+      allow(store.episodes[ep.id]).to receive(:expired?).and_return(true)
+      store.tick
+      expect(store.episodes).not_to have_key(ep.id)
+    end
+  end
+
+  describe '#count' do
+    it 'returns current episode count' do
+      store.create_episode
+      store.create_episode
+      expect(store.count).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      h = store.to_h
+      expect(h).to include(:episode_count, :history_size, :multimodal_count, :avg_coherence)
+    end
+
+    it 'reflects current episode count' do
+      store.create_episode
+      expect(store.to_h[:episode_count]).to eq(1)
+    end
+  end
+end