lex-agentic-memory 0.1.20 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4e20449f626874ab90b96c4452b4b35e4eae22e61df8fb6c9e5a51e4b0b8cd3
-  data.tar.gz: eff572db0f462ada591dcfc6e6efa2d8d3092cc43b1be6f907ddcfe9003b0cd9
+  metadata.gz: be817722cc940ed946ce77beb9a7c33b5671ea3bf84d206229cdc507dbe85f0a
+  data.tar.gz: 73c42aea2da869ecce1de5c02346320531361fd4d563884d6724cd00ffbdb9c0
 SHA512:
-  metadata.gz: e0e21635a796f9d4c9fbb2503446657d727bb01de9bb82a5b6323270611ff13c72a18bb0c520f2fb0ab3a987d5a869ca92ebf7e1e718dce0d20cd0b3712f1722
-  data.tar.gz: 0ea2e0a708e2cb8f853bc17595935a596de7e98c03955c9ce97582a7edcdc5546a22e645f9e929b05a08a43e9b52a4e4a1a45329129b1d797cea58d42f833b76
+  metadata.gz: f35dce2fc9fd3d2a1fb7e2eb9e22b2656f4b637d24d5c9635dc737075015ef3b38237b570bb279d7a73e33cfeda5b49f8bbd4b75f5bf8b2f1cd2ee6ca74315f7
+  data.tar.gz: 381973ab2893d6b5f651e62b16ae6dbfe166e8b949243ca9f8f3cc717fe58d80012e6cca5a14fce9513eb0abac9b58f8d02978c6ce1707b75afdc34eb85b7b76

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.1.22] - 2026-04-03
+
+### Changed
+- Refactor `Store#save_to_local` into `snapshot_dirty_state`, `persist_dirty_traces`, `persist_dirty_associations`, and `clear_dirty_flags` helpers to reduce cyclomatic/perceived complexity
+- Restructure `Consolidation#decay_cycle` early return to satisfy `RunnerReturnHash` cop
+- Add exception capture and logging to `Consolidation#trace_count` rescue clause
+
+## [0.1.21] - 2026-04-01
+
+### Changed
+- `ErrorTracer.record_trace` now dispatches `Trace.shared_store` writes/flushes in a background `Thread.new` — error/fatal logging hooks no longer block the calling Puma thread, regardless of store backend (Postgres, CacheStore, or in-memory)
+- Debounce check remains synchronous; only the store write and flush go async
+
 ## [0.1.20] - 2026-03-31
 
 ### Added

data/Gemfile

@@ -3,3 +3,5 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem 'rubocop-legion'

data/lex-agentic-memory.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'msgpack', '~> 1.7'
 
   spec.add_development_dependency 'rspec', '~> 3.13'
-  spec.add_development_dependency 'rubocop', '~> 1.60'
-  spec.add_development_dependency 'rubocop-legion', '~> 0.1'
-  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-legion'
+  spec.add_development_dependency 'rubocop-rspec'
 end

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

@@ -17,6 +17,10 @@ module Legion
                 'decay_cycle'
               end
 
+              def args
+                { maintenance: true }
+              end
+
               def time
                 60
               end

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

@@ -17,8 +17,12 @@ module Legion
                 def setup
                   return if @active
 
-                  @recent = {}
-                  @runner = Object.new.extend(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
+                  @recent       = {}
+                  @recent_mutex = ::Mutex.new
+                  @runner       = Object.new.extend(Legion::Extensions::Agentic::Memory::Trace::Runners::Traces)
+                  @write_queue  = ::Queue.new
+                  @worker       = ::Thread.new { drain_queue }
+                  @worker.name  = 'legion-error-tracer'
                   wrap_logging_methods
                   @active = true
                   Legion::Logging.info '[memory] ErrorTracer active — errors/fatals will become episodic traces'
@@ -30,6 +34,19 @@ module Legion
 
                 private
 
+                def drain_queue
+                  loop do
+                    payload = @write_queue.pop
+                    break if payload == :stop
+
+                    @runner.store_trace(**payload)
+                    store = @runner.send(:default_store)
+                    store.flush if store.respond_to?(:flush)
+                  rescue StandardError
+                    nil
+                  end
+                end
+
                 def wrap_logging_methods
                   original_error = Legion::Logging.method(:error)
                   original_fatal = Legion::Logging.method(:fatal)
@@ -50,23 +67,21 @@ module Legion
                 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
+                  @recent_mutex.synchronize do
+                    return if @recent[key] && (now - @recent[key]) < DEBOUNCE_WINDOW
 
-                  # Clean old entries periodically
-                  @recent.delete_if { |_, t| (now - t) > DEBOUNCE_WINDOW } if @recent.size > 500
+                    @recent[key] = now
+                    @recent.delete_if { |_, t| (now - t) > DEBOUNCE_WINDOW } if @recent.size > 500
+                  end
 
-                  # 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(
+                  @write_queue.push(
                     type:                :episodic,
                     content_payload:     message,
                     domain_tags:         ['error', component.downcase],
@@ -76,12 +91,7 @@ module Legion
                     unresolved:          true,
                     confidence:          0.9
                   )
-
-                  # Flush if cache-backed
-                  store = @runner.send(:default_store)
-                  store.flush if store.respond_to?(:flush)
-                rescue StandardError => _e
-                  # Never let trace creation break the logging pipeline
+                rescue StandardError
                   nil
                 end
               end

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

@@ -12,24 +12,24 @@ module Legion
               module_function
 
               # Cache a trace in the Redis hot tier.
-              def cache_trace(trace, tenant_id: nil)
+              def cache_trace(trace, tenant_id: nil, agent_id: nil)
                 return unless available?
 
-                tid = tenant_id || trace[:partition_id]
-                key = trace_key(tid, trace[:trace_id])
+                scope = cache_scope_id(trace, tenant_id: tenant_id, agent_id: agent_id)
+                key = trace_key(scope, trace[:trace_id])
                 data = serialize_trace(trace)
                 Legion::Cache::RedisHash.hset(key, data)
                 Legion::Cache::RedisHash.expire(key, HOT_TTL)
 
-                index_key = "legion:tier:hot:#{tid}"
+                index_key = "legion:tier:hot:#{scope}"
                 Legion::Cache::RedisHash.zadd(index_key, Time.now.to_f, trace[:trace_id])
               end
 
               # Fetch a trace from the hot tier. Returns a deserialized trace hash or nil on miss.
-              def fetch_trace(trace_id, tenant_id: nil)
+              def fetch_trace(trace_id, tenant_id: nil, agent_id: nil)
                 return nil unless available?
 
-                key = trace_key(tenant_id, trace_id)
+                key = trace_key(scope_id(tenant_id: tenant_id, agent_id: agent_id), trace_id)
                 data = Legion::Cache::RedisHash.hgetall(key)
                 return nil if data.nil? || data.empty?
 
@@ -37,13 +37,14 @@ module Legion
               end
 
               # Evict a trace from the hot tier and remove it from the sorted-set index.
-              def evict_trace(trace_id, tenant_id: nil)
+              def evict_trace(trace_id, tenant_id: nil, agent_id: nil)
                 return unless available?
 
-                key = trace_key(tenant_id, trace_id)
+                scope = scope_id(tenant_id: tenant_id, agent_id: agent_id)
+                key = trace_key(scope, trace_id)
                 Legion::Cache.delete(key)
 
-                index_key = "legion:tier:hot:#{tenant_id}"
+                index_key = "legion:tier:hot:#{scope}"
                 Legion::Cache::RedisHash.zrem(index_key, trace_id)
               end
 
@@ -56,8 +57,22 @@ module Legion
               end
 
               # Build the namespaced Redis key for a trace.
-              def trace_key(tenant_id, trace_id)
-                "legion:trace:#{tenant_id}:#{trace_id}"
+              def trace_key(scope_id, trace_id)
+                "legion:trace:#{scope_id}:#{trace_id}"
+              end
+
+              def scope_id(tenant_id: nil, agent_id: nil)
+                return tenant_id if tenant_id && agent_id.nil?
+                return agent_id if agent_id && tenant_id.nil?
+
+                [tenant_id, agent_id].compact.join(':')
+              end
+
+              def cache_scope_id(trace, tenant_id: nil, agent_id: nil)
+                return scope_id(tenant_id: tenant_id, agent_id: agent_id) if agent_id
+                return tenant_id if tenant_id
+
+                trace[:partition_id]
               end
 
               # Serialize a trace hash to a string-only flat hash suitable for Redis HSET.

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

@@ -10,7 +10,7 @@ module Legion
           module Helpers
             # Write-through durable store backed by Legion::Data (PostgreSQL or MySQL).
             # All writes go directly to the database — no in-memory dirty tracking, no flush.
-            # Scoped by tenant_id so multiple agents can share the same DB tables safely.
+            # Scoped by tenant_id and agent_id so multiple agents can share the same DB tables safely.
             class PostgresStore
               TRACES_TABLE = :memory_traces
               ASSOCIATIONS_TABLE = :memory_associations
@@ -32,19 +32,19 @@ module Legion
                 else
                   ds.insert_conflict(target: :trace_id, update: row.except(:trace_id)).insert(row)
                 end
-                HotTier.cache_trace(trace, tenant_id: @tenant_id) if HotTier.available?
+                HotTier.cache_trace(trace, tenant_id: @tenant_id, agent_id: @agent_id) if HotTier.available?
                 trace[:trace_id]
               rescue StandardError => e
                 log_warn("store failed: #{e.message}")
                 nil
               end
 
-              # Retrieve a single trace by trace_id (tenant-scoped).
+              # Retrieve a single trace by trace_id (tenant/agent scoped).
               # Checks the Redis hot tier first; falls through to DB on a miss and caches the result.
               # Returns a trace hash or nil.
               def retrieve(trace_id)
                 if HotTier.available?
-                  cached = HotTier.fetch_trace(trace_id, tenant_id: @tenant_id)
+                  cached = HotTier.fetch_trace(trace_id, tenant_id: @tenant_id, agent_id: @agent_id)
                   return cached if cached
                 end
 
@@ -52,13 +52,15 @@ module Legion
 
                 row = traces_ds.where(trace_id: trace_id).first
                 trace = row ? deserialize_trace(row) : nil
-                HotTier.cache_trace(trace, tenant_id: @tenant_id) if HotTier.available? && trace
+                HotTier.cache_trace(trace, tenant_id: @tenant_id, agent_id: @agent_id) if HotTier.available? && trace
                 trace
               rescue StandardError => e
                 log_warn("retrieve failed: #{e.message}")
                 nil
               end
 
+              alias get retrieve
+
               # Retrieve traces by type, ordered by strength descending.
               def retrieve_by_type(type, limit: 100, min_strength: 0.0)
                 return [] unless db_ready?
@@ -105,7 +107,7 @@ module Legion
 
               # Delete a trace and its association rows.
               def delete(trace_id)
-                HotTier.evict_trace(trace_id, tenant_id: @tenant_id) if HotTier.available?
+                HotTier.evict_trace(trace_id, tenant_id: @tenant_id, agent_id: @agent_id) if HotTier.available?
                 return unless db_ready?
 
                 db[ASSOCIATIONS_TABLE].where(trace_id_a: trace_id).delete
@@ -121,7 +123,7 @@ module Legion
                 return unless db_ready?
 
                 db[TRACES_TABLE].where(trace_id: trace_id).update(map_update_fields(fields))
-                HotTier.evict_trace(trace_id, tenant_id: @tenant_id) if HotTier.available?
+                HotTier.evict_trace(trace_id, tenant_id: @tenant_id, agent_id: @agent_id) if HotTier.available?
               rescue StandardError => e
                 log_warn("update failed: #{e.message}")
               end
@@ -247,6 +249,15 @@ module Legion
                 retrieve_by_type(:firmware)
               end
 
+              def count
+                return 0 unless db_ready?
+
+                traces_ds.count
+              rescue StandardError => e
+                log_warn("count failed: #{e.message}")
+                0
+              end
+
               # No-op — this store is write-through; nothing to flush.
               def flush; end
 
@@ -272,9 +283,10 @@ module Legion
                 'default'
               end
 
-              # Dataset for memory_traces scoped by tenant_id (if set).
+              # Dataset for memory_traces scoped by agent_id and tenant_id (if set).
               def traces_ds
                 ds = db[TRACES_TABLE]
+                ds = ds.where(agent_id: @agent_id)
                 @tenant_id ? ds.where(tenant_id: @tenant_id) : ds
               end
 

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

@@ -13,27 +13,41 @@ module Legion
             class Store
               attr_reader :traces, :associations
 
-              def initialize
+              def initialize(partition_id: nil)
                 @mutex = Mutex.new
                 @traces = {}
                 @associations = Hash.new { |h, k| h[k] = Hash.new(0) }
+                @partition_id = partition_id || resolve_partition_id
+                @traces_dirty = false
+                @associations_dirty = false
+                @persisted_trace_rows = {}
                 load_from_local
               end
 
               def store(trace)
-                @mutex.synchronize { @traces[trace[:trace_id]] = trace }
-                trace[:trace_id]
+                persisted_trace = trace.dup
+                persisted_trace[:partition_id] ||= @partition_id
+                @mutex.synchronize do
+                  @traces_dirty = true if @traces[persisted_trace[:trace_id]] != persisted_trace
+                  @traces[persisted_trace[:trace_id]] = persisted_trace
+                end
+                persisted_trace[:trace_id]
               end
 
               def get(trace_id)
-                @traces[trace_id]
+                @mutex.synchronize { @traces[trace_id] }
               end
 
               def delete(trace_id)
                 @mutex.synchronize do
-                  @traces.delete(trace_id)
-                  @associations.delete(trace_id)
+                  removed_trace = @traces.delete(trace_id)
+                  @traces.each_value { |trace| trace[:associated_traces]&.delete(trace_id) }
+
+                  removed_links = @associations.delete(trace_id)
                   @associations.each_value { |links| links.delete(trace_id) }
+
+                  @traces_dirty = true if removed_trace
+                  @associations_dirty = true if removed_trace || removed_links
                 end
               end
 
@@ -68,9 +82,11 @@ module Legion
                 @mutex.synchronize do
                   @associations[trace_id_a][trace_id_b] += 1
                   @associations[trace_id_b][trace_id_a] += 1
+                  @associations_dirty = true
 
                   threshold = Helpers::Trace::COACTIVATION_THRESHOLD
-                  link_traces(trace_id_a, trace_id_b) if @associations[trace_id_a][trace_id_b] >= threshold
+                  @traces_dirty = true if @associations[trace_id_a][trace_id_b] >= threshold &&
+                                          link_traces(trace_id_a, trace_id_b)
                 end
               end
 
@@ -80,7 +96,7 @@ module Legion
               end
 
               def count
-                @traces.size
+                @mutex.synchronize { @traces.size }
               end
 
               def synchronize(&) = @mutex.synchronize(&)
@@ -89,6 +105,28 @@ module Legion
                 retrieve_by_type(:firmware)
               end
 
+              def flush
+                save_to_local
+              end
+
+              def restore_traces(traces)
+                snapshot = Array(traces).each_with_object({}) do |trace, memo|
+                  next unless trace.is_a?(Hash) && trace[:trace_id]
+
+                  restored = trace.dup
+                  restored[:partition_id] ||= @partition_id
+                  memo[restored[:trace_id]] = restored
+                end
+
+                @mutex.synchronize do
+                  @traces = snapshot
+                  @associations = Hash.new { |h, k| h[k] = Hash.new(0) }
+                  @traces_dirty = true
+                  @associations_dirty = true
+                end
+                flush
+              end
+
               def walk_associations(start_id:, max_hops: 12, min_strength: 0.1)
                 snapshot = @mutex.synchronize { @traces.dup }
                 return [] unless snapshot.key?(start_id)
@@ -123,49 +161,96 @@ module Legion
                 return unless Legion::Data::Local.connection.table_exists?(:memory_traces)
 
                 db = Legion::Data::Local.connection
-                traces_snapshot = @mutex.synchronize { @traces.dup }
+                snapshots = snapshot_dirty_state
+                return unless snapshots
 
-                traces_snapshot.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)
+                traces_snapshot, associations_snapshot, trace_rows_snapshot, traces_dirty, associations_dirty = snapshots
+                scoped_trace_ids = db[:memory_traces].where(partition_id: @partition_id).select_map(:trace_id)
+                memory_trace_ids = traces_snapshot.keys
+                stale_ids = persist_dirty_traces(db, trace_rows_snapshot, scoped_trace_ids, memory_trace_ids, traces_dirty)
+                persist_dirty_associations(db, associations_snapshot, scoped_trace_ids, memory_trace_ids, stale_ids, associations_dirty)
+                clear_dirty_flags(trace_rows_snapshot)
+              end
+
+              def snapshot_dirty_state
+                traces_snapshot, associations_snapshot, trace_rows_snapshot, traces_dirty, associations_dirty = @mutex.synchronize do
+                  ts = @traces.transform_values(&:dup)
+                  as = @associations.each_with_object({}) { |(tid, targets), memo| memo[tid] = targets.dup }
+                  trs = ts.transform_values { |trace| serialize_trace_for_db(trace) }
+                  [ts, as, trs, @traces_dirty || trs != @persisted_trace_rows, @associations_dirty]
+                end
+                return nil unless traces_dirty || associations_dirty
+
+                [traces_snapshot, associations_snapshot, trace_rows_snapshot, traces_dirty, associations_dirty]
+              end
+
+              def persist_dirty_traces(db, trace_rows_snapshot, scoped_trace_ids, memory_trace_ids, traces_dirty)
+                return [] unless traces_dirty
+
+                trace_rows_snapshot.each do |trace_id, row|
+                  if db[:memory_traces].where(trace_id: trace_id).first
+                    db[:memory_traces].where(trace_id: 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_snapshot.keys
-                stale_ids = db_trace_ids - memory_trace_ids
+                stale_ids = scoped_trace_ids - memory_trace_ids
                 db[:memory_traces].where(trace_id: stale_ids).delete unless stale_ids.empty?
+                stale_ids
+              end
 
-                db[:memory_associations].delete
-                @associations.each do |id_a, targets|
+              def persist_dirty_associations(db, associations_snapshot, scoped_trace_ids, memory_trace_ids, stale_ids, dirty)
+                assoc_scope_ids = (scoped_trace_ids + memory_trace_ids).uniq
+                return unless (dirty || !stale_ids.empty?) && !assoc_scope_ids.empty?
+
+                db[:memory_associations].where(trace_id_a: assoc_scope_ids).delete
+                db[:memory_associations].where(trace_id_b: assoc_scope_ids).delete
+                associations_snapshot.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 clear_dirty_flags(trace_rows_snapshot)
+                @mutex.synchronize do
+                  @traces_dirty = false
+                  @associations_dirty = false
+                  @persisted_trace_rows = trace_rows_snapshot
+                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|
+                db[:memory_traces].where(partition_id: @partition_id).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]
+                trace_ids = @traces.keys
+                unless trace_ids.empty?
+                  db[:memory_associations].where(trace_id_a: trace_ids).each do |row|
+                    @associations[row[:trace_id_a]] ||= {}
+                    @associations[row[:trace_id_a]][row[:trace_id_b]] = row[:coactivation_count]
+                  end
                 end
