lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/semantic/helpers/concept.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+          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
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic/helpers/constants.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+          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
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic/helpers/knowledge_store.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+          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
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic/runners/semantic_memory.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+          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
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/memory/semantic/version'
+require 'legion/extensions/agentic/memory/semantic/helpers/constants'
+require 'legion/extensions/agentic/memory/semantic/helpers/concept'
+require 'legion/extensions/agentic/memory/semantic/helpers/knowledge_store'
+require 'legion/extensions/agentic/memory/semantic/runners/semantic_memory'
+require 'legion/extensions/agentic/memory/semantic/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Semantic
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic_priming/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+          class Client
+            include Runners::SemanticPriming
+
+            def initialize(engine: nil)
+              @default_engine = engine || Helpers::PrimingNetwork.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic_priming/helpers/connection.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+          module Helpers
+            class Connection
+              include Constants
+
+              attr_reader :id, :source_id, :target_id, :weight, :traversal_count, :created_at
+
+              def initialize(source_id:, target_id:, weight: DEFAULT_WEIGHT)
+                @id              = SecureRandom.uuid
+                @source_id       = source_id
+                @target_id       = target_id
+                @weight          = weight.to_f.clamp(MIN_WEIGHT, 1.0).round(10)
+                @traversal_count = 0
+                @created_at      = Time.now.utc
+              end
+
+              def strengthen!(amount: WEIGHT_GROWTH_RATE)
+                @weight = (@weight + amount).clamp(MIN_WEIGHT, 1.0).round(10)
+                self
+              end
+
+              def weaken!(amount: WEIGHT_DECAY_RATE)
+                @weight = (@weight - amount).clamp(MIN_WEIGHT, 1.0).round(10)
+                self
+              end
+
+              def traverse!
+                @traversal_count += 1
+                strengthen!(amount: WEIGHT_GROWTH_RATE)
+                self
+              end
+
+              def strong?
+                @weight >= 0.7
+              end
+
+              def weak?
+                @weight <= 0.2
+              end
+
+              def spreading_amount(source_activation)
+                (source_activation * @weight * SPREADING_FACTOR).round(10)
+              end
+
+              def weight_label
+                match = WEIGHT_LABELS.find { |range, _| range.cover?(@weight) }
+                match ? match.last : :very_weak
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  source_id:       @source_id,
+                  target_id:       @target_id,
+                  weight:          @weight,
+                  weight_label:    weight_label,
+                  strong:          strong?,
+                  weak:            weak?,
+                  traversal_count: @traversal_count,
+                  created_at:      @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic_priming/helpers/constants.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+          module Helpers
+            module Constants
+              # Network limits
+              MAX_NODES = 500
+              MAX_CONNECTIONS = 2000
+
+              # Activation dynamics
+              DEFAULT_ACTIVATION = 0.0
+              RESTING_ACTIVATION = 0.0
+              MAX_ACTIVATION = 1.0
+              ACTIVATION_DECAY = 0.05
+              SPREADING_FACTOR = 0.6
+              PRIMING_BOOST = 0.3
+              ACTIVATION_THRESHOLD = 0.1
+
+              # Connection properties
+              DEFAULT_WEIGHT = 0.5
+              WEIGHT_GROWTH_RATE = 0.02
+              WEIGHT_DECAY_RATE = 0.01
+              MIN_WEIGHT = 0.05
+
+              # Spreading activation
+              MAX_SPREAD_DEPTH = 3
+              DEPTH_DECAY_FACTOR = 0.5
+
+              # Node types
+              NODE_TYPES = %i[concept category feature relation action emotion context].freeze
+
+              # Activation labels
+              ACTIVATION_LABELS = {
+                (0.8..)     => :highly_primed,
+                (0.6...0.8) => :primed,
+                (0.4...0.6) => :partially_primed,
+                (0.2...0.4) => :weakly_primed,
+                (..0.2)     => :unprimed
+              }.freeze
+
+              # Connection strength labels
+              WEIGHT_LABELS = {
+                (0.8..)     => :very_strong,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :weak,
+                (..0.2)     => :very_weak
+              }.freeze
+
+              # Priming effect labels
+              PRIMING_LABELS = {
+                (0.8..)     => :massive,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :mild,
+                (..0.2)     => :negligible
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end