lex-agentic-memory 0.1.0

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module BatchDecay
+            DEFAULTS = {
+              rate:           0.999,
+              min_confidence: 0.01,
+              interval_hours: 1
+            }.freeze
+
+            class << self
+              def apply!(agent_id: nil, rate: DEFAULTS[:rate], min_confidence: DEFAULTS[:min_confidence])
+                return { updated: 0, evicted: 0 } unless db_ready?
+
+                conn = Legion::Data.connection
+                ds = conn[PersistentStore::TABLE]
+                ds = ds.where(agent_id: agent_id) if agent_id
+
+                updated = ds.where { confidence > min_confidence }
+                            .update(confidence: Sequel[:confidence] * rate)
+
+                evicted = ds.where { confidence <= min_confidence }.delete
+
+                { updated: updated, evicted: evicted }
+              end
+
+              private
+
+              def db_ready?
+                defined?(Legion::Data) && Legion::Data.connection&.table_exists?(PersistentStore::TABLE)
+              rescue StandardError
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+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/runners/traces'
+require 'legion/extensions/agentic/memory/trace/runners/consolidation'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          class Client
+            include Legion::Extensions::Agentic::Memory::Trace::Runners::Traces
+            include Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidation
+
+            attr_reader :store
+
+            def initialize(store: nil, **)
+              @default_store = store || Legion::Extensions::Agentic::Memory::Trace.shared_store
+            end
+
+            private
+
+            attr_reader :default_store
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Helpers
+            # Cache-backed store using Legion::Cache (Memcached/Redis).
+            # Keeps a local copy in memory, syncs to/from cache on load/flush.
+            # Call `flush` after a batch of writes, or it auto-flushes when dirty.
+            # Call `reload` to pull latest state from cache (e.g. after another process wrote).
+            class CacheStore
+              TRACES_KEY = 'legion:memory:traces'
+              ASSOC_KEY  = 'legion:memory:associations'
+              TTL        = 86_400 # 24 hours
+
+              attr_reader :traces, :associations
+
+              def initialize
+                Legion::Logging.info '[memory] CacheStore initialized (memcached-backed)'
+                @traces       = Legion::Cache.get(TRACES_KEY) || {}
+                @associations = Legion::Cache.get(ASSOC_KEY) || {}
+                @dirty        = false
+                Legion::Logging.info "[memory] CacheStore loaded #{@traces.size} traces from cache"
+              end
+
+              def store(trace)
+                @traces[trace[:trace_id]] = trace
+                @dirty = true
+                trace[:trace_id]
+              end
+
+              def get(trace_id)
+                @traces[trace_id]
+              end
+
+              def delete(trace_id)
+                @traces.delete(trace_id)
+                @associations.delete(trace_id)
+                @associations.each_value { |links| links.delete(trace_id) }
+                @dirty = true
+              end
+
+              def retrieve_by_type(type, min_strength: 0.0, limit: 100)
+                @traces.values
+                       .select { |t| t[:trace_type] == type && t[:strength] >= min_strength }
+                       .sort_by { |t| -t[:strength] }
+                       .first(limit)
+              end
+
+              def retrieve_by_domain(domain_tag, min_strength: 0.0, limit: 100)
+                @traces.values
+                       .select { |t| t[:domain_tags].include?(domain_tag) && t[:strength] >= min_strength }
+                       .sort_by { |t| -t[:strength] }
+                       .first(limit)
+              end
+
+              def retrieve_associated(trace_id, min_strength: 0.0, limit: 20)
+                trace = @traces[trace_id]
+                return [] unless trace
+
+                trace[:associated_traces]
+                  .filter_map { |id| @traces[id] }
+                  .select { |t| t[:strength] >= min_strength }
+                  .sort_by { |t| -t[:strength] }
+                  .first(limit)
+              end
+
+              def record_coactivation(trace_id_a, trace_id_b)
+                return if trace_id_a == trace_id_b
+
+                @associations[trace_id_a] ||= {}
+                @associations[trace_id_b] ||= {}
+                @associations[trace_id_a][trace_id_b] = (@associations[trace_id_a][trace_id_b] || 0) + 1
+                @associations[trace_id_b][trace_id_a] = (@associations[trace_id_b][trace_id_a] || 0) + 1
+
+                threshold = Helpers::Trace::COACTIVATION_THRESHOLD
+                link_traces(trace_id_a, trace_id_b) if @associations[trace_id_a][trace_id_b] >= threshold
+                @dirty = true
+              end
+
+              def all_traces(min_strength: 0.0)
+                @traces.values.select { |t| t[:strength] >= min_strength }
+              end
+
+              def count
+                @traces.size
+              end
+
+              def firmware_traces
+                retrieve_by_type(:firmware)
+              end
+
+              def walk_associations(start_id:, max_hops: 12, min_strength: 0.1)
+                return [] unless @traces.key?(start_id)
+
+                results = []
+                visited = Set.new([start_id])
+                queue   = [[start_id, 0, [start_id]]]
+
+                until queue.empty?
+                  current_id, depth, path = queue.shift
+                  current = @traces[current_id]
+                  next unless current
+
+                  current[:associated_traces].each do |neighbor_id|
+                    next if visited.include?(neighbor_id)
+
+                    neighbor = @traces[neighbor_id]
+                    next unless neighbor
+                    next unless neighbor[:strength] >= min_strength
+
+                    visited << neighbor_id
+                    neighbor_path = path + [neighbor_id]
+                    results << { trace_id: neighbor_id, depth: depth + 1, path: neighbor_path }
+                    queue << [neighbor_id, depth + 1, neighbor_path] if depth + 1 < max_hops
+                  end
+                end
+
+                results
+              end
+
+              # Write local state to cache
+              def flush
+                return unless @dirty
+
+                Legion::Cache.set(TRACES_KEY, @traces, TTL)
+                Legion::Cache.set(ASSOC_KEY, strip_default_procs(@associations), TTL)
+                @dirty = false
+                Legion::Logging.debug "[memory] CacheStore flushed #{@traces.size} traces to cache"
+              end
+
+              # Pull latest state from cache (after another process wrote)
+              def reload
+                @traces       = Legion::Cache.get(TRACES_KEY) || {}
+                @associations = Legion::Cache.get(ASSOC_KEY) || {}
+                @dirty        = false
+                Legion::Logging.debug "[memory] CacheStore reloaded #{@traces.size} traces from cache"
+              end
+
+              private
+
+              def strip_default_procs(hash)
+                hash.each_with_object({}) do |(k, v), plain|
+                  plain[k] = v.is_a?(Hash) ? {}.merge(v) : v
+                end
+              end
+
+              def link_traces(id_a, id_b)
+                trace_a = @traces[id_a]
+                trace_b = @traces[id_b]
+                return unless trace_a && trace_b
+
+                max = Helpers::Trace::MAX_ASSOCIATIONS
+                trace_a[:associated_traces] << id_b unless trace_a[:associated_traces].include?(id_b) || trace_a[:associated_traces].size >= max
+                return if trace_b[:associated_traces].include?(id_a) || trace_b[:associated_traces].size >= max
+
+                trace_b[:associated_traces] << id_a
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Helpers
+            module Decay
+              module_function
+
+              # Power-law decay formula from spec:
+              # new_strength = peak_strength * (ticks_since_access + 1)^(-base_decay_rate / (1 + emotional_intensity * E_WEIGHT))
+              def compute_decay(peak_strength:, base_decay_rate:, ticks_since_access:, emotional_intensity: 0.0, **)
+                return peak_strength if base_decay_rate.zero?
+                return 0.0 if peak_strength.zero?
+
+                e_weight = Helpers::Trace::E_WEIGHT
+                effective_rate = base_decay_rate / (1.0 + (emotional_intensity * e_weight))
+                new_strength = peak_strength * ((ticks_since_access + 1).to_f**(-effective_rate))
+                new_strength.clamp(0.0, 1.0)
+              end
+
+              # Reinforcement formula from spec:
+              # new_strength = min(1.0, current_strength + R_AMOUNT * IMPRINT_MULTIPLIER_if_applicable)
+              def compute_reinforcement(current_strength:, imprint_active: false, **)
+                r_amount = Helpers::Trace::R_AMOUNT
+                multiplier = imprint_active ? Helpers::Trace::IMPRINT_MULTIPLIER : 1.0
+                new_strength = current_strength + (r_amount * multiplier)
+                new_strength.clamp(0.0, 1.0)
+              end
+
+              # Composite retrieval score from spec:
+              # score = strength * recency_factor * emotional_weight * (1 + association_bonus)
+              def compute_retrieval_score(trace:, query_time: nil, associated: false, **)
+                query_time ||= Time.now.utc
+                seconds_since = [query_time - trace[:last_reinforced], 0].max
+                half_life = Helpers::Trace::RETRIEVAL_RECENCY_HALF.to_f
+
+                recency_factor = 2.0**(-seconds_since / half_life)
+                emotional_weight = 1.0 + trace[:emotional_intensity]
+                assoc_bonus = associated ? (1.0 + Helpers::Trace::ASSOCIATION_BONUS) : 1.0
+
+                trace[:strength] * recency_factor * emotional_weight * assoc_bonus
+              end
+
+              # Determine storage tier based on last access time
+              def compute_storage_tier(trace:, now: nil, **)
+                now ||= Time.now.utc
+                seconds_since = now - trace[:last_reinforced]
+
+                if trace[:strength] <= Helpers::Trace::PRUNE_THRESHOLD
+                  :erased
+                elsif seconds_since <= Helpers::Trace::HOT_TIER_WINDOW
+                  :hot
+                elsif seconds_since <= Helpers::Trace::WARM_TIER_WINDOW
+                  :warm
+                else
+                  :cold
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Helpers
+            module ErrorTracer
+              DEBOUNCE_WINDOW = 60 # seconds
+              ERROR_VALENCE   = -0.6
+              ERROR_INTENSITY = 0.7
+              FATAL_VALENCE   = -0.8
+              FATAL_INTENSITY = 0.9
+
+              class << self
+                def setup
+                  return if @active
+
+                  @recent = {}
+                  @runner = Object.new.extend(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
+                  wrap_logging_methods
+                  @active = true
+                  Legion::Logging.info '[memory] ErrorTracer active — errors/fatals will become episodic traces'
+                end
+
+                def active?
+                  @active == true
+                end
+
+                private
+
+                def wrap_logging_methods
+                  original_error = Legion::Logging.method(:error)
+                  original_fatal = Legion::Logging.method(:fatal)
+
+                  Legion::Logging.define_singleton_method(:error) do |message = nil, &block|
+                    message = block.call if message.nil? && block
+                    original_error.call(message)
+                    ErrorTracer.send(:record_trace, message, :error) if message.is_a?(String)
+                  end
+
+                  Legion::Logging.define_singleton_method(:fatal) do |message = nil, &block|
+                    message = block.call if message.nil? && block
+                    original_fatal.call(message)
+                    ErrorTracer.send(:record_trace, message, :fatal) if message.is_a?(String)
+                  end
+                end
+
+                def record_trace(message, level)
+                  return unless message.is_a?(String) && !message.empty?
+
+                  # Debounce: skip if same message within window
+                  now = Time.now.utc
+                  key = "#{level}:#{message[0..100]}"
+                  return if @recent[key] && (now - @recent[key]) < DEBOUNCE_WINDOW
+
+                  @recent[key] = now
+
+                  # Clean old entries periodically
+                  @recent.delete_if { |_, t| (now - t) > DEBOUNCE_WINDOW } if @recent.size > 500
+
+                  # Extract component from [bracket] prefix
+                  component = message.match(/\A\[([^\]]+)\]/)&.captures&.first || 'unknown'
+
+                  valence   = level == :fatal ? FATAL_VALENCE : ERROR_VALENCE
+                  intensity = level == :fatal ? FATAL_INTENSITY : ERROR_INTENSITY
+
+                  @runner.store_trace(
+                    type:                :episodic,
+                    content_payload:     message,
+                    domain_tags:         ['error', component.downcase],
+                    origin:              :direct_experience,
+                    emotional_valence:   valence,
+                    emotional_intensity: intensity,
+                    unresolved:          true,
+                    confidence:          0.9
+                  )
+
+                  # Flush if cache-backed
+                  store = @runner.send(:default_store)
+                  store.flush if store.respond_to?(:flush)
+                rescue StandardError
+                  # Never let trace creation break the logging pipeline
+                  nil
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Helpers
+            # In-memory store for development and testing.
+            # Production deployments should use a PostgreSQL + Redis backed store.
+            class Store
+              attr_reader :traces, :associations
+
+              def initialize
+                @traces = {}
+                @associations = Hash.new { |h, k| h[k] = Hash.new(0) }
+                load_from_local
+              end
+
+              def store(trace)
+                @traces[trace[:trace_id]] = trace
+                trace[:trace_id]
+              end
+
+              def get(trace_id)
+                @traces[trace_id]
+              end
+
+              def delete(trace_id)
+                @traces.delete(trace_id)
+                @associations.delete(trace_id)
+                @associations.each_value { |links| links.delete(trace_id) }
+              end
+
+              def retrieve_by_type(type, min_strength: 0.0, limit: 100)
+                @traces.values
+                       .select { |t| t[:trace_type] == type && t[:strength] >= min_strength }
+                       .sort_by { |t| -t[:strength] }
+                       .first(limit)
+              end
+
+              def retrieve_by_domain(domain_tag, min_strength: 0.0, limit: 100)
+                @traces.values
+                       .select { |t| t[:domain_tags].include?(domain_tag) && t[:strength] >= min_strength }
+                       .sort_by { |t| -t[:strength] }
+                       .first(limit)
+              end
+
+              def retrieve_associated(trace_id, min_strength: 0.0, limit: 20)
+                trace = @traces[trace_id]
+                return [] unless trace
+
+                trace[:associated_traces]
+                  .filter_map { |id| @traces[id] }
+                  .select { |t| t[:strength] >= min_strength }
+                  .sort_by { |t| -t[:strength] }
+                  .first(limit)
+              end
+
+              def record_coactivation(trace_id_a, trace_id_b)
+                return if trace_id_a == trace_id_b
+
+                @associations[trace_id_a][trace_id_b] += 1
+                @associations[trace_id_b][trace_id_a] += 1
+
+                threshold = Helpers::Trace::COACTIVATION_THRESHOLD
+
+                return unless @associations[trace_id_a][trace_id_b] >= threshold
+
+                link_traces(trace_id_a, trace_id_b)
+              end
+
+              def all_traces(min_strength: 0.0)
+                @traces.values.select { |t| t[:strength] >= min_strength }
+              end
+
+              def count
+                @traces.size
+              end
+
+              def firmware_traces
+                retrieve_by_type(:firmware)
+              end
+
+              def walk_associations(start_id:, max_hops: 12, min_strength: 0.1)
+                return [] unless @traces.key?(start_id)
+
+                results  = []
+                visited  = Set.new([start_id])
+                queue    = [[start_id, 0, [start_id]]]
+
+                until queue.empty?
+                  current_id, depth, path = queue.shift
+                  next unless (current = @traces[current_id])
+
+                  current[:associated_traces].each do |neighbor_id|
+                    next if visited.include?(neighbor_id)
+
+                    neighbor = @traces[neighbor_id]
+                    next unless neighbor
+                    next unless neighbor[:strength] >= min_strength
+
+                    visited << neighbor_id
+                    neighbor_path = path + [neighbor_id]
+                    results << { trace_id: neighbor_id, depth: depth + 1, path: neighbor_path }
+                    queue << [neighbor_id, depth + 1, neighbor_path] if depth + 1 < max_hops
+                  end
+                end
+
+                results
+              end
+
+              def save_to_local
+                return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+                return unless Legion::Data::Local.connection.table_exists?(:memory_traces)
+
+                db = Legion::Data::Local.connection
+
+                @traces.each_value do |trace|
+                  row = serialize_trace_for_db(trace)
+                  existing = db[:memory_traces].where(trace_id: trace[:trace_id]).first
+                  if existing
+                    db[:memory_traces].where(trace_id: trace[:trace_id]).update(row)
+                  else
+                    db[:memory_traces].insert(row)
+                  end
+                end
+
+                db_trace_ids = db[:memory_traces].select_map(:trace_id)
+                memory_trace_ids = @traces.keys
+                stale_ids = db_trace_ids - memory_trace_ids
+                db[:memory_traces].where(trace_id: stale_ids).delete unless stale_ids.empty?
+
+                db[:memory_associations].delete
+                @associations.each do |id_a, targets|
+                  targets.each do |id_b, count|
+                    db[:memory_associations].insert(trace_id_a: id_a, trace_id_b: id_b, coactivation_count: count)
+                  end
+                end
+              end
+
+              def load_from_local
+                return unless defined?(Legion::Data::Local) && Legion::Data::Local.connected?
+                return unless Legion::Data::Local.connection.table_exists?(:memory_traces)
+
+                db = Legion::Data::Local.connection
+
+                db[:memory_traces].each do |row|
+                  @traces[row[:trace_id]] = deserialize_trace_from_db(row)
+                end
+
+                db[:memory_associations].each do |row|
+                  @associations[row[:trace_id_a]] ||= {}
+                  @associations[row[:trace_id_a]][row[:trace_id_b]] = row[:coactivation_count]
+                end
+              end
+
+              private
+
+              def serialize_trace_for_db(trace)
+                payload = trace[:content_payload] || trace[:content]
+                {
+                  trace_id:                trace[:trace_id],
+                  trace_type:              trace[:trace_type].to_s,
+                  content:                 payload.is_a?(Hash) ? ::JSON.generate(payload) : payload.to_s,
+                  strength:                trace[:strength],
+                  peak_strength:           trace[:peak_strength],
+                  base_decay_rate:         trace[:base_decay_rate],
+                  emotional_valence:       trace[:emotional_valence].is_a?(Hash) ? ::JSON.generate(trace[:emotional_valence]) : nil,
+                  emotional_intensity:     trace[:emotional_intensity],
+                  domain_tags:             trace[:domain_tags].is_a?(Array) ? ::JSON.generate(trace[:domain_tags]) : nil,
+                  origin:                  trace[:origin].to_s,
+                  created_at:              trace[:created_at],
+                  last_reinforced:         trace[:last_reinforced],
+                  last_decayed:            trace[:last_decayed],
+                  reinforcement_count:     trace[:reinforcement_count],
+                  confidence:              trace[:confidence],
+                  storage_tier:            trace[:storage_tier].to_s,
+                  partition_id:            trace[:partition_id],
+                  associated_traces:       trace[:associated_traces].is_a?(Array) ? ::JSON.generate(trace[:associated_traces]) : nil,
+                  parent_id:               trace[:parent_trace_id] || trace[:parent_id],
+                  child_ids:               (trace[:child_trace_ids] || trace[:child_ids]).then do |v|
+                                             v.is_a?(Array) ? ::JSON.generate(v) : nil
+                                           end,
+                  unresolved:              trace[:unresolved] || false,
+                  consolidation_candidate: trace[:consolidation_candidate] || false
+                }
+              end
+
+              def deserialize_trace_from_db(row)
+                content_raw = row[:content]
+                content = begin
+                  parsed = ::JSON.parse(content_raw, symbolize_names: true)
+                  parsed.is_a?(Hash) ? parsed : content_raw
+                rescue StandardError
+                  content_raw
+                end
+                {
+                  trace_id:                row[:trace_id],
+                  trace_type:              row[:trace_type]&.to_sym,
+                  content_payload:         content,
+                  content:                 content,
+                  strength:                row[:strength],
+                  peak_strength:           row[:peak_strength],
+                  base_decay_rate:         row[:base_decay_rate],
+                  emotional_valence:       begin
+                    ::JSON.parse(row[:emotional_valence], symbolize_names: true)
+                  rescue StandardError
+                    0.0
+                  end,
+                  emotional_intensity:     row[:emotional_intensity],
+                  domain_tags:             begin
+                    ::JSON.parse(row[:domain_tags])
+                  rescue StandardError
+                    []
+                  end,
+                  origin:                  row[:origin]&.to_sym,
+                  created_at:              row[:created_at],
+                  last_reinforced:         row[:last_reinforced],
+                  last_decayed:            row[:last_decayed],
+                  reinforcement_count:     row[:reinforcement_count],
+                  confidence:              row[:confidence],
+                  storage_tier:            row[:storage_tier]&.to_sym,
+                  partition_id:            row[:partition_id],
+                  associated_traces:       begin
+                    ::JSON.parse(row[:associated_traces])
+                  rescue StandardError
+                    []
+                  end,
+                  parent_trace_id:         row[:parent_id],
+                  child_trace_ids:         begin
+                    ::JSON.parse(row[:child_ids])
+                  rescue StandardError
+                    []
+                  end,
+                  unresolved:              row[:unresolved] || false,
+                  consolidation_candidate: row[:consolidation_candidate] || false
+                }
+              end
+
+              def link_traces(id_a, id_b)
+                trace_a = @traces[id_a]
+                trace_b = @traces[id_b]
+                return unless trace_a && trace_b
+
+                max = Helpers::Trace::MAX_ASSOCIATIONS
+                trace_a[:associated_traces] << id_b unless trace_a[:associated_traces].include?(id_b) || trace_a[:associated_traces].size >= max
+                return if trace_b[:associated_traces].include?(id_a) || trace_b[:associated_traces].size >= max
+
+                trace_b[:associated_traces] << id_a
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end