lex-interoception

Visceral body sense for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).

What It Does

lex-interoception models the agent's internal body budget — monitoring nine system vital channels via EMA smoothing, detecting deviations from baseline, and building somatic markers that bias action selection. Just as interoception in humans provides gut-level "body feelings," this extension provides system-level visceral signals to the cognitive architecture.

Key capabilities:

• Nine vital channels: cpu_load, memory_pressure, queue_depth, response_latency, error_rate, connection_health, disk_usage, thread_count, gc_pressure
• EMA smoothing: vital readings smooth toward baseline (alpha=0.15) to avoid noise spikes
• Deviation detection: flags channels that have drifted more than 0.2 from baseline
• Somatic markers: learned approach/avoid/neutral biases per action based on historical vital signatures
• Body budget score: composite health score from all vital channels

Installation

Add to your Gemfile:

gem 'lex-interoception'

Or install directly:

gem install lex-interoception

Usage

require 'legion/extensions/interoception'

client = Legion::Extensions::Interoception::Client.new

# Report system vital readings
client.report_vital(channel: :cpu_load, value: 0.85)
client.report_vital(channel: :response_latency, value: 0.7)

# Check overall body status
status = client.body_status
# => { vitals: { cpu_load: { value: 0.85, label: :high }, ... },
#      body_budget: 0.45, body_label: :strained, deviating: [:cpu_load] }

# Create a somatic marker (learned bias)
client.create_somatic_marker(action: :deploy, valence: :avoid, strength: 0.8)

# Query action bias
bias = client.query_bias(action: :deploy)
# => { valence: :avoid, strength: 0.8, net: -0.8 }

# Check what's deviating
client.deviating_vitals

# Stats
client.interoception_stats

Runner Methods

Method	Description
report_vital	Report a single vital channel reading
create_somatic_marker	Create a learned approach/avoid/neutral bias for an action
query_bias	Get net approach/avoid/neutral bias for an action
reinforce_somatic	Reinforce existing markers matching action and valence
deviating_vitals	List channels currently above deviation threshold
body_status	Full vital readings with labels and body budget score
update_interoception	Extract vitals from tick results; decay markers
interoception_stats	Vital count, marker count, budget label, deviating count

Development

bundle install
bundle exec rspec
bundle exec rubocop

License

MIT