lex-memory 0.1.2

data/lib/legion/extensions/memory/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/memory/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/memory/runners/consolidation.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Memory
+      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::Memory.shared_store
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Memory
+      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::Memory.shared_store
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/memory.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/memory/version'
+require 'legion/extensions/memory/helpers/trace'
+require 'legion/extensions/memory/helpers/decay'
+require 'legion/extensions/memory/helpers/store'
+require 'legion/extensions/memory/helpers/cache_store'
+require 'legion/extensions/memory/helpers/error_tracer'
+require 'legion/extensions/memory/runners/traces'
+require 'legion/extensions/memory/runners/consolidation'
+require 'legion/extensions/memory/client'
+
+module Legion
+  module Extensions
+    module Memory
+      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
+
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end
+
+if defined?(Legion::Data::Local)
+  Legion::Data::Local.register_migrations(
+    name: :memory,
+    path: File.join(__dir__, 'memory', 'local_migrations')
+  )
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: lex-memory
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Memory trace system for brain-modeled agentic AI — consolidation, reinforcement,
+  and decay
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-memory.gemspec
+- lib/legion/extensions/memory.rb
+- lib/legion/extensions/memory/actors/decay.rb
+- lib/legion/extensions/memory/actors/tier_migration.rb
+- lib/legion/extensions/memory/client.rb
+- lib/legion/extensions/memory/helpers/cache_store.rb
+- lib/legion/extensions/memory/helpers/decay.rb
+- lib/legion/extensions/memory/helpers/error_tracer.rb
+- lib/legion/extensions/memory/helpers/store.rb
+- lib/legion/extensions/memory/helpers/trace.rb
+- lib/legion/extensions/memory/local_migrations/20260316000001_create_memory_traces.rb
+- lib/legion/extensions/memory/local_migrations/20260316000002_create_memory_associations.rb
+- lib/legion/extensions/memory/runners/consolidation.rb
+- lib/legion/extensions/memory/runners/traces.rb
+- lib/legion/extensions/memory/version.rb
+homepage: https://github.com/LegionIO/lex-memory
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-memory
+  source_code_uri: https://github.com/LegionIO/lex-memory
+  documentation_uri: https://github.com/LegionIO/lex-memory
+  changelog_uri: https://github.com/LegionIO/lex-memory
+  bug_tracker_uri: https://github.com/LegionIO/lex-memory/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Memory
+test_files: []