lex-hebbian-assembly 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7a9d7d72a5ff5d0f18795d1429a8db621b543021e9ccc316027110529a6f235
+  data.tar.gz: 30287fe026d3c978361f85bf5e43757946f0c1bb4ee28bb7472a7ae11d9df70a
+SHA512:
+  metadata.gz: fed78e7e6d176dad68a17b9239311bf932c7e1160978b511557e9836b66afea52a10d2ce57427d3608bd60a59a67d3595d5c15df59fe0fa29103b8fa9ca53a55
+  data.tar.gz: e00aa1d2f97b2c87e14db0109b1f6a0500f6b043793c7b587a53c18daa2e32ea31c04d050955d922fda134373ce27dc1baa58f735523daed59034cd8629e755b

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-hebbian-assembly.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/hebbian_assembly/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-hebbian-assembly'
+  spec.version       = Legion::Extensions::HebbianAssembly::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Hebbian Assembly'
+  spec.description   = "Hebb's Cell Assembly Theory for brain-modeled agentic AI — neurons that fire " \
+                       'together wire together, forming emergent assemblies that represent concepts, ' \
+                       'enable pattern completion, and support associative recall through ' \
+                       'co-activation-driven synaptic strengthening.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-hebbian-assembly'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = 'https://github.com/LegionIO/lex-hebbian-assembly'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-hebbian-assembly'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-hebbian-assembly'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-hebbian-assembly/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-hebbian-assembly.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/hebbian_assembly/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::HebbianAssembly::Runners::HebbianAssembly
+          end
+
+          def runner_function
+            'update_hebbian'
+          end
+
+          def time
+            60
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hebbian_assembly/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hebbian_assembly/helpers/constants'
+require 'legion/extensions/hebbian_assembly/helpers/unit'
+require 'legion/extensions/hebbian_assembly/helpers/assembly'
+require 'legion/extensions/hebbian_assembly/helpers/assembly_network'
+require 'legion/extensions/hebbian_assembly/runners/hebbian_assembly'
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      class Client
+        include Runners::HebbianAssembly
+
+        def initialize(network: nil, **)
+          @network = network || Helpers::AssemblyNetwork.new
+        end
+
+        private
+
+        attr_reader :network
+      end
+    end
+  end
+end

