lex-agentic-memory 0.1.19 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 440d04008d2af919b940d155b035cf4d1cac9d8e67361792008b166504ed9a2a
-  data.tar.gz: 0f0d8fade5d070d635b707e792501d9b88624205940b32b9babf194c33970620
+  metadata.gz: f403d34cba75eaf3f800a8852c8d6e16d2f56924b2454b7c444a0cee82a00f04
+  data.tar.gz: f946558e6cf3103bc32bf44d9accb9a4c3a13d91342e7a06a5f6b5ec98c0c856
 SHA512:
-  metadata.gz: d6695c59a99700fb47490bafbf29e9749fca9f9b523d38ec67ee31f3a522f633fc0c5a36d0cdbd6f362e6bbb78ac35a896a2bcf9023f16a3c3d6d9cb25ea6279
-  data.tar.gz: 7e79c8329c3de95c22a832144d729c5430586048727a88762698df887fb8b9a06689391f9539ac081375082b19e76b8805dcb807554d7f30df342cd3b1eb00f1
+  metadata.gz: e49ff76e259d4237f19a7998f8e973438ebcfceb44322990a6213f35bd07481adfea5f8cd037c351217af569931f2344ceb04b5603bc53cadd5c27d02cec4cbe
+  data.tar.gz: 28a6d1d21d23f0ba91d034b441ee7e858fc51d1d1662e9445b58ac215e09dd271871f90941121d04566e259d971cf6d615c56412ccf2cd9f08e5658e1dd20f0f

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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
+- CommunicationPattern sub-module for Phase C relational intelligence
+- PatternAnalyzer: time-of-day/day-of-week histograms, channel preference, topic clustering, consistency scoring
+- CommunicationPattern runner: update_patterns, analyze_patterns, pattern_stats
+- Apollo Local persistence for communication pattern state
+
 ## [0.1.19] - 2026-03-31
 
 ### Fixed

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/communication_pattern/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module CommunicationPattern
+          class Client
+            include Runners::CommunicationPattern
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module CommunicationPattern
+          module Helpers
+            module Constants
+              HOURS_IN_DAY = 24
+              DAYS_IN_WEEK = 7
+
+              MESSAGE_LENGTH_BUCKETS = %i[short medium long].freeze
+              MESSAGE_LENGTH_THRESHOLDS = { short: 50, medium: 200 }.freeze
+
+              SLIDING_WINDOW_SIZE = 100
+              MIN_TRACES_FOR_PATTERN = 10
+
+              TAG_PREFIX = %w[bond communication_pattern].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/communication_pattern/helpers/pattern_analyzer.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module CommunicationPattern
+          module Helpers
+            class PatternAnalyzer
+              attr_reader :agent_id, :trace_count
+
+              def initialize(agent_id:)
+                @agent_id      = agent_id
+                @tod_histogram = Array.new(Constants::HOURS_IN_DAY, 0)
+                @dow_histogram = Array.new(Constants::DAYS_IN_WEEK, 0)
+                @channel_counts    = Hash.new(0)
+                @direct_count      = 0
+                @topic_counts      = Hash.new(0)
+                @trace_count       = 0
+                @dirty             = false
+              end
+
+              def update_from_traces(traces)
+                traces.each { |t| process_trace(t) }
+                @dirty = true
+              end
+
+              def time_of_day_distribution
+                @tod_histogram.dup
+              end
+
+              def day_of_week_distribution
+                @dow_histogram.dup
+              end
+
+              def channel_preference
+                @channel_counts.sort_by { |_k, v| -v }.map(&:first)
+              end
+
+              def direct_address_frequency
+                return 0.0 if @trace_count.zero?
+
+                @direct_count.to_f / @trace_count
+              end
+
+              def topic_clustering
+                @topic_counts.dup
+              end
+
+              def consistency
+                return 0.0 if @trace_count < Constants::MIN_TRACES_FOR_PATTERN
+
+                channel_entropy = normalized_entropy(@channel_counts.values)
+                tod_entropy     = normalized_entropy(@tod_histogram)
+                (1.0 - ((channel_entropy + tod_entropy) / 2.0)).clamp(0.0, 1.0)
+              end
+
+              def dirty?
+                @dirty
+              end
+
+              def mark_clean!
+                @dirty = false
+                self
+              end
+
+              def to_apollo_entries
+                tags = Constants::TAG_PREFIX.dup + [@agent_id]
+                [{ content: serialize(state_hash), tags: tags }]
+              end
+
+              def from_apollo(store:)
+                result = store.query(text: 'communication_pattern',
+                                     tags: Constants::TAG_PREFIX + [@agent_id])
+                return false unless result[:success] && result[:results]&.any?
+
+                parsed = deserialize(result[:results].first[:content])
+                return false unless parsed
+
+                restore_state(parsed)
+                true
+              rescue StandardError => e
+                warn "[pattern_analyzer] from_apollo error: #{e.message}"
+                false
+              end
+
+              private
+
+              def process_trace(trace)
+                ts = trace[:created_at]
+                ts = Time.parse(ts.to_s) unless ts.is_a?(Time)
+
+                @tod_histogram[ts.hour] += 1
+                @dow_histogram[ts.wday] += 1
+
+                payload = trace[:content_payload] || {}
+                payload = payload.transform_keys(&:to_sym) if payload.is_a?(Hash)
+
+                channel = payload[:channel]&.to_s
+                @channel_counts[channel] += 1 if channel
+
+                @direct_count += 1 if payload[:direct_address]
+
+                (trace[:domain_tags] || []).each { |tag| @topic_counts[tag.to_s] += 1 }
+
+                @trace_count += 1
+              rescue StandardError => e
+                Legion::Logging.warn("[pattern_analyzer] process_trace error: #{e.message}")
+                nil
+              end
+
+              def normalized_entropy(counts)
+                total = counts.sum.to_f
+                return 0.0 if total.zero?
+
+                probs = counts.select(&:positive?).map { |c| c / total }
+                max_entropy = Math.log(probs.size)
+                return 0.0 if max_entropy.zero?
+
+                entropy = -probs.sum { |p| p * Math.log(p) }
+                entropy / max_entropy
+              end
+
+              def state_hash
+                { agent_id: @agent_id, trace_count: @trace_count,
+                  tod_histogram: @tod_histogram, dow_histogram: @dow_histogram,
+                  channel_counts: @channel_counts, direct_count: @direct_count,
+                  topic_counts: @topic_counts, consistency: consistency }
+              end
+
+              def restore_state(parsed)
+                @trace_count    = parsed[:trace_count].to_i
+                @tod_histogram  = parsed[:tod_histogram] || Array.new(24, 0)
+                @dow_histogram  = parsed[:dow_histogram] || Array.new(7, 0)
+                @channel_counts = Hash.new(0).merge(parsed[:channel_counts] || {})
+                @direct_count   = parsed[:direct_count].to_i
+                @topic_counts   = Hash.new(0).merge(parsed[:topic_counts] || {})
+              end
+
+              def serialize(hash)
+                defined?(Legion::JSON) ? Legion::JSON.dump(hash) : ::JSON.dump(hash)
+              end
+
+              def deserialize(content)
+                parsed = defined?(Legion::JSON) ? Legion::JSON.parse(content) : ::JSON.parse(content, symbolize_names: true)
+                parsed.is_a?(Hash) ? parsed.transform_keys(&:to_sym) : nil
+              rescue StandardError => e
+                Legion::Logging.warn("[pattern_analyzer] deserialize error: #{e.message}")
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/communication_pattern/runners/communication_pattern.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module CommunicationPattern
+          module Runners
+            module CommunicationPattern
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex, false)
+
+              def update_patterns(agent_id:, traces: [], **)
+                analyzer = analyzer_for(agent_id)
+                analyzer.update_from_traces(traces)
+
+                { success: true, trace_count: analyzer.trace_count,
+                  channel_preference: analyzer.channel_preference,
+                  direct_address_frequency: analyzer.direct_address_frequency,
+                  consistency: analyzer.consistency }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def analyze_patterns(agent_id:, **)
+                analyzer = analyzer_for(agent_id)
+                { time_of_day_distribution: analyzer.time_of_day_distribution,
+                  day_of_week_distribution: analyzer.day_of_week_distribution,
+                  channel_preference:       analyzer.channel_preference,
+                  direct_address_frequency: analyzer.direct_address_frequency,
+                  topic_clustering:         analyzer.topic_clustering,
+                  consistency:              analyzer.consistency,
+                  trace_count:              analyzer.trace_count }
+              end
+
+              def pattern_stats(agent_id:, **)
+                analyzer = analyzer_for(agent_id)
+                { trace_count:        analyzer.trace_count,
+                  channel_preference: analyzer.channel_preference,
+                  consistency:        analyzer.consistency }
+              end
+
+              private
+
+              def analyzer_for(agent_id)
+                @analyzers ||= {}
+                @analyzers[agent_id.to_s] ||= Helpers::PatternAnalyzer.new(agent_id: agent_id.to_s)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'communication_pattern/version'
+require_relative 'communication_pattern/helpers/constants'
+require_relative 'communication_pattern/helpers/pattern_analyzer'
+require_relative 'communication_pattern/runners/communication_pattern'
+require_relative 'communication_pattern/client'

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/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Memory
-        VERSION = '0.1.19'
+        VERSION = '0.1.21'
       end
     end
   end

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