+
+                @persisted_trace_rows = @traces.transform_values { |trace| serialize_trace_for_db(trace) }
+                @traces_dirty = false
+                @associations_dirty = false
               end
 
               private
 
+              def resolve_partition_id
+                Legion::Settings.dig(:agent, :id) || 'default'
+              rescue StandardError => _e
+                'default'
+              end
+
               def serialize_trace_for_db(trace)
                 payload = trace[:content_payload] || trace[:content]
                 {
@@ -253,10 +338,19 @@ module Legion
                 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
+                changed = false
+
+                unless trace_a[:associated_traces].include?(id_b) || trace_a[:associated_traces].size >= max
+                  trace_a[:associated_traces] << id_b
+                  changed = true
+                end
+
+                unless trace_b[:associated_traces].include?(id_a) || trace_b[:associated_traces].size >= max
+                  trace_b[:associated_traces] << id_a
+                  changed = true
+                end
 
-                trace_b[:associated_traces] << id_a
+                changed
               end
             end
           end

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

@@ -79,7 +79,7 @@ module Legion
                   reinforcement_count:     imprint_active ? 1 : 0,
                   confidence:              confidence || (type == :firmware ? 1.0 : 0.5),
                   storage_tier:            :hot,
-                  partition_id:            partition_id,
+                  partition_id:            partition_id || default_partition_id,
                   encryption_key_id:       nil,
                   associated_traces:       [],
                   parent_trace_id:         nil,
@@ -97,6 +97,12 @@ module Legion
 
                 true
               end
+
+              def default_partition_id
+                Legion::Settings.dig(:agent, :id) || 'default'
+              rescue StandardError => _e
+                'default'
+              end
             end
           end
         end

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

@@ -24,15 +24,22 @@ module Legion
                 trace[:reinforcement_count] += 1
 
                 store.store(trace)
+                persist_store(store)
 
                 log.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, **)
