lex-agentic-memory 0.1.21 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f403d34cba75eaf3f800a8852c8d6e16d2f56924b2454b7c444a0cee82a00f04
-  data.tar.gz: f946558e6cf3103bc32bf44d9accb9a4c3a13d91342e7a06a5f6b5ec98c0c856
+  metadata.gz: be817722cc940ed946ce77beb9a7c33b5671ea3bf84d206229cdc507dbe85f0a
+  data.tar.gz: 73c42aea2da869ecce1de5c02346320531361fd4d563884d6724cd00ffbdb9c0
 SHA512:
-  metadata.gz: e49ff76e259d4237f19a7998f8e973438ebcfceb44322990a6213f35bd07481adfea5f8cd037c351217af569931f2344ceb04b5603bc53cadd5c27d02cec4cbe
-  data.tar.gz: 28a6d1d21d23f0ba91d034b441ee7e858fc51d1d1662e9445b58ac215e09dd271871f90941121d04566e259d971cf6d615c56412ccf2cd9f08e5658e1dd20f0f
+  metadata.gz: f35dce2fc9fd3d2a1fb7e2eb9e22b2656f4b637d24d5c9635dc737075015ef3b38237b570bb279d7a73e33cfeda5b49f8bbd4b75f5bf8b2f1cd2ee6ca74315f7
+  data.tar.gz: 381973ab2893d6b5f651e62b16ae6dbfe166e8b949243ca9f8f3cc717fe58d80012e6cca5a14fce9513eb0abac9b58f8d02978c6ce1707b75afdc34eb85b7b76

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

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/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.21'
+        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/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.21
+  version: 0.1.22
 platform: ruby
 authors:
 - Esity