lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/semantic_satiation/runners/semantic_satiation_spec.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/semantic_satiation/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticSatiation::Runners::SemanticSatiation do
+  let(:client) { Legion::Extensions::Agentic::Memory::SemanticSatiation::Client.new }
+
+  describe '#expose' do
+    it 'returns a hash with fluency key' do
+      result = client.expose(label: 'banana')
+      expect(result[:fluency]).to be_a(Float)
+    end
+
+    it 'reduces fluency on repeated exposure' do
+      client.expose(label: 'banana')
+      result = client.expose(label: 'banana')
+      expect(result[:fluency]).to be < 1.0
+    end
+
+    it 'uses default domain :general' do
+      result = client.expose(label: 'banana')
+      expect(result[:domain]).to eq(:general)
+    end
+
+    it 'accepts explicit domain' do
+      result = client.expose(label: 'apple', domain: :food)
+      expect(result[:domain]).to eq(:food)
+    end
+
+    it 'includes satiated flag' do
+      result = client.expose(label: 'fresh')
+      expect(result).to have_key(:satiated)
+    end
+  end
+
+  describe '#register' do
+    it 'returns a hash with id key' do
+      result = client.register(label: 'oak')
+      expect(result[:id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'includes label in result' do
+      result = client.register(label: 'maple')
+      expect(result[:label]).to eq('maple')
+    end
+
+    it 'assigns domain' do
+      result = client.register(label: 'pine', domain: :nature)
+      expect(result[:domain]).to eq(:nature)
+    end
+  end
+
+  describe '#expose_by_id' do
+    it 'exposes a registered concept by id' do
+      registered = client.register(label: 'cedar')
+      result = client.expose_by_id(concept_id: registered[:id])
+      expect(result[:fluency]).to be < 1.0
+    end
+
+    it 'returns error for unknown concept_id' do
+      result = client.expose_by_id(concept_id: 'no-such-id')
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#recover' do
+    it 'returns recovered count' do
+      client.expose(label: 'worn')
+      result = client.recover
+      expect(result[:recovered]).to eq(1)
+    end
+
+    it 'accepts custom amount kwarg without error' do
+      client.expose(label: 'test')
+      expect { client.recover(amount: 0.1) }.not_to raise_error
+    end
+  end
+
+  describe '#satiation_status' do
+    it 'returns concept_count' do
+      client.expose(label: 'word1')
+      client.expose(label: 'word2')
+      result = client.satiation_status
+      expect(result[:concept_count]).to eq(2)
+    end
+
+    it 'includes satiated_count' do
+      result = client.satiation_status
+      expect(result).to have_key(:satiated_count)
+    end
+
+    it 'includes novelty_report' do
+      result = client.satiation_status
+      expect(result).to have_key(:novelty_report)
+    end
+  end
+
+  describe '#domain_satiation' do
+    it 'returns avg_fluency for domain' do
+      client.expose(label: 'cat', domain: :animals)
+      result = client.domain_satiation(domain: :animals)
+      expect(result[:avg_fluency]).to be_a(Float)
+    end
+
+    it 'includes domain in result' do
+      result = client.domain_satiation(domain: :animals)
+      expect(result[:domain]).to eq(:animals)
+    end
+
+    it 'returns 0.0 for unknown domain' do
+      result = client.domain_satiation(domain: :unknown)
+      expect(result[:avg_fluency]).to eq(0.0)
+    end
+  end
+
+  describe '#most_exposed' do
+    it 'returns concepts array' do
+      client.expose(label: 'a')
+      result = client.most_exposed
+      expect(result[:concepts]).to be_an(Array)
+    end
+
+    it 'returns count' do
+      client.expose(label: 'b')
+      result = client.most_exposed
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'respects limit parameter' do
+      5.times { |i| client.expose(label: "w#{i}") }
+      result = client.most_exposed(limit: 3)
+      expect(result[:concepts].size).to eq(3)
+    end
+  end
+
+  describe '#freshest_concepts' do
+    it 'returns concepts array' do
+      client.register(label: 'fresh')
+      result = client.freshest_concepts
+      expect(result[:concepts]).to be_an(Array)
+    end
+
+    it 'respects limit parameter' do
+      5.times { |i| client.register(label: "f#{i}") }
+      result = client.freshest_concepts(limit: 2)
+      expect(result[:concepts].size).to eq(2)
+    end
+  end
+
+  describe '#novelty_report' do
+    it 'returns distribution hash' do
+      client.register(label: 'new_concept')
+      result = client.novelty_report
+      expect(result[:distribution]).to be_a(Hash)
+    end
+
+    it 'returns total count' do
+      client.register(label: 'another')
+      result = client.novelty_report
+      expect(result[:total]).to eq(1)
+    end
+  end
+
+  describe '#prune_saturated' do
+    it 'returns removed count' do
+      result = client.prune_saturated
+      expect(result[:removed]).to be_a(Integer)
+    end
+
+    it 'returns 0 when no saturated concepts' do
+      client.register(label: 'healthy')
+      result = client.prune_saturated
+      expect(result[:removed]).to eq(0)
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/source_monitoring/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SourceMonitoring::Client do
+  subject(:client) { described_class.new }
+
+  it 'records and verifies sources' do
+    rec = client.record_source(content_id: 'fact:x', source: :external_perception)
+    result = client.verify_source(record_id: rec[:record][:id])
+    expect(result[:success]).to be true
+    expect(result[:record][:verified]).to be true
+  end
+
+  it 'performs reality checks' do
+    client.record_source(content_id: 'thought:y', source: :internal_generation)
+    result = client.reality_check(content_id: 'thought:y')
+    expect(result[:status]).to eq(:constructed)
+  end
+
+  it 'reports stats' do
+    result = client.source_monitoring_stats
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/agentic/memory/source_monitoring/helpers/source_record_spec.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SourceMonitoring::Helpers::SourceRecord do
+  subject(:rec) do
+    described_class.new(id: :src_one, content_id: 'fact:sky_blue', source: :external_perception)
+  end
+
+  let(:constants) { Legion::Extensions::Agentic::Memory::SourceMonitoring::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets id, content_id, and source' do
+      expect(rec.id).to eq(:src_one)
+      expect(rec.content_id).to eq('fact:sky_blue')
+      expect(rec.source).to eq(:external_perception)
+    end
+
+    it 'uses default confidence' do
+      expect(rec.confidence).to eq(constants::DEFAULT_CONFIDENCE)
+    end
+
+    it 'starts unverified' do
+      expect(rec.verified).to be false
+    end
+  end
+
+  describe '#reality_status' do
+    it 'returns :real for external perception' do
+      expect(rec.reality_status).to eq(:real)
+    end
+
+    it 'returns :constructed for internal generation' do
+      r = described_class.new(id: :x, content_id: :y, source: :internal_generation)
+      expect(r.reality_status).to eq(:constructed)
+    end
+
+    it 'returns :imagined for imagination' do
+      r = described_class.new(id: :x, content_id: :y, source: :imagination)
+      expect(r.reality_status).to eq(:imagined)
+    end
+  end
+
+  describe '#external? and #internal?' do
+    it 'external_perception is external' do
+      expect(rec.external?).to be true
+      expect(rec.internal?).to be false
+    end
+
+    it 'imagination is internal' do
+      r = described_class.new(id: :x, content_id: :y, source: :imagination)
+      expect(r.internal?).to be true
+      expect(r.external?).to be false
+    end
+
+    it 'inference is neither external nor internal' do
+      r = described_class.new(id: :x, content_id: :y, source: :inference)
+      expect(r.external?).to be false
+      expect(r.internal?).to be false
+    end
+  end
+
+  describe '#verify' do
+    it 'marks as verified' do
+      rec.verify
+      expect(rec.verified).to be true
+    end
+
+    it 'boosts confidence' do
+      before = rec.confidence
+      rec.verify
+      expect(rec.confidence).to be > before
+    end
+  end
+
+  describe '#correct' do
+    it 'changes source' do
+      rec.correct(new_source: :memory_retrieval)
+      expect(rec.source).to eq(:memory_retrieval)
+    end
+
+    it 'reduces confidence' do
+      before = rec.confidence
+      rec.correct(new_source: :memory_retrieval)
+      expect(rec.confidence).to be < before
+    end
+
+    it 'increments correction count' do
+      rec.correct(new_source: :memory_retrieval)
+      expect(rec.correction_count).to eq(1)
+    end
+  end
+
+  describe '#confused?' do
+    it 'returns true when source is in confusion pair and low confidence' do
+      rec.confidence = 0.3
+      expect(rec.confused?).to be true
+    end
+
+    it 'returns false with high confidence' do
+      rec.confidence = 0.8
+      expect(rec.confused?).to be false
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces confidence' do
+      before = rec.confidence
+      rec.decay
+      expect(rec.confidence).to be < before
+    end
+
+    it 'respects floor' do
+      100.times { rec.decay }
+      expect(rec.confidence).to be >= constants::CONFIDENCE_FLOOR
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns false initially' do
+      expect(rec.faded?).to be false
+    end
+
+    it 'returns true at floor when unverified' do
+      rec.confidence = constants::CONFIDENCE_FLOOR
+      expect(rec.faded?).to be true
+    end
+
+    it 'returns false at floor when verified' do
+      rec.verify
+      rec.confidence = constants::CONFIDENCE_FLOOR
+      expect(rec.faded?).to be false
+    end
+  end
+
+  describe '#confidence_label' do
+    it 'returns a symbol' do
+      expect(rec.confidence_label).to be_a(Symbol)
+    end
+
+    it 'returns :confident for default confidence' do
+      expect(rec.confidence_label).to eq(:confident)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      h = rec.to_h
+      expect(h).to include(:id, :content_id, :source, :domain, :reality_status,
+                           :confidence, :confidence_label, :verified, :external,
+                           :internal, :confused, :corrections, :recorded_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/source_monitoring/helpers/source_tracker_spec.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SourceMonitoring::Helpers::SourceTracker do
+  subject(:tracker) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Memory::SourceMonitoring::Helpers::Constants }
+
+  describe '#record_source' do
+    it 'creates a source record' do
+      rec = tracker.record_source(content_id: 'fact:one', source: :external_perception)
+      expect(rec).to be_a(Legion::Extensions::Agentic::Memory::SourceMonitoring::Helpers::SourceRecord)
+      expect(tracker.records.size).to eq(1)
+    end
+
+    it 'rejects invalid sources' do
+      expect(tracker.record_source(content_id: 'x', source: :bogus)).to be_nil
+    end
+
+    it 'enforces MAX_RECORDS' do
+      constants::MAX_RECORDS.times do |i|
+        tracker.record_source(content_id: "fact:#{i}", source: :external_perception)
+      end
+      expect(tracker.record_source(content_id: 'overflow', source: :external_perception)).to be_nil
+    end
+  end
+
+  describe '#attribute' do
+    it 'returns records for a content_id sorted by confidence' do
+      tracker.record_source(content_id: 'fact:x', source: :external_perception, confidence: 0.5)
+      tracker.record_source(content_id: 'fact:x', source: :memory_retrieval, confidence: 0.8)
+      results = tracker.attribute(content_id: 'fact:x')
+      expect(results.size).to eq(2)
+      expect(results.first.confidence).to be > results.last.confidence
+    end
+
+    it 'returns empty for unknown content' do
+      expect(tracker.attribute(content_id: 'nope')).to be_empty
+    end
+  end
+
+  describe '#verify_source' do
+    it 'verifies a record' do
+      rec = tracker.record_source(content_id: 'fact:x', source: :external_perception)
+      result = tracker.verify_source(record_id: rec.id)
+      expect(result.verified).to be true
+    end
+
+    it 'returns nil for unknown record' do
+      expect(tracker.verify_source(record_id: :nope)).to be_nil
+    end
+
+    it 'logs attribution' do
+      rec = tracker.record_source(content_id: 'fact:x', source: :external_perception)
+      tracker.verify_source(record_id: rec.id)
+      expect(tracker.attribution_log.size).to eq(1)
+    end
+  end
+
+  describe '#correct_source' do
+    it 'corrects the source' do
+      rec = tracker.record_source(content_id: 'fact:x', source: :external_perception)
+      result = tracker.correct_source(record_id: rec.id, new_source: :memory_retrieval)
+      expect(result.source).to eq(:memory_retrieval)
+    end
+
+    it 'rejects invalid new source' do
+      rec = tracker.record_source(content_id: 'fact:x', source: :external_perception)
+      expect(tracker.correct_source(record_id: rec.id, new_source: :bogus)).to be_nil
+    end
+  end
+
+  describe '#reality_check' do
+    it 'returns status for known content' do
+      tracker.record_source(content_id: 'fact:x', source: :external_perception)
+      result = tracker.reality_check(content_id: 'fact:x')
+      expect(result[:status]).to eq(:real)
+    end
+
+    it 'returns unknown for unknown content' do
+      result = tracker.reality_check(content_id: 'nope')
+      expect(result[:status]).to eq(:unknown)
+    end
+  end
+
+  describe '#confused_records' do
+    it 'returns records with source confusion and low confidence' do
+      rec = tracker.record_source(content_id: 'fact:x', source: :external_perception, confidence: 0.3)
+      confused = tracker.confused_records
+      expect(confused.size).to eq(1)
+      expect(confused.first[:id]).to eq(rec.id)
+    end
+  end
+
+  describe '#records_by_source' do
+    it 'filters by source type' do
+      tracker.record_source(content_id: 'a', source: :external_perception)
+      tracker.record_source(content_id: 'b', source: :imagination)
+      results = tracker.records_by_source(source: :imagination)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#attribution_accuracy' do
+    it 'returns 0 with no verifications' do
+      expect(tracker.attribution_accuracy).to eq(0.0)
+    end
+
+    it 'returns ratio of hits to total' do
+      rec = tracker.record_source(content_id: 'a', source: :external_perception)
+      tracker.verify_source(record_id: rec.id)
+      rec2 = tracker.record_source(content_id: 'b', source: :imagination)
+      tracker.correct_source(record_id: rec2.id, new_source: :memory_retrieval)
+      expect(tracker.attribution_accuracy).to eq(0.5)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays records and removes faded ones' do
+      tracker.record_source(content_id: 'faint', source: :inference, confidence: 0.12)
+      20.times { tracker.decay_all }
+      expect(tracker.records.values.none? { |r| r.content_id == 'faint' }).to be true
+    end
+
+    it 'preserves verified records' do
+      rec = tracker.record_source(content_id: 'solid', source: :external_perception, confidence: 0.12)
+      tracker.verify_source(record_id: rec.id)
+      20.times { tracker.decay_all }
+      expect(tracker.records).to have_key(rec.id)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary hash' do
+      h = tracker.to_h
+      expect(h).to include(:total_records, :verified_count, :confused_count,
+                           :accuracy, :source_distribution, :attribution_log_size)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/source_monitoring/runners/source_monitoring_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/source_monitoring/runners/source_monitoring'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SourceMonitoring::Runners::SourceMonitoring do
+  let(:tracker) { Legion::Extensions::Agentic::Memory::SourceMonitoring::Helpers::SourceTracker.new }
+  let(:host) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@tracker, tracker)
+    obj
+  end
+
+  describe '#record_source' do
+    it 'records successfully' do
+      result = host.record_source(content_id: 'fact:x', source: :external_perception)
+      expect(result[:success]).to be true
+      expect(result[:record][:source]).to eq(:external_perception)
+    end
+
+    it 'fails for invalid source' do
+      result = host.record_source(content_id: 'fact:x', source: :bogus)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#attribute_source' do
+    it 'returns matching records' do
+      host.record_source(content_id: 'fact:x', source: :external_perception)
+      result = host.attribute_source(content_id: 'fact:x')
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#verify_source' do
+    it 'verifies a record' do
+      rec = host.record_source(content_id: 'fact:x', source: :external_perception)
+      result = host.verify_source(record_id: rec[:record][:id])
+      expect(result[:success]).to be true
+      expect(result[:record][:verified]).to be true
+    end
+
+    it 'fails for unknown record' do
+      result = host.verify_source(record_id: :nope)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#correct_source' do
+    it 'corrects a source' do
+      rec = host.record_source(content_id: 'fact:x', source: :external_perception)
+      result = host.correct_source(record_id: rec[:record][:id], new_source: :memory_retrieval)
+      expect(result[:success]).to be true
+      expect(result[:record][:source]).to eq(:memory_retrieval)
+    end
+  end
+
+  describe '#reality_check' do
+    it 'returns reality status' do
+      host.record_source(content_id: 'fact:x', source: :imagination)
+      result = host.reality_check(content_id: 'fact:x')
+      expect(result[:status]).to eq(:imagined)
+    end
+  end
+
+  describe '#confused_sources' do
+    it 'returns confused records' do
+      result = host.confused_sources
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#sources_by_type' do
+    it 'filters by source type' do
+      host.record_source(content_id: 'a', source: :inference)
+      result = host.sources_by_type(source: :inference)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#attribution_accuracy' do
+    it 'returns accuracy' do
+      result = host.attribution_accuracy
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#update_source_monitoring' do
+    it 'decays and returns count' do
+      result = host.update_source_monitoring
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#source_monitoring_stats' do
+    it 'returns stats' do
+      result = host.source_monitoring_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:total_records)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/actors/decay_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/decay'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Actor::Decay 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 decay_cycle' do
+      expect(actor.runner_function).to eq('decay_cycle')
+    end
+  end
+
+  describe '#time' do
+    it 'returns 60 seconds' do
+      expect(actor.time).to eq(60)
+    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