+              def decay_cycle(store: nil, tick_count: 1, maintenance: true, **)
                 store ||= default_store
+                unless maintenance
+                  deferred = deferred_decay_summary(store)
+                  return { **deferred }
+                end
+
                 decayed = 0
                 pruned = 0
+                total = trace_count(store)
 
                 store.all_traces.each do |trace|
                   next if trace[:base_decay_rate].zero?
@@ -55,8 +62,20 @@ module Legion
                   end
                 end
 
+                persist_store(store) if decayed.positive? || pruned.positive?
+
+                remaining = trace_count(store)
+                summary = {
+                  decayed:       decayed,
+                  pruned:        pruned,
+                  total:         total,
+                  remaining:     remaining,
+                  maintained_at: Time.now.utc
+                }
+                Legion::Extensions::Agentic::Memory::Trace.record_maintenance_summary(summary.dup)
+
                 log.debug("[memory] decay cycle: decayed=#{decayed} pruned=#{pruned}")
-                { decayed: decayed, pruned: pruned }
+                summary
               end
 
               def migrate_tier(store: nil, **)
@@ -73,6 +92,7 @@ module Legion
                   migrated += 1
                 end
 
+                persist_store(store) if migrated.positive?
                 log.debug("[memory] tier migration: migrated=#{migrated}")
                 { migrated: migrated }
               end
