lex-cognitive-architecture 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '092043a1bda6a7ef72fdfa70981dcbfa1804327a1271a1c6f688f9336af261ab'
+  data.tar.gz: 4aff5efd3be134b77150e1389f8a730c7eb14d3f1601de4457bc393db27f64d3
+SHA512:
+  metadata.gz: 875b1f19bd4883428b0f63ed0226b8f3646909700292b28c3ab8c7b5b93b09f2c3025347bf006ce5fea7fa9ed45d210f47d0a5a419ea289edbaf3aa49b5d6358
+  data.tar.gz: b4867d3611de73f06bcf81c99b3ade4e5f818fdcd53bc245a5f3d696b4bfde8c01b89830cbe929a1f0a121186d5752b89c493ef3f1d5459df5785090f0fc49d9

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,48 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,81 @@
+# lex-cognitive-architecture
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Meta-extension that models the agent cognitive architecture as a graph of subsystems, connections, and information flows — enabling self-awareness of its own architecture. Provides health monitoring, bottleneck detection, and downstream traversal across named subsystems.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-architecture`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveArchitecture`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_architecture/
+  cognitive_architecture.rb        # top-level require
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    subsystem.rb
+    connection.rb
+    architecture_engine.rb
+  runners/
+    cognitive_architecture.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `SUBSYSTEM_TYPES` — `%i[perception cognition memory motivation safety communication introspection coordination]`
+- `CONNECTION_TYPES` — `%i[excitatory inhibitory modulatory informational]`
+- `STATUS_LEVELS` — `%i[active idle degraded offline]`
+- `HEALTH_LABELS` — range map: `0.8+` = `:excellent`, `0.6` = `:good`, `0.4` = `:fair`, `0.2` = `:degraded`, below = `:critical`
+- `BOTTLENECK_THRESHOLD` = `0.3` (load > threshold AND health < 0.5)
+- `MAX_SUBSYSTEMS` = `200`, `MAX_CONNECTIONS` = `1000`, `MAX_HISTORY` = `500`
+- `DEFAULT_HEALTH` = `0.8`, `HEALTH_DECAY` = `0.01`, `HEALTH_BOOST` = `0.05`
+
+## Runners
+
+All methods in `Runners::CognitiveArchitecture` (`extend self`):
+
+- `register_architecture_subsystem(name:, subsystem_type:, health: DEFAULT_HEALTH)` — registers a new named subsystem; raises on duplicate or capacity exceeded
+- `create_architecture_connection(source_name:, target_name:, connection_type: :informational, weight: 0.5)` — creates a directed connection between two subsystems
+- `activate_architecture_subsystem(name:)` — activates subsystem and propagates activation to excitatory targets
+- `degrade_architecture_subsystem(name:)` — applies health decay; marks `:degraded` when health < 0.4
+- `subsystem_status_report(name:)` — returns full `to_h` for a named subsystem
+- `bottleneck_report` — returns all subsystems where load > 0.3 AND health < 0.5
+- `architecture_health_report` — average health across all subsystems + active count
+- `architecture_graph_report` — full `{ nodes:, edges: }` graph
+- `downstream_subsystems(name:, max_depth: 5)` — BFS traversal of reachable subsystems
+- `update_cognitive_architecture` — runs `decay_all` (decrements health by `HEALTH_DECAY` on all)
+- `cognitive_architecture_stats` — summary hash: counts, health, bottleneck count
+
+## Helpers
+
+- `ArchitectureEngine` — in-memory store of `Subsystem` and `Connection` objects. BFS traversal via `downstream`. Excitatory connections propagate activation.
+- `Subsystem` — has `id`, `name`, `subsystem_type`, `health`, `status`, `load`, `activation_count`. Methods: `activate!`, `degrade!(amount)`, `recover!(amount)`, `bottlenecked?`, `health_label`.
+- `Connection` — directed edge with `source_id`, `target_id`, `connection_type`, `weight`, `active`. Methods: `strengthen!`, `weaken!`, `toggle!`.
+
+## Integration Points
+
+- No direct dependencies on other agentic LEXs. This extension is a meta-layer: any other extension can register its processing subsystem here to make the architecture graph self-aware.
+- `lex-cortex` is the natural caller: wiring `lex-cognitive-architecture` into the tick cycle allows the agent to model its own cognitive topology during introspection phases.
+- `activate_architecture_subsystem` propagates through excitatory connections, modeling cascading activation across cognitive subsystems.
+
+## Development Notes
+
+- `ArchitectureEngine` state is per-`RunnerHost` instance (in-memory only; resets on restart).
+- `decay_all` runs `degrade!(HEALTH_DECAY)` on every subsystem — intended to be called periodically (e.g., `update_cognitive_architecture` runner).
+- Subsystem names are coerced to symbols on registration; duplicate names raise `ArgumentError`.
+- Bottleneck detection requires both high load (`@load > BOTTLENECK_THRESHOLD`) and low health (`@health < 0.5`). `@load` is set externally — the engine does not auto-compute it.
+- BFS depth limit (`max_depth: 5`) prevents runaway traversal in dense graphs.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-architecture (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-architecture!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,44 @@
+# lex-cognitive-architecture
+
+Meta-extension that models the agent cognitive architecture as a graph of subsystems, connections, and information flows — enabling self-awareness of its own architecture.
+
+## What It Does
+
+Provides a self-model of the agent's cognitive topology. Subsystems (perception, memory, motivation, safety, etc.) are registered as graph nodes with health scores and load tracking. Directed connections between subsystems have types (excitatory, inhibitory, modulatory, informational) and weights. The engine supports:
+
+- Health decay and activation propagation across connected subsystems
+- Bottleneck detection (high load + low health)
+- BFS downstream traversal to find all reachable subsystems from a source
+- Architecture-wide health scoring and graph export
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveArchitecture::Client.new
+
+client.register_architecture_subsystem(name: :memory, subsystem_type: :memory)
+client.register_architecture_subsystem(name: :emotion, subsystem_type: :cognition)
+client.create_architecture_connection(
+  source_name: :emotion,
+  target_name: :memory,
+  connection_type: :excitatory,
+  weight: 0.8
+)
+
+client.activate_architecture_subsystem(name: :emotion)
+client.architecture_health_report
+client.bottleneck_report
+client.architecture_graph_report
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-architecture.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_architecture/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-architecture'
+  spec.version       = Legion::Extensions::CognitiveArchitecture::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Architecture'
+  spec.description   = 'Meta-extension that models the agent cognitive architecture as a graph of subsystems, ' \
+                       'connections, and information flows — enabling self-awareness of its own architecture'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-architecture'
+  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-cognitive-architecture'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-architecture'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-architecture'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-architecture/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      class Client
+        include Runners::CognitiveArchitecture
+
+        def initialize(**)
+          @engine = Helpers::ArchitectureEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_architecture/helpers/architecture_engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      module Helpers
+        class ArchitectureEngine
+          include Constants
+
+          def initialize
+            @subsystems  = {}
+            @connections = {}
+          end
+
+          def register_subsystem(name:, subsystem_type:, health: Constants::DEFAULT_HEALTH)
+            raise ArgumentError, "subsystem '#{name}' already registered" if @subsystems.key?(name.to_sym)
+            raise ArgumentError, "max subsystems (#{Constants::MAX_SUBSYSTEMS}) reached" if @subsystems.size >= Constants::MAX_SUBSYSTEMS
+
+            subsystem = Subsystem.new(name: name, subsystem_type: subsystem_type, health: health)
+            @subsystems[subsystem.name] = subsystem
+            subsystem
+          end
+
+          def create_connection(source_name:, target_name:, connection_type: :informational, weight: 0.5)
+            raise ArgumentError, "max connections (#{Constants::MAX_CONNECTIONS}) reached" if @connections.size >= Constants::MAX_CONNECTIONS
+
+            source = find_subsystem!(source_name)
+            target = find_subsystem!(target_name)
+
+            conn = Connection.new(
+              source_id:       source.id,
+              target_id:       target.id,
+              connection_type: connection_type,
+              weight:          weight
+            )
+            @connections[conn.id] = conn
+            conn
+          end
+
+          def activate_subsystem(name:)
+            subsystem = find_subsystem!(name)
+            subsystem.activate!
+
+            excitatory_connections_from(subsystem.id).each do |conn|
+              target = subsystem_by_id(conn.target_id)
+              target&.activate!
+            end
+
+            { name: subsystem.name, status: subsystem.status, health: subsystem.health }
+          end
+
+          def degrade_subsystem(name:)
+            subsystem = find_subsystem!(name)
+            subsystem.degrade!
+            { name: subsystem.name, status: subsystem.status, health: subsystem.health }
+          end
+
+          def recover_subsystem(name:)
+            subsystem = find_subsystem!(name)
+            subsystem.recover!
+            { name: subsystem.name, status: subsystem.status, health: subsystem.health }
+          end
+
+          def subsystem_status(name:)
+            find_subsystem!(name).to_h
+          end
+
+          def active_subsystems
+            @subsystems.values.select { |s| s.status == :active }
+          end
+
+          def bottlenecked_subsystems
+            @subsystems.values.select(&:bottlenecked?)
+          end
+
+          def connections_for(name:)
+            subsystem = find_subsystem!(name)
+            @connections.values.select do |c|
+              c.source_id == subsystem.id || c.target_id == subsystem.id
+            end
+          end
+
+          def downstream(name:, max_depth: 5)
+            start   = find_subsystem!(name)
+            visited = bfs_visited(start.id, max_depth)
+            visited.keys.filter_map { |sid| subsystem_by_id(sid) }.reject { |s| s.id == start.id }
+          end
+
+          def architecture_health
+            return 0.0 if @subsystems.empty?
+
+            total = @subsystems.values.sum(&:health)
+            total / @subsystems.size
+          end
+
+          def architecture_graph
+            {
+              nodes: @subsystems.values.map(&:to_h),
+              edges: @connections.values.map(&:to_h)
+            }
+          end
+
+          def decay_all
+            @subsystems.each_value { |s| s.degrade!(Constants::HEALTH_DECAY) }
+            { decayed: @subsystems.size }
+          end
+
+          def to_h
+            {
+              subsystem_count:     @subsystems.size,
+              connection_count:    @connections.size,
+              active_count:        active_subsystems.size,
+              bottlenecked_count:  bottlenecked_subsystems.size,
+              architecture_health: architecture_health
+            }
+          end
+
+          private
+
+          def find_subsystem!(name)
+            @subsystems.fetch(name.to_sym) do
+              raise ArgumentError, "subsystem '#{name}' not found"
+            end
+          end
+
+          def subsystem_by_id(id)
+            @subsystems.values.find { |s| s.id == id }
+          end
+
+          def excitatory_connections_from(source_id)
+            @connections.values.select do |c|
+              c.source_id == source_id && c.connection_type == :excitatory && c.active
+            end
+          end
+
+          def bfs_visited(start_id, max_depth)
+            visited = {}
+            queue   = [[start_id, 0]]
+
+            until queue.empty?
+              current_id, depth = queue.shift
+              next if visited.key?(current_id)
+
+              visited[current_id] = depth
+              enqueue_neighbors(current_id, depth, visited, queue) if depth < max_depth
+            end
+
+            visited
+          end
+
+          def enqueue_neighbors(current_id, depth, visited, queue)
+            @connections.each_value do |conn|
+              next unless conn.source_id == current_id && conn.active
+              next if visited.key?(conn.target_id)
+
+              queue << [conn.target_id, depth + 1]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_architecture/helpers/connection.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      module Helpers
+        class Connection
+          attr_reader :id, :source_id, :target_id, :connection_type, :created_at
+          attr_accessor :weight, :active
+
+          def initialize(source_id:, target_id:, connection_type: :informational, weight: 0.5)
+            @id              = SecureRandom.uuid
+            @source_id       = source_id
+            @target_id       = target_id
+            @connection_type = connection_type.to_sym
+            @weight          = weight.clamp(0.0, 1.0)
+            @active          = true
+            @created_at      = Time.now.utc
+          end
+
+          def strengthen!(amount = 0.05)
+            @weight = (@weight + amount).clamp(0.0, 1.0)
+            self
+          end
+
+          def weaken!(amount = 0.05)
+            @weight = (@weight - amount).clamp(0.0, 1.0)
+            self
+          end
+
+          def toggle!
+            @active = !@active
+            self
+          end
+
+          def to_h
+            {
+              id:              @id,
+              source_id:       @source_id,
+              target_id:       @target_id,
+              connection_type: @connection_type,
+              weight:          @weight,
+              active:          @active,
+              created_at:      @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      module Helpers
+        module Constants
+          SUBSYSTEM_TYPES  = %i[perception cognition memory motivation safety communication introspection coordination].freeze
+          CONNECTION_TYPES = %i[excitatory inhibitory modulatory informational].freeze
+          STATUS_LEVELS    = %i[active idle degraded offline].freeze
+
+          HEALTH_LABELS = {
+            (0.8..)     => :excellent,
+            (0.6...0.8) => :good,
+            (0.4...0.6) => :fair,
+            (0.2...0.4) => :degraded,
+            (..0.2)     => :critical
+          }.freeze
+
+          BOTTLENECK_THRESHOLD = 0.3
+
+          MAX_SUBSYSTEMS  = 200
+          MAX_CONNECTIONS = 1000
+          MAX_HISTORY     = 500
+
+          DEFAULT_HEALTH = 0.8
+          HEALTH_DECAY   = 0.01
+          HEALTH_BOOST   = 0.05
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_architecture/helpers/subsystem.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      module Helpers
+        class Subsystem
+          include Constants
+
+          attr_reader :id, :name, :subsystem_type, :activation_count, :last_activated_at, :created_at
+          attr_accessor :health, :status, :load
+
+          def initialize(name:, subsystem_type:, health: Constants::DEFAULT_HEALTH)
+            @id               = SecureRandom.uuid
+            @name             = name.to_sym
+            @subsystem_type   = subsystem_type.to_sym
+            @health           = health.clamp(0.0, 1.0)
+            @status           = :active
+            @load             = 0.0
+            @activation_count = 0
+            @last_activated_at = nil
+            @created_at       = Time.now.utc
+          end
+
+          def activate!
+            @activation_count += 1
+            @last_activated_at = Time.now.utc
+            @health = (@health + Constants::HEALTH_BOOST).clamp(0.0, 1.0)
+            self
+          end
+
+          def degrade!(amount = Constants::HEALTH_DECAY)
+            @health = (@health - amount).clamp(0.0, 1.0)
+            @status = :degraded if @health < 0.4
+            self
+          end
+
+          def recover!(amount = Constants::HEALTH_BOOST)
+            @health = (@health + amount).clamp(0.0, 1.0)
+            @status = :active if @health >= 0.4
+            self
+          end
+
+          def bottlenecked?
+            @load > Constants::BOTTLENECK_THRESHOLD && @health < 0.5
+          end
+
+          def health_label
+            Constants::HEALTH_LABELS.each do |range, label|
+              return label if range.cover?(@health)
+            end
+            :critical
+          end
+
+          def to_h
+            {
+              id:                @id,
+              name:              @name,
+              subsystem_type:    @subsystem_type,
+              health:            @health,
+              health_label:      health_label,
+              status:            @status,
+              load:              @load,
+              activation_count:  @activation_count,
+              last_activated_at: @last_activated_at,
+              created_at:        @created_at,
+              bottlenecked:      bottlenecked?
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      module Runners
+        module CognitiveArchitecture
+          extend self
+
+          def register_architecture_subsystem(name:, subsystem_type:, health: Helpers::Constants::DEFAULT_HEALTH, **)
+            Legion::Logging.debug "[cognitive_architecture] registering subsystem: #{name} (#{subsystem_type})"
+            subsystem = engine.register_subsystem(name: name, subsystem_type: subsystem_type, health: health)
+            { status: :registered, subsystem: subsystem.to_h }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_architecture] register_subsystem failed: #{e.message}"
+            { status: :error, message: e.message }
+          end
+
+          def create_architecture_connection(source_name:, target_name:,
+                                             connection_type: :informational, weight: 0.5, **)
+            Legion::Logging.debug "[cognitive_architecture] creating connection: #{source_name} -> #{target_name} (#{connection_type})"
+            conn = engine.create_connection(
+              source_name:     source_name,
+              target_name:     target_name,
+              connection_type: connection_type,
+              weight:          weight
+            )
+            { status: :created, connection: conn.to_h }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_architecture] create_connection failed: #{e.message}"
+            { status: :error, message: e.message }
+          end
+
+          def activate_architecture_subsystem(name:, **)
+            Legion::Logging.debug "[cognitive_architecture] activating subsystem: #{name}"
+            result = engine.activate_subsystem(name: name)
+            { status: :activated, name: result[:name], health: result[:health], subsystem_status: result[:status] }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_architecture] activate_subsystem failed: #{e.message}"
+            { status: :error, message: e.message }
+          end
+
+          def degrade_architecture_subsystem(name:, **)
+            Legion::Logging.debug "[cognitive_architecture] degrading subsystem: #{name}"
+            result = engine.degrade_subsystem(name: name)
+            { status: :degraded, name: result[:name], health: result[:health], subsystem_status: result[:status] }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_architecture] degrade_subsystem failed: #{e.message}"
+            { status: :error, message: e.message }
+          end
+
+          def subsystem_status_report(name:, **)
+            Legion::Logging.debug "[cognitive_architecture] status report for: #{name}"
+            engine.subsystem_status(name: name)
+          rescue ArgumentError => e
+            { status: :error, message: e.message }
+          end
+
+          def bottleneck_report(**)
+            bottlenecked = engine.bottlenecked_subsystems
+            Legion::Logging.debug "[cognitive_architecture] bottleneck_report: #{bottlenecked.size} bottlenecked"
+            {
+              bottlenecked_count: bottlenecked.size,
+              subsystems:         bottlenecked.map(&:to_h)
+            }
+          end
+
+          def architecture_health_report(**)
+            health = engine.architecture_health
+            Legion::Logging.debug "[cognitive_architecture] architecture_health: #{health.round(3)}"
+            {
+              health:       health,
+              health_label: label_for_health(health),
+              active_count: engine.active_subsystems.size
+            }
+          end
+
+          def architecture_graph_report(**)
+            Legion::Logging.debug '[cognitive_architecture] building architecture_graph'
+            engine.architecture_graph
+          end
+
+          def downstream_subsystems(name:, max_depth: 5, **)
+            Legion::Logging.debug "[cognitive_architecture] downstream traversal from: #{name} (max_depth=#{max_depth})"
+            reachable = engine.downstream(name: name, max_depth: max_depth)
+            {
+              source:    name,
+              reachable: reachable.map(&:to_h),
+              count:     reachable.size
+            }
+          rescue ArgumentError => e
+            { status: :error, message: e.message }
+          end
+
+          def update_cognitive_architecture(**)
+            Legion::Logging.debug '[cognitive_architecture] running decay cycle'
+            result = engine.decay_all
+            { status: :updated, decayed: result[:decayed] }
+          end
+
+          def cognitive_architecture_stats(**)
+            engine.to_h
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::ArchitectureEngine.new
+          end
+
+          def label_for_health(health)
+            Helpers::Constants::HEALTH_LABELS.each do |range, label|
+              return label if range.cover?(health)
+            end
+            :critical
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_architecture.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_architecture/version'
+require 'legion/extensions/cognitive_architecture/helpers/constants'
+require 'legion/extensions/cognitive_architecture/helpers/subsystem'
+require 'legion/extensions/cognitive_architecture/helpers/connection'
+require 'legion/extensions/cognitive_architecture/helpers/architecture_engine'
+require 'legion/extensions/cognitive_architecture/runners/cognitive_architecture'
+require 'legion/extensions/cognitive_architecture/client'
+
+module Legion
+  module Extensions
+    module CognitiveArchitecture
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-architecture
+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: Meta-extension that models the agent cognitive architecture as a graph
+  of subsystems, connections, and information flows — enabling self-awareness of its
+  own architecture
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-architecture.gemspec
+- lib/legion/extensions/cognitive_architecture.rb
+- lib/legion/extensions/cognitive_architecture/client.rb
+- lib/legion/extensions/cognitive_architecture/helpers/architecture_engine.rb
+- lib/legion/extensions/cognitive_architecture/helpers/connection.rb
+- lib/legion/extensions/cognitive_architecture/helpers/constants.rb
+- lib/legion/extensions/cognitive_architecture/helpers/subsystem.rb
+- lib/legion/extensions/cognitive_architecture/runners/cognitive_architecture.rb
+- lib/legion/extensions/cognitive_architecture/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-architecture
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-architecture
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-architecture
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-architecture
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-architecture
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-architecture/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 Cognitive Architecture
+test_files: []