lex-cognitive-immune-memory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 012131c8a1758dd81ca39180981eeece28699fdd6e29b9e21c00150fbee3ba2b
+  data.tar.gz: 9fbc8c5b7f8d3cdc8e63e21de41b6012fd1e78266d78e214b0f1956f45c0da15
+SHA512:
+  metadata.gz: 2f36b3a716fef71808de082745ec4cec13e31147d1e60140d3f18c4b0cedad0ffbb554b8823ab33dd3c2ffa7cf7d3f4b843e5b6ae060a978ca40408b8ba8b984
+  data.tar.gz: 9d2318d3428096bc2d882fbd954ffcf4728e8e4bcb8fa9ddf4864b3c1e3f1d62c830f28ad33918ec8f4da1617dde938ee1fd6803e9f672f87226f4e493300112

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,10 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+pkg
+spec/reports
+tmp
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--order random

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*
+
+Style/OneClassPerFile:
+  Exclude:
+    - spec/spec_helper.rb

data/CLAUDE.md

@@ -0,0 +1,116 @@
+# lex-cognitive-immune-memory
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-immune-memory`
+
+## Purpose
+
+Models long-term immunological memory for cognitive threat recognition. Memory cells are trained records of past threats — each encounter with a known threat type produces a primary response and creates or strengthens a memory cell. Subsequent encounters trigger secondary responses that are faster and stronger than primary. Vaccination artificially installs memory cells without requiring a live encounter. Memory cells decay over time if not reinforced. Tracks threat coverage, neutralization rate, and average response speed across the cell population.
+
+## Gem Info
+
+| Field | Value |
+|---|---|
+| Gem name | `lex-cognitive-immune-memory` |
+| Version | `0.1.0` |
+| Namespace | `Legion::Extensions::CognitiveImmuneMemory` |
+| Ruby | `>= 3.4` |
+| License | MIT |
+| GitHub | https://github.com/LegionIO/lex-cognitive-immune-memory |
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_immune_memory/
+  cognitive_immune_memory.rb        # Top-level require
+  version.rb                        # VERSION = '0.1.0'
+  client.rb                         # Client class
+  helpers/
+    constants.rb                    # Threat types, cell types, activation thresholds, response speeds, labels
+    memory_cell.rb                  # MemoryCell value object
+    immune_memory_engine.rb         # Engine: cells, vaccination, encounters, decay, coverage
+  runners/
+    cognitive_immune_memory.rb      # Runner module
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `MAX_MEMORY_CELLS` | 500 | Memory cell cap |
+| `T_CELL_ACTIVATION_THRESHOLD` | 0.5 | Strength threshold for T-cell activation |
+| `B_CELL_ACTIVATION_THRESHOLD` | 0.4 | Strength threshold for B-cell activation |
+| `T_CELL_BOOST` | 0.15 | Strength increase per encounter for T-cells |
+| `B_CELL_BOOST` | 0.12 | Strength increase per encounter for B-cells |
+| `PRIMARY_RESPONSE_SPEED` | 0.3 | Baseline response speed for primary encounter |
+| `SECONDARY_RESPONSE_SPEED` | 0.8 | Elevated response speed for known threats |
+| `VACCINATION_STRENGTH` | 0.5 | Starting strength for vaccinated cells |
+| `THREAT_TYPES` | array | `[:manipulation, :deception, :coercion, :exploitation, :distraction, :flooding, :anchoring, :mirroring]` |
+| `CELL_TYPES` | array | `[:t_cell, :b_cell, :memory_t, :memory_b, :natural_killer]` |
+| `IMMUNITY_LABELS` | hash | `immune` (0.8+) through `naive` |
+| `RESPONSE_SPEED_LABELS` | hash | `instant` (0.9+) through `slow` |
+| `HEALTH_LABELS` | hash | `robust` through `depleted` |
+| `MATURITY_LABELS` | hash | `veteran` through `naive` |
+
+## Helpers
+
+### `MemoryCell`
+
+A trained immunological record for a specific threat type.
+
+- `initialize(threat_type:, cell_type:, strength: 0.5, cell_id: nil)`
+- `encounter!(boost)` — increases strength by cell-type boost; increments encounter_count; increases response_speed
+- `decay!(rate)` — decreases strength, floor 0.0
+- `active?` — strength >= cell-type activation threshold
+- `veteran?` — encounter_count above veteran threshold
+- `response_speed` — starts at PRIMARY_RESPONSE_SPEED; increases toward SECONDARY_RESPONSE_SPEED with encounters
+- `to_h`
+
+### `ImmuneMemoryEngine`
+
+- `create_memory_cell(threat_type:, cell_type: :memory_t, strength: 0.5)` — returns `{ created:, cell_id:, cell: }` or capacity error
+- `vaccinate(threat_type:)` — creates a memory cell at `VACCINATION_STRENGTH` without a live encounter
+- `encounter_threat(threat_type:)` — checks for existing memory cells matching threat_type; if found, triggers secondary response (boosts all matching cells, returns fast response); if not found, triggers primary response and creates new memory cell
+- `decay_all!` — decrements all cell strength values
+- `secondary_response_rate` — proportion of threats that have established memory cells
+- `neutralization_rate` — proportion of active (above-threshold) cells
+- `average_response_speed` — mean response_speed across all cells
+- `threat_coverage` — hash of threat_type -> strongest cell strength
+- `overall_health` — composite score from neutralization, coverage breadth, and mean strength
+- `immune_status_report` — full stats
+
+## Runners
+
+**Module**: `Legion::Extensions::CognitiveImmuneMemory::Runners::CognitiveImmuneMemory`
+
+| Method | Key Args | Returns |
+|---|---|---|
+| `create_memory_cell` | `threat_type:`, `cell_type: :memory_t`, `strength: 0.5` | `{ success:, cell_id:, cell: }` |
+| `vaccinate` | `threat_type:` | `{ success:, cell_id:, cell: }` |
+| `encounter_threat` | `threat_type:` | `{ success:, response_type:, response_speed:, cells_activated: }` |
+| `decay_all` | — | `{ success:, decayed: N }` |
+| `immunity_for` | `threat_type:` | `{ success:, strength:, cells: }` |
+| `active_cells` | `limit: 20` | `{ success:, cells: }` |
+| `veteran_cells` | `limit: 10` | `{ success:, cells: }` |
+| `threat_coverage` | — | `{ success:, coverage: { threat_type => strength } }` |
+| `immune_status` | — | `{ success:, report: }` |
+
+Private: `immune_memory_engine` — memoized `ImmuneMemoryEngine`. Logs via `log_debug` helper.
+
+## Integration Points
+
+- **`lex-cognitive-immunology`**: `lex-cognitive-immune-memory` handles long-term recognition and learned threat response. `lex-cognitive-immunology` handles live threat detection, quarantine, and inflammatory response. The two complement each other: immunology for acute response, immune-memory for durable recognition.
+- **`lex-cognitive-immune-response`**: Immune response generates antibodies; immune memory stores the learned patterns. After a threat encounter in `lex-cognitive-immune-response`, a corresponding vaccination in immune-memory can install durable recognition.
+- **`lex-trust`**: Low secondary_response_rate (few threats in memory) corresponds to a naive agent with undeveloped trust discrimination. High memory coverage supports more nuanced trust evaluation.
+
+## Development Notes
+
+- `encounter_threat` distinguishes primary vs. secondary response by whether any memory cell for the threat_type exists and is active. New memory cells are created on primary encounter regardless of capacity (up to MAX_MEMORY_CELLS).
+- `vaccinate` creates a new cell at `VACCINATION_STRENGTH` each call — calling vaccinate multiple times for the same threat_type creates multiple cells.
+- `decay_all!` decays all cells unconditionally. Cells that decay to 0.0 remain in the store; callers should check `active?` and prune manually.
+- In-memory only.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

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

data/README.md

@@ -0,0 +1,47 @@
+# lex-cognitive-immune-memory
+
+Long-term cognitive threat recognition engine for brain-modeled agentic AI in the LegionIO ecosystem.
+
+## What It Does
+
+Models immunological memory for cognitive security. Memory cells are trained records of past threat encounters — manipulation, deception, coercion, exploitation, and related adversarial patterns. Encountering a known threat triggers a fast secondary response (response speed 0.8); encountering an unknown threat triggers a slower primary response (0.3) and installs a new memory cell. Vaccination artificially creates memory cells without a live encounter. Memory cells decay over time without reinforcement.
+
+## Usage
+
+```ruby
+require 'legion/extensions/cognitive_immune_memory'
+
+client = Legion::Extensions::CognitiveImmuneMemory::Client.new
+
+# Vaccinate against a known threat pattern
+client.vaccinate(threat_type: :manipulation)
+# => { success: true, cell_id: "...", cell: { strength: 0.5, response_speed: 0.3, ... } }
+
+# Encounter a threat — secondary response since vaccination installed a cell
+client.encounter_threat(threat_type: :manipulation)
+# => { success: true, response_type: :secondary, response_speed: 0.65, cells_activated: 1 }
+
+# Encounter an unknown threat — primary response, installs new memory cell
+client.encounter_threat(threat_type: :anchoring)
+# => { success: true, response_type: :primary, response_speed: 0.3, cells_activated: 0 }
+
+# Check coverage across all known threats
+client.threat_coverage
+# => { success: true, coverage: { manipulation: 0.62, anchoring: 0.5, ... } }
+
+# Overall immune health
+client.immune_status
+# => { success: true, report: { cell_count: 2, health: 0.55, ... } }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-immune-memory.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_immune_memory/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-immune-memory'
+  spec.version       = Legion::Extensions::CognitiveImmuneMemory::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Long-term adaptive immune memory for LegionIO agents'
+  spec.description   = 'T-cell/B-cell persistent threat recognition with secondary response ' \
+                       'amplification for the LegionIO cognitive architecture'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-immune-memory'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => spec.homepage,
+    'documentation_uri'     => "#{spec.homepage}/blob/origin/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/origin/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveImmuneMemory
+      class Client
+        include Runners::CognitiveImmuneMemory
+
+        def initialize
+          @default_engine = Helpers::ImmuneMemoryEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveImmuneMemory
+      module Helpers
+        module Constants
+          MAX_MEMORY_CELLS = 500
+          MAX_ENCOUNTERS = 1000
+          MAX_ANTIBODY_LIBRARY = 300
+
+          # T-cell parameters (cell-mediated: direct threat neutralization)
+          T_CELL_ACTIVATION_THRESHOLD = 0.4
+          T_CELL_BOOST = 0.12
+          T_CELL_DECAY = 0.01
+          T_CELL_LIFESPAN = 100 # decay cycles before expiry check
+
+          # B-cell parameters (humoral: antibody production)
+          B_CELL_ACTIVATION_THRESHOLD = 0.3
+          B_CELL_BOOST = 0.1
+          B_CELL_DECAY = 0.008
+          B_CELL_ANTIBODY_PRODUCTION = 0.15
+
+          # Secondary response amplification
+          PRIMARY_RESPONSE_SPEED = 1.0
+          SECONDARY_RESPONSE_SPEED = 3.0
+          MEMORY_RECOGNITION_THRESHOLD = 0.6
+
+          # Vaccination (pre-exposure)
+          VACCINATION_STRENGTH = 0.5
+
+          THREAT_TYPES = %i[
+            prompt_injection data_poisoning social_engineering
+            resource_exhaustion privilege_escalation information_leak
+            logic_manipulation identity_spoofing
+          ].freeze
+
+          CELL_TYPES = %i[t_helper t_killer b_memory b_plasma].freeze
+
+          IMMUNITY_LABELS = {
+            (0.8..)     => :immune,
+            (0.6...0.8) => :resistant,
+            (0.4...0.6) => :partial,
+            (0.2...0.4) => :vulnerable,
+            (..0.2)     => :naive
+          }.freeze
+
+          RESPONSE_SPEED_LABELS = {
+            (2.5..)     => :lightning,
+            (1.8...2.5) => :rapid,
+            (1.0...1.8) => :normal,
+            (0.5...1.0) => :slow,
+            (..0.5)     => :impaired
+          }.freeze
+
+          HEALTH_LABELS = {
+            (0.8..)     => :robust,
+            (0.6...0.8) => :healthy,
+            (0.4...0.6) => :adequate,
+            (0.2...0.4) => :weakened,
+            (..0.2)     => :compromised
+          }.freeze
+
+          MATURITY_LABELS = {
+            (0.8..)     => :veteran,
+            (0.6...0.8) => :experienced,
+            (0.4...0.6) => :developing,
+            (0.2...0.4) => :immature,
+            (..0.2)     => :naive
+          }.freeze
+
+          def self.label_for(labels, value)
+            labels.each { |range, label| return label if range.cover?(value) }
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_immune_memory/helpers/encounter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveImmuneMemory
+      module Helpers
+        class Encounter
+          include Constants
+
+          attr_reader :id, :threat_type, :threat_signature, :severity,
+                      :response_type, :response_speed, :outcome, :created_at
+
+          def initialize(threat_type:, threat_signature:, severity: 0.5, response_type: :primary,
+                         response_speed: PRIMARY_RESPONSE_SPEED, outcome: :neutralized)
+            @id = SecureRandom.uuid
+            @threat_type = threat_type.to_sym
+            @threat_signature = threat_signature.to_s
+            @severity = severity.to_f.clamp(0.0, 1.0)
+            @response_type = response_type.to_sym
+            @response_speed = response_speed.to_f.round(10)
+            @outcome = outcome.to_sym
+            @created_at = Time.now
+          end
+
+          def secondary? = @response_type == :secondary
+          def primary? = @response_type == :primary
+          def neutralized? = @outcome == :neutralized
+          def evaded? = @outcome == :evaded
+          def critical? = @severity >= 0.8
+
+          def to_h
+            {
+              id:               @id,
+              threat_type:      @threat_type,
+              threat_signature: @threat_signature,
+              severity:         @severity,
+              response_type:    @response_type,
+              response_speed:   @response_speed,
+              outcome:          @outcome,
+              critical:         critical?,
+              created_at:       @created_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_immune_memory/helpers/immune_memory_engine.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveImmuneMemory
+      module Helpers
+        class ImmuneMemoryEngine
+          include Constants
+
+          def initialize
+            @memory_cells = {}
+            @encounters = []
+          end
+
+          def create_memory_cell(threat_type:, signature:, cell_type: :b_memory, strength: VACCINATION_STRENGTH)
+            prune_expired
+            cell = MemoryCell.new(threat_type: threat_type, signature: signature,
+                                  cell_type: cell_type, strength: strength)
+            @memory_cells[cell.id] = cell
+            cell
+          end
+
+          def vaccinate(threat_type:, signature:, strength: VACCINATION_STRENGTH)
+            existing = find_by_signature(signature)
+            return existing.activate! if existing
+
+            create_memory_cell(threat_type: threat_type, signature: signature,
+                               cell_type: :b_memory, strength: strength)
+          end
+
+          def encounter_threat(threat_type:, threat_signature:, severity: 0.5)
+            matching = find_by_signature(threat_signature)
+            response_type = matching ? :secondary : :primary
+            speed = matching ? matching.response_speed : PRIMARY_RESPONSE_SPEED
+            outcome = determine_outcome(matching, severity)
+
+            matching&.activate!
+
+            record = Encounter.new(
+              threat_type: threat_type, threat_signature: threat_signature,
+              severity: severity, response_type: response_type,
+              response_speed: speed, outcome: outcome
+            )
+            @encounters << record
+            prune_encounters
+
+            unless matching
+              create_memory_cell(threat_type: threat_type, signature: threat_signature,
+                                 cell_type: :b_memory, strength: B_CELL_ACTIVATION_THRESHOLD)
+            end
+
+            record
+          end
+
+          def decay_all!
+            @memory_cells.each_value(&:decay!)
+            prune_expired
+            { cells_remaining: @memory_cells.size }
+          end
+
+          def find_by_signature(signature)
+            @memory_cells.values.find { |c| c.signature == signature.to_s && !c.expired? }
+          end
+
+          def cells_for_threat(threat_type:)
+            @memory_cells.values.select { |c| c.threat_type == threat_type.to_sym && !c.expired? }
+          end
+
+          def immunity_for(threat_type:)
+            cells = cells_for_threat(threat_type: threat_type)
+            return 0.0 if cells.empty?
+
+            cells.max_by(&:strength).strength
+          end
+
+          def active_cells = @memory_cells.values.reject(&:expired?)
+          def t_cells = @memory_cells.values.select(&:t_cell?)
+          def b_cells = @memory_cells.values.select(&:b_cell?)
+          def veteran_cells = @memory_cells.values.select(&:veteran?)
+          def naive_cells = @memory_cells.values.select(&:naive?)
+
+          def encounters_for(threat_type:)
+            @encounters.select { |e| e.threat_type == threat_type.to_sym }
+          end
+
+          def secondary_response_rate
+            return 0.0 if @encounters.empty?
+
+            secondary = @encounters.count(&:secondary?)
+            (secondary.to_f / @encounters.size).round(10)
+          end
+
+          def neutralization_rate
+            return 0.0 if @encounters.empty?
+
+            neutralized = @encounters.count(&:neutralized?)
+            (neutralized.to_f / @encounters.size).round(10)
+          end
+
+          def average_response_speed
+            return PRIMARY_RESPONSE_SPEED if @encounters.empty?
+
+            (@encounters.sum(&:response_speed) / @encounters.size).round(10)
+          end
+
+          def threat_coverage
+            known_types = @memory_cells.values.map(&:threat_type).uniq
+            (known_types.size.to_f / THREAT_TYPES.size).clamp(0.0, 1.0).round(10)
+          end
+
+          def overall_health
+            return 0.0 if @memory_cells.empty?
+
+            avg_strength = (@memory_cells.values.sum(&:strength) / @memory_cells.size).round(10)
+            coverage_factor = threat_coverage
+            ((avg_strength * 0.6) + (coverage_factor * 0.4)).clamp(0.0, 1.0).round(10)
+          end
+
+          def health_label = Constants.label_for(HEALTH_LABELS, overall_health)
+
+          def immune_report
+            {
+              total_cells:             @memory_cells.size,
+              active_cells:            active_cells.size,
+              t_cells:                 t_cells.size,
+              b_cells:                 b_cells.size,
+              veteran_cells:           veteran_cells.size,
+              total_encounters:        @encounters.size,
+              secondary_response_rate: secondary_response_rate,
+              neutralization_rate:     neutralization_rate,
+              average_response_speed:  average_response_speed,
+              threat_coverage:         threat_coverage,
+              overall_health:          overall_health,
+              health_label:            health_label
+            }
+          end
+
+          def to_h
+            {
+              total_cells:     @memory_cells.size,
+              active:          active_cells.size,
+              encounters:      @encounters.size,
+              health:          overall_health,
+              threat_coverage: threat_coverage
+            }
+          end
+
+          private
+
+          def determine_outcome(matching_cell, severity)
+            return :neutralized if matching_cell && matching_cell.strength >= severity
+
+            severity < 0.5 ? :neutralized : :evaded
+          end
+
+          def prune_expired
+            @memory_cells.reject! { |_, c| c.expired? } if @memory_cells.size >= MAX_MEMORY_CELLS
+          end
+
+          def prune_encounters
+            @encounters.shift while @encounters.size > MAX_ENCOUNTERS
+          end
+        end
+      end
+    end
+  end
+end