lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/trace/actors/tier_migration_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Stub the framework actor base class since legionio gem is not available in test
+module Legion
+  module Extensions
+    module Actors
+      class Every # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+# Intercept the require in the actor file so it doesn't fail
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require 'legion/extensions/agentic/memory/trace/actors/tier_migration'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Actor::TierMigration do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it 'returns the Consolidation module' do
+      expect(actor.runner_class).to eq(Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidation)
+    end
+  end
+
+  describe '#runner_function' do
+    it 'returns migrate_tier' do
+      expect(actor.runner_function).to eq('migrate_tier')
+    end
+  end
+
+  describe '#time' do
+    it 'returns 300 seconds' do
+      expect(actor.time).to eq(300)
+    end
+  end
+
+  describe '#run_now?' do
+    it 'returns false' do
+      expect(actor.run_now?).to be false
+    end
+  end
+
+  describe '#use_runner?' do
+    it 'returns false' do
+      expect(actor.use_runner?).to be false
+    end
+  end
+
+  describe '#check_subtask?' do
+    it 'returns false' do
+      expect(actor.check_subtask?).to be false
+    end
+  end
+
+  describe '#generate_task?' do
+    it 'returns false' do
+      expect(actor.generate_task?).to be false
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/batch_decay_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/trace/persistent_store'
+require 'legion/extensions/agentic/memory/trace/batch_decay'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::BatchDecay do
+  describe '.apply!' do
+    it 'returns zeros when db unavailable' do
+      allow(described_class).to receive(:db_ready?).and_return(false)
+      result = described_class.apply!
+      expect(result).to eq({ updated: 0, evicted: 0 })
+    end
+  end
+
+  describe 'DEFAULTS' do
+    it 'has sensible rate' do
+      expect(described_class::DEFAULTS[:rate]).to eq(0.999)
+      expect(described_class::DEFAULTS[:min_confidence]).to eq(0.01)
+    end
+
+    it 'specifies interval in hours' do
+      expect(described_class::DEFAULTS[:interval_hours]).to eq(1)
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/trace/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to trace runner methods' do
+    expect(client).to respond_to(:store_trace)
+    expect(client).to respond_to(:get_trace)
+    expect(client).to respond_to(:retrieve_by_type)
+    expect(client).to respond_to(:retrieve_by_domain)
+    expect(client).to respond_to(:retrieve_associated)
+    expect(client).to respond_to(:retrieve_ranked)
+    expect(client).to respond_to(:delete_trace)
+  end
+
+  it 'responds to consolidation runner methods' do
+    expect(client).to respond_to(:reinforce)
+    expect(client).to respond_to(:decay_cycle)
+    expect(client).to respond_to(:migrate_tier)
+    expect(client).to respond_to(:hebbian_link)
+    expect(client).to respond_to(:erase_by_type)
+    expect(client).to respond_to(:erase_by_agent)
+  end
+
+  it 'uses provided store' do
+    store = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+    client = described_class.new(store: store)
+    client.store_trace(type: :semantic, content_payload: { fact: 'test' })
+    expect(store.count).to eq(1)
+  end
+
+  it 'round-trips a full trace lifecycle' do
+    # Store
+    stored = client.store_trace(type: :procedural, content_payload: { action: 'greet' }, domain_tags: ['social'])
+
+    # Retrieve
+    trace = client.get_trace(trace_id: stored[:trace_id])
+    expect(trace[:found]).to be true
+    expect(trace[:trace][:strength]).to eq(0.4)
+
+    # Reinforce
+    client.reinforce(trace_id: stored[:trace_id])
+    trace = client.get_trace(trace_id: stored[:trace_id])
+    expect(trace[:trace][:strength]).to eq(0.5)
+
+    # Reinforce again
+    client.reinforce(trace_id: stored[:trace_id])
+    trace = client.get_trace(trace_id: stored[:trace_id])
+    expect(trace[:trace][:strength]).to eq(0.6)
+
+    # Query by domain
+    by_domain = client.retrieve_by_domain(domain_tag: 'social')
+    expect(by_domain[:count]).to eq(1)
+
+    # Delete
+    client.delete_trace(trace_id: stored[:trace_id])
+    trace = client.get_trace(trace_id: stored[:trace_id])
+    expect(trace[:found]).to be false
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/helpers/decay_spec.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Decay do
+  describe '.compute_decay' do
+    it 'returns peak_strength for zero decay rate (firmware)' do
+      result = described_class.compute_decay(
+        peak_strength: 1.0, base_decay_rate: 0.0, ticks_since_access: 1000
+      )
+      expect(result).to eq(1.0)
+    end
+
+    it 'decays sensory traces fastest' do
+      sensory = described_class.compute_decay(
+        peak_strength: 0.4, base_decay_rate: 0.1, ticks_since_access: 100
+      )
+      semantic = described_class.compute_decay(
+        peak_strength: 0.5, base_decay_rate: 0.01, ticks_since_access: 100
+      )
+      expect(sensory).to be < semantic
+    end
+
+    it 'emotional intensity slows decay' do
+      without_emotion = described_class.compute_decay(
+        peak_strength: 0.6, base_decay_rate: 0.02, ticks_since_access: 50, emotional_intensity: 0.0
+      )
+      with_emotion = described_class.compute_decay(
+        peak_strength: 0.6, base_decay_rate: 0.02, ticks_since_access: 50, emotional_intensity: 0.9
+      )
+      expect(with_emotion).to be > without_emotion
+    end
+
+    it 'returns zero for zero peak strength' do
+      result = described_class.compute_decay(
+        peak_strength: 0.0, base_decay_rate: 0.01, ticks_since_access: 10
+      )
+      expect(result).to eq(0.0)
+    end
+
+    it 'clamps result between 0 and 1' do
+      result = described_class.compute_decay(
+        peak_strength: 1.0, base_decay_rate: 0.001, ticks_since_access: 1
+      )
+      expect(result).to be_between(0.0, 1.0)
+    end
+
+    it 'decays more with more ticks' do
+      early = described_class.compute_decay(
+        peak_strength: 0.5, base_decay_rate: 0.01, ticks_since_access: 10
+      )
+      late = described_class.compute_decay(
+        peak_strength: 0.5, base_decay_rate: 0.01, ticks_since_access: 1000
+      )
+      expect(late).to be < early
+    end
+  end
+
+  describe '.compute_reinforcement' do
+    it 'increases strength by R_AMOUNT' do
+      result = described_class.compute_reinforcement(current_strength: 0.5)
+      expect(result).to eq(0.6)
+    end
+
+    it 'applies imprint multiplier when active' do
+      result = described_class.compute_reinforcement(current_strength: 0.5, imprint_active: true)
+      expect(result).to eq(0.8)
+    end
+
+    it 'clamps at 1.0' do
+      result = described_class.compute_reinforcement(current_strength: 0.95)
+      expect(result).to eq(1.0)
+    end
+
+    it 'clamps imprint reinforcement at 1.0' do
+      result = described_class.compute_reinforcement(current_strength: 0.8, imprint_active: true)
+      expect(result).to eq(1.0)
+    end
+  end
+
+  describe '.compute_retrieval_score' do
+    let(:trace) do
+      Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace.new_trace(
+        type: :semantic, content_payload: { fact: 'test' }, emotional_intensity: 0.5
+      )
+    end
+
+    it 'returns positive score for valid trace' do
+      score = described_class.compute_retrieval_score(trace: trace)
+      expect(score).to be > 0.0
+    end
+
+    it 'returns higher score for associated traces' do
+      normal = described_class.compute_retrieval_score(trace: trace, associated: false)
+      associated = described_class.compute_retrieval_score(trace: trace, associated: true)
+      expect(associated).to be > normal
+    end
+
+    it 'recency reduces score over time' do
+      recent = described_class.compute_retrieval_score(trace: trace, query_time: Time.now.utc)
+      later = described_class.compute_retrieval_score(trace: trace, query_time: Time.now.utc + 7200)
+      expect(later).to be < recent
+    end
+  end
+
+  describe '.compute_storage_tier' do
+    let(:trace) do
+      Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace.new_trace(
+        type: :semantic, content_payload: { fact: 'test' }
+      )
+    end
+
+    it 'returns :hot for recently accessed traces' do
+      tier = described_class.compute_storage_tier(trace: trace)
+      expect(tier).to eq(:hot)
+    end
+
+    it 'returns :warm for traces accessed within 90 days' do
+      trace[:last_reinforced] = Time.now.utc - (30 * 86_400)
+      tier = described_class.compute_storage_tier(trace: trace)
+      expect(tier).to eq(:warm)
+    end
+
+    it 'returns :cold for old traces' do
+      trace[:last_reinforced] = Time.now.utc - (100 * 86_400)
+      tier = described_class.compute_storage_tier(trace: trace)
+      expect(tier).to eq(:cold)
+    end
+
+    it 'returns :erased for traces below prune threshold' do
+      trace[:strength] = 0.005
+      tier = described_class.compute_storage_tier(trace: trace)
+      expect(tier).to eq(:erased)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/helpers/store_spec.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Store do
+  let(:store) { described_class.new }
+  let(:trace_helper) { Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace }
+
+  let(:semantic_trace) { trace_helper.new_trace(type: :semantic, content_payload: { fact: 'ruby is great' }, domain_tags: ['programming']) }
+  let(:episodic_trace) { trace_helper.new_trace(type: :episodic, content_payload: { event: 'meeting' }, domain_tags: ['work']) }
+  let(:firmware_trace) { trace_helper.new_trace(type: :firmware, content_payload: { directive_text: 'protect' }) }
+
+  describe '#store and #get' do
+    it 'stores and retrieves a trace' do
+      store.store(semantic_trace)
+      result = store.get(semantic_trace[:trace_id])
+      expect(result[:trace_type]).to eq(:semantic)
+    end
+
+    it 'returns nil for unknown trace_id' do
+      expect(store.get('nonexistent')).to be_nil
+    end
+  end
+
+  describe '#delete' do
+    it 'removes a trace' do
+      store.store(semantic_trace)
+      store.delete(semantic_trace[:trace_id])
+      expect(store.get(semantic_trace[:trace_id])).to be_nil
+    end
+  end
+
+  describe '#retrieve_by_type' do
+    it 'returns traces of specified type' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      results = store.retrieve_by_type(:semantic)
+      expect(results.size).to eq(1)
+      expect(results.first[:trace_type]).to eq(:semantic)
+    end
+
+    it 'filters by min_strength' do
+      weak_trace = trace_helper.new_trace(type: :semantic, content_payload: {})
+      weak_trace[:strength] = 0.1
+      store.store(weak_trace)
+      store.store(semantic_trace)
+
+      results = store.retrieve_by_type(:semantic, min_strength: 0.4)
+      expect(results.size).to eq(1)
+    end
+
+    it 'respects limit' do
+      3.times { store.store(trace_helper.new_trace(type: :semantic, content_payload: {})) }
+      results = store.retrieve_by_type(:semantic, limit: 2)
+      expect(results.size).to eq(2)
+    end
+  end
+
+  describe '#retrieve_by_domain' do
+    it 'returns traces matching domain tag' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      results = store.retrieve_by_domain('programming')
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#record_coactivation and #retrieve_associated' do
+    it 'links traces after reaching coactivation threshold' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+
+      associated = store.retrieve_associated(semantic_trace[:trace_id])
+      expect(associated.size).to eq(1)
+      expect(associated.first[:trace_id]).to eq(episodic_trace[:trace_id])
+    end
+
+    it 'does not link before threshold' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id])
+
+      associated = store.retrieve_associated(semantic_trace[:trace_id])
+      expect(associated.size).to eq(0)
+    end
+  end
+
+  describe '#all_traces' do
+    it 'returns all stored traces' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+      expect(store.all_traces.size).to eq(2)
+    end
+
+    it 'filters by min_strength' do
+      weak = trace_helper.new_trace(type: :semantic, content_payload: {})
+      weak[:strength] = 0.01
+      store.store(weak)
+      store.store(semantic_trace)
+
+      expect(store.all_traces(min_strength: 0.1).size).to eq(1)
+    end
+  end
+
+  describe '#count' do
+    it 'returns number of stored traces' do
+      expect(store.count).to eq(0)
+      store.store(semantic_trace)
+      expect(store.count).to eq(1)
+    end
+  end
+
+  describe '#firmware_traces' do
+    it 'returns only firmware traces' do
+      store.store(firmware_trace)
+      store.store(semantic_trace)
+
+      results = store.firmware_traces
+      expect(results.size).to eq(1)
+      expect(results.first[:trace_type]).to eq(:firmware)
+    end
+  end
+
+  describe '#walk_associations' do
+    let(:trace_a) { trace_helper.new_trace(type: :semantic, content_payload: { label: 'a' }) }
+    let(:trace_b) { trace_helper.new_trace(type: :semantic, content_payload: { label: 'b' }) }
+    let(:trace_c) { trace_helper.new_trace(type: :semantic, content_payload: { label: 'c' }) }
+    let(:trace_d) { trace_helper.new_trace(type: :semantic, content_payload: { label: 'd' }) }
+
+    before do
+      store.store(trace_a)
+      store.store(trace_b)
+      store.store(trace_c)
+      store.store(trace_d)
+      # Chain: a -> b -> c -> d
+      trace_a[:associated_traces] << trace_b[:trace_id]
+      trace_b[:associated_traces] << trace_a[:trace_id]
+      trace_b[:associated_traces] << trace_c[:trace_id]
+      trace_c[:associated_traces] << trace_b[:trace_id]
+      trace_c[:associated_traces] << trace_d[:trace_id]
+      trace_d[:associated_traces] << trace_c[:trace_id]
+    end
+
+    it 'walks multiple hops from start trace' do
+      results = store.walk_associations(start_id: trace_a[:trace_id])
+      found_ids = results.map { |r| r[:trace_id] }
+      expect(found_ids).to include(trace_b[:trace_id], trace_c[:trace_id], trace_d[:trace_id])
+    end
+
+    it 'respects max_hops limit' do
+      results = store.walk_associations(start_id: trace_a[:trace_id], max_hops: 1)
+      found_ids = results.map { |r| r[:trace_id] }
+      expect(found_ids).to include(trace_b[:trace_id])
+      expect(found_ids).not_to include(trace_c[:trace_id])
+      expect(found_ids).not_to include(trace_d[:trace_id])
+    end
+
+    it 'does not include start trace in results' do
+      results = store.walk_associations(start_id: trace_a[:trace_id])
+      found_ids = results.map { |r| r[:trace_id] }
+      expect(found_ids).not_to include(trace_a[:trace_id])
+    end
+
+    it 'handles cycles without infinite loop' do
+      # Add a back-edge from d to a to create a cycle
+      trace_d[:associated_traces] << trace_a[:trace_id]
+      trace_a[:associated_traces] << trace_d[:trace_id]
+      expect { store.walk_associations(start_id: trace_a[:trace_id]) }.not_to raise_error
+      results = store.walk_associations(start_id: trace_a[:trace_id])
+      found_ids = results.map { |r| r[:trace_id] }
+      expect(found_ids.uniq.size).to eq(found_ids.size)
+    end
+
+    it 'records depth for each discovered trace' do
+      results = store.walk_associations(start_id: trace_a[:trace_id])
+      b_result = results.find { |r| r[:trace_id] == trace_b[:trace_id] }
+      c_result = results.find { |r| r[:trace_id] == trace_c[:trace_id] }
+      d_result = results.find { |r| r[:trace_id] == trace_d[:trace_id] }
+      expect(b_result[:depth]).to eq(1)
+      expect(c_result[:depth]).to eq(2)
+      expect(d_result[:depth]).to eq(3)
+    end
+
+    it 'records the full path to each discovered trace' do
+      results = store.walk_associations(start_id: trace_a[:trace_id])
+      d_result = results.find { |r| r[:trace_id] == trace_d[:trace_id] }
+      expect(d_result[:path].first).to eq(trace_a[:trace_id])
+      expect(d_result[:path].last).to eq(trace_d[:trace_id])
+      expect(d_result[:path].size).to eq(4)
+    end
+
+    it 'filters by min_strength and does not traverse beyond filtered nodes' do
+      trace_b[:strength] = 0.05
+      results = store.walk_associations(start_id: trace_a[:trace_id], min_strength: 0.1)
+      found_ids = results.map { |r| r[:trace_id] }
+      expect(found_ids).not_to include(trace_b[:trace_id])
+      expect(found_ids).not_to include(trace_c[:trace_id])
+      expect(found_ids).not_to include(trace_d[:trace_id])
+    end
+
+    it 'returns empty array for trace with no associations' do
+      lone = trace_helper.new_trace(type: :semantic, content_payload: { label: 'lone' })
+      store.store(lone)
+      results = store.walk_associations(start_id: lone[:trace_id])
+      expect(results).to eq([])
+    end
+
+    it 'returns empty array for unknown start_id' do
+      results = store.walk_associations(start_id: 'nonexistent-id')
+      expect(results).to eq([])
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/helpers/trace_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace do
+  describe '.new_trace' do
+    it 'creates a firmware trace with correct defaults' do
+      trace = described_class.new_trace(type: :firmware, content_payload: { directive_text: 'protect' })
+
+      expect(trace[:trace_type]).to eq(:firmware)
+      expect(trace[:strength]).to eq(1.0)
+      expect(trace[:base_decay_rate]).to eq(0.0)
+      expect(trace[:storage_tier]).to eq(:hot)
+      expect(trace[:trace_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'creates an episodic trace with correct starting strength' do
+      trace = described_class.new_trace(type: :episodic, content_payload: { text: 'hello' })
+
+      expect(trace[:strength]).to eq(0.6)
+      expect(trace[:base_decay_rate]).to eq(0.02)
+    end
+
+    it 'creates a sensory trace with highest decay rate' do
+      trace = described_class.new_trace(type: :sensory, content_payload: { signal: 'ping' })
+
+      expect(trace[:strength]).to eq(0.4)
+      expect(trace[:base_decay_rate]).to eq(0.1)
+    end
+
+    it 'clamps emotional values to valid ranges' do
+      trace = described_class.new_trace(
+        type: :semantic, content_payload: { fact: 'test' },
+        emotional_valence: 2.5, emotional_intensity: -0.5
+      )
+
+      expect(trace[:emotional_valence]).to eq(1.0)
+      expect(trace[:emotional_intensity]).to eq(0.0)
+    end
+
+    it 'rejects invalid trace types' do
+      expect do
+        described_class.new_trace(type: :bogus, content_payload: {})
+      end.to raise_error(ArgumentError, /invalid trace type/)
+    end
+
+    it 'rejects invalid origins' do
+      expect do
+        described_class.new_trace(type: :semantic, content_payload: {}, origin: :unknown)
+      end.to raise_error(ArgumentError, /invalid origin/)
+    end
+
+    it 'sets domain tags as array' do
+      trace = described_class.new_trace(type: :semantic, content_payload: {}, domain_tags: %w[work calendar])
+
+      expect(trace[:domain_tags]).to eq(%w[work calendar])
+    end
+
+    it 'initializes associated_traces as empty array' do
+      trace = described_class.new_trace(type: :semantic, content_payload: {})
+
+      expect(trace[:associated_traces]).to eq([])
+    end
+
+    it 'creates all 7 trace types' do
+      described_class::TRACE_TYPES.each do |type|
+        trace = described_class.new_trace(type: type, content_payload: {})
+        expect(trace[:trace_type]).to eq(type)
+        expect(trace[:strength]).to be_between(0.0, 1.0)
+      end
+    end
+
+    it 'includes unresolved defaulting to false' do
+      trace = described_class.new_trace(type: :episodic, content_payload: { text: 'hello' })
+
+      expect(trace).to have_key(:unresolved)
+      expect(trace[:unresolved]).to be false
+    end
+
+    it 'includes consolidation_candidate defaulting to false' do
+      trace = described_class.new_trace(type: :episodic, content_payload: { text: 'hello' })
+
+      expect(trace).to have_key(:consolidation_candidate)
+      expect(trace[:consolidation_candidate]).to be false
+    end
+
+    it 'allows unresolved to be set to true at creation' do
+      trace = described_class.new_trace(type: :episodic, content_payload: { text: 'hello' }, unresolved: true)
+
+      expect(trace[:unresolved]).to be true
+    end
+
+    it 'allows consolidation_candidate to be set to true at creation' do
+      trace = described_class.new_trace(type: :semantic, content_payload: { fact: 'test' }, consolidation_candidate: true)
+
+      expect(trace[:consolidation_candidate]).to be true
+    end
+  end
+
+  describe '.valid_trace?' do
+    it 'returns true for valid traces' do
+      trace = described_class.new_trace(type: :semantic, content_payload: {})
+      expect(described_class.valid_trace?(trace)).to be true
+    end
+
+    it 'returns false for non-hash' do
+      expect(described_class.valid_trace?('not a trace')).to be false
+    end
+
+    it 'returns false for invalid type' do
+      trace = described_class.new_trace(type: :semantic, content_payload: {})
+      trace[:trace_type] = :invalid
+      expect(described_class.valid_trace?(trace)).to be false
+    end
+
+    it 'returns false for out-of-range strength' do
+      trace = described_class.new_trace(type: :semantic, content_payload: {})
+      trace[:strength] = 1.5
+      expect(described_class.valid_trace?(trace)).to be false
+    end
+  end
+end