lex-agentic-memory 0.1.0

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+          module Helpers
+            class PrimingNetwork
+              include Constants
+
+              def initialize
+                @nodes       = {}
+                @connections = {}
+                @adjacency   = Hash.new { |h, k| h[k] = [] }
+              end
+
+              def add_node(label:, node_type: :concept)
+                prune_nodes_if_needed
+                node = SemanticNode.new(label: label, node_type: node_type)
+                @nodes[node.id] = node
+                node
+              end
+
+              def remove_node(node_id:)
+                node = @nodes.delete(node_id)
+                return nil unless node
+
+                @adjacency.delete(node_id)
+                @adjacency.each_value { |list| list.reject! { |cid| connection_involves?(cid, node_id) } }
+                @connections.reject! { |_, c| c.source_id == node_id || c.target_id == node_id }
+                node
+              end
+
+              def connect(source_id:, target_id:, weight: DEFAULT_WEIGHT)
+                return nil unless @nodes[source_id] && @nodes[target_id]
+                return nil if source_id == target_id
+
+                prune_connections_if_needed
+                conn = Connection.new(source_id: source_id, target_id: target_id, weight: weight)
+                @connections[conn.id] = conn
+                @adjacency[source_id] << conn.id
+                @adjacency[target_id] << conn.id
+                conn
+              end
+
+              def prime_node(node_id:, amount: PRIMING_BOOST)
+                node = @nodes[node_id]
+                return nil unless node
+
+                node.prime!(amount: amount)
+                node
+              end
+
+              def spread_activation(source_id:, depth: MAX_SPREAD_DEPTH)
+                source = @nodes[source_id]
+                return nil unless source
+
+                activated = {}
+                spread_recursive(source_id, source.activation, depth, 0, activated)
+                activated.map { |nid, amount| { node_id: nid, label: @nodes[nid]&.label, activation_added: amount } }
+              end
+
+              def prime_and_spread(node_id:, amount: PRIMING_BOOST, depth: MAX_SPREAD_DEPTH)
+                node = prime_node(node_id: node_id, amount: amount)
+                return nil unless node
+
+                node.access!
+                spread = spread_activation(source_id: node_id, depth: depth)
+                { primed_node: node.to_h, spread: spread }
+              end
+
+              def decay_all!
+                @nodes.each_value(&:decay!)
+                @connections.each_value { |c| c.weaken!(amount: WEIGHT_DECAY_RATE) }
+                prune_weak_connections
+                { nodes_decayed: @nodes.size, connections_remaining: @connections.size }
+              end
+
+              def reset_all! = @nodes.each_value(&:reset!) && { nodes_reset: @nodes.size }
+              def find_node_by_label(label:) = @nodes.values.find { |n| n.label == label.to_s }
+
+              def neighbors(node_id:)
+                conn_ids = @adjacency[node_id] || []
+                conn_ids.filter_map do |cid|
+                  conn = @connections[cid]
+                  next unless conn
+
+                  other_id = conn.source_id == node_id ? conn.target_id : conn.source_id
+                  @nodes[other_id]
+                end
+              end
+
+              def connection_between(source_id:, target_id:)
+                @connections.values.find do |c|
+                  (c.source_id == source_id && c.target_id == target_id) ||
+                    (c.source_id == target_id && c.target_id == source_id)
+                end
+              end
+
+              def primed_nodes = @nodes.values.select(&:primed?)
+              def active_nodes = @nodes.values.select(&:active?)
+              def most_primed(limit: 5) = @nodes.values.sort_by { |n| -n.activation }.first(limit)
+              def strongest_connections(limit: 5) = @connections.values.sort_by { |c| -c.weight }.first(limit)
+
+              def average_activation
+                return DEFAULT_ACTIVATION if @nodes.empty?
+
+                vals = @nodes.values.map(&:activation)
+                (vals.sum / vals.size).round(10)
+              end
+
+              def average_connection_weight
+                return DEFAULT_WEIGHT if @connections.empty?
+
+                vals = @connections.values.map(&:weight)
+                (vals.sum / vals.size).round(10)
+              end
+
+              def network_density
+                return 0.0 if @nodes.size < 2
+
+                (@connections.size.to_f / (@nodes.size * (@nodes.size - 1) / 2)).round(10)
+              end
+
+              def priming_report
+                to_h.merge(
+                  average_weight:        average_connection_weight,
+                  most_primed:           most_primed(limit: 3).map(&:to_h),
+                  strongest_connections: strongest_connections(limit: 3).map(&:to_h)
+                )
+              end
+
+              def to_h
+                {
+                  total_nodes:        @nodes.size,
+                  total_connections:  @connections.size,
+                  primed_count:       primed_nodes.size,
+                  active_count:       active_nodes.size,
+                  average_activation: average_activation,
+                  network_density:    network_density
+                }
+              end
+
+              private
+
+              def spread_recursive(node_id, activation, max_depth, current_depth, activated)
+                return if current_depth >= max_depth || activation < ACTIVATION_THRESHOLD
+
+                each_neighbor(node_id) do |conn, other_id, target_node|
+                  next if activated.key?(other_id)
+
+                  amount = (conn.spreading_amount(activation) * (DEPTH_DECAY_FACTOR**current_depth)).round(10)
+                  next if amount < ACTIVATION_THRESHOLD
+
+                  conn.traverse!
+                  target_node.prime!(amount: amount)
+                  activated[other_id] = amount
+                  spread_recursive(other_id, amount, max_depth, current_depth + 1, activated)
+                end
+              end
+
+              def each_neighbor(node_id)
+                (@adjacency[node_id] || []).each do |cid|
+                  conn = @connections[cid]
+                  next unless conn
+
+                  other_id = conn.source_id == node_id ? conn.target_id : conn.source_id
+                  target_node = @nodes[other_id]
+                  yield conn, other_id, target_node if target_node
+                end
+              end
+
+              def connection_involves?(cid, nid)
+                (c = @connections[cid]) && (c.source_id == nid || c.target_id == nid)
+              end
+
+              def prune_nodes_if_needed
+                return if @nodes.size < MAX_NODES
+
+                remove_node(node_id: @nodes.values.min_by(&:activation).id)
+              end
+
+              def prune_connections_if_needed
+                return if @connections.size < MAX_CONNECTIONS
+
+                remove_connection(@connections.values.min_by(&:weight).id)
+              end
+
+              def prune_weak_connections
+                @connections.each { |id, c| remove_connection(id) if c.weight <= MIN_WEIGHT }
+              end
+
+              def remove_connection(conn_id)
+                return unless (conn = @connections.delete(conn_id))
+
+                @adjacency[conn.source_id]&.delete(conn_id)
+                @adjacency[conn.target_id]&.delete(conn_id)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+          module Helpers
+            class SemanticNode
+              include Constants
+
+              attr_reader :id, :label, :node_type, :activation, :prime_count,
+                          :access_count, :created_at
+
+              def initialize(label:, node_type: :concept, activation: DEFAULT_ACTIVATION)
+                @id           = SecureRandom.uuid
+                @label        = label.to_s
+                @node_type    = node_type.to_sym
+                @activation   = activation.to_f.clamp(0.0, MAX_ACTIVATION).round(10)
+                @prime_count  = 0
+                @access_count = 0
+                @created_at   = Time.now.utc
+              end
+
+              def prime!(amount: PRIMING_BOOST)
+                @activation = (@activation + amount).clamp(0.0, MAX_ACTIVATION).round(10)
+                @prime_count += 1
+                self
+              end
+
+              def decay!
+                @activation = (@activation - ACTIVATION_DECAY).clamp(0.0, MAX_ACTIVATION).round(10)
+                self
+              end
+
+              def access!
+                @access_count += 1
+                self
+              end
+
+              def reset!
+                @activation = RESTING_ACTIVATION
+                self
+              end
+
+              def primed?
+                @activation >= 0.4
+              end
+
+              def active?
+                @activation > ACTIVATION_THRESHOLD
+              end
+
+              def activation_label
+                match = ACTIVATION_LABELS.find { |range, _| range.cover?(@activation) }
+                match ? match.last : :unprimed
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  label:            @label,
+                  node_type:        @node_type,
+                  activation:       @activation,
+                  activation_label: activation_label,
+                  primed:           primed?,
+                  active:           active?,
+                  prime_count:      @prime_count,
+                  access_count:     @access_count,
+                  created_at:       @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+          module Runners
+            module SemanticPriming
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def add_node(label:, node_type: :concept, engine: nil, **)
+                eng = engine || default_engine
+                node = eng.add_node(label: label, node_type: node_type)
+                { success: true, node: node.to_h }
+              end
+
+              def remove_node(node_id:, engine: nil, **)
+                eng = engine || default_engine
+                node = eng.remove_node(node_id: node_id)
+                return { success: false, error: 'node not found' } unless node
+
+                { success: true, removed: node.to_h }
+              end
+
+              def connect_nodes(source_id:, target_id:, weight: nil, engine: nil, **)
+                eng = engine || default_engine
+                w = weight || Helpers::Constants::DEFAULT_WEIGHT
+                conn = eng.connect(source_id: source_id, target_id: target_id, weight: w)
+                return { success: false, error: 'invalid nodes or self-connection' } unless conn
+
+                { success: true, connection: conn.to_h }
+              end
+
+              def prime(node_id:, amount: nil, engine: nil, **)
+                eng = engine || default_engine
+                amt = amount || Helpers::Constants::PRIMING_BOOST
+                node = eng.prime_node(node_id: node_id, amount: amt)
+                return { success: false, error: 'node not found' } unless node
+
+                { success: true, node: node.to_h }
+              end
+
+              def prime_and_spread(node_id:, amount: nil, depth: nil, engine: nil, **)
+                eng = engine || default_engine
+                amt = amount || Helpers::Constants::PRIMING_BOOST
+                d = depth || Helpers::Constants::MAX_SPREAD_DEPTH
+                result = eng.prime_and_spread(node_id: node_id, amount: amt, depth: d)
+                return { success: false, error: 'node not found' } unless result
+
+                { success: true, **result }
+              end
+
+              def spread_activation(source_id:, depth: nil, engine: nil, **)
+                eng = engine || default_engine
+                d = depth || Helpers::Constants::MAX_SPREAD_DEPTH
+                result = eng.spread_activation(source_id: source_id, depth: d)
+                return { success: false, error: 'node not found' } unless result
+
+                { success: true, activated: result }
+              end
+
+              def decay(engine: nil, **)
+                eng = engine || default_engine
+                result = eng.decay_all!
+                { success: true, **result }
+              end
+
+              def reset(engine: nil, **)
+                eng = engine || default_engine
+                result = eng.reset_all!
+                { success: true, **result }
+              end
+
+              def find_node(label:, engine: nil, **)
+                eng = engine || default_engine
+                node = eng.find_node_by_label(label: label)
+                return { success: false, error: 'node not found' } unless node
+
+                { success: true, node: node.to_h }
+              end
+
+              def neighbors(node_id:, engine: nil, **)
+                eng = engine || default_engine
+                nodes = eng.neighbors(node_id: node_id)
+                { success: true, neighbors: nodes.map(&:to_h) }
+              end
+
+              def primed_nodes(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, nodes: eng.primed_nodes.map(&:to_h) }
+              end
+
+              def most_primed(limit: 5, engine: nil, **)
+                eng = engine || default_engine
+                { success: true, nodes: eng.most_primed(limit: limit).map(&:to_h) }
+              end
+
+              def priming_report(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, report: eng.priming_report }
+              end
+
+              def status(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, **eng.to_h }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::PrimingNetwork.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'semantic_priming/version'
+require_relative 'semantic_priming/helpers/constants'
+require_relative 'semantic_priming/helpers/semantic_node'
+require_relative 'semantic_priming/helpers/connection'
+require_relative 'semantic_priming/helpers/priming_network'
+require_relative 'semantic_priming/runners/semantic_priming'
+require_relative 'semantic_priming/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticPriming
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/semantic_satiation/helpers/constants'
+require 'legion/extensions/agentic/memory/semantic_satiation/helpers/concept'
+require 'legion/extensions/agentic/memory/semantic_satiation/helpers/satiation_engine'
+require 'legion/extensions/agentic/memory/semantic_satiation/runners/semantic_satiation'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticSatiation
+          class Client
+            include Runners::SemanticSatiation
+
+            def initialize(**)
+              @satiation_engine = Helpers::SatiationEngine.new
+            end
+
+            private
+
+            attr_reader :satiation_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticSatiation
+          module Helpers
+            class Concept
+              include Constants
+
+              attr_reader :id, :label, :domain, :fluency, :exposure_count,
+                          :last_exposed_at, :created_at
+
+              def initialize(label:, domain: :general)
+                @id             = SecureRandom.uuid
+                @label          = label
+                @domain         = domain
+                @fluency        = DEFAULT_FLUENCY
+                @exposure_count = 0
+                @last_exposed_at = nil
+                @created_at      = Time.now.utc
+              end
+
+              def expose!
+                @exposure_count += 1
+                @fluency = (@fluency - SATIATION_RATE).clamp(0.0, DEFAULT_FLUENCY).round(10)
+                @last_exposed_at = Time.now.utc
+              end
+
+              def recover!(amount: RECOVERY_RATE)
+                @fluency = (@fluency + amount).clamp(0.0, DEFAULT_FLUENCY).round(10)
+              end
+
+              def satiated?
+                fluency < (DEFAULT_FLUENCY - SATIATION_THRESHOLD)
+              end
+
+              def fluency_label
+                FLUENCY_LABELS.find { |range, _| range.cover?(fluency) }&.last || :meaningless
+              end
+
+              def novelty
+                saturation = [exposure_count.to_f / 50.0, 1.0].min
+                (DEFAULT_FLUENCY - saturation).clamp(0.0, DEFAULT_FLUENCY).round(10)
+              end
+
+              def novelty_label
+                n = novelty
+                NOVELTY_LABELS.find { |range, _| range.cover?(n) }&.last || :saturated
+              end
+
+              def time_since_exposure
+                return nil unless last_exposed_at
+
+                Time.now.utc - last_exposed_at
+              end
+
+              def to_h
+                {
+                  id:              id,
+                  label:           label,
+                  domain:          domain,
+                  fluency:         fluency,
+                  fluency_label:   fluency_label,
+                  novelty:         novelty,
+                  novelty_label:   novelty_label,
+                  exposure_count:  exposure_count,
+                  satiated:        satiated?,
+                  last_exposed_at: last_exposed_at,
+                  created_at:      created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticSatiation
+          module Helpers
+            module Constants
+              MAX_CONCEPTS        = 300
+              SATIATION_RATE      = 0.08
+              RECOVERY_RATE       = 0.03
+              SATIATION_THRESHOLD = 0.7
+              DEFAULT_FLUENCY     = 1.0
+
+              FLUENCY_LABELS = {
+                (0.8..)     => :fluent,
+                (0.6...0.8) => :normal,
+                (0.4...0.6) => :reduced,
+                (0.2...0.4) => :satiated,
+                (..0.2)     => :meaningless
+              }.freeze
+
+              NOVELTY_LABELS = {
+                (0.8..)     => :novel,
+                (0.6...0.8) => :familiar,
+                (0.4...0.6) => :routine,
+                (0.2...0.4) => :overexposed,
+                (..0.2)     => :saturated
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/semantic_satiation/helpers/satiation_engine.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module SemanticSatiation
+          module Helpers
+            class SatiationEngine
+              include Constants
+
+              attr_reader :concepts
+
+              def initialize
+                @concepts = {}
+              end
+
+              def register_concept(label:, domain: :general)
+                prune_saturated if @concepts.size >= MAX_CONCEPTS
+
+                existing = find_by_label(label)
+                return existing if existing
+
+                concept = Concept.new(label: label, domain: domain)
+                @concepts[concept.id] = concept
+                concept
+              end
+
+              def expose_concept(concept_id:)
+                concept = @concepts[concept_id]
+                return { error: :not_found, concept_id: concept_id } unless concept
+
+                concept.expose!
+                concept.to_h
+              end
+
+              def expose_by_label(label:, domain: :general)
+                concept = find_by_label(label) || register_concept(label: label, domain: domain)
+                concept.expose!
+                concept.to_h
+              end
+
+              def recover_all
+                @concepts.each_value(&:recover!)
+                { recovered: @concepts.size }
+              end
+
+              def satiated_concepts
+                @concepts.values.select(&:satiated?)
+              end
+
+              def most_exposed(limit: 5)
+                @concepts.values.sort_by { |c| -c.exposure_count }.first(limit)
+              end
+
+              def freshest(limit: 5)
+                @concepts.values.sort_by { |c| -c.fluency }.first(limit)
+              end
+
+              def domain_satiation(domain:)
+                domain_concepts = @concepts.values.select { |c| c.domain == domain }
+                return 0.0 if domain_concepts.empty?
+
+                avg = domain_concepts.sum(&:fluency) / domain_concepts.size.to_f
+                avg.round(10)
+              end
+
+              def novelty_report
+                distribution = Hash.new(0)
+                @concepts.each_value do |c|
+                  distribution[c.novelty_label] += 1
+                end
+                distribution
+              end
+
+              def prune_saturated
+                to_remove = @concepts.select { |_, c| c.fluency <= 0.05 }.keys
+                to_remove.each { |id| @concepts.delete(id) }
+                to_remove.size
+              end
+
+              def to_h
+                {
+                  concept_count:  @concepts.size,
+                  satiated_count: satiated_concepts.size,
+                  novelty_report: novelty_report,
+                  most_exposed:   most_exposed.map(&:to_h),
+                  freshest:       freshest.map(&:to_h)
+                }
+              end
+
+              private
+
+              def find_by_label(label)
+                @concepts.values.find { |c| c.label == label }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end