data/lib/legion/extensions/hebbian_assembly/helpers/assembly.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      module Helpers
+        class Assembly
+          include Constants
+
+          attr_reader :id, :member_ids, :formed_at, :activation_count, :last_activated
+          attr_accessor :coherence
+
+          def initialize(id:, member_ids:)
+            @id               = id
+            @member_ids       = Array(member_ids).uniq
+            @coherence        = 0.5
+            @formed_at        = Time.now.utc
+            @activation_count = 0
+            @last_activated   = nil
+          end
+
+          def activate
+            @activation_count += 1
+            @last_activated = Time.now.utc
+          end
+
+          def consolidate
+            @coherence = [@coherence + CONSOLIDATION_BOOST, MAX_WEIGHT].min
+          end
+
+          def decay
+            @coherence = [@coherence - WEIGHT_DECAY, 0.0].max
+          end
+
+          def dissolving?
+            @coherence < ASSEMBLY_MIN_WEIGHT
+          end
+
+          def member_count
+            @member_ids.size
+          end
+
+          def includes?(unit_id)
+            @member_ids.include?(unit_id)
+          end
+
+          def state
+            if @last_activated && (Time.now.utc - @last_activated) < CO_ACTIVATION_WINDOW
+              :active
+            elsif @last_activated && (Time.now.utc - @last_activated) < (CO_ACTIVATION_WINDOW * 3)
+              :primed
+            elsif dissolving?
+              :dissolving
+            elsif @coherence >= ASSEMBLY_MIN_WEIGHT
+              :dormant
+            else
+              :forming
+            end
+          end
+
+          def to_h
+            {
+              id: @id,
+              members: @member_ids.dup,
+              member_count: member_count,
+              coherence: @coherence.round(4),
+              state: state,
+              state_label: ASSEMBLY_STATE_LABELS[state],
+              activation_count: @activation_count,
+              formed_at: @formed_at,
+              last_activated: @last_activated
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hebbian_assembly/helpers/assembly_network.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      module Helpers
+        class AssemblyNetwork
+          include Constants
+
+          attr_reader :units, :assemblies, :activation_history
+
+          def initialize
+            @units              = {}
+            @assemblies         = {}
+            @activation_history = []
+            @assembly_counter   = 0
+          end
+
+          def add_unit(id:, domain: :general)
+            return @units[id] if @units.key?(id)
+            return nil if @units.size >= MAX_UNITS
+
+            @units[id] = Unit.new(id: id, domain: domain)
+          end
+
+          def activate_unit(id:, level: 1.0)
+            ensure_unit(id)
+            unit = @units[id]
+            unit.activate(level: level)
+            record_activation(id)
+            hebbian_update(id)
+            detect_assemblies
+            unit
+          end
+
+          def co_activate(ids:, level: 1.0)
+            ids = Array(ids)
+            ids.each do |id|
+              ensure_unit(id)
+              @units[id].activate(level: level)
+              record_activation(id)
+            end
+
+            ids.combination(2).each do |a, b|
+              ensure_connection(a, b)
+              @units[a].strengthen(b)
+              @units[b].strengthen(a)
+            end
+
+            detect_assemblies
+            ids.map { |id| @units[id].to_h }
+          end
+
+          def query_weight(from:, to:)
+            return 0.0 unless @units.key?(from)
+
+            @units[from].weight_to(to)
+          end
+
+          def query_assembly(id:)
+            @assemblies[id]
+          end
+
+          def assemblies_containing(unit_id:)
+            @assemblies.values.select { |a| a.includes?(unit_id) }
+          end
+
+          def pattern_complete(partial_ids:)
+            partial = Array(partial_ids)
+            candidates = partial.flat_map { |uid| assemblies_containing(unit_id: uid) }.uniq(&:id)
+            return nil if candidates.empty?
+
+            best = candidates.max_by { |a| (partial & a.member_ids).size }
+            missing = best.member_ids - partial
+            { assembly_id: best.id, known: partial & best.member_ids, predicted: missing, coherence: best.coherence }
+          end
+
+          def strongest_units(n = 10)
+            @units.values
+                  .sort_by { |u| -u.activation_count }
+                  .first(n)
+                  .map(&:to_h)
+          end
+
+          def decay_all
+            @units.each_value(&:decay_weights)
+            @assemblies.each_value(&:decay)
+            @assemblies.reject! { |_, a| a.dissolving? }
+          end
+
+          def unit_count
+            @units.size
+          end
+
+          def assembly_count
+            @assemblies.size
+          end
+
+          def to_h
+            {
+              units: @units.size,
+              assemblies: @assemblies.size,
+              total_connections: @units.values.sum(&:connection_count),
+              history_size: @activation_history.size,
+              active_units: @units.values.count(&:active?)
+            }
+          end
+
+          private
+
+          def ensure_unit(id)
+            add_unit(id: id) unless @units.key?(id)
+          end
+
+          def ensure_connection(a, b)
+            @units[a].connect(b) unless @units[a].connections.key?(b)
+            @units[b].connect(a) unless @units[b].connections.key?(a)
+          end
+
+          def record_activation(id)
+            @activation_history << { unit_id: id, at: Time.now.utc }
+            @activation_history.shift while @activation_history.size > MAX_ACTIVATION_HISTORY
+          end
+
+          def hebbian_update(active_id)
+            recent_window = Time.now.utc - CO_ACTIVATION_WINDOW
+            recent_ids = @activation_history
+                         .select { |h| h[:at] >= recent_window && h[:unit_id] != active_id }
+                         .map { |h| h[:unit_id] }
+                         .uniq
+
+            recent_ids.each do |other_id|
+              next unless @units.key?(other_id) && @units[other_id].active?
+
+              ensure_connection(active_id, other_id)
+              @units[active_id].strengthen(other_id)
+              @units[other_id].strengthen(active_id)
+            end
+          end
+
+          def detect_assemblies
+            strongly_connected = find_strongly_connected
+            return if strongly_connected.size < ASSEMBLY_THRESHOLD
+
+            existing = find_matching_assembly(strongly_connected)
+            existing ? reinforce_assembly(existing) : create_assembly(strongly_connected)
+          end
+
+          def find_strongly_connected
+            active_ids = @units.values.select(&:active?).map(&:id)
+            return [] if active_ids.size < ASSEMBLY_THRESHOLD
+
+            active_ids.select do |uid|
+              peers = active_ids - [uid]
+              peers.count { |p| @units[uid].weight_to(p) >= ASSEMBLY_MIN_WEIGHT } >= (ASSEMBLY_THRESHOLD - 1)
+            end
+          end
+
+          def find_matching_assembly(member_ids)
+            @assemblies.values.find do |a|
+              (member_ids - a.member_ids).empty? && (a.member_ids - member_ids).empty?
+            end
+          end
+
+          def reinforce_assembly(assembly)
+            assembly.activate
+            assembly.consolidate
+          end
+
+          def create_assembly(member_ids)
+            @assembly_counter += 1
+            id = :"assembly_#{@assembly_counter}"
+            @assemblies[id] = Assembly.new(id: id, member_ids: member_ids)
+            @assemblies[id].activate
+            prune_assemblies if @assemblies.size > MAX_ASSEMBLIES
+          end
+
+          def prune_assemblies
+            weakest = @assemblies.min_by { |_, a| a.coherence }&.first
+            @assemblies.delete(weakest) if weakest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hebbian_assembly/helpers/constants.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      module Helpers
+        module Constants
+          MAX_UNITS = 500
+          MAX_ASSEMBLIES = 100
+          MAX_CONNECTIONS_PER_UNIT = 30
+          MAX_ACTIVATION_HISTORY = 200
+
+          DEFAULT_WEIGHT = 0.1
+          WEIGHT_FLOOR = 0.01
+          MAX_WEIGHT = 1.0
+          LEARNING_RATE = 0.05
+          WEIGHT_DECAY = 0.002
+
+          ACTIVATION_THRESHOLD = 0.3
+          CO_ACTIVATION_WINDOW = 5
+          ASSEMBLY_THRESHOLD = 3
+          ASSEMBLY_MIN_WEIGHT = 0.3
+
+          CONSOLIDATION_BOOST = 0.02
+          COMPETITION_FACTOR = 0.01
+
+          WEIGHT_LABELS = {
+            (0.8..) => :bonded,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :weak,
+            (..0.2) => :nascent
+          }.freeze
+
+          ASSEMBLY_STATE_LABELS = {
+            active: 'assembly currently firing',
+            primed: 'assembly recently active',
+            dormant: 'assembly stable but inactive',
+            forming: 'assembly still consolidating',
+            dissolving: 'assembly losing coherence'
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hebbian_assembly/helpers/unit.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      module Helpers
+        class Unit
+          include Constants
+
+          attr_reader :id, :domain, :connections, :activation_count, :last_activated
+          attr_accessor :activation_level
+
+          def initialize(id:, domain: :general)
+            @id               = id
+            @domain           = domain
+            @activation_level = 0.0
+            @connections      = {}
+            @activation_count = 0
+            @last_activated   = nil
+          end
+
+          def activate(level: 1.0)
+            @activation_level = level.to_f.clamp(0.0, 1.0)
+            @activation_count += 1
+            @last_activated = Time.now.utc
+          end
+
+          def active?
+            @activation_level >= ACTIVATION_THRESHOLD
+          end
+
+          def connect(other_id, weight: DEFAULT_WEIGHT)
+            return if @connections.size >= MAX_CONNECTIONS_PER_UNIT && !@connections.key?(other_id)
+
+            @connections[other_id] = weight.to_f.clamp(WEIGHT_FLOOR, MAX_WEIGHT)
+          end
+
+          def strengthen(other_id, amount: LEARNING_RATE)
+            return unless @connections.key?(other_id)
+
+            @connections[other_id] = [@connections[other_id] + amount, MAX_WEIGHT].min
+          end
+
+          def weaken(other_id, amount: COMPETITION_FACTOR)
+            return unless @connections.key?(other_id)
+
+            @connections[other_id] = [@connections[other_id] - amount, WEIGHT_FLOOR].max
+          end
+
+          def weight_to(other_id)
+            @connections[other_id] || 0.0
+          end
+
+          def weight_label(other_id)
+            w = weight_to(other_id)
+            WEIGHT_LABELS.each { |range, lbl| return lbl if range.cover?(w) }
+            :nascent
+          end
+
+          def decay_weights
+            @connections.each do |k, w|
+              @connections[k] = [w - WEIGHT_DECAY, WEIGHT_FLOOR].max
+            end
+            @connections.reject! { |_, w| w <= WEIGHT_FLOOR }
+          end
+
+          def connection_count
+            @connections.size
+          end
+
+          def strongest_connections(n = 5)
+            @connections.sort_by { |_, w| -w }.first(n).to_h
+          end
+
+          def to_h
+            {
+              id: @id,
+              domain: @domain,
+              activation_level: @activation_level.round(4),
+              active: active?,
+              connections: @connections.size,
+              activation_count: @activation_count,
+              last_activated: @last_activated
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hebbian_assembly/runners/hebbian_assembly.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      module Runners
+        module HebbianAssembly
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def activate_unit(id:, level: 1.0, domain: :general, **)
+            Legion::Logging.debug "[hebbian] activate: id=#{id} level=#{level}"
+            network.add_unit(id: id, domain: domain)
+            unit = network.activate_unit(id: id, level: level)
+            { success: true, unit: unit.to_h, assemblies: network.assembly_count }
+          end
+
+          def co_activate_units(ids:, level: 1.0, **)
+            Legion::Logging.debug "[hebbian] co_activate: ids=#{ids}"
+            results = network.co_activate(ids: ids, level: level)
+            { success: true, units: results, assemblies: network.assembly_count }
+          end
+
+          def query_weight(from:, to:, **)
+            w = network.query_weight(from: from, to: to)
+            label = Helpers::Constants::WEIGHT_LABELS.each { |range, l| break l if range.cover?(w) }
+            label = :nascent unless label.is_a?(Symbol)
+            Legion::Logging.debug "[hebbian] weight: #{from}->#{to} = #{w}"
+            { success: true, from: from, to: to, weight: w.round(4), label: label }
+          end
+
+          def list_assemblies(**)
+            assemblies = network.assemblies.values.map(&:to_h)
+            Legion::Logging.debug "[hebbian] list_assemblies: #{assemblies.size}"
+            { success: true, assemblies: assemblies, count: assemblies.size }
+          end
+
+          def query_assembly(id:, **)
+            asm = network.query_assembly(id: id.to_sym)
+            Legion::Logging.debug "[hebbian] query_assembly: id=#{id} found=#{!asm.nil?}"
+            if asm
+              { success: true, assembly: asm.to_h }
+            else
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def pattern_complete(partial_ids:, **)
+            Legion::Logging.debug "[hebbian] pattern_complete: partial=#{partial_ids}"
+            result = network.pattern_complete(partial_ids: partial_ids)
+            if result
+              { success: true, completion: result }
+            else
+              { success: false, reason: :no_matching_assembly }
+            end
+          end
+
+          def strongest_units(limit: 10, **)
+            units = network.strongest_units(limit.to_i)
+            Legion::Logging.debug "[hebbian] strongest_units: #{units.size}"
+            { success: true, units: units }
+          end
+
+          def assemblies_for(unit_id:, **)
+            asms = network.assemblies_containing(unit_id: unit_id).map(&:to_h)
+            Legion::Logging.debug "[hebbian] assemblies_for: unit=#{unit_id} count=#{asms.size}"
+            { success: true, assemblies: asms, count: asms.size }
+          end
+
+          def update_hebbian(**)
+            Legion::Logging.debug '[hebbian] decay tick'
+            network.decay_all
+            { success: true, units: network.unit_count, assemblies: network.assembly_count }
+          end
+
+          def hebbian_stats(**)
+            Legion::Logging.debug '[hebbian] stats'
+            { success: true, stats: network.to_h }
+          end
+
+          private
+
+          def network
+            @network ||= Helpers::AssemblyNetwork.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/hebbian_assembly.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hebbian_assembly/version'
+require 'legion/extensions/hebbian_assembly/helpers/constants'
+require 'legion/extensions/hebbian_assembly/helpers/unit'
+require 'legion/extensions/hebbian_assembly/helpers/assembly'
+require 'legion/extensions/hebbian_assembly/helpers/assembly_network'
+require 'legion/extensions/hebbian_assembly/runners/hebbian_assembly'
+require 'legion/extensions/hebbian_assembly/client'
+
+module Legion
+  module Extensions
+    module HebbianAssembly
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/hebbian_assembly/client_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::HebbianAssembly::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::HebbianAssembly' do
+    expect(described_class.ancestors).to include(Legion::Extensions::HebbianAssembly::Runners::HebbianAssembly)
+  end
+
+  it 'supports full Hebbian learning lifecycle' do
+    # Repeatedly co-activate a pattern
+    10.times { client.co_activate_units(ids: %i[see dog bark]) }
+
+    # Assembly should form
+    assemblies = client.list_assemblies
+    expect(assemblies[:count]).to be >= 1
+
+    # Pattern completion: given "see" and "dog", predict "bark"
+    completion = client.pattern_complete(partial_ids: %i[see dog])
+    expect(completion[:success]).to be true
+    expect(completion[:completion][:predicted]).to include(:bark)
+
+    # Weights should be strong
+    weight = client.query_weight(from: :see, to: :dog)
+    expect(weight[:weight]).to be > 0.3
+
+    # Find assemblies containing :dog
+    dog_asms = client.assemblies_for(unit_id: :dog)
+    expect(dog_asms[:count]).to be >= 1
+
+    # Decay
+    client.update_hebbian
+
+    # Stats
+    stats = client.hebbian_stats
+    expect(stats[:stats][:units]).to eq(3)
+  end
+end

data/spec/legion/extensions/hebbian_assembly/helpers/assembly_network_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::HebbianAssembly::Helpers::AssemblyNetwork do
+  subject(:network) { described_class.new }
+
+  let(:constants) { Legion::Extensions::HebbianAssembly::Helpers::Constants }
+
+  describe '#add_unit' do
+    it 'adds a unit' do
+      unit = network.add_unit(id: :a)
+      expect(unit.id).to eq(:a)
+      expect(network.unit_count).to eq(1)
+    end
+
+    it 'returns existing unit on duplicate' do
+      first = network.add_unit(id: :a)
+      second = network.add_unit(id: :a)
+      expect(first).to equal(second)
+    end
+
+    it 'limits units' do
+      constants::MAX_UNITS.times { |i| network.add_unit(id: :"u_#{i}") }
+      expect(network.add_unit(id: :overflow)).to be_nil
+    end
+  end
+
+  describe '#activate_unit' do
+    it 'activates a unit' do
+      unit = network.activate_unit(id: :a, level: 0.8)
+      expect(unit.activation_level).to eq(0.8)
+      expect(unit.active?).to be true
+    end
+
+    it 'auto-creates unit if missing' do
+      network.activate_unit(id: :new_unit)
+      expect(network.unit_count).to eq(1)
+    end
+
+    it 'records activation history' do
+      network.activate_unit(id: :a)
+      expect(network.activation_history.size).to eq(1)
+    end
+  end
+
+  describe '#co_activate' do
+    it 'activates multiple units' do
+      results = network.co_activate(ids: %i[a b c])
+      expect(results.size).to eq(3)
+      expect(network.unit_count).to eq(3)
+    end
+
+    it 'strengthens connections between co-activated units' do
+      network.co_activate(ids: %i[a b])
+      expect(network.query_weight(from: :a, to: :b)).to be > 0
+      expect(network.query_weight(from: :b, to: :a)).to be > 0
+    end
+
+    it 'repeated co-activation increases weight' do
+      network.co_activate(ids: %i[a b])
+      first_weight = network.query_weight(from: :a, to: :b)
+      network.co_activate(ids: %i[a b])
+      expect(network.query_weight(from: :a, to: :b)).to be > first_weight
+    end
+  end
+
+  describe '#query_weight' do
+    it 'returns 0 for unconnected units' do
+      expect(network.query_weight(from: :a, to: :b)).to eq(0.0)
+    end
+  end
+
+  describe 'assembly detection' do
+    it 'forms assembly from repeated co-activation of 3+ units' do
+      10.times { network.co_activate(ids: %i[a b c], level: 1.0) }
+      expect(network.assembly_count).to be >= 1
+    end
+
+    it 'consolidates existing assembly on repeated co-activation' do
+      10.times { network.co_activate(ids: %i[a b c], level: 1.0) }
+      assembly = network.assemblies.values.first
+      first_coherence = assembly.coherence
+      5.times { network.co_activate(ids: %i[a b c], level: 1.0) }
+      expect(assembly.coherence).to be >= first_coherence
+    end
+  end
+
+  describe '#assemblies_containing' do
+    it 'finds assemblies containing a unit' do
+      10.times { network.co_activate(ids: %i[a b c], level: 1.0) }
+      asms = network.assemblies_containing(unit_id: :a)
+      expect(asms).not_to be_empty
+      expect(asms.first.includes?(:a)).to be true
+    end
+  end
+
+  describe '#pattern_complete' do
+    it 'completes partial pattern from assembly' do
+      10.times { network.co_activate(ids: %i[a b c], level: 1.0) }
+      result = network.pattern_complete(partial_ids: %i[a b])
+      expect(result).not_to be_nil
+      expect(result[:predicted]).to include(:c)
+    end
+
+    it 'returns nil when no matching assembly' do
+      expect(network.pattern_complete(partial_ids: [:unknown])).to be_nil
+    end
+  end
+
+  describe '#strongest_units' do
+    it 'returns most activated units' do
+      5.times { network.activate_unit(id: :frequent, level: 1.0) }
+      network.activate_unit(id: :rare, level: 1.0)
+      top = network.strongest_units(1)
+      expect(top.first[:id]).to eq(:frequent)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays unit weights' do
+      network.co_activate(ids: %i[a b])
+      before = network.query_weight(from: :a, to: :b)
+      network.decay_all
+      expect(network.query_weight(from: :a, to: :b)).to be < before
+    end
+
+    it 'removes dissolving assemblies' do
+      10.times { network.co_activate(ids: %i[a b c], level: 1.0) }
+      network.assemblies.each_value { |a| a.coherence = 0.1 }
+      network.decay_all
+      expect(network.assembly_count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats' do
+      network.co_activate(ids: %i[a b c])
+      h = network.to_h
+      expect(h).to include(:units, :assemblies, :total_connections, :history_size, :active_units)
+      expect(h[:units]).to eq(3)
+    end
+  end
+end

data/spec/legion/extensions/hebbian_assembly/helpers/assembly_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::HebbianAssembly::Helpers::Assembly do
+  subject(:assembly) { described_class.new(id: :asm_one, member_ids: %i[a b c]) }
+
+  let(:constants) { Legion::Extensions::HebbianAssembly::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets attributes' do
+      expect(assembly.id).to eq(:asm_one)
+      expect(assembly.member_ids).to eq(%i[a b c])
+      expect(assembly.coherence).to eq(0.5)
+    end
+
+    it 'deduplicates members' do
+      asm = described_class.new(id: :dup, member_ids: %i[a a b])
+      expect(asm.member_ids).to eq(%i[a b])
+    end
+  end
+
+  describe '#activate' do
+    it 'increments activation count' do
+      assembly.activate
+      expect(assembly.activation_count).to eq(1)
+      expect(assembly.last_activated).to be_a(Time)
+    end
+  end
+
+  describe '#consolidate' do
+    it 'increases coherence' do
+      before = assembly.coherence
+      assembly.consolidate
+      expect(assembly.coherence).to be > before
+    end
+  end
+
+  describe '#decay' do
+    it 'decreases coherence' do
+      before = assembly.coherence
+      assembly.decay
+      expect(assembly.coherence).to be < before
+    end
+  end
+
+  describe '#dissolving?' do
+    it 'returns false when coherent' do
+      expect(assembly.dissolving?).to be false
+    end
+
+    it 'returns true when coherence drops below threshold' do
+      assembly.coherence = 0.1
+      expect(assembly.dissolving?).to be true
+    end
+  end
+
+  describe '#includes?' do
+    it 'returns true for members' do
+      expect(assembly.includes?(:a)).to be true
+    end
+
+    it 'returns false for non-members' do
+      expect(assembly.includes?(:z)).to be false
+    end
+  end
+
+  describe '#state' do
+    it 'returns :dormant for stable inactive assembly' do
+      expect(assembly.state).to eq(:dormant)
+    end
+
+    it 'returns :active when recently activated' do
+      assembly.activate
+      expect(assembly.state).to eq(:active)
+    end
+
+    it 'returns :dissolving when coherence is low' do
+      assembly.coherence = 0.1
+      expect(assembly.state).to eq(:dissolving)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = assembly.to_h
+      expect(h).to include(:id, :members, :member_count, :coherence, :state, :state_label, :activation_count)
+      expect(h[:member_count]).to eq(3)
+    end
+  end
+end

data/spec/legion/extensions/hebbian_assembly/helpers/unit_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::HebbianAssembly::Helpers::Unit do
+  subject(:unit) { described_class.new(id: :neuron_a, domain: :cognition) }
+
+  let(:constants) { Legion::Extensions::HebbianAssembly::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets attributes' do
+      expect(unit.id).to eq(:neuron_a)
+      expect(unit.domain).to eq(:cognition)
+      expect(unit.activation_level).to eq(0.0)
+      expect(unit.activation_count).to eq(0)
+    end
+  end
+
+  describe '#activate' do
+    it 'sets activation level and increments count' do
+      unit.activate(level: 0.8)
+      expect(unit.activation_level).to eq(0.8)
+      expect(unit.activation_count).to eq(1)
+      expect(unit.last_activated).to be_a(Time)
+    end
+
+    it 'clamps activation' do
+      unit.activate(level: 1.5)
+      expect(unit.activation_level).to eq(1.0)
+    end
+  end
+
+  describe '#active?' do
+    it 'returns true when above threshold' do
+      unit.activate(level: 0.5)
+      expect(unit.active?).to be true
+    end
+
+    it 'returns false when below threshold' do
+      expect(unit.active?).to be false
+    end
+  end
+
+  describe '#connect' do
+    it 'creates a connection' do
+      unit.connect(:neuron_b, weight: 0.3)
+      expect(unit.weight_to(:neuron_b)).to eq(0.3)
+    end
+
+    it 'clamps weight' do
+      unit.connect(:neuron_b, weight: 2.0)
+      expect(unit.weight_to(:neuron_b)).to eq(1.0)
+    end
+
+    it 'limits connections' do
+      constants::MAX_CONNECTIONS_PER_UNIT.times { |i| unit.connect(:"n_#{i}") }
+      unit.connect(:overflow)
+      expect(unit.connection_count).to eq(constants::MAX_CONNECTIONS_PER_UNIT)
+    end
+  end
+
+  describe '#strengthen' do
+    it 'increases weight' do
+      unit.connect(:neuron_b, weight: 0.3)
+      unit.strengthen(:neuron_b)
+      expect(unit.weight_to(:neuron_b)).to eq(0.3 + constants::LEARNING_RATE)
+    end
+
+    it 'caps at MAX_WEIGHT' do
+      unit.connect(:neuron_b, weight: 0.98)
+      unit.strengthen(:neuron_b)
+      expect(unit.weight_to(:neuron_b)).to eq(constants::MAX_WEIGHT)
+    end
+  end
+
+  describe '#weaken' do
+    it 'decreases weight' do
+      unit.connect(:neuron_b, weight: 0.5)
+      unit.weaken(:neuron_b)
+      expect(unit.weight_to(:neuron_b)).to eq(0.5 - constants::COMPETITION_FACTOR)
+    end
+  end
+
+  describe '#decay_weights' do
+    it 'decays all connections' do
+      unit.connect(:neuron_b, weight: 0.5)
+      unit.decay_weights
+      expect(unit.weight_to(:neuron_b)).to eq(0.5 - constants::WEIGHT_DECAY)
+    end
+
+    it 'prunes connections at floor' do
+      unit.connect(:neuron_b, weight: constants::WEIGHT_FLOOR + 0.001)
+      unit.decay_weights
+      expect(unit.connection_count).to eq(0)
+    end
+  end
+
+  describe '#weight_label' do
+    it 'returns label for weight' do
+      unit.connect(:neuron_b, weight: 0.9)
+      expect(unit.weight_label(:neuron_b)).to eq(:bonded)
+    end
+  end
+
+  describe '#strongest_connections' do
+    it 'returns top connections sorted by weight' do
+      unit.connect(:a, weight: 0.3)
+      unit.connect(:b, weight: 0.8)
+      unit.connect(:c, weight: 0.5)
+      top = unit.strongest_connections(2)
+      expect(top.keys).to eq(%i[b c])
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash' do
+      h = unit.to_h
+      expect(h).to include(:id, :domain, :activation_level, :active, :connections, :activation_count)
+    end
+  end
+end

data/spec/legion/extensions/hebbian_assembly/runners/hebbian_assembly_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::HebbianAssembly::Runners::HebbianAssembly do
+  let(:client) { Legion::Extensions::HebbianAssembly::Client.new }
+
+  describe '#activate_unit' do
+    it 'activates a unit' do
+      result = client.activate_unit(id: :a, level: 0.8, domain: :cognition)
+      expect(result[:success]).to be true
+      expect(result[:unit][:id]).to eq(:a)
+      expect(result[:unit][:active]).to be true
+    end
+  end
+
+  describe '#co_activate_units' do
+    it 'co-activates multiple units' do
+      result = client.co_activate_units(ids: %i[a b c])
+      expect(result[:success]).to be true
+      expect(result[:units].size).to eq(3)
+    end
+  end
+
+  describe '#query_weight' do
+    it 'returns weight between units' do
+      client.co_activate_units(ids: %i[a b])
+      result = client.query_weight(from: :a, to: :b)
+      expect(result[:success]).to be true
+      expect(result[:weight]).to be > 0
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'returns 0 for unconnected' do
+      result = client.query_weight(from: :x, to: :y)
+      expect(result[:weight]).to eq(0.0)
+    end
+  end
+
+  describe '#list_assemblies' do
+    it 'lists assemblies' do
+      10.times { client.co_activate_units(ids: %i[a b c]) }
+      result = client.list_assemblies
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+    end
+  end
+
+  describe '#query_assembly' do
+    it 'queries a specific assembly' do
+      10.times { client.co_activate_units(ids: %i[a b c]) }
+      all = client.list_assemblies
+      id = all[:assemblies].first[:id]
+      result = client.query_assembly(id: id)
+      expect(result[:success]).to be true
+      expect(result[:assembly][:members]).to include(:a, :b, :c)
+    end
+
+    it 'returns not_found for unknown' do
+      result = client.query_assembly(id: :nonexistent)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#pattern_complete' do
+    it 'completes partial pattern' do
+      10.times { client.co_activate_units(ids: %i[a b c]) }
+      result = client.pattern_complete(partial_ids: %i[a b])
+      expect(result[:success]).to be true
+      expect(result[:completion][:predicted]).to include(:c)
+    end
+
+    it 'returns failure when no match' do
+      result = client.pattern_complete(partial_ids: [:unknown])
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#strongest_units' do
+    it 'returns most activated units' do
+      5.times { client.activate_unit(id: :freq) }
+      client.activate_unit(id: :rare)
+      result = client.strongest_units(limit: 1)
+      expect(result[:units].first[:id]).to eq(:freq)
+    end
+  end
+
+  describe '#assemblies_for' do
+    it 'finds assemblies for a unit' do
+      10.times { client.co_activate_units(ids: %i[a b c]) }
+      result = client.assemblies_for(unit_id: :a)
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+    end
+  end
+
+  describe '#update_hebbian' do
+    it 'runs decay tick' do
+      result = client.update_hebbian
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#hebbian_stats' do
+    it 'returns stats' do
+      result = client.hebbian_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:units, :assemblies, :total_connections)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/hebbian_assembly'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: lex-hebbian-assembly
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Hebb's Cell Assembly Theory for brain-modeled agentic AI — neurons that
+  fire together wire together, forming emergent assemblies that represent concepts,
+  enable pattern completion, and support associative recall through co-activation-driven
+  synaptic strengthening.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-hebbian-assembly.gemspec
+- lib/legion/extensions/hebbian_assembly.rb
+- lib/legion/extensions/hebbian_assembly/actors/decay.rb
+- lib/legion/extensions/hebbian_assembly/client.rb
+- lib/legion/extensions/hebbian_assembly/helpers/assembly.rb
+- lib/legion/extensions/hebbian_assembly/helpers/assembly_network.rb
+- lib/legion/extensions/hebbian_assembly/helpers/constants.rb
+- lib/legion/extensions/hebbian_assembly/helpers/unit.rb
+- lib/legion/extensions/hebbian_assembly/runners/hebbian_assembly.rb
+- lib/legion/extensions/hebbian_assembly/version.rb
+- spec/legion/extensions/hebbian_assembly/client_spec.rb
+- spec/legion/extensions/hebbian_assembly/helpers/assembly_network_spec.rb
+- spec/legion/extensions/hebbian_assembly/helpers/assembly_spec.rb
+- spec/legion/extensions/hebbian_assembly/helpers/unit_spec.rb
+- spec/legion/extensions/hebbian_assembly/runners/hebbian_assembly_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-hebbian-assembly
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-hebbian-assembly
+  source_code_uri: https://github.com/LegionIO/lex-hebbian-assembly
+  documentation_uri: https://github.com/LegionIO/lex-hebbian-assembly
+  changelog_uri: https://github.com/LegionIO/lex-hebbian-assembly
+  bug_tracker_uri: https://github.com/LegionIO/lex-hebbian-assembly/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Hebbian Assembly
+test_files: []