MAXIM
Embodiment
Composable hardware & world abstraction through Sensor-Entity-Modulator triples
The SEM Protocol
Core Insight
Hardware varies wildly — cameras, joints, wheels, grippers, IMUs, swords, NPCs. Rather than building monolithic abstractions per robot type, every interactive thing is described as a composable triple: an Entity (the thing), its Sensors (how you read it), and its Modulators (how you change it).
Entity
The physical or virtual thing. Entities compose into trees: arm → elbow → wrist → gripper. Each entity is self-describing.
Examples: joint, camera, wheel, sword, NPC, door
Sensor
Reads state from an entity. One sensor = one readable quantity, returned with a value, unit, and timestamp.
Examples: angle, temperature, durability, trust, frame
Modulator
Changes state of an entity. Exposes named affordances — each with typed parameters, description, and timeout.
Examples: rotate_angle, slash, speak, restart, sharpen
When an entity tree loads, every sensor and affordance becomes a registered tool automatically — shoulder_rotate_angle, rusty_sword_slash — with no hand-written tool classes per hardware component; name collisions are handled by progressive prefixing. The protocol contract and module map live in the SEM protocol reference and the embodiment overview.
Cerebellum: Forward Models
Biological Inspiration
The biological cerebellum stores forward models that predict sensory consequences of motor commands. Climbing-fiber complex spikes carry prediction error; massive microcircuit specialization enables fast, accurate motor control without conscious thought.
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 current parameters and API are on the Cerebellum reference page.
The SEM Learning Loop
Biological Inspiration
In the brain, the cerebellum doesn't just predict — it emits signals when predictions fail or succeed. These signals propagate to the hippocampus (contextual memory) and nucleus accumbens (reward learning) simultaneously, closing the loop between motor execution and long-term behavioral adaptation. Success and failure are not symmetric: negative outcomes carry disproportionate weight, a phenomenon known as negativity bias.
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. Each affordance execution lands on one of three paths:
Confident Prediction
Confidence ≥ 0.3, low variance. No LLM fallback; emits a success reaction with positive valence.
LLM Fallback
Confidence < 0.3 or high variance. The LLM teaches; the Cerebellum trains on its response. No reaction — still learning.
Failure
A failure mode fires (shatter, overheat). Emits a pain reaction with negative valence via the PainBus.
Both reactions dispatch to two subscribers in parallel. The Hippocampus captures the reaction in the current episode, sets the episode's valence at close, and annotates its Hebbian edges — so later recall carries affective coloring. The NAc adjusts per-node reward bias in the same graph and shifts its similarity thresholds: positive tightens, negative loosens. A sharp pain spike forces the episode to close so the next starts clean.
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.
The loop produces valence and reward bias in the substrate, but the LLM also needs to see it — so the prompt builder surfaces valence annotations (“this entity is associated with negative experiences”) and homeostatic drives fire hunger, fatigue, and deprivation pain through the same body. Both were validated by the cross-session affective memory and consumable-learning experiments in Experiments & Results.
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.
The program registry is indexed in three directions, because the agent asks three different questions: by goal (“I want to reach forward” → matching programs), by entity (“I'm holding a sword” → all programs involving swords), and by affordance (“I want to slash” → programs for sword, axe, arm, claws).
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, and the PainBus is subscribed for real-time mid-sequence interrupts.
Motor Engrams
Biological Inspiration
Hippocampal-cerebellar interactions are well-documented: the hippocampus provides contextual scaffolding for motor learning ("where and when did I learn this movement?"), while the cerebellum stores the procedural knowledge itself.
Design intent — not wired yet
Everything in this section is implemented and unit-tested, and none of it runs in production: nothing outside the tests forms, reads or strengthens a motor engram, and there is no engram decay code. An earlier version of this page said engrams form and decay on their own; that was the design, not the running system. Engrams tells that story and what happens next.
The design: a motor engram is a cross-system trace linking a motor program to the situation it ran in. The Cerebellum holds the how (the program steps), the Hippocampus holds the when/where/what (a trace marked as an engram for that program), and a node in the associative graph links the two.
Formation was meant to be selective — only on significant outcomes: pain above 0.3, a reward prediction error above 0.3, novelty above 0.7, or a program the Cerebellum is still unsure of (confidence below 0.3). Routine successes would not need episodic context. The intended loop: a program outcome becomes an engram, recalling the engram gates the program by context, and the NAc's prediction vetoes or greenlights it.
None of those arrows has a caller today. The Cerebellum's forward model does train on real readings every session, but its predictions have no consumer and its state is not saved between sessions. Wiring the save is scheduled engineering; whether the motor engram gets a real reader or is retired is decided by a later audit of the forward model.
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 a narrative modulator instead of hardware. The same cognitive stack that learns about robot joints also learns about swords, NPCs, and doors.
Rusty Sword
Sensors: durability, sharpness, weight
Modulators: slash, parry, throw, sharpen, repair
Failure: shatter (durability < 0.1), dulled (sharpness < 0.15)
Grim Ferryman (NPC)
Sensors: trust, mood, health
Modulators: speak, offer_payment, threaten, punch
Failure: hostility (trust < 0.1), refusal (mood < -0.5)
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. Tennis elbow, for instance, composes strain and fatigue: it triggers only when both cross their thresholds, it is persistent, and it recovers only once fatigue drops back down.
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, and all failure state persists across sessions.
Default Embodiment
Simulations load bodies/base_humanoid when no other embodiment is given. It is a genre-neutral humanoid that works in any campaign setting, so the agent always has a body in sim mode — 4 entity sensors, 8 affordances, and 5 failure modes — unless you explicitly opt out.
Giving a live agent a different body is a single flag that loads a bundled component, attaches the pain bus, and registers its affordances as tools — the embodiment quickstart walks through it. One design rule from that wiring is worth keeping here: the executor requires an explicit pain_bus= decision with no default, so a forgotten pain bridge is a TypeError instead of a silent no-op — adopted after three identical bugs in three weeks, because three-times-is-structural.
Component Library & Genre Gating
SEM components are reusable templates across seven categories — bodies, creatures, environments, items, npcs, vehicles, and weapons — discovered from campaign-local, user, and bundled search paths. Genre gating prevents cross-genre contamination: when a campaign declares a genre, the registry only suggests genre-matching or genre-neutral components, so a fantasy campaign won't accidentally spawn a cyberpunk patrol drone. Explicit refs bypass the gate when you mean to cross genres. The Component Library essay covers the catalog design; the component library reference lists what ships.
Asset Foundry
The Asset Foundry generates new SEM components via LLM, validates them against the protocol, runs them through a 3-encounter gauntlet, and scores them on four bio-system engagement dimensions: do sensors change meaningfully, do failure modes trigger under different conditions, are all affordances exercised, and does the entity produce causal links the agent can learn from? Pass or fail, the pipeline produces actionable feedback; passing components are promoted into the user's library. Usage and options are in the Asset Foundry reference.
Auto-Curation
Before a simulation starts, auto-curation 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. A two-layer lookup (alias table, then embedding similarity) avoids regenerating components that already exist under a different name.
Imagination
Biological Inspiration
Imagination fires during low-arousal idle states — the same way you don't daydream while fighting. When the brain encounters something unfamiliar, it constructs a mental model from prior experience to reason about the novel entity before physically interacting with it. The Default Network, which activates during rest and mind-wandering, gates this process.
When the agent meets a novel entity in percept text with no existing SEM component, the imagination system designs one in real time — only after the two-layer index lookup comes up empty, only during low-arousal idle states, and only when the energy budget allows. Imagined entities live in a session-scoped overlay, and the episodes and causal links they generate are tagged as imagined so their confidence decays when the entity is discarded: partial learning is useful, but reduced confidence reflects simulated origin. Full design in the Imagination essay; reference on pymaxim.bio.
Acting Coach
The Acting Coach is a meta-prompt that prevents the agent from entering respond loops when embodied. Instead of asking "what should I do?", the agent explores its physical affordances proactively.
Bio-System Modulation (not suppression)
The coach is a default policy that three bio-systems continuously modulate: NAc valence adds learned caution on specific affordances ("sword_slash has caused damage before"), pain anticipation adds anxiety from hippocampal pattern-matching against past pain episodes, and Cerebellum predictions add forward-model forecasts ("predicted low success, risks: jammed").
Composition order: base directive → NAc caution → pain anticipation → cerebellum predictions. Each layer adds information; none removes the base exploration directive.
Case Study: Learned Sound Orienting
The SEM pattern's first real-hardware learned policy: a Reachy Mini body declares an azimuth sensor, a centeredness drive, and two orient affordances — and the reward substrate learns which turn, in which state, reduces the error, from scratch, in ~10 hardware trials, with no LLM in the action path. Cross-session correct at trial 0; independently trained substrates merge into one gauntlet-validated policy. Read the full essay →
Reference on pymaxim.bio
This page is the design story. Install steps, CLI flags, configuration, and the current evidence live in the docs: