Embodiment

The SEM Protocol

Auto-Generated Tools

When an entity tree loads from YAML, tools are automatically created and registered. No hand-written tool classes per hardware component.

Name collisions are handled by progressive prefixing: shoulder_rotate_angle → robot2_shoulder_rotate_angle if two robots share the same entity name.

Cerebellum: Forward Models

Maxim's Cerebellum stores lightweight predictors per (entity, modulator, affordance, param_bucket). Each learns via Rescorla-Wagner prediction error:

• Confidence < 0.3 → LLM fallback (teaches the Cerebellum)
• Confidence ≥ 0.3 → cached prediction (no LLM call)
• High variance → LLM fallback (uncertain predictions need grounding)

The LLM is a teacher, not a per-tick oracle. After enough observations, the Cerebellum handles predictions deterministically. In testing, LLM calls drop from 100 to ≤40 over 100 actions.

The SEM Learning Loop

When the Cerebellum evaluates an affordance, the outcome flows through the bio-pipeline as a reaction — a typed evaluative signal that drives learning across multiple systems simultaneously. This is the SEM Learning Loop.

CerebellumModulator Outcomes

The CerebellumModulator classifies each affordance execution into one of three outcome paths:

Signal Flow

Both success and pain reactions flow through the ReactionBus, which dispatches to two subscribers in parallel:

Negativity Bias

Success reactions carry positive valence but at lower intensity than pain reactions — mirroring biological negativity bias. A single painful failure creates a stronger learning signal than several routine successes. This asymmetry means the agent develops caution around dangerous affordances faster than it develops confidence around safe ones, which is the correct survival trade-off for an embodied system.

Cerebellum Activation via BioStack

In production, the Cerebellum is wired through BioStack.cerebellum and activated by build_executor. This means every agent entry point that constructs a bio-stack gets Cerebellum forward models and the full SEM Learning Loop automatically — no per-caller wiring required.

Behavioral Convergence Wiring

The SEM Learning Loop produces valence and reward bias in the substrate, but the LLM also needs to see this information. Behavioral convergence wiring (shipped 2026-04-17) closes four gaps: valence annotations in PromptAssembler so the LLM sees “this entity is associated with negative experiences,” observe_episode_event in the agent loop for real-time episode capture, an energy→Reaction bridge that fires hunger/fatigue/satiation interoceptive reactions from energy depletion, and bundled food/water/poison SEM specs. Validated by two experiments: cross-session affective memory (11/11 PASS) and energy-driven consumable learning (13/13 PASS). See Experiments & Results for details.

Motor Programs

A reach-and-grasp isn't three separate LLM decisions. It's one motor program — an ordered sequence of SEM actions that fires as a unit. Programs crystallize when the agent repeats the same sequence 3+ times for the same goal.

Triple-Indexed Registry

The ProgramRegistry indexes programs in three directions:

• By goal — "I want to reach forward" → matching programs
• By entity — "I'm holding a sword" → all programs involving swords
• By affordance — "I want to slash" → programs for sword, axe, arm, claws

Pain-Gated Execution

Each step has an optional pain gate — a sensor threshold that aborts the program before damage occurs. Gates tighten by 10% after each painful execution. The PainBus is subscribed for real-time mid-sequence interrupts.

Motor Engrams

Motor engrams are ephemeral cross-system traces linking motor programs to situational context:

• Cerebellum stores the how (motor program steps)
• Hippocampus stores the when/where/what (contextual episode)
• The engram links them via the associative graph

Engrams form only on significant outcomes — pain > 0.3, surprising results (RPE > 0.3), or novel programs. Routine successes don't need episodic context. Engrams decay after ~2 days unless reinforced, using the standard hippocampal consolidation cycle.

The Cyclical Feedback Loop

Virtual Entities: Beyond Robotics

The SEM protocol is hardware-agnostic. A sword is just an Entity with sensors (durability, sharpness) and modulators (slash, parry) backed by NarrativeModulator instead of hardware. The same cognitive stack that learns about robot joints also learns about swords, NPCs, and doors.

The Cerebellum learns "swinging a damaged sword at a stone golem reduces durability by ~0.15" the same way it learns "rotating an elbow at 90°/s increases strain by ~0.1." Same Rescorla-Wagner update, same forward model, same pain triggers.

Composable Failure Modes

Six base failure modes: overextension, overheating, strain, fatigue, impact, exhaustion. Custom failures compose from these without taxonomy explosion:

Failures route through the existing PainBus and ToolPainBridge. NAc learns (affordance, entity_state) → failure causal links. Persistent failures stay active until recovery conditions are met. All failure state persists across sessions.

Default Embodiment 0.7

Running an Agent with a SEM Body