@@ -82,6 +102,7 @@ module Legion
 
                 store ||= default_store
                 store.record_coactivation(trace_id_a, trace_id_b)
+                persist_store(store)
                 log.debug("[memory] hebbian link #{trace_id_a[0..7]} <-> #{trace_id_b[0..7]}")
                 { linked: true }
               end
@@ -99,6 +120,7 @@ module Legion
                 traces = store.retrieve_by_type(type, min_strength: 0.0, limit: 100_000)
                 count = traces.size
                 traces.each { |t| store.delete(t[:trace_id]) }
+                persist_store(store) if count.positive?
                 log.info("[memory] erased #{count} traces of type=#{type}")
                 { erased: count, type: type }
               end
@@ -108,12 +130,45 @@ module Legion
                 traces = store.all_traces.select { |t| t[:partition_id] == partition_id }
                 count = traces.size
                 traces.each { |t| store.delete(t[:trace_id]) }
+                persist_store(store) if count.positive?
                 log.info("[memory] erased #{count} traces for partition=#{partition_id}")
                 { erased: count, partition_id: partition_id }
               end
 
               private
 
+              def deferred_decay_summary(store)
+                summary = Legion::Extensions::Agentic::Memory::Trace.last_maintenance_summary || {}
+                current_count = trace_count(store)
+
+                {
+                  decayed:       summary[:decayed] || 0,
+                  pruned:        summary[:pruned] || 0,
+                  total:         summary[:total] || current_count,
+                  remaining:     summary[:remaining] || current_count,
+                  maintained_at: summary[:maintained_at],
+                  deferred:      true,
+                  reason:        :background_decay_actor
+                }
+              end
+
+              def trace_count(store)
+                if store.respond_to?(:count)
+                  store.count
+                else
+                  store.all_traces.size
+                end
+              rescue StandardError => e
+                log.debug("[memory] trace_count fallback: #{e.message}")
+                store.all_traces.size
+              end
+
+              def persist_store(store)
+                store.flush if store.respond_to?(:flush)
+              rescue StandardError => e
+                log.debug("[memory] persist_store skipped: #{e.message}")
+              end
+
               def default_store
                 @default_store ||= Legion::Extensions::Agentic::Memory::Trace.shared_store
               end

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

@@ -11,6 +11,7 @@ module Legion
                 store ||= default_store
                 trace = Helpers::Trace.new_trace(type: type.to_sym, content_payload: content_payload, **)
                 store.store(trace)
+                persist_store(store)
                 log.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
@@ -68,6 +69,7 @@ module Legion
               def delete_trace(trace_id:, store: nil, **)
                 store ||= default_store
                 store.delete(trace_id)
+                persist_store(store)
                 log.debug("[memory] deleted trace #{trace_id[0..7]}")
                 { deleted: true, trace_id: trace_id }
               end
@@ -85,12 +87,20 @@ module Legion
                   store.store(trace)
                 end
 
+                persist_store(store) unless top.empty?
+
                 log.debug("[memory] retrieve_and_reinforce: retrieved=#{top.size} from=#{all.size} total")
                 { count: top.size, traces: top }
               end
 
               private
 
+              def persist_store(store)
+                store.flush if store.respond_to?(:flush)
+              rescue StandardError => e
+                log.debug("[memory] persist_store skipped: #{e.message}")
+              end
+
               def default_store
                 @default_store ||= Legion::Extensions::Agentic::Memory::Trace.shared_store
               end

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

@@ -17,33 +17,62 @@ module Legion
       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.
+            # Process-wide default trace store. All memory runners delegate here so
+            # traces written by one component remain visible to the rest of the
+            # current agent runtime. Raw trace storage prefers agent-local durable
+            # state and only falls back to shared stores when explicitly requested
+            # or when local persistence is unavailable.
             def shared_store
               @shared_store ||= create_store
             end
 
+            def last_maintenance_summary
+              @maintenance_summary
+            end
+
+            def record_maintenance_summary(summary)
+              @maintenance_summary = summary
+            end
+
             def reset_store!
               @shared_store = nil
+              @maintenance_summary = nil
             end
 
             private
 
             def create_store
-              if postgres_available?
+              if local_store_available? && configured_trace_store != :shared
+                Legion::Logging.debug '[memory] Using agent-local Store (Data::Local-backed)'
+                Helpers::Store.new(partition_id: resolve_agent_id)
+              elsif postgres_available?
                 Legion::Logging.debug '[memory] Using shared PostgresStore (write-through)'
                 Helpers::PostgresStore.new(tenant_id: resolve_tenant_id, agent_id: resolve_agent_id)
               elsif 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
+                Legion::Logging.debug '[memory] Using agent-local in-memory Store'
+                Helpers::Store.new(partition_id: resolve_agent_id)
               end
             end
 
+            def configured_trace_store
+              Legion::Settings.dig(:memory, :trace_store)&.to_sym
+            rescue StandardError => _e
+              nil
+            end
+
+            def local_store_available?
+              defined?(Legion::Data::Local) &&
+                Legion::Data::Local.respond_to?(:connected?) &&
+                Legion::Data::Local.connected? &&
+                Legion::Data::Local.connection&.table_exists?(:memory_traces) &&
+                Legion::Data::Local.connection.table_exists?(:memory_associations)
+            rescue StandardError => _e
+              false
+            end
+
             def postgres_available?
               defined?(Legion::Data) &&
                 Legion::Data.respond_to?(:connection) &&

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Memory
-        VERSION = '0.1.20'
+        VERSION = '0.1.22'
       end
     end
   end

data/spec/legion/extensions/agentic/memory/trace/actors/decay_spec.rb

@@ -30,6 +30,12 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Actor::Decay do
     end
   end
 
