lex-agentic-memory 0.1.0

data/lib/legion/extensions/agentic/memory/trace/helpers/trace.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Helpers
+            module Trace
+              TRACE_TYPES = %i[firmware identity procedural trust semantic episodic sensory].freeze
+
+              ORIGINS = %i[firmware direct_experience mesh_transfer imprint].freeze
+
+              STORAGE_TIERS = %i[hot warm cold erased].freeze
+
+              BASE_DECAY_RATES = {
+                firmware:   0.000,
+                identity:   0.001,
+                procedural: 0.005,
+                trust:      0.008,
+                semantic:   0.010,
+                episodic:   0.020,
+                sensory:    0.100
+              }.freeze
+
+              STARTING_STRENGTHS = {
+                firmware:   1.000,
+                identity:   1.000,
+                procedural: 0.400,
+                trust:      0.300,
+                semantic:   0.500,
+                episodic:   0.600,
+                sensory:    0.400
+              }.freeze
+
+              # Tuning constants from spec Section 4.5
+              E_WEIGHT                = 0.3   # emotional intensity weight on decay
+              R_AMOUNT                = 0.10  # base reinforcement amount
+              IMPRINT_MULTIPLIER      = 3.0   # reinforcement boost during imprint window
+              AUTO_FIRE_THRESHOLD     = 0.85  # procedural auto-fire strength threshold
+              ARCHIVE_THRESHOLD       = 0.05  # below this, trace moves to cold storage
+              PRUNE_THRESHOLD         = 0.01  # below this, trace eligible for removal
+              HOT_TIER_WINDOW         = 86_400    # 24 hours in seconds
+              WARM_TIER_WINDOW        = 7_776_000 # 90 days in seconds
+              RETRIEVAL_RECENCY_HALF  = 3600      # half-life for recency scoring (1 hour)
+              ASSOCIATION_BONUS       = 0.15  # bonus for Hebbian-associated traces
+              MAX_ASSOCIATIONS        = 20    # max Hebbian links per trace
+              COACTIVATION_THRESHOLD  = 3     # co-activations before Hebbian link forms
+
+              module_function
+
+              def new_trace(type:, content_payload:, content_embedding: nil, emotional_valence: 0.0, # rubocop:disable Metrics/ParameterLists
+                            emotional_intensity: 0.0, domain_tags: [], origin: :direct_experience,
+                            source_agent_id: nil, partition_id: nil, imprint_active: false,
+                            unresolved: false, consolidation_candidate: false, confidence: nil, **)
+                raise ArgumentError, "invalid trace type: #{type}" unless TRACE_TYPES.include?(type)
+                raise ArgumentError, "invalid origin: #{origin}" unless ORIGINS.include?(origin)
+
+                now = Time.now.utc
+
+                {
+                  trace_id:                SecureRandom.uuid,
+                  trace_type:              type,
+                  content_embedding:       content_embedding,
+                  content_payload:         content_payload,
+                  strength:                STARTING_STRENGTHS[type],
+                  peak_strength:           STARTING_STRENGTHS[type],
+                  base_decay_rate:         BASE_DECAY_RATES[type],
+                  emotional_valence:       emotional_valence.clamp(-1.0, 1.0),
+                  emotional_intensity:     emotional_intensity.clamp(0.0, 1.0),
+                  domain_tags:             Array(domain_tags),
+                  origin:                  origin,
+                  source_agent_id:         source_agent_id,
+                  created_at:              now,
+                  last_reinforced:         now,
+                  last_decayed:            now,
+                  reinforcement_count:     imprint_active ? 1 : 0,
+                  confidence:              confidence || (type == :firmware ? 1.0 : 0.5),
+                  storage_tier:            :hot,
+                  partition_id:            partition_id,
+                  encryption_key_id:       nil,
+                  associated_traces:       [],
+                  parent_trace_id:         nil,
+                  child_trace_ids:         [],
+                  unresolved:              unresolved,
+                  consolidation_candidate: consolidation_candidate
+                }
+              end
+
+              def valid_trace?(trace)
+                return false unless trace.is_a?(Hash)
+                return false unless TRACE_TYPES.include?(trace[:trace_type])
+                return false unless trace[:strength].is_a?(Numeric)
+                return false unless trace[:strength].between?(0.0, 1.0)
+
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/local_migrations/20260316000001_create_memory_traces.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:memory_traces) do
+      primary_key :id
+      String :trace_id, null: false, unique: true, index: true
+      String :trace_type, null: false, index: true
+      String :content, text: true, null: false
+      Float :strength, null: false, default: 1.0
+      Float :peak_strength, null: false, default: 1.0
+      Float :base_decay_rate, null: false, default: 0.02
+      String :emotional_valence, text: true
+      Float :emotional_intensity, default: 0.0
+      String :domain_tags, text: true
+      String :origin, default: 'direct_experience'
+      DateTime :created_at, null: false
+      DateTime :last_reinforced
+      DateTime :last_decayed
+      Integer :reinforcement_count, default: 0
+      Float :confidence, default: 0.5
+      String :storage_tier, default: 'hot', index: true
+      String :partition_id, index: true
+      String :associated_traces, text: true
+      String :parent_id
+      String :child_ids, text: true
+      TrueClass :unresolved, default: false, index: true
+      TrueClass :consolidation_candidate, default: false
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/local_migrations/20260316000002_create_memory_associations.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:memory_associations) do
+      primary_key :id
+      String :trace_id_a, null: false, index: true
+      String :trace_id_b, null: false, index: true
+      Integer :coactivation_count, null: false, default: 1
+      unique %i[trace_id_a trace_id_b]
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/persistent_store.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          class PersistentStore
+            TABLE = :memory_traces
+
+            def initialize(agent_id:)
+              @agent_id = agent_id
+            end
+
+            def write(trace_type:, content:, associations: {}, confidence: 1.0)
+              return nil unless db_ready?
+
+              Legion::Data.connection[TABLE].insert(
+                agent_id:     @agent_id,
+                trace_type:   trace_type.to_s,
+                content:      content.is_a?(String) ? content : Legion::JSON.dump(content),
+                associations: Legion::JSON.dump(associations),
+                confidence:   confidence,
+                created_at:   Time.now,
+                accessed_at:  Time.now
+              )
+            end
+
+            def read(trace_type: nil, limit: 50, min_confidence: 0.0)
+              return [] unless db_ready?
+
+              ds = Legion::Data.connection[TABLE].where(agent_id: @agent_id)
+              ds = ds.where(trace_type: trace_type.to_s) if trace_type
+              ds = ds.where { confidence >= min_confidence }
+              ds.order(Sequel.desc(:accessed_at)).limit(limit).all
+            end
+
+            def touch(id)
+              return unless db_ready?
+
+              Legion::Data.connection[TABLE]
+                          .where(id: id, agent_id: @agent_id)
+                          .update(accessed_at: Time.now)
+            end
+
+            def count
+              return 0 unless db_ready?
+
+              Legion::Data.connection[TABLE].where(agent_id: @agent_id).count
+            end
+
+            def total_bytes
+              return 0 unless db_ready?
+
+              Legion::Data.connection[TABLE]
+                          .where(agent_id: @agent_id)
+                          .sum(Sequel.function(:length, :content)) || 0
+            end
+
+            def delete_lowest_confidence(count: 1)
+              return 0 unless db_ready?
+
+              ids = Legion::Data.connection[TABLE]
+                                .where(agent_id: @agent_id)
+                                .order(:confidence)
+                                .limit(count)
+                                .select(:id)
+              Legion::Data.connection[TABLE].where(id: ids).delete
+            end
+
+            def delete_least_recently_used(count: 1)
+              return 0 unless db_ready?
+
+              ids = Legion::Data.connection[TABLE]
+                                .where(agent_id: @agent_id)
+                                .order(:accessed_at)
+                                .limit(count)
+                                .select(:id)
+              Legion::Data.connection[TABLE].where(id: ids).delete
+            end
+
+            private
+
+            def db_ready?
+              defined?(Legion::Data) && Legion::Data.connection&.table_exists?(TABLE)
+            rescue StandardError
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/quota.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          class Quota
+            DEFAULTS = {
+              max_traces: 10_000,
+              max_bytes:  52_428_800, # 50MB
+              eviction:   :lru
+            }.freeze
+
+            attr_reader :max_traces, :max_bytes, :eviction
+
+            def initialize(**opts)
+              config = DEFAULTS.merge(opts)
+              @max_traces = config[:max_traces]
+              @max_bytes = config[:max_bytes]
+              @eviction = config[:eviction].to_sym
+            end
+
+            def enforce!(store)
+              evict_count = store.count - max_traces
+              evict!(store, evict_count) if evict_count.positive?
+
+              overage = store.total_bytes - max_bytes
+              evict!(store, estimate_eviction_count(overage)) if overage.positive?
+            end
+
+            def within_limits?(store)
+              store.count <= max_traces && store.total_bytes <= max_bytes
+            end
+
+            private
+
+            def evict!(store, count)
+              return if count <= 0
+
+              case eviction
+              when :lru then store.delete_least_recently_used(count: count)
+              when :lowest_confidence then store.delete_lowest_confidence(count: count)
+              end
+            end
+
+            def estimate_eviction_count(overage_bytes)
+              [(overage_bytes / 1024.0 * 10).ceil, 1].max
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/runners/consolidation.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Runners
+            module Consolidation
+              def reinforce(trace_id:, store: nil, imprint_active: false, **)
+                store ||= default_store
+                trace = store.get(trace_id)
+                return { found: false } unless trace
+                return { found: true, reinforced: false, reason: :firmware } if trace[:trace_type] == :firmware
+
+                new_strength = Helpers::Decay.compute_reinforcement(
+                  current_strength: trace[:strength], imprint_active: imprint_active
+                )
+
+                now = Time.now.utc
+                trace[:strength] = new_strength
+                trace[:peak_strength] = [trace[:peak_strength], new_strength].max
+                trace[:last_reinforced] = now
+                trace[:reinforcement_count] += 1
+
+                store.store(trace)
+
+                Legion::Logging.debug "[memory] reinforced #{trace_id[0..7]} strength=#{new_strength.round(3)}#{' (imprint 3x)' if imprint_active}"
+                { found: true, reinforced: true, trace_id: trace_id, new_strength: new_strength }
+              end
+
+              def decay_cycle(store: nil, tick_count: 1, **)
+                store ||= default_store
+                decayed = 0
+                pruned = 0
+
+                store.all_traces.each do |trace|
+                  next if trace[:base_decay_rate].zero?
+
+                  new_strength = Helpers::Decay.compute_decay(
+                    peak_strength:       trace[:peak_strength],
+                    base_decay_rate:     trace[:base_decay_rate],
+                    ticks_since_access:  tick_count,
+                    emotional_intensity: trace[:emotional_intensity]
+                  )
+
+                  if new_strength <= Helpers::Trace::PRUNE_THRESHOLD
+                    store.delete(trace[:trace_id])
+                    pruned += 1
+                  else
+                    trace[:strength] = new_strength
+                    trace[:last_decayed] = Time.now.utc
+                    store.store(trace)
+                    decayed += 1
+                  end
+                end
+
+                Legion::Logging.debug "[memory] decay cycle: decayed=#{decayed} pruned=#{pruned}"
+                { decayed: decayed, pruned: pruned }
+              end
+
+              def migrate_tier(store: nil, **)
+                store ||= default_store
+                migrated = 0
+                now = Time.now.utc
+
+                store.all_traces.each do |trace|
+                  new_tier = Helpers::Decay.compute_storage_tier(trace: trace, now: now)
+                  next if trace[:storage_tier] == new_tier
+
+                  trace[:storage_tier] = new_tier
+                  store.store(trace)
+                  migrated += 1
+                end
+
+                Legion::Logging.debug "[memory] tier migration: migrated=#{migrated}"
+                { migrated: migrated }
+              end
+
+              def hebbian_link(trace_id_a: nil, trace_id_b: nil, store: nil, **)
+                return { linked: false, reason: :missing_trace_ids } if trace_id_a.nil? || trace_id_b.nil?
+
+                store ||= default_store
+                store.record_coactivation(trace_id_a, trace_id_b)
+                Legion::Logging.debug "[memory] hebbian link #{trace_id_a[0..7]} <-> #{trace_id_b[0..7]}"
+                { linked: true }
+              end
+
+              def erase_by_type(type:, store: nil, **)
+                store ||= default_store
+                type = type.to_sym
+                traces = store.retrieve_by_type(type, min_strength: 0.0, limit: 100_000)
+                count = traces.size
+                traces.each { |t| store.delete(t[:trace_id]) }
+                Legion::Logging.info "[memory] erased #{count} traces of type=#{type}"
+                { erased: count, type: type }
+              end
+
+              def erase_by_agent(partition_id:, store: nil, **)
+                store ||= default_store
+                traces = store.all_traces.select { |t| t[:partition_id] == partition_id }
+                count = traces.size
+                traces.each { |t| store.delete(t[:trace_id]) }
+                Legion::Logging.info "[memory] erased #{count} traces for partition=#{partition_id}"
+                { erased: count, partition_id: partition_id }
+              end
+
+              private
+
+              def default_store
+                @default_store ||= Legion::Extensions::Agentic::Memory::Trace.shared_store
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/trace/runners/traces.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Runners
+            module Traces
+              def store_trace(type:, content_payload:, store: nil, **)
+                store ||= default_store
+                trace = Helpers::Trace.new_trace(type: type.to_sym, content_payload: content_payload, **)
+                store.store(trace)
+                Legion::Logging.debug "[memory] stored trace #{trace[:trace_id][0..7]} type=#{trace[:trace_type]} strength=#{trace[:strength].round(2)}"
+                { trace_id: trace[:trace_id], trace_type: trace[:trace_type], strength: trace[:strength] }
+              end
+
+              def get_trace(trace_id:, store: nil, **)
+                store ||= default_store
+                trace = store.get(trace_id)
+                Legion::Logging.debug "[memory] get trace #{trace_id[0..7]} found=#{!trace.nil?}"
+                return { found: false } unless trace
+
+                { found: true, trace: trace }
+              end
+
+              def retrieve_by_type(type:, store: nil, min_strength: 0.0, limit: 100, **)
+                store ||= default_store
+                traces = store.retrieve_by_type(type.to_sym, min_strength: min_strength, limit: limit)
+                Legion::Logging.debug "[memory] retrieve_by_type=#{type} count=#{traces.size} min_strength=#{min_strength}"
+                { count: traces.size, traces: traces }
+              end
+
+              def retrieve_by_domain(domain_tag:, store: nil, min_strength: 0.0, limit: 100, **)
+                store ||= default_store
+                traces = store.retrieve_by_domain(domain_tag, min_strength: min_strength, limit: limit)
+                Legion::Logging.debug "[memory] retrieve_by_domain=#{domain_tag} count=#{traces.size}"
+                { count: traces.size, traces: traces }
+              end
+
+              def retrieve_associated(trace_id:, store: nil, min_strength: 0.0, limit: 20, **)
+                store ||= default_store
+                traces = store.retrieve_associated(trace_id, min_strength: min_strength, limit: limit)
+                Legion::Logging.debug "[memory] retrieve_associated for #{trace_id[0..7]} count=#{traces.size}"
+                { count: traces.size, traces: traces }
+              end
+
+              def retrieve_ranked(trace_ids: [], store: nil, query_time: nil, **)
+                store ||= default_store
+                query_time ||= Time.now.utc
+                associated_set = Set.new
+
+                traces = trace_ids.filter_map { |id| store.get(id) }
+                traces.each { |t| associated_set.merge(t[:associated_traces]) }
+
+                scored = traces.map do |t|
+                  score = Helpers::Decay.compute_retrieval_score(
+                    trace: t, query_time: query_time, associated: associated_set.include?(t[:trace_id])
+                  )
+                  { trace: t, score: score }
+                end
+
+                result = scored.sort_by { |s| -s[:score] }
+                Legion::Logging.debug "[memory] retrieve_ranked ids=#{trace_ids.size} scored=#{result.size}"
+                result
+              end
+
+              def delete_trace(trace_id:, store: nil, **)
+                store ||= default_store
+                store.delete(trace_id)
+                Legion::Logging.debug "[memory] deleted trace #{trace_id[0..7]}"
+                { deleted: true, trace_id: trace_id }
+              end
+
+              def retrieve_and_reinforce(limit: 10, store: nil, **)
+                store ||= default_store
+                all = store.all_traces(min_strength: 0.1)
+                top = all.sort_by { |t| -t[:strength] }.first(limit)
+
+                top.each do |trace|
+                  next if trace[:base_decay_rate].zero? # skip firmware
+
+                  trace[:reinforcement_count] += 1
+                  trace[:last_reinforced] = Time.now.utc
+                  store.store(trace)
+                end
+
+                Legion::Logging.debug "[memory] retrieve_and_reinforce: retrieved=#{top.size} from=#{all.size} total"
+                { count: top.size, traces: top }
+              end
+
+              private
+
+              def default_store
+                @default_store ||= Legion::Extensions::Agentic::Memory::Trace.shared_store
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/trace/version'
+require 'legion/extensions/agentic/memory/trace/helpers/trace'
+require 'legion/extensions/agentic/memory/trace/helpers/decay'
+require 'legion/extensions/agentic/memory/trace/helpers/store'
+require 'legion/extensions/agentic/memory/trace/helpers/cache_store'
+require 'legion/extensions/agentic/memory/trace/helpers/error_tracer'
+require 'legion/extensions/agentic/memory/trace/runners/traces'
+require 'legion/extensions/agentic/memory/trace/runners/consolidation'
+require 'legion/extensions/agentic/memory/trace/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          class << self
+            # Process-wide shared store. All memory runners delegate here so that
+            # traces written by one component (ErrorTracer, coldstart, tick) are
+            # visible to every other component (dream cycle, cortex, predictions).
+            # CacheStore adds cross-process sharing via memcached on top of this.
+            def shared_store
+              @shared_store ||= create_store
+            end
+
+            def reset_store!
+              @shared_store = nil
+            end
+
+            private
+
+            def create_store
+              if defined?(Legion::Cache) && Legion::Cache.respond_to?(:connected?) && Legion::Cache.connected?
+                Legion::Logging.debug '[memory] Using shared CacheStore (memcached)'
+                Helpers::CacheStore.new
+              else
+                Legion::Logging.debug '[memory] Using shared in-memory Store'
+                Helpers::Store.new
+              end
+            end
+          end
+        end
+      end
+    end
+
+    if defined?(Legion::Data::Local)
+      Legion::Data::Local.register_migrations(
+        name: :memory,
+        path: File.join(__dir__, 'memory', 'local_migrations')
+      )
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/transfer/helpers/constants'
+require 'legion/extensions/agentic/memory/transfer/helpers/domain_knowledge'
+require 'legion/extensions/agentic/memory/transfer/helpers/transfer_engine'
+require 'legion/extensions/agentic/memory/transfer/runners/transfer_learning'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Transfer
+          class Client
+            include Runners::TransferLearning
+
+            def initialize(**)
+              @transfer_engine = Helpers::TransferEngine.new
+            end
+
+            private
+
+            attr_reader :transfer_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Transfer
+          module Helpers
+            module Constants
+              MAX_DOMAINS                  = 200
+              POSITIVE_TRANSFER_THRESHOLD  = 0.6
+              NEGATIVE_TRANSFER_THRESHOLD  = 0.3
+              TRANSFER_BOOST               = 0.15
+              INTERFERENCE_PENALTY         = 0.1
+
+              TRANSFER_LABELS = {
+                positive:     'positive',
+                neutral:      'neutral',
+                negative:     'negative',
+                interference: 'interference'
+              }.freeze
+
+              DISTANCE_LABELS = {
+                near:     'near',
+                moderate: 'moderate',
+                far:      'far'
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end