lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/semantic_priming/helpers/semantic_node_spec.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::SemanticNode do
+  subject(:node) { described_class.new(label: 'doctor') }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(node.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets label' do
+      expect(node.label).to eq('doctor')
+    end
+
+    it 'defaults to concept type' do
+      expect(node.node_type).to eq(:concept)
+    end
+
+    it 'starts with zero activation' do
+      expect(node.activation).to eq(0.0)
+    end
+
+    it 'starts with zero prime count' do
+      expect(node.prime_count).to eq(0)
+    end
+
+    it 'clamps high activation' do
+      high = described_class.new(label: 'x', activation: 5.0)
+      expect(high.activation).to eq(1.0)
+    end
+  end
+
+  describe '#prime!' do
+    it 'increases activation' do
+      node.prime!
+      expect(node.activation).to be > 0.0
+    end
+
+    it 'increments prime count' do
+      node.prime!
+      expect(node.prime_count).to eq(1)
+    end
+
+    it 'clamps at max activation' do
+      5.times { node.prime!(amount: 0.5) }
+      expect(node.activation).to eq(1.0)
+    end
+
+    it 'returns self' do
+      expect(node.prime!).to eq(node)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces activation' do
+      node.prime!(amount: 0.5)
+      original = node.activation
+      node.decay!
+      expect(node.activation).to be < original
+    end
+
+    it 'does not go below zero' do
+      node.decay!
+      expect(node.activation).to eq(0.0)
+    end
+  end
+
+  describe '#access!' do
+    it 'increments access count' do
+      node.access!
+      expect(node.access_count).to eq(1)
+    end
+  end
+
+  describe '#reset!' do
+    it 'resets activation to resting level' do
+      node.prime!(amount: 0.8)
+      node.reset!
+      expect(node.activation).to eq(0.0)
+    end
+  end
+
+  describe '#primed?' do
+    it 'is false when unactivated' do
+      expect(node.primed?).to be false
+    end
+
+    it 'is true when highly activated' do
+      node.prime!(amount: 0.5)
+      expect(node.primed?).to be true
+    end
+  end
+
+  describe '#active?' do
+    it 'is false at zero activation' do
+      expect(node.active?).to be false
+    end
+
+    it 'is true above threshold' do
+      node.prime!(amount: 0.3)
+      expect(node.active?).to be true
+    end
+  end
+
+  describe '#activation_label' do
+    it 'returns unprimed for zero activation' do
+      expect(node.activation_label).to eq(:unprimed)
+    end
+
+    it 'returns primed for high activation' do
+      node.prime!(amount: 0.7)
+      expect(node.activation_label).to eq(:primed)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = node.to_h
+      expect(hash).to include(
+        :id, :label, :node_type, :activation, :activation_label,
+        :primed, :active, :prime_count, :access_count, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/semantic_priming/semantic_priming_spec.rb

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/semantic_satiation/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticSatiation::Client do
+  it 'responds to runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:expose)
+    expect(client).to respond_to(:register)
+    expect(client).to respond_to(:expose_by_id)
+    expect(client).to respond_to(:recover)
+    expect(client).to respond_to(:satiation_status)
+    expect(client).to respond_to(:domain_satiation)
+    expect(client).to respond_to(:most_exposed)
+    expect(client).to respond_to(:freshest_concepts)
+    expect(client).to respond_to(:novelty_report)
+    expect(client).to respond_to(:prune_saturated)
+  end
+end

data/spec/legion/extensions/agentic/memory/semantic_satiation/helpers/concept_spec.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticSatiation::Helpers::Concept do
+  subject(:concept) { described_class.new(label: 'banana', domain: :food) }
+
+  describe '#initialize' do
+    it 'generates a uuid id' do
+      expect(concept.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets label' do
+      expect(concept.label).to eq('banana')
+    end
+
+    it 'sets domain' do
+      expect(concept.domain).to eq(:food)
+    end
+
+    it 'starts with full fluency' do
+      expect(concept.fluency).to eq(1.0)
+    end
+
+    it 'starts with zero exposures' do
+      expect(concept.exposure_count).to eq(0)
+    end
+
+    it 'starts with nil last_exposed_at' do
+      expect(concept.last_exposed_at).to be_nil
+    end
+
+    it 'sets created_at' do
+      expect(concept.created_at).to be_a(Time)
+    end
+
+    it 'defaults domain to :general' do
+      c = described_class.new(label: 'test')
+      expect(c.domain).to eq(:general)
+    end
+  end
+
+  describe '#expose!' do
+    it 'increments exposure_count' do
+      concept.expose!
+      expect(concept.exposure_count).to eq(1)
+    end
+
+    it 'reduces fluency by SATIATION_RATE' do
+      expected = (1.0 - Legion::Extensions::Agentic::Memory::SemanticSatiation::Helpers::Constants::SATIATION_RATE).round(10)
+      concept.expose!
+      expect(concept.fluency).to eq(expected)
+    end
+
+    it 'sets last_exposed_at' do
+      concept.expose!
+      expect(concept.last_exposed_at).to be_a(Time)
+    end
+
+    it 'does not reduce fluency below 0.0' do
+      20.times { concept.expose! }
+      expect(concept.fluency).to be >= 0.0
+    end
+
+    it 'accumulates multiple exposures' do
+      3.times { concept.expose! }
+      expect(concept.exposure_count).to eq(3)
+    end
+  end
+
+  describe '#recover!' do
+    it 'increases fluency by RECOVERY_RATE' do
+      concept.expose!
+      fluency_before = concept.fluency
+      concept.recover!
+      expect(concept.fluency).to be > fluency_before
+    end
+
+    it 'does not exceed 1.0' do
+      concept.recover!
+      expect(concept.fluency).to eq(1.0)
+    end
+
+    it 'accepts custom amount' do
+      concept.expose!
+      concept.expose!
+      fluency_before = concept.fluency
+      concept.recover!(amount: 0.5)
+      expect(concept.fluency).to be > fluency_before
+    end
+  end
+
+  describe '#satiated?' do
+    it 'returns false when fluency is full' do
+      expect(concept.satiated?).to be false
+    end
+
+    it 'returns true when fluency is below threshold' do
+      threshold = Legion::Extensions::Agentic::Memory::SemanticSatiation::Helpers::Constants
+      target = 1.0 - threshold::SATIATION_THRESHOLD - 0.05
+      allow(concept).to receive(:fluency).and_return(target)
+      expect(concept.satiated?).to be true
+    end
+  end
+
+  describe '#fluency_label' do
+    it 'returns :fluent for high fluency' do
+      expect(concept.fluency_label).to eq(:fluent)
+    end
+
+    it 'returns :meaningless for near-zero fluency' do
+      15.times { concept.expose! }
+      expect(%i[meaningless satiated reduced]).to include(concept.fluency_label)
+    end
+  end
+
+  describe '#novelty' do
+    it 'returns 1.0 for a fresh concept' do
+      expect(concept.novelty).to eq(1.0)
+    end
+
+    it 'decreases with more exposures' do
+      10.times { concept.expose! }
+      expect(concept.novelty).to be < 1.0
+    end
+
+    it 'does not go below 0.0' do
+      100.times { concept.expose! }
+      expect(concept.novelty).to be >= 0.0
+    end
+  end
+
+  describe '#novelty_label' do
+    it 'returns :novel for a fresh concept' do
+      expect(concept.novelty_label).to eq(:novel)
+    end
+
+    it 'returns a symbol' do
+      expect(concept.novelty_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#time_since_exposure' do
+    it 'returns nil before first exposure' do
+      expect(concept.time_since_exposure).to be_nil
+    end
+
+    it 'returns a numeric value after exposure' do
+      concept.expose!
+      expect(concept.time_since_exposure).to be_a(Float).or be_a(Integer)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = concept.to_h
+      expect(h.keys).to include(:id, :label, :domain, :fluency, :fluency_label,
+                                :novelty, :novelty_label, :exposure_count,
+                                :satiated, :last_exposed_at, :created_at)
+    end
+
+    it 'reflects current state' do
+      concept.expose!
+      h = concept.to_h
+      expect(h[:exposure_count]).to eq(1)
+      expect(h[:fluency]).to be < 1.0
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticSatiation::Helpers::Constants do
+  subject(:constants) { described_class }
+
+  describe 'numeric constants' do
+    it 'defines MAX_CONCEPTS as 300' do
+      expect(constants::MAX_CONCEPTS).to eq(300)
+    end
+
+    it 'defines SATIATION_RATE as 0.08' do
+      expect(constants::SATIATION_RATE).to eq(0.08)
+    end
+
+    it 'defines RECOVERY_RATE as 0.03' do
+      expect(constants::RECOVERY_RATE).to eq(0.03)
+    end
+
+    it 'defines SATIATION_THRESHOLD as 0.7' do
+      expect(constants::SATIATION_THRESHOLD).to eq(0.7)
+    end
+
+    it 'defines DEFAULT_FLUENCY as 1.0' do
+      expect(constants::DEFAULT_FLUENCY).to eq(1.0)
+    end
+  end
+
+  describe 'FLUENCY_LABELS' do
+    it 'maps high fluency to :fluent' do
+      label = constants::FLUENCY_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:fluent)
+    end
+
+    it 'maps mid-high fluency to :normal' do
+      label = constants::FLUENCY_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:normal)
+    end
+
+    it 'maps mid fluency to :reduced' do
+      label = constants::FLUENCY_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:reduced)
+    end
+
+    it 'maps low fluency to :satiated' do
+      label = constants::FLUENCY_LABELS.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:satiated)
+    end
+
+    it 'maps very low fluency to :meaningless' do
+      label = constants::FLUENCY_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:meaningless)
+    end
+  end
+
+  describe 'NOVELTY_LABELS' do
+    it 'maps high novelty to :novel' do
+      label = constants::NOVELTY_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:novel)
+    end
+
+    it 'maps mid-high novelty to :familiar' do
+      label = constants::NOVELTY_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:familiar)
+    end
+
+    it 'maps mid novelty to :routine' do
+      label = constants::NOVELTY_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:routine)
+    end
+
+    it 'maps low novelty to :overexposed' do
+      label = constants::NOVELTY_LABELS.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:overexposed)
+    end
+
+    it 'maps very low novelty to :saturated' do
+      label = constants::NOVELTY_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:saturated)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/semantic_satiation/helpers/satiation_engine_spec.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticSatiation::Helpers::SatiationEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#register_concept' do
+    it 'registers a new concept and returns it' do
+      concept = engine.register_concept(label: 'apple')
+      expect(concept).to be_a(Legion::Extensions::Agentic::Memory::SemanticSatiation::Helpers::Concept)
+      expect(concept.label).to eq('apple')
+    end
+
+    it 'returns existing concept if label already registered' do
+      c1 = engine.register_concept(label: 'apple')
+      c2 = engine.register_concept(label: 'apple')
+      expect(c1.id).to eq(c2.id)
+    end
+
+    it 'assigns the given domain' do
+      concept = engine.register_concept(label: 'oak', domain: :nature)
+      expect(concept.domain).to eq(:nature)
+    end
+
+    it 'defaults domain to :general' do
+      concept = engine.register_concept(label: 'test')
+      expect(concept.domain).to eq(:general)
+    end
+
+    it 'stores concept in @concepts' do
+      concept = engine.register_concept(label: 'pear')
+      expect(engine.concepts[concept.id]).to eq(concept)
+    end
+  end
+
+  describe '#expose_concept' do
+    it 'reduces fluency for a registered concept' do
+      concept = engine.register_concept(label: 'word')
+      engine.expose_concept(concept_id: concept.id)
+      expect(concept.fluency).to be < 1.0
+    end
+
+    it 'returns error hash for unknown concept_id' do
+      result = engine.expose_concept(concept_id: 'nonexistent')
+      expect(result[:error]).to eq(:not_found)
+    end
+
+    it 'returns concept hash on success' do
+      concept = engine.register_concept(label: 'tree')
+      result = engine.expose_concept(concept_id: concept.id)
+      expect(result[:fluency]).to be_a(Float)
+    end
+  end
+
+  describe '#expose_by_label' do
+    it 'creates and exposes a concept by label' do
+      result = engine.expose_by_label(label: 'cloud')
+      expect(result[:fluency]).to be < 1.0
+    end
+
+    it 'reuses existing concept on second exposure' do
+      engine.expose_by_label(label: 'cloud')
+      engine.expose_by_label(label: 'cloud')
+      concepts_with_label = engine.concepts.values.select { |c| c.label == 'cloud' }
+      expect(concepts_with_label.size).to eq(1)
+    end
+
+    it 'increments exposure_count each call' do
+      2.times { engine.expose_by_label(label: 'rain') }
+      concept = engine.concepts.values.find { |c| c.label == 'rain' }
+      expect(concept.exposure_count).to eq(2)
+    end
+  end
+
+  describe '#recover_all' do
+    it 'recovers all concepts' do
+      engine.expose_by_label(label: 'a')
+      engine.expose_by_label(label: 'b')
+      result = engine.recover_all
+      expect(result[:recovered]).to eq(2)
+    end
+
+    it 'increases fluency of exposed concepts' do
+      engine.expose_by_label(label: 'test')
+      concept = engine.concepts.values.first
+      fluency_before = concept.fluency
+      engine.recover_all
+      expect(concept.fluency).to be > fluency_before
+    end
+  end
+
+  describe '#satiated_concepts' do
+    it 'returns empty array when no concepts are satiated' do
+      engine.register_concept(label: 'fresh')
+      expect(engine.satiated_concepts).to be_empty
+    end
+
+    it 'returns satiated concepts' do
+      engine.register_concept(label: 'worn')
+      concept = engine.concepts.values.first
+      15.times { concept.expose! }
+      expect(engine.satiated_concepts).to include(concept)
+    end
+  end
+
+  describe '#most_exposed' do
+    it 'returns concepts sorted by exposure_count descending' do
+      engine.expose_by_label(label: 'a')
+      3.times { engine.expose_by_label(label: 'b') }
+      2.times { engine.expose_by_label(label: 'c') }
+      result = engine.most_exposed(limit: 3)
+      expect(result.first.label).to eq('b')
+    end
+
+    it 'respects limit parameter' do
+      5.times { |i| engine.expose_by_label(label: "word#{i}") }
+      expect(engine.most_exposed(limit: 3).size).to eq(3)
+    end
+  end
+
+  describe '#freshest' do
+    it 'returns concepts sorted by fluency descending' do
+      engine.register_concept(label: 'fresh')
+      worn = engine.register_concept(label: 'worn')
+      5.times { worn.expose! }
+      result = engine.freshest(limit: 2)
+      expect(result.first.label).to eq('fresh')
+    end
+
+    it 'respects limit parameter' do
+      5.times { |i| engine.register_concept(label: "c#{i}") }
+      expect(engine.freshest(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#domain_satiation' do
+    it 'returns average fluency for domain' do
+      engine.expose_by_label(label: 'sun', domain: :nature)
+      engine.expose_by_label(label: 'moon', domain: :nature)
+      result = engine.domain_satiation(domain: :nature)
+      expect(result).to be < 1.0
+      expect(result).to be > 0.0
+    end
+
+    it 'returns 0.0 for unknown domain' do
+      expect(engine.domain_satiation(domain: :unknown)).to eq(0.0)
+    end
+  end
+
+  describe '#novelty_report' do
+    it 'returns a hash distribution' do
+      engine.register_concept(label: 'new')
+      report = engine.novelty_report
+      expect(report).to be_a(Hash)
+    end
+
+    it 'counts concepts per novelty label' do
+      engine.register_concept(label: 'fresh')
+      report = engine.novelty_report
+      expect(report[:novel]).to eq(1)
+    end
+  end
+
+  describe '#prune_saturated' do
+    it 'removes concepts with fluency <= 0.05' do
+      concept = engine.register_concept(label: 'stale')
+      allow(concept).to receive(:fluency).and_return(0.03)
+      removed = engine.prune_saturated
+      expect(removed).to eq(1)
+    end
+
+    it 'does not remove healthy concepts' do
+      engine.register_concept(label: 'healthy')
+      engine.prune_saturated
+      expect(engine.concepts.size).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      h = engine.to_h
+      expect(h.keys).to include(:concept_count, :satiated_count, :novelty_report, :most_exposed, :freshest)
+    end
+
+    it 'reflects current state' do
+      engine.register_concept(label: 'test')
+      expect(engine.to_h[:concept_count]).to eq(1)
+    end
+  end
+end