+  describe '#args' do
+    it 'runs full maintenance when scheduled in the background' do
+      expect(actor.args).to eq({ maintenance: true })
+    end
+  end
+
   describe '#time' do
     it 'returns 60 seconds' do
       expect(actor.time).to eq(60)

data/spec/legion/extensions/agentic/memory/trace/helpers/error_tracer_spec.rb

@@ -11,13 +11,24 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer
     # Reset state between examples
     described_class.instance_variable_set(:@active, nil)
     described_class.instance_variable_set(:@recent, nil)
+    described_class.instance_variable_set(:@recent_mutex, nil)
     described_class.instance_variable_set(:@runner, nil)
+    described_class.instance_variable_set(:@write_queue, nil)
+    old_worker = described_class.instance_variable_get(:@worker)
+    old_worker&.kill
+    described_class.instance_variable_set(:@worker, nil)
   end
 
   after do
     # Restore logging singleton methods to prevent cross-test side effects
     Legion::Logging.define_singleton_method(:error, &original_error)
     Legion::Logging.define_singleton_method(:fatal, &original_fatal)
+    # Stop worker thread if still alive
+    worker = described_class.instance_variable_get(:@worker)
+    if worker&.alive?
+      described_class.instance_variable_get(:@write_queue)&.push(:stop)
+      worker.join(1)
+    end
   end
 
   describe '.setup' do
@@ -31,6 +42,13 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer
       described_class.setup
       expect(described_class.active?).to be true
     end
+
+    it 'starts a single background worker thread' do
+      described_class.setup
+      worker = described_class.instance_variable_get(:@worker)
+      expect(worker).to be_a(Thread)
+      expect(worker).to be_alive
+    end
   end
 
   describe '.active?' do
@@ -43,4 +61,114 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer
       expect(described_class.active?).to be true
     end
   end
+
+  describe 'record_trace (async dispatch via queue)' do
+    let(:store_dbl) { double('store', flush: nil) }
+    let(:runner_double) do
+      dbl = double('runner')
+      allow(dbl).to receive(:store_trace)
+      allow(dbl).to receive(:default_store).and_return(store_dbl)
+      dbl
+    end
+    let(:write_queue) { Queue.new }
+
+    before do
+      described_class.instance_variable_set(:@active, true)
+      described_class.instance_variable_set(:@recent, {})
+      described_class.instance_variable_set(:@recent_mutex, Mutex.new)
+      described_class.instance_variable_set(:@runner, runner_double)
+      described_class.instance_variable_set(:@write_queue, write_queue)
+    end
+
+    it 'enqueues a payload hash (fire-and-forget dispatch)' do
+      described_class.send(:record_trace, 'something broke', :error)
+      expect(write_queue.size).to eq(1)
+      payload = write_queue.pop
+      expect(payload).to be_a(Hash)
+    end
+
+    it 'enqueues a payload with expected keys' do
+      described_class.send(:record_trace, '[mycomponent] disk full', :error)
+      payload = write_queue.pop
+      expect(payload).to include(
+        type:            :episodic,
+        content_payload: '[mycomponent] disk full',
+        domain_tags:     %w[error mycomponent],
+        unresolved:      true
+      )
+    end
+
+    it 'uses fatal valence and intensity for :fatal level' do
+      described_class.send(:record_trace, 'total meltdown', :fatal)
+      payload = write_queue.pop
+      expect(payload).to include(
+        emotional_valence:   Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer::FATAL_VALENCE,
+        emotional_intensity: Legion::Extensions::Agentic::Memory::Trace::Helpers::ErrorTracer::FATAL_INTENSITY
+      )
+    end
+
+    it 'does not enqueue (debounced) when same message is within the window' do
+      described_class.send(:record_trace, 'repeated error', :error)
+      described_class.send(:record_trace, 'repeated error', :error)
+      expect(write_queue.size).to eq(1)
+    end
+
+    it 'returns nil for blank messages without raising' do
+      expect(described_class.send(:record_trace, '', :error)).to be_nil
+      expect(write_queue.size).to eq(0)
+    end
+
+    it 'does not propagate errors from store_trace' do
+      worker_queue = Queue.new
+      described_class.instance_variable_set(:@write_queue, worker_queue)
+      allow(runner_double).to receive(:store_trace).and_raise(StandardError, 'db down')
+
+      # rubocop:disable ThreadSafety/NewThread
+      worker = Thread.new do
+        payload = worker_queue.pop
+        break if payload == :stop
+
+        runner_double.store_trace(**payload)
+      rescue StandardError
+        nil
+      end
+      # rubocop:enable ThreadSafety/NewThread
+
+      described_class.send(:record_trace, 'store failure', :error)
+      expect { worker.join(2) }.not_to raise_error
+    end
+
+    it 'the background worker calls store_trace with the enqueued payload' do
+      dedicated_queue = Queue.new
+      described_class.instance_variable_set(:@write_queue, dedicated_queue)
+
+      # rubocop:disable ThreadSafety/NewThread
+      worker = Thread.new do
+        loop do
+          payload = dedicated_queue.pop
+          break if payload == :stop
+
+          runner_double.store_trace(**payload)
+          store = runner_double.send(:default_store)
+          store.flush if store.respond_to?(:flush)
+        rescue StandardError
+          nil
+        end
+      end
+      # rubocop:enable ThreadSafety/NewThread
+
+      described_class.send(:record_trace, '[mycomponent] disk full', :error)
+      dedicated_queue.push(:stop)
+      worker.join(2)
+
+      expect(runner_double).to have_received(:store_trace).with(
+        hash_including(
+          type:            :episodic,
+          content_payload: '[mycomponent] disk full',
+          domain_tags:     %w[error mycomponent],
+          unresolved:      true
+        )
+      )
+    end
+  end
 end

