lex-semantic-memory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '078f5ae8f0283c2644b9713a80bb865bdd750ec02a60a6e3aa2f980a81541bc9'
+  data.tar.gz: af9949496a45f4c85e10a47754a939b5b746be2892dd206394fc72fd521e3c58
+SHA512:
+  metadata.gz: 62b9c20fc08fdae67e52da0283126eb26c940307973e4bb1a91f14cda435f940b58b3eeb372d6137220bedff52ec6388044140c5d786cf86d1cf7de713fc1b2c
+  data.tar.gz: f677725f1951be5496ca865485835f1e94ade8d30e1eba60dc064ea619242a5238e2ae68651e1abfb82cf61ed881e2f63f2323763152db85b75be9d810d5fe8f

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-semantic-memory.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/semantic_memory/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-semantic-memory'
+  spec.version       = Legion::Extensions::SemanticMemory::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Semantic Memory'
+  spec.description   = 'Tulving semantic memory store for brain-modeled agentic AI — concept storage, ' \
+                       'taxonomic relations (is_a, has_a, part_of), spreading activation retrieval, ' \
+                       'and knowledge consolidation with confidence-based decay.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-semantic-memory'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = 'https://github.com/LegionIO/lex-semantic-memory'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-semantic-memory'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-semantic-memory'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-semantic-memory/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-semantic-memory.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/semantic_memory/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::SemanticMemory::Runners::SemanticMemory
+          end
+
+          def runner_function
+            'update_semantic_memory'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/semantic_memory/helpers/constants'
+require 'legion/extensions/semantic_memory/helpers/concept'
+require 'legion/extensions/semantic_memory/helpers/knowledge_store'
+require 'legion/extensions/semantic_memory/runners/semantic_memory'
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      class Client
+        include Runners::SemanticMemory
+
+        def initialize(knowledge_store: nil, **)
+          @knowledge_store = knowledge_store || Helpers::KnowledgeStore.new
+        end
+
+        private
+
+        attr_reader :knowledge_store
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory/helpers/concept.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      module Helpers
+        class Concept
+          attr_reader :id, :name, :domain, :properties, :relations, :created_at
+          attr_accessor :confidence, :access_count
+
+          def initialize(name:, domain: :general, confidence: nil, properties: {})
+            @id           = SecureRandom.uuid
+            @name         = name
+            @domain       = domain
+            @confidence   = (confidence || Constants::DEFAULT_CONFIDENCE).clamp(0.0, 1.0)
+            @properties   = properties.dup
+            @relations    = []
+            @access_count = 0
+            @created_at   = Time.now.utc
+          end
+
+          def add_relation(type:, target_name:, confidence: nil)
+            return false unless Constants::RELATION_TYPES.include?(type)
+
+            existing = @relations.find { |r| r[:type] == type && r[:target] == target_name }
+            if existing
+              existing[:confidence] = [existing[:confidence] + Constants::ACCESS_BOOST, 1.0].min
+              return existing
+            end
+
+            trim_relations if @relations.size >= Constants::MAX_RELATIONS_PER_CONCEPT
+            rel = { type: type, target: target_name, confidence: (confidence || Constants::DEFAULT_CONFIDENCE).clamp(0.0, 1.0) }
+            @relations << rel
+            rel
+          end
+
+          def relations_of_type(type)
+            @relations.select { |r| r[:type] == type }
+          end
+
+          def related_concepts
+            @relations.map { |r| r[:target] }.uniq
+          end
+
+          def set_property(key, value)
+            @properties[key] = value
+          end
+
+          def get_property(key)
+            @properties[key]
+          end
+
+          def access
+            @access_count += 1
+            @confidence = [@confidence + Constants::ACCESS_BOOST, 1.0].min
+          end
+
+          def decay
+            @confidence = [@confidence - Constants::CONFIDENCE_DECAY, Constants::CONFIDENCE_FLOOR].max
+            @relations.each { |r| r[:confidence] = [r[:confidence] - Constants::CONFIDENCE_DECAY, Constants::CONFIDENCE_FLOOR].max }
+            @relations.reject! { |r| r[:confidence] <= Constants::CONFIDENCE_FLOOR }
+          end
+
+          def faded?
+            @confidence <= Constants::CONFIDENCE_FLOOR
+          end
+
+          def label
+            Constants::CONFIDENCE_LABELS.each { |range, lbl| return lbl if range.cover?(@confidence) }
+            :uncertain
+          end
+
+          def to_h
+            {
+              id:           @id,
+              name:         @name,
+              domain:       @domain,
+              confidence:   @confidence,
+              properties:   @properties,
+              relations:    @relations,
+              access_count: @access_count,
+              label:        label,
+              created_at:   @created_at
+            }
+          end
+
+          private
+
+          def trim_relations
+            @relations.sort_by! { |r| r[:confidence] }
+            @relations.shift
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory/helpers/constants.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      module Helpers
+        module Constants
+          MAX_CONCEPTS = 500
+          MAX_RELATIONS_PER_CONCEPT = 50
+          MAX_HISTORY = 200
+
+          # Relation types between concepts
+          RELATION_TYPES = %i[
+            is_a has_a part_of
+            property_of used_for
+            causes prevents
+            similar_to opposite_of
+            instance_of category_of
+          ].freeze
+
+          # Confidence thresholds
+          DEFAULT_CONFIDENCE = 0.5
+          CONFIDENCE_FLOOR = 0.05
+          CONFIDENCE_DECAY = 0.005
+          CONFIDENCE_ALPHA = 0.12
+
+          # Access frequency tracking
+          ACCESS_BOOST = 0.05
+          ACCESS_DECAY = 0.01
+
+          # Retrieval spreading activation
+          SPREAD_FACTOR = 0.6
+          MAX_SPREAD_HOPS = 3
+          SPREAD_THRESHOLD = 0.1
+
+          CONFIDENCE_LABELS = {
+            (0.8..)     => :established,
+            (0.6...0.8) => :reliable,
+            (0.4...0.6) => :provisional,
+            (0.2...0.4) => :tentative,
+            (..0.2)     => :uncertain
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory/helpers/knowledge_store.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      module Helpers
+        class KnowledgeStore
+          include Constants
+
+          attr_reader :concepts, :retrieval_history
+
+          def initialize
+            @concepts          = {}
+            @retrieval_history = []
+          end
+
+          def store(name:, domain: :general, confidence: nil, properties: {})
+            if @concepts.key?(name)
+              existing = @concepts[name]
+              existing.access
+              properties.each { |k, v| existing.set_property(k, v) }
+              return existing
+            end
+
+            ensure_capacity
+            concept = Concept.new(name: name, domain: domain, confidence: confidence, properties: properties)
+            @concepts[name] = concept
+            concept
+          end
+
+          def relate(source:, target:, type:, confidence: nil)
+            store(name: source) unless @concepts.key?(source)
+            store(name: target) unless @concepts.key?(target)
+            @concepts[source].add_relation(type: type, target_name: target, confidence: confidence)
+          end
+
+          def retrieve(name:)
+            concept = @concepts[name]
+            return nil unless concept
+
+            concept.access
+            record_retrieval(name)
+            concept
+          end
+
+          def query_relations(name:, type: nil)
+            concept = @concepts[name]
+            return [] unless concept
+
+            concept.access
+            if type
+              concept.relations_of_type(type)
+            else
+              concept.relations
+            end
+          end
+
+          def check_is_a(concept_name, category_name)
+            rels = query_relations(name: concept_name, type: :is_a)
+            rels.any? { |r| r[:target] == category_name }
+          end
+
+          def instances_of(category_name)
+            @concepts.values.select do |c|
+              c.relations.any? { |r| r[:type] == :is_a && r[:target] == category_name }
+            end
+          end
+
+          def spreading_activation(seed:, hops: MAX_SPREAD_HOPS)
+            activated = {}
+            queue = [[seed, 1.0]]
+
+            hops.times do
+              next_queue = []
+              queue.each do |name, strength|
+                next if strength < SPREAD_THRESHOLD
+                next if activated.key?(name) && activated[name] >= strength
+
+                activated[name] = strength
+                concept = @concepts[name]
+                next unless concept
+
+                concept.related_concepts.each do |related|
+                  next_strength = strength * SPREAD_FACTOR
+                  next_queue << [related, next_strength] if next_strength >= SPREAD_THRESHOLD
+                end
+              end
+              queue = next_queue
+            end
+
+            activated.sort_by { |_, s| -s }.to_h
+          end
+
+          def concepts_in_domain(domain)
+            @concepts.values.select { |c| c.domain == domain }
+          end
+
+          def search(query)
+            @concepts.values.select { |c| c.name.to_s.include?(query.to_s) }
+          end
+
+          def decay_all
+            @concepts.each_value(&:decay)
+            @concepts.reject! { |_, c| c.faded? }
+          end
+
+          def concept_count
+            @concepts.size
+          end
+
+          def relation_count
+            @concepts.values.sum { |c| c.relations.size }
+          end
+
+          def to_h
+            {
+              concepts:     concept_count,
+              relations:    relation_count,
+              domains:      @concepts.values.map(&:domain).uniq.size,
+              history_size: @retrieval_history.size
+            }
+          end
+
+          private
+
+          def ensure_capacity
+            return if @concepts.size < MAX_CONCEPTS
+
+            weakest = @concepts.min_by { |_, c| c.confidence }
+            @concepts.delete(weakest.first) if weakest
+          end
+
+          def record_retrieval(name)
+            @retrieval_history << { name: name, at: Time.now.utc }
+            @retrieval_history.shift while @retrieval_history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory/runners/semantic_memory.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      module Runners
+        module SemanticMemory
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def store_concept(name:, domain: :general, confidence: nil, properties: {}, **)
+            concept = knowledge_store.store(name: name, domain: domain, confidence: confidence, properties: properties)
+            Legion::Logging.debug "[semantic_memory] store: name=#{name} domain=#{domain} conf=#{concept.confidence.round(3)}"
+            { success: true, concept: concept.to_h }
+          end
+
+          def relate_concepts(source:, target:, type:, confidence: nil, **)
+            type_sym = type.to_sym
+            result = knowledge_store.relate(source: source, target: target, type: type_sym, confidence: confidence)
+            Legion::Logging.debug "[semantic_memory] relate: #{source} --#{type_sym}--> #{target}"
+            { success: true, source: source, target: target, type: type_sym, relation: result }
+          end
+
+          def retrieve_concept(name:, **)
+            concept = knowledge_store.retrieve(name: name)
+            if concept
+              Legion::Logging.debug "[semantic_memory] retrieve: name=#{name} conf=#{concept.confidence.round(3)}"
+              { success: true, found: true, concept: concept.to_h }
+            else
+              Legion::Logging.debug "[semantic_memory] retrieve: name=#{name} not_found"
+              { success: true, found: false, name: name }
+            end
+          end
+
+          def query_concept_relations(name:, type: nil, **)
+            relations = knowledge_store.query_relations(name: name, type: type&.to_sym)
+            Legion::Logging.debug "[semantic_memory] query_relations: name=#{name} type=#{type} count=#{relations.size}"
+            { success: true, name: name, relations: relations, count: relations.size }
+          end
+
+          def check_category(concept:, category:, **)
+            result = knowledge_store.check_is_a(concept, category)
+            Legion::Logging.debug "[semantic_memory] check_category: #{concept} is_a #{category} = #{result}"
+            { success: true, concept: concept, category: category, is_member: result }
+          end
+
+          def find_instances(category:, **)
+            instances = knowledge_store.instances_of(category)
+            Legion::Logging.debug "[semantic_memory] instances_of: #{category} count=#{instances.size}"
+            { success: true, category: category, instances: instances.map(&:name), count: instances.size }
+          end
+
+          def activate_spread(seed:, hops: nil, **)
+            hop_count = hops || Helpers::Constants::MAX_SPREAD_HOPS
+            activated = knowledge_store.spreading_activation(seed: seed, hops: hop_count)
+            Legion::Logging.debug "[semantic_memory] spread: seed=#{seed} hops=#{hop_count} activated=#{activated.size}"
+            { success: true, seed: seed, activated: activated, count: activated.size }
+          end
+
+          def concepts_in(domain:, **)
+            concepts = knowledge_store.concepts_in_domain(domain)
+            Legion::Logging.debug "[semantic_memory] domain_query: domain=#{domain} count=#{concepts.size}"
+            { success: true, domain: domain, concepts: concepts.map(&:name), count: concepts.size }
+          end
+
+          def update_semantic_memory(**)
+            knowledge_store.decay_all
+            Legion::Logging.debug "[semantic_memory] tick: concepts=#{knowledge_store.concept_count} " \
+                                  "relations=#{knowledge_store.relation_count}"
+            {
+              success:   true,
+              concepts:  knowledge_store.concept_count,
+              relations: knowledge_store.relation_count
+            }
+          end
+
+          def semantic_memory_stats(**)
+            { success: true, stats: knowledge_store.to_h }
+          end
+
+          private
+
+          def knowledge_store
+            @knowledge_store ||= Helpers::KnowledgeStore.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/semantic_memory.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/semantic_memory/version'
+require 'legion/extensions/semantic_memory/helpers/constants'
+require 'legion/extensions/semantic_memory/helpers/concept'
+require 'legion/extensions/semantic_memory/helpers/knowledge_store'
+require 'legion/extensions/semantic_memory/runners/semantic_memory'
+require 'legion/extensions/semantic_memory/client'
+
+module Legion
+  module Extensions
+    module SemanticMemory
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/semantic_memory/client_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SemanticMemory::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::SemanticMemory' do
+    expect(described_class.ancestors).to include(Legion::Extensions::SemanticMemory::Runners::SemanticMemory)
+  end
+
+  it 'supports full knowledge lifecycle' do
+    # Build a taxonomy
+    client.store_concept(name: :animal, domain: :biology, properties: { kingdom: :animalia })
+    client.relate_concepts(source: :mammal, target: :animal, type: :is_a)
+    client.relate_concepts(source: :dog, target: :mammal, type: :is_a)
+    client.relate_concepts(source: :cat, target: :mammal, type: :is_a)
+    client.relate_concepts(source: :dog, target: :tail, type: :has_a)
+
+    # Query taxonomy
+    expect(client.check_category(concept: :dog, category: :mammal)[:is_member]).to be true
+    expect(client.find_instances(category: :mammal)[:count]).to eq(2)
+
+    # Spreading activation
+    activated = client.activate_spread(seed: :dog)
+    expect(activated[:activated]).to have_key(:dog)
+
+    # Retrieve
+    concept = client.retrieve_concept(name: :dog)
+    expect(concept[:found]).to be true
+
+    # Tick
+    client.update_semantic_memory
+    stats = client.semantic_memory_stats
+    expect(stats[:stats][:concepts]).to be >= 3
+  end
+end

data/spec/legion/extensions/semantic_memory/helpers/concept_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SemanticMemory::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::SemanticMemory::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::SemanticMemory::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::SemanticMemory::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/semantic_memory/helpers/knowledge_store_spec.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SemanticMemory::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::SemanticMemory::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/semantic_memory/runners/semantic_memory_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SemanticMemory::Runners::SemanticMemory do
+  let(:client) { Legion::Extensions::SemanticMemory::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/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/semantic_memory'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-semantic-memory
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Tulving semantic memory store for brain-modeled agentic AI — concept
+  storage, taxonomic relations (is_a, has_a, part_of), spreading activation retrieval,
+  and knowledge consolidation with confidence-based decay.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-semantic-memory.gemspec
+- lib/legion/extensions/semantic_memory.rb
+- lib/legion/extensions/semantic_memory/actors/decay.rb
+- lib/legion/extensions/semantic_memory/client.rb
+- lib/legion/extensions/semantic_memory/helpers/concept.rb
+- lib/legion/extensions/semantic_memory/helpers/constants.rb
+- lib/legion/extensions/semantic_memory/helpers/knowledge_store.rb
+- lib/legion/extensions/semantic_memory/runners/semantic_memory.rb
+- lib/legion/extensions/semantic_memory/version.rb
+- spec/legion/extensions/semantic_memory/client_spec.rb
+- spec/legion/extensions/semantic_memory/helpers/concept_spec.rb
+- spec/legion/extensions/semantic_memory/helpers/knowledge_store_spec.rb
+- spec/legion/extensions/semantic_memory/runners/semantic_memory_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-semantic-memory
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-semantic-memory
+  source_code_uri: https://github.com/LegionIO/lex-semantic-memory
+  documentation_uri: https://github.com/LegionIO/lex-semantic-memory
+  changelog_uri: https://github.com/LegionIO/lex-semantic-memory
+  bug_tracker_uri: https://github.com/LegionIO/lex-semantic-memory/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Semantic Memory
+test_files: []