@@ -19,6 +19,7 @@ require_relative 'memory/semantic_priming'
 require_relative 'memory/semantic_satiation'
 require_relative 'memory/source_monitoring'
 require_relative 'memory/transfer'
+require_relative 'memory/communication_pattern'
 
 module Legion
   module Extensions

data/spec/legion/extensions/agentic/memory/communication_pattern/helpers/constants_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/communication_pattern/helpers/constants'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::CommunicationPattern::Helpers::Constants do
+  describe 'HOURS_IN_DAY' do
+    it 'is 24' do
+      expect(described_class::HOURS_IN_DAY).to eq(24)
+    end
+  end
+
+  describe 'DAYS_IN_WEEK' do
+    it 'is 7' do
+      expect(described_class::DAYS_IN_WEEK).to eq(7)
+    end
+  end
+
+  describe 'MESSAGE_LENGTH_BUCKETS' do
+    it 'defines 3 buckets' do
+      expect(described_class::MESSAGE_LENGTH_BUCKETS).to eq(%i[short medium long])
+    end
+  end
+
+  describe 'SLIDING_WINDOW_SIZE' do
+    it 'is 100' do
+      expect(described_class::SLIDING_WINDOW_SIZE).to eq(100)
+    end
+  end
+
+  describe 'MIN_TRACES_FOR_PATTERN' do
+    it 'is 10' do
+      expect(described_class::MIN_TRACES_FOR_PATTERN).to eq(10)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/communication_pattern/helpers/pattern_analyzer_spec.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/communication_pattern/helpers/constants'
+require 'legion/extensions/agentic/memory/communication_pattern/helpers/pattern_analyzer'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::CommunicationPattern::Helpers::PatternAnalyzer do
+  subject(:analyzer) { described_class.new(agent_id: 'partner-1') }
+
+  let(:trace_9am) do
+    { trace_id: 'tr1', trace_type: :episodic, created_at: Time.utc(2026, 3, 31, 9, 0),
+      content_payload: { channel: 'teams', direct_address: true, agent_id: 'partner-1' },
+      domain_tags: %w[partner observation], source_agent_id: 'partner-1' }
+  end
+
+  let(:trace_2pm) do
+    { trace_id: 'tr2', trace_type: :episodic, created_at: Time.utc(2026, 3, 31, 14, 0),
+      content_payload: { channel: 'cli', direct_address: false, agent_id: 'partner-1' },
+      domain_tags: %w[partner observation work], source_agent_id: 'partner-1' }
+  end
+
+  describe '#update_from_traces' do
+    it 'processes an array of traces' do
+      analyzer.update_from_traces([trace_9am, trace_2pm])
+      expect(analyzer.trace_count).to eq(2)
+    end
+
+    it 'marks dirty' do
+      analyzer.update_from_traces([trace_9am])
+      expect(analyzer).to be_dirty
+    end
+  end
+
+  describe '#time_of_day_distribution' do
+    before { analyzer.update_from_traces([trace_9am, trace_2pm]) }
+
+    it 'returns 24-bucket histogram' do
+      dist = analyzer.time_of_day_distribution
+      expect(dist.size).to eq(24)
+    end
+
+    it 'has counts in the right buckets' do
+      dist = analyzer.time_of_day_distribution
+      expect(dist[9]).to eq(1)
+      expect(dist[14]).to eq(1)
+      expect(dist[0]).to eq(0)
+    end
+  end
+
+  describe '#day_of_week_distribution' do
+    before { analyzer.update_from_traces([trace_9am]) }
+
+    it 'returns 7-bucket histogram' do
+      dist = analyzer.day_of_week_distribution
+      expect(dist.size).to eq(7)
+    end
+  end
+
+  describe '#channel_preference' do
+    before { analyzer.update_from_traces([trace_9am, trace_2pm, trace_9am.merge(trace_id: 'tr3')]) }
+
+    it 'ranks channels by frequency' do
+      prefs = analyzer.channel_preference
+      expect(prefs.first).to eq('teams')
+    end
+  end
+
+  describe '#direct_address_frequency' do
+    before { analyzer.update_from_traces([trace_9am, trace_2pm]) }
+
+    it 'computes ratio of direct address traces' do
+      ratio = analyzer.direct_address_frequency
+      expect(ratio).to be_within(0.01).of(0.5)
+    end
+  end
+
+  describe '#topic_clustering' do
+    before { analyzer.update_from_traces([trace_9am, trace_2pm]) }
+
+    it 'returns domain tag frequencies' do
+      topics = analyzer.topic_clustering
+      expect(topics).to have_key('partner')
+      expect(topics['partner']).to eq(2)
+    end
+  end
+
+  describe '#consistency' do
+    it 'returns 0.0 with no data' do
+      expect(analyzer.consistency).to eq(0.0)
+    end
+
+    it 'returns positive value with data' do
+      analyzer.update_from_traces([trace_9am, trace_2pm])
+      expect(analyzer.consistency).to eq(0.0)
+    end
+  end
+
+  describe 'Apollo persistence' do
+    describe '#to_apollo_entries' do
+      before { analyzer.update_from_traces([trace_9am]) }
+
+      it 'returns entries with correct tags' do
+        entries = analyzer.to_apollo_entries
+        expect(entries.first[:tags]).to include('bond', 'communication_pattern', 'partner-1')
+      end
+    end
+
+    describe '#from_apollo' do
+      let(:mock_store) { double('apollo_local') }
+
+      it 'restores state' do
+        analyzer.update_from_traces([trace_9am, trace_2pm])
+        content = analyzer.send(:serialize, analyzer.send(:state_hash))
+
+        new_analyzer = described_class.new(agent_id: 'partner-1')
+        allow(mock_store).to receive(:query)
+          .and_return({ success: true, results: [{ content: content }] })
+
+        expect(new_analyzer.from_apollo(store: mock_store)).to be true
+        expect(new_analyzer.trace_count).to eq(2)
+      end
+    end
+
+    describe '#mark_clean!' do
+      it 'clears dirty flag' do
+        analyzer.update_from_traces([trace_9am])
+        analyzer.mark_clean!
+        expect(analyzer).not_to be_dirty
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/communication_pattern/runners/communication_pattern_spec.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/communication_pattern/helpers/constants'
+require 'legion/extensions/agentic/memory/communication_pattern/helpers/pattern_analyzer'
+require 'legion/extensions/agentic/memory/communication_pattern/runners/communication_pattern'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::CommunicationPattern::Runners::CommunicationPattern do
+  let(:host) { Object.new.extend(described_module) }
+  let(:described_module) { described_class }
+
+  before { host.instance_variable_set(:@analyzers, nil) }
+
+  describe '#update_patterns' do
+    let(:traces) do
+      [
+        { trace_id: 'tr1', trace_type: :episodic, created_at: Time.utc(2026, 3, 31, 9, 0),
+          content_payload: { channel: 'teams', direct_address: true }, domain_tags: %w[partner],
+          source_agent_id: 'partner-1' },
+        { trace_id: 'tr2', trace_type: :episodic, created_at: Time.utc(2026, 3, 31, 14, 0),
+          content_payload: { channel: 'cli', direct_address: false }, domain_tags: %w[partner],
+          source_agent_id: 'partner-1' }
+      ]
+    end
+
+    it 'processes traces and returns result' do
+      result = host.update_patterns(agent_id: 'partner-1', traces: traces)
+      expect(result[:success]).to be true
+      expect(result[:trace_count]).to eq(2)
+    end
+
+    it 'returns channel preference' do
+      result = host.update_patterns(agent_id: 'partner-1', traces: traces)
+      expect(result[:channel_preference]).to be_an(Array)
+    end
+
+    it 'returns direct address frequency' do
+      result = host.update_patterns(agent_id: 'partner-1', traces: traces)
+      expect(result[:direct_address_frequency]).to be_within(0.01).of(0.5)
+    end
+  end
+
+  describe '#analyze_patterns' do
+    it 'returns current patterns for an agent' do
+      host.update_patterns(agent_id: 'p1', traces: [
+                             { trace_id: 't1', trace_type: :episodic, created_at: Time.now.utc,
+                               content_payload: { channel: 'teams' }, domain_tags: [], source_agent_id: 'p1' }
+                           ])
+      result = host.analyze_patterns(agent_id: 'p1')
+      expect(result).to have_key(:time_of_day_distribution)
+      expect(result).to have_key(:channel_preference)
+    end
+
+    it 'returns empty result for unknown agent' do
+      result = host.analyze_patterns(agent_id: 'unknown')
+      expect(result[:trace_count]).to eq(0)
+    end
+  end
+
+  describe '#pattern_stats' do
+    it 'returns stats hash' do
+      result = host.pattern_stats(agent_id: 'p1')
+      expect(result).to have_key(:trace_count)
+    end
+  end
+end

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-memory
 version: !ruby/object:Gem::Version
-  version: 0.1.19
+  version: 0.1.21
 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
@@ -199,6 +199,12 @@ files:
 - lib/legion/extensions/agentic/memory/archaeology/helpers/excavation_site.rb
 - lib/legion/extensions/agentic/memory/archaeology/runners/cognitive_archaeology.rb
 - lib/legion/extensions/agentic/memory/archaeology/version.rb
+- lib/legion/extensions/agentic/memory/communication_pattern.rb
+- lib/legion/extensions/agentic/memory/communication_pattern/client.rb
+- lib/legion/extensions/agentic/memory/communication_pattern/helpers/constants.rb
+- lib/legion/extensions/agentic/memory/communication_pattern/helpers/pattern_analyzer.rb
+- lib/legion/extensions/agentic/memory/communication_pattern/runners/communication_pattern.rb
+- lib/legion/extensions/agentic/memory/communication_pattern/version.rb
 - lib/legion/extensions/agentic/memory/compression.rb
 - lib/legion/extensions/agentic/memory/compression/actors/maintenance.rb
 - lib/legion/extensions/agentic/memory/compression/client.rb
@@ -363,6 +369,9 @@ files:
 - spec/legion/extensions/agentic/memory/archaeology/helpers/constants_spec.rb
 - spec/legion/extensions/agentic/memory/archaeology/helpers/excavation_site_spec.rb
 - spec/legion/extensions/agentic/memory/archaeology/runners/cognitive_archaeology_spec.rb
+- spec/legion/extensions/agentic/memory/communication_pattern/helpers/constants_spec.rb
+- spec/legion/extensions/agentic/memory/communication_pattern/helpers/pattern_analyzer_spec.rb
+- spec/legion/extensions/agentic/memory/communication_pattern/runners/communication_pattern_spec.rb
 - spec/legion/extensions/agentic/memory/compression/actors/maintenance_spec.rb
 - spec/legion/extensions/agentic/memory/compression/helpers/compression_engine_spec.rb
 - spec/legion/extensions/agentic/memory/compression/helpers/constants_spec.rb