data/spec/legion/extensions/agentic/memory/trace/helpers/hot_tier_spec.rb

@@ -97,6 +97,16 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::HotTier do
     end
   end
 
+  describe '.scope_id' do
+    it 'uses tenant scope when agent_id is not provided' do
+      expect(mod.scope_id(tenant_id: 'tenant-1')).to eq('tenant-1')
+    end
+
+    it 'uses combined tenant and agent scope when both are provided' do
+      expect(mod.scope_id(tenant_id: 'tenant-1', agent_id: 'agent-1')).to eq('tenant-1:agent-1')
+    end
+  end
+
   # --- serialize_trace / deserialize_trace round-trip ---
 
   describe '.serialize_trace' do
@@ -239,6 +249,12 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::HotTier do
         expect(Legion::Cache::RedisHash).to receive(:hset).with(key, anything)
         mod.cache_trace(trace)
       end
+
+      it 'uses a combined tenant and agent scope when both are provided' do
+        key = mod.trace_key('tenant-abc:agent-1', trace_id)
+        expect(Legion::Cache::RedisHash).to receive(:hset).with(key, anything)
+        mod.cache_trace(trace, tenant_id: tenant_id, agent_id: 'agent-1')
+      end
     end
   end
 

data/spec/legion/extensions/agentic/memory/trace/helpers/postgres_store_spec.rb

@@ -179,6 +179,12 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::PostgresStor
       expect(other_store.retrieve(semantic_trace[:trace_id])).to be_nil
     end
 
+    it 'scopes retrieve to the correct agent within the same tenant' do
+      store.store(semantic_trace)
+      other_store = described_class.new(tenant_id: tenant_id, agent_id: 'other-agent')
+      expect(other_store.retrieve(semantic_trace[:trace_id])).to be_nil
+    end
+
     it 'returns nil when db not ready' do
       db.drop_table(:memory_traces)
       expect(store.retrieve(semantic_trace[:trace_id])).to be_nil
@@ -301,6 +307,13 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::PostgresStor
       expect(store.all_traces.size).to eq(1)
     end
 
+    it 'does not include traces from another agent in the same tenant' do
+      store.store(semantic_trace)
+      other = described_class.new(tenant_id: tenant_id, agent_id: 'other-agent')
+      other.store(episodic_trace)
+      expect(store.all_traces.map { |trace| trace[:trace_id] }).to eq([semantic_trace[:trace_id]])
+    end
+
     it 'returns empty array when db not ready' do
       db.drop_table(:memory_traces)
       expect(store.all_traces).to eq([])

data/spec/legion/extensions/agentic/memory/trace/helpers/store_spec.rb

@@ -15,6 +15,14 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Store do
       expect(result[:trace_type]).to eq(:semantic)
     end
 
+    it 'assigns the store partition_id when a trace does not already have one' do
+      semantic_trace[:partition_id] = nil
+
+      store.store(semantic_trace)
+      result = store.get(semantic_trace[:trace_id])
+      expect(result[:partition_id]).to eq('default')
+    end
+
     it 'returns nil for unknown trace_id' do
       expect(store.get('nonexistent')).to be_nil
     end
@@ -194,7 +202,7 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Store do
     end
 
     it 'filters by min_strength and does not traverse beyond filtered nodes' do
-      trace_b[:strength] = 0.05
+      store.traces[trace_b[:trace_id]][:strength] = 0.05
       results = store.walk_associations(start_id: trace_a[:trace_id], min_strength: 0.1)
       found_ids = results.map { |r| r[:trace_id] }
       expect(found_ids).not_to include(trace_b[:trace_id])
@@ -214,4 +222,21 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Store do
       expect(results).to eq([])
     end
   end
+
+  describe '#restore_traces' do
+    it 'replaces existing traces and clears stale associations' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+
+      replacement = trace_helper.new_trace(type: :semantic, content_payload: { fact: 'replacement' })
+      store.restore_traces([replacement])
+
+      expect(store.count).to eq(1)
+      expect(store.get(semantic_trace[:trace_id])).to be_nil
+      expect(store.associations).to be_empty
+    end
+  end
 end

data/spec/legion/extensions/agentic/memory/trace/local_persistence_spec.rb

@@ -2,6 +2,8 @@
 
 require 'sequel'
 require 'sequel/extensions/migration'
+require 'logger'
+require 'stringio'
 
 # Minimal stub for Legion::Data::Local used in persistence specs.
 # Does not require the full legion-data gem.
@@ -35,9 +37,9 @@ module Legion
         private
 
         def run_memory_migrations