A live agent can take a SEM body in one CLI flag. --embodiment <ref> loads a bundled component, wraps it in Embodiment(pain_bus=...), and registers all of its affordance tools into the agent's tool registry — the agent can then invoke them on its own timeline through normal tool dispatch with the full pain cascade running end-to-end.

If the ref is wrong, doctor groups same-category alternatives first so a typo in weapons/X shows you the other weapons before unrelated categories:

Behind the Scenes

1. cli.py reads --embodiment weapons/rusty_sword.
2. runtime/bootstrap.py::build_executor — the canonical agent-construction site since the executor bootstrap unification — instantiates the entity via ComponentRegistry, wraps it in Embodiment(pain_bus=...), and calls generate_tools_for_entity.
3. The agent's LLM sees the affordance tools alongside the standard tools and can invoke them via normal tool dispatch.
4. When the agent invokes rusty_sword_slash on a low-durability sword, embodiment.evaluate_failures() fires the shatter failure mode → PainBus.publish(PainSignal) → the executor's ToolPainBridge calls record_tool_embodiment_failure → NAc forms a NEGATIVE causal link.
5. On the next turn, nac.predict() returns NEGATIVE for that tool, informing the agent's policy.

Structural enforcement: the build_executor constructor requires an explicit pain_bus= decision (no default), so forgetting to wire the bridge is a TypeError instead of a silent no-op. Every agent entry point in the codebase makes an explicit pain_bus decision; the prior helper-discipline approach was deprecated after three identical "forgot to wire ToolPainBridge" bugs in three weeks — three-times-is-structural.

Verified end-to-end by tests/substrate/test_sem_execution_production.py against the real bundled weapons/rusty_sword.yaml — no mocks in the cascade chain. Current constraints: --embodiment is mutually exclusive with --sim (sim-mode SEM body wiring is tracked under the AgentFactory canonicalization plan); only one entity can be loaded via the flag (multi-entity bodies are still loaded the old way via Embodiment(spec.root_entity) in code).

Component Library & Genre Gating

SEM components are reusable YAML templates stored in src/maxim/_data/components/ across 5 categories: bodies, creatures, environments, npcs, and weapons. The ComponentRegistry discovers them automatically from three search paths: campaign-local, user (~/.maxim/components/), and bundled.

Genre gating prevents cross-genre contamination. When a campaign declares genre: fantasy, the ComponentRegistry and EntityDesigner only suggest genre-matching or genre-neutral components. A fantasy campaign won't accidentally spawn a cyberpunk patrol drone.

Recognized genre tags: fantasy, cyberpunk, scifi, modern, devops, horror, historical. Explicit registry refs bypass the genre gate — you can intentionally cross genres when needed.

Asset Foundry E1+E2 — 0.6+

Scoring Dimensions

Auto-Curation E3 — 0.7

Before a simulation starts, --auto-curate scans the campaign for entity references that have no matching component in the registry. Missing entities are generated via the Asset Foundry, validated, and promoted to the user directory — filling coverage gaps before the first percept fires.

Deduplication uses the ComponentIndex two-layer lookup (alias + embedding) to avoid generating components that already exist under a different name. Components that pass validation are saved to ~/.maxim/components/.

Architecture

Imagination I1+I2 — 0.7

When the agent encounters a novel entity mentioned in percept text that has no existing SEM component, the imagination system designs one in real-time:

Entity Extraction

Lightweight NLP heuristics extract entity-like noun phrases from narration text — physical objects, creatures, weapons, environmental features, items, vehicles, and NPCs. Abstract concepts, body parts, and clothing are filtered out. Two strategies: sentence-level intro patterns ("You see a rusty gate") and head-noun scanning against a curated indicator vocabulary.

ComponentIndex: Two-Layer Lookup

Before imagining, each candidate phrase is checked against the ComponentIndex:

• Layer 1: Alias table (O(1)) — exact match against component names and synonyms
• Layer 2: Embedding similarity — cosine similarity against all component signatures (threshold 0.65)

This means "old iron door" finds environments/rusty_gate and skips imagination.

Ephemeral Registration

Imagined entities are registered in a separate overlay (_ephemeral_index) from the persistent component index. They're visible to get(), has(), and query() during the session, but cleared at session end via clear_ephemeral().

Provenance Tagging

Episodes and CausalLinks from imagined entity interactions carry imagined=True. On entity discard (session end), imagined causal links get 50% confidence decay — partial learning is useful, but reduced confidence reflects simulated origin.

Gates

Acting Coach B3 — 0.7

The Acting Coach is a meta-prompt system that prevents the agent from entering respond loops when embodied. Instead of asking "what should I do?", the agent explores its physical affordances proactively.