lex-agentic-memory 0.1.19 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 440d04008d2af919b940d155b035cf4d1cac9d8e67361792008b166504ed9a2a
-  data.tar.gz: 0f0d8fade5d070d635b707e792501d9b88624205940b32b9babf194c33970620
+  metadata.gz: c4e20449f626874ab90b96c4452b4b35e4eae22e61df8fb6c9e5a51e4b0b8cd3
+  data.tar.gz: eff572db0f462ada591dcfc6e6efa2d8d3092cc43b1be6f907ddcfe9003b0cd9
 SHA512:
-  metadata.gz: d6695c59a99700fb47490bafbf29e9749fca9f9b523d38ec67ee31f3a522f633fc0c5a36d0cdbd6f362e6bbb78ac35a896a2bcf9023f16a3c3d6d9cb25ea6279
-  data.tar.gz: 7e79c8329c3de95c22a832144d729c5430586048727a88762698df887fb8b9a06689391f9539ac081375082b19e76b8805dcb807554d7f30df342cd3b1eb00f1
+  metadata.gz: e0e21635a796f9d4c9fbb2503446657d727bb01de9bb82a5b6323270611ff13c72a18bb0c520f2fb0ab3a987d5a869ca92ebf7e1e718dce0d20cd0b3712f1722
+  data.tar.gz: 0ea2e0a708e2cb8f853bc17595935a596de7e98c03955c9ce97582a7edcdc5546a22e645f9e929b05a08a43e9b52a4e4a1a45329129b1d797cea58d42f833b76

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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/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/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Memory
-        VERSION = '0.1.19'
+        VERSION = '0.1.20'
       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

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.20
 platform: ruby
 authors:
 - Esity
@@ -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