-          migration_path = File.join(
-            __dir__,
-            '../lib/legion/extensions/memory/local_migrations'
+          migration_path = File.expand_path(
+            '../../../../../../lib/legion/extensions/agentic/memory/trace/local_migrations',
+            __dir__
           )
           ::Sequel::TimestampMigrator.new(@connection, migration_path).run
         end
@@ -159,6 +161,51 @@ RSpec.describe 'lex-memory local SQLite persistence' do
       expect(second_count).to eq(first_count)
     end
 
+    it 'does not rewrite association rows when only trace fields change' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+      store.save_to_local
+
+      io = StringIO.new
+      logger = Logger.new(io)
+      logger.level = Logger::DEBUG
+      Legion::Data::Local.connection.loggers << logger
+
+      store.traces[semantic_trace[:trace_id]][:strength] = 0.77
+      store.save_to_local
+
+      sql = io.string
+      expect(sql).not_to match(/DELETE FROM [`"]memory_associations[`"]/)
+      expect(sql).not_to match(/INSERT INTO [`"]memory_associations[`"]/)
+    ensure
+      Legion::Data::Local.connection.loggers.delete(logger) if logger
+    end
+
+    it 'only deletes stale rows for the current partition' do
+      other_partition = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new(partition_id: 'agent-2')
+      agent_two_trace = trace_helper.new_trace(
+        type:            :episodic,
+        content_payload: { event: 'agent 2 boot' },
+        domain_tags:     ['boot'],
+        partition_id:    'agent-2'
+      )
+
+      store.store(semantic_trace)
+      other_partition.store(agent_two_trace)
+      other_partition.save_to_local
+      store.save_to_local
+
+      store.delete(semantic_trace[:trace_id])
+      store.save_to_local
+
+      db = Legion::Data::Local.connection
+      expect(db[:memory_traces].where(partition_id: 'agent-2').count).to eq(1)
+      expect(db[:memory_traces].where(trace_id: agent_two_trace[:trace_id]).count).to eq(1)
+    end
+
     it 'is a no-op when Local is not connected' do
       allow(Legion::Data::Local).to receive(:connected?).and_return(false)
       expect { store.save_to_local }.not_to raise_error
@@ -189,6 +236,29 @@ RSpec.describe 'lex-memory local SQLite persistence' do
       expect(fresh.associations[semantic_trace[:trace_id]]).not_to be_empty
     end
 
+    it 'loads only traces for the requested partition' do
+      other_partition = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new(partition_id: 'agent-2')
+      agent_two_trace = trace_helper.new_trace(
+        type:            :episodic,
+        content_payload: { event: 'agent 2 boot' },
+        domain_tags:     ['boot'],
+        partition_id:    'agent-2'
+      )
+
+      store.store(semantic_trace)
+      other_partition.store(agent_two_trace)
+      store.save_to_local
+      other_partition.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new(partition_id: 'default')
+      other = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new(partition_id: 'agent-2')
+
+      expect(fresh.get(semantic_trace[:trace_id])).not_to be_nil
+      expect(fresh.get(agent_two_trace[:trace_id])).to be_nil
+      expect(other.get(agent_two_trace[:trace_id])).not_to be_nil
+      expect(other.get(semantic_trace[:trace_id])).to be_nil
+    end
+
     it 'is a no-op when Local is not connected' do
       allow(Legion::Data::Local).to receive(:connected?).and_return(false)
       expect { store.load_from_local }.not_to raise_error

data/spec/legion/extensions/agentic/memory/trace/memory_spec.rb

@@ -8,4 +8,31 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace do
   it 'has a version that is a string' do
     expect(Legion::Extensions::Agentic::Memory::Trace::VERSION).to be_a(String)
   end
+
+  describe '.shared_store' do
+    before { described_class.reset_store! }
+    after { described_class.reset_store! }
+
+    it 'prefers the agent-local store when local persistence is available' do
+      allow(described_class).to receive(:local_store_available?).and_return(true)
+      allow(described_class).to receive(:configured_trace_store).and_return(nil)
+      allow(described_class).to receive(:resolve_agent_id).and_return('agent-1')
+      allow(described_class::Helpers::Store).to receive(:new).with(partition_id: 'agent-1').and_return(:local_store)
+
+      expect(described_class.shared_store).to eq(:local_store)
+    end
+
+    it 'uses the shared Postgres store when trace_store is explicitly shared' do
+      allow(described_class).to receive(:local_store_available?).and_return(true)
+      allow(described_class).to receive(:configured_trace_store).and_return(:shared)
+      allow(described_class).to receive(:postgres_available?).and_return(true)
+      allow(described_class).to receive(:resolve_agent_id).and_return('agent-1')
+      allow(described_class).to receive(:resolve_tenant_id).and_return('tenant-1')
+      allow(described_class::Helpers::PostgresStore).to receive(:new)
+        .with(tenant_id: 'tenant-1', agent_id: 'agent-1')
+        .and_return(:shared_store)
+
+      expect(described_class.shared_store).to eq(:shared_store)
+    end
+  end
 end

data/spec/legion/extensions/agentic/memory/trace/runners/consolidation_spec.rb

@@ -3,6 +3,8 @@
 require 'legion/extensions/agentic/memory/trace/client'
 
 RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidation do
+  before(:each) { Legion::Extensions::Agentic::Memory::Trace.reset_store! }
+
   let(:client) { Legion::Extensions::Agentic::Memory::Trace::Client.new }
 
   describe '#reinforce' do
@@ -51,6 +53,30 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidatio
   end
 
   describe '#decay_cycle' do
+    it 'defers Gaia heartbeat decay work to the background actor when maintenance is false' do
+      client.store_trace(type: :semantic, content_payload: {})
+
+      result = client.decay_cycle(maintenance: false)
+      expect(result).to include(
+        decayed:   0,
+        pruned:    0,
+        total:     1,
+        remaining: 1,
+        deferred:  true,
+        reason:    :background_decay_actor
+      )
+    end
+
+    it 'reuses the latest maintenance summary when decay is deferred' do
+      client.store_trace(type: :semantic, content_payload: {})
+      client.decay_cycle(tick_count: 100)
+
+      result = client.decay_cycle(maintenance: false)
+      expect(result[:deferred]).to be true
+      expect(result[:total]).to be >= result[:remaining]
+      expect(result[:maintained_at]).not_to be_nil
+    end
+
     it 'decays non-firmware traces' do
       client.store_trace(type: :semantic, content_payload: {})
       client.store_trace(type: :firmware, content_payload: { directive_text: 'protect' })

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-memory
 version: !ruby/object:Gem::Version
-  version: 0.1.20
+  version: 0.1.22
 platform: ruby
 authors:
 - Esity
@@ -139,44 +139,44 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.60'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.60'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop-legion
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.26'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.26'
+        version: '0'
 description: 'LEX agentic memory domain: episodic, semantic, and working memory'
 email:
 - matthewdiverson@gmail.com