lex-agentic-memory 0.1.0

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Semantic::Helpers::Concept do
+  subject(:concept) { described_class.new(name: :dog, domain: :animals) }
+
+  describe '#initialize' do
+    it 'assigns fields' do
+      expect(concept.name).to eq(:dog)
+      expect(concept.domain).to eq(:animals)
+      expect(concept.access_count).to eq(0)
+    end
+
+    it 'defaults confidence to DEFAULT_CONFIDENCE' do
+      expect(concept.confidence).to eq(Legion::Extensions::Agentic::Memory::Semantic::Helpers::Constants::DEFAULT_CONFIDENCE)
+    end
+
+    it 'assigns uuid and timestamp' do
+      expect(concept.id).to match(/\A[0-9a-f-]{36}\z/)
+      expect(concept.created_at).to be_a(Time)
+    end
+
+    it 'accepts custom properties' do
+      c = described_class.new(name: :cat, properties: { legs: 4 })
+      expect(c.get_property(:legs)).to eq(4)
+    end
+  end
+
+  describe '#add_relation' do
+    it 'adds a typed relation' do
+      rel = concept.add_relation(type: :is_a, target_name: :mammal)
+      expect(rel[:type]).to eq(:is_a)
+      expect(rel[:target]).to eq(:mammal)
+      expect(concept.relations.size).to eq(1)
+    end
+
+    it 'rejects invalid relation types' do
+      expect(concept.add_relation(type: :invalid, target_name: :thing)).to be false
+    end
+
+    it 'reinforces existing relation instead of duplicating' do
+      concept.add_relation(type: :is_a, target_name: :mammal)
+      concept.add_relation(type: :is_a, target_name: :mammal)
+      expect(concept.relations.size).to eq(1)
+    end
+  end
+
+  describe '#relations_of_type' do
+    it 'filters by type' do
+      concept.add_relation(type: :is_a, target_name: :mammal)
+      concept.add_relation(type: :has_a, target_name: :tail)
+      expect(concept.relations_of_type(:is_a).size).to eq(1)
+    end
+  end
+
+  describe '#related_concepts' do
+    it 'lists unique related concept names' do
+      concept.add_relation(type: :is_a, target_name: :mammal)
+      concept.add_relation(type: :has_a, target_name: :tail)
+      expect(concept.related_concepts).to contain_exactly(:mammal, :tail)
+    end
+  end
+
+  describe '#access' do
+    it 'increments count and boosts confidence' do
+      before = concept.confidence
+      concept.access
+      expect(concept.access_count).to eq(1)
+      expect(concept.confidence).to be > before
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces confidence' do
+      before = concept.confidence
+      concept.decay
+      expect(concept.confidence).to be < before
+    end
+
+    it 'does not drop below floor' do
+      100.times { concept.decay }
+      expect(concept.confidence).to be >= Legion::Extensions::Agentic::Memory::Semantic::Helpers::Constants::CONFIDENCE_FLOOR
+    end
+
+    it 'prunes weak relations' do
+      concept.add_relation(type: :is_a, target_name: :mammal, confidence: 0.06)
+      100.times { concept.decay }
+      expect(concept.relations).to be_empty
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns false for healthy concept' do
+      expect(concept.faded?).to be false
+    end
+
+    it 'returns true at floor' do
+      concept.confidence = Legion::Extensions::Agentic::Memory::Semantic::Helpers::Constants::CONFIDENCE_FLOOR
+      expect(concept.faded?).to be true
+    end
+  end
+
+  describe '#label' do
+    it 'returns :provisional for default confidence' do
+      expect(concept.label).to eq(:provisional)
+    end
+
+    it 'returns :established for high confidence' do
+      concept.confidence = 0.9
+      expect(concept.label).to eq(:established)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = concept.to_h
+      expect(h).to include(:id, :name, :domain, :confidence, :properties, :relations, :access_count, :label)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/semantic/helpers/knowledge_store_spec.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Semantic::Helpers::KnowledgeStore do
+  subject(:store) { described_class.new }
+
+  describe '#store' do
+    it 'creates a new concept' do
+      concept = store.store(name: :dog, domain: :animals)
+      expect(concept.name).to eq(:dog)
+      expect(store.concept_count).to eq(1)
+    end
+
+    it 'updates existing concept on re-store' do
+      store.store(name: :dog, domain: :animals)
+      store.store(name: :dog, properties: { legs: 4 })
+      expect(store.concept_count).to eq(1)
+      expect(store.retrieve(name: :dog).get_property(:legs)).to eq(4)
+    end
+  end
+
+  describe '#relate' do
+    it 'creates relation between concepts' do
+      store.relate(source: :dog, target: :mammal, type: :is_a)
+      rels = store.query_relations(name: :dog, type: :is_a)
+      expect(rels.size).to eq(1)
+      expect(rels.first[:target]).to eq(:mammal)
+    end
+
+    it 'auto-creates concepts that do not exist' do
+      store.relate(source: :sparrow, target: :bird, type: :is_a)
+      expect(store.concept_count).to eq(2)
+    end
+  end
+
+  describe '#retrieve' do
+    it 'returns concept and increments access' do
+      store.store(name: :dog, domain: :animals)
+      concept = store.retrieve(name: :dog)
+      expect(concept.access_count).to eq(1)
+    end
+
+    it 'returns nil for unknown concept' do
+      expect(store.retrieve(name: :unknown)).to be_nil
+    end
+
+    it 'records retrieval in history' do
+      store.store(name: :dog)
+      store.retrieve(name: :dog)
+      expect(store.retrieval_history.size).to eq(1)
+    end
+  end
+
+  describe '#check_is_a' do
+    it 'returns true for valid is_a relation' do
+      store.relate(source: :dog, target: :mammal, type: :is_a)
+      expect(store.check_is_a(:dog, :mammal)).to be true
+    end
+
+    it 'returns false for non-existent relation' do
+      store.store(name: :dog)
+      expect(store.check_is_a(:dog, :reptile)).to be false
+    end
+  end
+
+  describe '#instances_of' do
+    it 'finds all instances of a category' do
+      store.relate(source: :dog, target: :mammal, type: :is_a)
+      store.relate(source: :cat, target: :mammal, type: :is_a)
+      store.relate(source: :sparrow, target: :bird, type: :is_a)
+      instances = store.instances_of(:mammal)
+      expect(instances.map(&:name)).to contain_exactly(:dog, :cat)
+    end
+  end
+
+  describe '#spreading_activation' do
+    it 'activates seed concept' do
+      store.store(name: :dog)
+      activated = store.spreading_activation(seed: :dog)
+      expect(activated).to have_key(:dog)
+    end
+
+    it 'spreads to related concepts' do
+      store.relate(source: :dog, target: :mammal, type: :is_a)
+      store.relate(source: :mammal, target: :animal, type: :is_a)
+      activated = store.spreading_activation(seed: :dog, hops: 3)
+      expect(activated.keys).to include(:dog, :mammal)
+    end
+
+    it 'diminishes activation with each hop' do
+      store.relate(source: :dog, target: :mammal, type: :is_a)
+      activated = store.spreading_activation(seed: :dog)
+      expect(activated[:dog]).to be > activated[:mammal] if activated.key?(:mammal)
+    end
+  end
+
+  describe '#concepts_in_domain' do
+    it 'returns concepts in specified domain' do
+      store.store(name: :dog, domain: :animals)
+      store.store(name: :ruby, domain: :programming)
+      expect(store.concepts_in_domain(:animals).map(&:name)).to eq([:dog])
+    end
+  end
+
+  describe '#search' do
+    it 'finds concepts matching query' do
+      store.store(name: :golden_retriever)
+      store.store(name: :golden_gate)
+      store.store(name: :poodle)
+      results = store.search(:golden)
+      expect(results.size).to eq(2)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all concepts' do
+      store.store(name: :dog, confidence: 0.5)
+      store.decay_all
+      concept = store.concepts[:dog]
+      expect(concept.confidence).to be < 0.5 if concept
+    end
+
+    it 'prunes faded concepts' do
+      floor = Legion::Extensions::Agentic::Memory::Semantic::Helpers::Constants::CONFIDENCE_FLOOR
+      store.store(name: :weak, confidence: floor + 0.004)
+      store.decay_all
+      expect(store.concept_count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats' do
+      store.store(name: :dog, domain: :animals)
+      store.relate(source: :dog, target: :mammal, type: :is_a)
+      h = store.to_h
+      expect(h).to include(:concepts, :relations, :domains, :history_size)
+      expect(h[:concepts]).to eq(2)
+      expect(h[:relations]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/semantic/runners/semantic_memory_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Semantic::Runners::SemanticMemory do
+  let(:client) { Legion::Extensions::Agentic::Memory::Semantic::Client.new }
+
+  describe '#store_concept' do
+    it 'stores a concept' do
+      result = client.store_concept(name: :dog, domain: :animals)
+      expect(result[:success]).to be true
+      expect(result[:concept][:name]).to eq(:dog)
+    end
+  end
+
+  describe '#relate_concepts' do
+    it 'creates a relation' do
+      result = client.relate_concepts(source: :dog, target: :mammal, type: :is_a)
+      expect(result[:success]).to be true
+      expect(result[:type]).to eq(:is_a)
+    end
+  end
+
+  describe '#retrieve_concept' do
+    it 'retrieves stored concept' do
+      client.store_concept(name: :dog, domain: :animals)
+      result = client.retrieve_concept(name: :dog)
+      expect(result[:found]).to be true
+      expect(result[:concept][:name]).to eq(:dog)
+    end
+
+    it 'returns found: false for unknown' do
+      result = client.retrieve_concept(name: :unknown)
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#query_concept_relations' do
+    it 'returns relations' do
+      client.relate_concepts(source: :dog, target: :mammal, type: :is_a)
+      result = client.query_concept_relations(name: :dog, type: :is_a)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#check_category' do
+    it 'checks is_a membership' do
+      client.relate_concepts(source: :dog, target: :mammal, type: :is_a)
+      result = client.check_category(concept: :dog, category: :mammal)
+      expect(result[:is_member]).to be true
+    end
+
+    it 'returns false for non-member' do
+      client.store_concept(name: :dog)
+      result = client.check_category(concept: :dog, category: :reptile)
+      expect(result[:is_member]).to be false
+    end
+  end
+
+  describe '#find_instances' do
+    it 'finds instances of category' do
+      client.relate_concepts(source: :dog, target: :mammal, type: :is_a)
+      client.relate_concepts(source: :cat, target: :mammal, type: :is_a)
+      result = client.find_instances(category: :mammal)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#activate_spread' do
+    it 'spreads activation from seed' do
+      client.relate_concepts(source: :dog, target: :mammal, type: :is_a)
+      result = client.activate_spread(seed: :dog)
+      expect(result[:success]).to be true
+      expect(result[:activated]).to have_key(:dog)
+    end
+  end
+
+  describe '#concepts_in' do
+    it 'returns concepts in domain' do
+      client.store_concept(name: :dog, domain: :animals)
+      client.store_concept(name: :ruby, domain: :programming)
+      result = client.concepts_in(domain: :animals)
+      expect(result[:count]).to eq(1)
+      expect(result[:concepts]).to eq([:dog])
+    end
+  end
+
+  describe '#update_semantic_memory' do
+    it 'decays and returns counts' do
+      client.store_concept(name: :dog)
+      result = client.update_semantic_memory
+      expect(result[:success]).to be true
+      expect(result).to have_key(:concepts)
+      expect(result).to have_key(:relations)
+    end
+  end
+
+  describe '#semantic_memory_stats' do
+    it 'returns stats' do
+      result = client.semantic_memory_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:concepts, :relations, :domains)
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::Connection do
+  subject(:conn) { described_class.new(source_id: 'src-1', target_id: 'tgt-1') }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(conn.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets source and target' do
+      expect(conn.source_id).to eq('src-1')
+      expect(conn.target_id).to eq('tgt-1')
+    end
+
+    it 'defaults weight to 0.5' do
+      expect(conn.weight).to eq(0.5)
+    end
+
+    it 'clamps low weight' do
+      low = described_class.new(source_id: 'a', target_id: 'b', weight: 0.0)
+      expect(low.weight).to eq(0.05)
+    end
+  end
+
+  describe '#strengthen!' do
+    it 'increases weight' do
+      original = conn.weight
+      conn.strengthen!
+      expect(conn.weight).to be > original
+    end
+
+    it 'clamps at 1.0' do
+      30.times { conn.strengthen!(amount: 0.1) }
+      expect(conn.weight).to eq(1.0)
+    end
+  end
+
+  describe '#weaken!' do
+    it 'decreases weight' do
+      original = conn.weight
+      conn.weaken!
+      expect(conn.weight).to be < original
+    end
+  end
+
+  describe '#traverse!' do
+    it 'increments traversal count' do
+      conn.traverse!
+      expect(conn.traversal_count).to eq(1)
+    end
+
+    it 'strengthens connection' do
+      original = conn.weight
+      conn.traverse!
+      expect(conn.weight).to be > original
+    end
+  end
+
+  describe '#spreading_amount' do
+    it 'computes spread based on activation and weight' do
+      amount = conn.spreading_amount(0.8)
+      expect(amount).to be > 0
+      expect(amount).to be < 0.8
+    end
+
+    it 'returns zero for zero activation' do
+      expect(conn.spreading_amount(0.0)).to eq(0.0)
+    end
+  end
+
+  describe '#strong?' do
+    it 'is false at default weight' do
+      expect(conn.strong?).to be false
+    end
+
+    it 'is true at high weight' do
+      high = described_class.new(source_id: 'a', target_id: 'b', weight: 0.8)
+      expect(high.strong?).to be true
+    end
+  end
+
+  describe '#weight_label' do
+    it 'returns a symbol' do
+      expect(conn.weight_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = conn.to_h
+      expect(hash).to include(
+        :id, :source_id, :target_id, :weight, :weight_label,
+        :strong, :weak, :traversal_count, :created_at
+      )
+    end
+  end
+end

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::PrimingNetwork do
+  subject(:network) { described_class.new }
+
+  let(:doctor) { network.add_node(label: 'doctor') }
+  let(:nurse) { network.add_node(label: 'nurse') }
+  let(:hospital) { network.add_node(label: 'hospital') }
+
+  describe '#add_node' do
+    it 'creates a semantic node' do
+      node = network.add_node(label: 'test')
+      expect(node).to be_a(Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::SemanticNode)
+    end
+
+    it 'stores the node' do
+      node = network.add_node(label: 'stored')
+      found = network.find_node_by_label(label: 'stored')
+      expect(found.id).to eq(node.id)
+    end
+  end
+
+  describe '#remove_node' do
+    it 'removes the node' do
+      node = network.add_node(label: 'remove_me')
+      network.remove_node(node_id: node.id)
+      expect(network.find_node_by_label(label: 'remove_me')).to be_nil
+    end
+
+    it 'returns nil for unknown node' do
+      expect(network.remove_node(node_id: 'nonexistent')).to be_nil
+    end
+
+    it 'removes associated connections' do
+      network.connect(source_id: doctor.id, target_id: nurse.id)
+      network.remove_node(node_id: doctor.id)
+      expect(network.connection_between(source_id: doctor.id, target_id: nurse.id)).to be_nil
+    end
+  end
+
+  describe '#connect' do
+    it 'creates a connection between nodes' do
+      conn = network.connect(source_id: doctor.id, target_id: nurse.id)
+      expect(conn).to be_a(Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::Connection)
+    end
+
+    it 'returns nil for self-connection' do
+      expect(network.connect(source_id: doctor.id, target_id: doctor.id)).to be_nil
+    end
+
+    it 'returns nil for unknown nodes' do
+      expect(network.connect(source_id: 'bad', target_id: nurse.id)).to be_nil
+    end
+  end
+
+  describe '#prime_node' do
+    it 'increases node activation' do
+      doctor
+      network.prime_node(node_id: doctor.id)
+      expect(doctor.activation).to be > 0.0
+    end
+
+    it 'returns nil for unknown node' do
+      expect(network.prime_node(node_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#prime_and_spread' do
+    it 'primes the target and spreads to neighbors' do
+      network.connect(source_id: doctor.id, target_id: nurse.id, weight: 0.8)
+      result = network.prime_and_spread(node_id: doctor.id, amount: 0.8)
+      expect(result[:primed_node][:activation]).to be > 0
+      expect(result[:spread].size).to be >= 1
+    end
+
+    it 'spreads activation through multi-hop paths' do
+      network.connect(source_id: doctor.id, target_id: nurse.id, weight: 0.9)
+      network.connect(source_id: nurse.id, target_id: hospital.id, weight: 0.9)
+      network.prime_and_spread(node_id: doctor.id, amount: 0.9)
+      expect(hospital.activation).to be > 0
+    end
+
+    it 'returns nil for unknown node' do
+      expect(network.prime_and_spread(node_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#spread_activation' do
+    it 'activates connected nodes' do
+      network.connect(source_id: doctor.id, target_id: nurse.id)
+      network.prime_node(node_id: doctor.id, amount: 0.8)
+      activated = network.spread_activation(source_id: doctor.id)
+      expect(activated.size).to be >= 1
+    end
+  end
+
+  describe '#decay_all!' do
+    it 'reduces activation on all nodes' do
+      network.prime_node(node_id: doctor.id, amount: 0.5)
+      network.decay_all!
+      expect(doctor.activation).to be < 0.5
+    end
+  end
+
+  describe '#reset_all!' do
+    it 'resets all activations to zero' do
+      network.prime_node(node_id: doctor.id, amount: 0.5)
+      network.reset_all!
+      expect(doctor.activation).to eq(0.0)
+    end
+  end
+
+  describe '#find_node_by_label' do
+    it 'finds node by label string' do
+      doctor
+      found = network.find_node_by_label(label: 'doctor')
+      expect(found.id).to eq(doctor.id)
+    end
+
+    it 'returns nil for unknown label' do
+      expect(network.find_node_by_label(label: 'nonexistent')).to be_nil
+    end
+  end
+
+  describe '#neighbors' do
+    it 'returns connected nodes' do
+      network.connect(source_id: doctor.id, target_id: nurse.id)
+      nbrs = network.neighbors(node_id: doctor.id)
+      expect(nbrs.map(&:id)).to include(nurse.id)
+    end
+  end
+
+  describe '#connection_between' do
+    it 'finds bidirectional connection' do
+      network.connect(source_id: doctor.id, target_id: nurse.id)
+      conn = network.connection_between(source_id: nurse.id, target_id: doctor.id)
+      expect(conn).not_to be_nil
+    end
+  end
+
+  describe '#primed_nodes' do
+    it 'returns only primed nodes' do
+      network.prime_node(node_id: doctor.id, amount: 0.5)
+      nurse
+      expect(network.primed_nodes.map(&:id)).to include(doctor.id)
+      expect(network.primed_nodes.map(&:id)).not_to include(nurse.id)
+    end
+  end
+
+  describe '#most_primed' do
+    it 'returns nodes sorted by activation descending' do
+      network.prime_node(node_id: doctor.id, amount: 0.8)
+      network.prime_node(node_id: nurse.id, amount: 0.3)
+      top = network.most_primed(limit: 2)
+      expect(top.first.id).to eq(doctor.id)
+    end
+  end
+
+  describe '#average_activation' do
+    it 'returns 0.0 with no nodes' do
+      expect(network.average_activation).to eq(0.0)
+    end
+
+    it 'computes mean activation' do
+      network.prime_node(node_id: doctor.id, amount: 0.6)
+      nurse
+      avg = network.average_activation
+      expect(avg).to be > 0.0
+      expect(avg).to be < 0.6
+    end
+  end
+
+  describe '#network_density' do
+    it 'returns 0.0 with fewer than 2 nodes' do
+      network.add_node(label: 'solo')
+      expect(network.network_density).to eq(0.0)
+    end
+
+    it 'increases with more connections' do
+      network.connect(source_id: doctor.id, target_id: nurse.id)
+      hospital
+      density1 = network.network_density
+      network.connect(source_id: doctor.id, target_id: hospital.id)
+      density2 = network.network_density
+      expect(density2).to be > density1
+    end
+  end
+
+  describe '#priming_report' do
+    it 'returns comprehensive report' do
+      doctor
+      report = network.priming_report
+      expect(report).to include(
+        :total_nodes, :total_connections, :primed_count, :active_count,
+        :average_activation, :average_weight, :network_density,
+        :most_primed, :strongest_connections
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary hash' do
+      doctor
+      hash = network.to_h
+      expect(hash).to include(:total_nodes, :total_connections, :primed_count, :active_count)
+    end
+  end
+end