gem install legionio
# or
brew tap LegionIO/tap && brew install legionio

Most AI agent frameworks give you a loop: prompt, tool call, repeat. LegionIO gives you a cognitive architecture — memory that fades, emotions that shift decisions, trust that's earned, predictions that fail and adapt, and agents that dream during idle cycles to consolidate what they've learned.

It's not a wrapper around an LLM. It's a brain built from first principles.

Every LegionIO agent runs a tick cycle — a 13-phase cognitive loop modeled on biological neural processing. Each tick, the agent perceives, remembers, predicts, decides, acts, and reflects. During idle periods, a 7-phase dream cycle consolidates and reorganizes memory.

flowchart LR
    subgraph TICK["Waking Tick Cycle"]
        direction LR
        A["Sensory\nProcessing"] --> B["Emotional\nEvaluation"]
        B --> C["Memory\nRetrieval"]
        C --> D["Knowledge\nRetrieval"]
        D --> E["Identity\nEntropy Check"]
        E --> F["Working Memory\nIntegration"]
        F --> G["Procedural\nCheck"]
        G --> H["Prediction\nEngine"]
        H --> I["Mesh\nInterface"]
        I --> J["Gut\nInstinct"]
        J --> K["Action\nSelection"]
        K --> L["Memory\nConsolidation"]
        L --> M["Post-Tick\nReflection"]
    end

    subgraph DREAM["Dream Cycle"]
        direction LR
        D1["Memory\nAudit"] --> D2["Association\nWalk"]
        D2 --> D3["Contradiction\nResolution"]
        D3 --> D4["Agenda\nFormation"]
        D4 --> D5["Consolidation\nCommit"]
        D5 --> D6["Dream\nReflection"]
        D6 --> D7["Dream\nNarration"]
    end

234 cognitive modules organized into 13 domain gems, each modeling a distinct aspect of cognition:

Every module is optional. They compose. They interact. Drop one and the rest adapt.

GAIA (General Agentic Intelligence Architecture) orchestrates the tick cycle, routes messages between cognitive modules, and manages the channel abstraction that connects perception to action.

Think of it as the thalamus — not doing the thinking, but making sure the right signals reach the right place at the right time.

Synapse models the nervous system between task execution and cognition:

Autonomy scales with confidence: Observe (0-0.3) → Filter (0.3-0.6) → Transform (0.6-0.8) → Autonomous (0.8-1.0). Three consecutive failures trigger auto-revert.

Apollo is the shared durable knowledge layer for the cognitive mesh. Backed by PostgreSQL with pgvector, it provides:

• Confidence decay: Knowledge starts at 0.5, strengthened by corroboration, weakened by time
• Semantic retrieval: Cosine similarity search over 1536-dimensional embeddings
• Cross-agent sharing: Agents interact via RabbitMQ only — no direct DB access
• Knowledge lifecycle: candidate → confirmed → decayed → archived

All of this cognition runs on a production-grade async job engine:

• RabbitMQ message broker with priority queues and dead-letter exchanges
• Task chaining — Task A -> [transform] -> Task B -> [condition] -> Task C
• Extension auto-discovery — drop a lex-* gem in your Gemfile and it's live
• 5 actor types — subscription, polling, interval, one-shot, loop
• Distributed scheduling with cron expressions and interval locking
• HashiCorp Vault for secrets, dynamic credentials, PKI, and JWT
• Multi-database support — SQLite, PostgreSQL, MySQL via Sequel
• Two-tier caching — Redis/Memcached with local fallback
• RBAC — Vault-style flat policies for fine-grained access control
• Transport spool — JSONL disk buffer when AMQP is unavailable (72hr retention)

# CLI — 60+ commands, every one supports --json
legion start
legion task run http.request.get url:https://example.com
legion lex list
legion dashboard

# Interactive AI Chat (built-in agentic REPL)
legion chat
legion chat prompt "analyze this codebase"

# REST API (Sinatra + Puma)
curl http://localhost:4567/api/v1/tasks

# MCP Server (Model Context Protocol) — plug Legion into any AI agent
legion mcp

LegionIO isn't competing with LLMs — it gives them a body.

Credentials resolve through a universal secret resolver: vault://path#key, env://VAR_NAME, or plain strings — with fallback chains.

                          ┌──────────────────────────────────────┐
                          │          LegionIO v1.4.74            │
                          │    CLI  /  REST API  /  MCP  / Chat  │
                          └──────────────────┬───────────────────┘
                                             │
              ┌──────────┬──────────┬────────┼────────┬──────────┬──────────┐
              │          │          │        │        │          │          │
          transport    crypt      data    cache    settings    llm       gaia
          (RabbitMQ)  (Vault)  (Sequel)  (Redis)  (config)  (ruby_llm) (tick)
              │          │          │        │        │          │          │
              └──────────┴──────────┴────────┼────────┴──────────┴──────────┘
                                             │
                  ┌──────────────────────────┼──────────────────────────┐
                  │                          │                          │
           18 Core LEXs              13 Cognitive Domains        29 Service LEXs
         (tasker, synapse,         (234 sub-modules:            (slack, redis, http,
          scheduler, node,          memory, emotion,             ssh, s3, vault,
          conditioner...)           trust, prediction...)        github, chef...)

# Install via Homebrew (recommended)
brew tap LegionIO/tap
brew install legion

# Or via RubyGems
gem install legionio

# Start the engine
legion start

# Scaffold a new extension in 10 seconds
legion lex create my_extension
legion generate runner my_runner
legion generate actor my_actor

# Or just start chatting
legion chat

• Ruby >= 3.4
• RabbitMQ (AMQP 0.9.1)
• Optional: PostgreSQL/MySQL/SQLite, Redis/Memcached, HashiCorp Vault

Core framework: Apache-2.0 | Extensions: MIT