MAXIM
Body Awareness
Proprioception, Pain, and Motor Learning
Close your eyes and touch your nose. You can do it because proprioception tells you where your arm is without looking. You don't smash your arm into the table because pain taught you to be careful. You've become smoother at the movement through practice. Maxim implements all three.
Contents
Proprioception: Knowing Where You Are
🧬 Biological Inspiration
Muscle spindles detect stretch. Golgi tendon organs sense tension. Joint receptors track angles. Together, they create a real-time map of body position that doesn't require vision.
Maxim's MovementTracker continuously monitors the robot's kinematic state: angular and translation velocity, angular acceleration, direction reversals that betray thrashing, and a sliding window of position history for trend analysis.
This isn't just logging. The data flows into pain detection, motor learning, and decision-making systems. The robot feels how it's moving. The sensor and entity plumbing underneath is described in the Embodiment overview.
Pain: Learning from Discomfort
Why Robots Need Pain
Pain isn't cruelty, it's information. Biological pain systems evolved because organisms that didn't feel damage didn't survive long. Robots without pain detection can destroy themselves, their environment, or hurt people. Maxim's pain system is a safety feature, not a bug.
The PainDetector identifies five types of aversive experience: excessive velocity (overshoot and mechanical stress), direction thrashing (rapid reversals that usually mean confusion or control instability), excessive acceleration (jerky motion that stresses actuators), sustained strain (holding near mechanical limits too long, like a heavy weight at arm's length), and movement failure (a commanded movement that didn't happen: obstruction, stall, or calibration error). Each signal carries an intensity and its context — which joint, which goal — so the system learns from the cause, not just the sensation.
Cognitive Pain: Tool Errors
Beyond physical discomfort, Maxim experiences cognitive pain when tools fail. Tool errors are routed through the same PainDetector → NAc → FearAgent pipeline as movement pain, enabling learned aversion to unreliable tools. Errors, timeouts, rejected input, and tools that run longer than expected all register as pain, escalating with repeated failures of the same tool.
🧬 Biological Parallel
Just as the amygdala learns to associate specific movements with pain, the ToolPainBridge teaches NAc to associate specific tools-in-context with failure. A tool that consistently times out on a restricted network develops a low predicted value — FearAgent will warn before retrying.
Anticipated Pain: Predicting Before Acting
Beyond consequence-pain, Maxim assesses anticipated pain before an action runs. The PerceivedPainAssessor asks: "if I did this right now, how likely is pain?" Its answer is the greater of an innate prior — aversions the agent is "born with", instincts rather than experience — and the NAc's learned prediction: the more times an action hurt before, the stronger the anticipation next time. That felt signal flows through PainBus → hippocampus → the AUT's next LLM context, so the agent can reason about a gut-feeling instead of relying purely on prompt-level logic.
🧬 Biological Parallel: ACC / vmPFC Anticipatory Aversion
In biology, anterior cingulate and ventromedial prefrontal cortex activate to threats before actual harm occurs. You don't think "P(harm)=0.87" — you just feel a bad gut feeling that shapes the decision. PerceivedPainAssessor is Maxim's version: it renders NAc's probabilistic prediction as a felt signal the agent can reason about.
The two layers form a loop: real pain fires after an action and trains NAc; the assessor fires before the next one. The more the AUT has done, the more accurate its anticipation becomes — conditioned aversion through experience.
Pain → Learning
Pain signals don't just trigger immediate responses. They feed into the Nucleus Accumbens through the PainCircuitBridge, creating lasting aversive associations: MovementTracker supplies position data, PainDetector matches patterns and emits a PainSignal, PainCircuitBridge formats it for the NAc, and the NAc does the causal learning.
After experiencing pain from a specific action pattern, the NAc learns to predict it. Next time a similar action is proposed, the robot can refuse or modify the plan before experiencing pain again — the anticipated-pain layer above, closing the loop.
Pain Reactions & The SEM Learning Loop
Pain signals don't stay on the PainBus alone. Every PainSignal is also converted into a typed Reaction and dispatched through the ReactionBus, so pain reaches two audiences through two contracts. The PainBus carries the full context — source, entity, failure mode, sensor readings — for causal learning. The ReactionBus carries a typed Reaction that enforces isolation rules (no cross-agent intent, no private state) for the hippocampus, which annotates episode valence, and the NAc.
In the NAc, a pain reaction adjusts reward bias in the Hebbian graph. Negative valence loosens similarity thresholds — the system casts a wider net, becoming more sensitive to anything that resembles a past painful context. High-intensity pain also closes the current episode immediately, capturing the accumulated negative valence, and starts a fresh one. The effect mirrors how biological trauma creates sharp memory boundaries — the moment of pain becomes the dividing line between "before" and "after" in memory.
Motor Learning & Workspace Bounds
🧬 Biological Inspiration
The cerebellum adapts motor commands through error-driven learning. Reach for a cup, miss by 2cm, and your next reach is slightly adjusted. Over trials, movements become smooth and accurate without conscious effort.
Maxim's FocusLearner implements this for gaze control. The problem: camera latency, mechanical dynamics, and tracking delays mean the robot often overshoots or undershoots when following a target. The solution is Rescorla-Wagner learning applied to movement gain: command a movement, observe actual versus expected position, and nudge the gain estimate toward what would have landed it. Convergence is bounded and asymptotic, so no oscillation; learned gains persist across sessions and keep adapting as conditions change.
Similarly, the WorkspaceBoundsLearner discovers the robot's reachable space through exploration. Rather than hard-coding limits, the system learns where it can and cannot move, adapting to mounting position, obstructions, and mechanical wear. Parameters and the full cerebellar model are documented under Cerebellum — motor learning.
Integration: The Embodied Loop
All proprioceptive systems connect to the decision-making loop. Movement planning uses learned gains and bounds; action proposals are checked against pain predictions; execution monitoring detects pain in real time; memory records painful episodes for future avoidance; energy tracking counts motor effort as a cost. The wiring is mapped in How the systems connect.
The result: a robot that moves smoothly, avoids harmful patterns, and improves with experience. Not because we programmed every case, but because we gave it the machinery to learn.
Embodiment & SEM Protocol
Building on these foundations, the Sensor-Entity-Modulator (SEM) protocol provides a composable abstraction for any interactive entity—robot joints, cameras, even virtual objects like swords or NPCs. Each entity has Sensors (readable state), Modulators (executable actions), and Failure Modes (pain triggers).
The Cerebellum stores learned forward models — once a movement consistently produces a specific reading, it caches the prediction and skips the LLM entirely — and repeated action sequences crystallize into reusable, pain-gated motor programs linked to hippocampal engrams. A reaching sequence that hurt near a wall is remembered differently from one that succeeded in open space.
Reference on pymaxim.bio
This page is the design story. Install steps, CLI flags, configuration, and the current evidence live in the docs: