MAXIM
Deliberation
Multi-cycle inner monologue with bio-system enrichment and computed salience
How It Works
Core Insight
Instead of reacting immediately to every percept, the agent pauses to think when the situation warrants it. Each thinking cycle consults bio-system memories, causal predictions, and learned associations — then the enriched reasoning feeds back for another round. The result is a chain of thought that genuinely builds on itself.
1. Gate
ThoughtGate decides if the situation warrants deliberation at all.
2. Enrich
Bio-systems surface relevant memories, causal predictions, active concepts, and motor programs for the current percept or reasoning text.
3. Think
The LLM reasons with enriched context. If it is not yet ready to act, the reasoning feeds back to step 2 for another cycle.
4. Act
When the agent declares itself ready, or successive cycles converge on the same reasoning, it executes the chosen action.
The module-by-module breakdown of this loop lives in the architecture reference; this page is about why it is shaped this way.
The Deliberation Transcript
Each deliberation cycle produces a transcript entry pairing the agent's reasoning with the bio-system response it triggered. The full transcript accumulates across cycles so the LLM in cycle 3 sees cycles 1 and 2.
=== Your inner deliberation (private — not speech) === [Cycle 1] You thought: The guard is sleeping and I notice keys on his belt. I could try to take them, but that risks waking him... Your experience responded: - Memory: Last time you reached for something near a sleeping NPC, the noise check succeeded (salience=0.71) - Prediction: stealth actions near sleeping entities have 72% success rate [Cycle 2] You thought: Given the memory of success with stealth near sleeping NPCs, and the prediction of 72% success, I'll reach for the keys slowly... Your experience responded: - Memory: Slow movements reduce noise check difficulty by one tier - Prediction: combined stealth + slow movement → 89% success estimate
The transcript runs on a proportional token budget that scales with the model's context window, so small local models get a shorter memory of their own reasoning than large ones. Oldest entries are dropped first when the budget is exceeded.
Computed Salience
Each thought receives a computed salience score based on how strongly the bio-systems responded to it. Three signals feed the score: how many bio-systems activated (more systems means more cross-system relevance), how many memories were recalled (stronger associative resonance), and how novel the thought is compared with the previous cycle (a new idea is more informative than a restatement).
High Salience
Novel thought that triggered multiple bio-systems. Typically cycle 1 (maximum novelty) or a thought that surfaces a surprising memory.
Low Salience
Converging thought that repeats prior reasoning. The agent is refining, not discovering. Important for reaching a conclusion but less informative.
Working memory can be queried by salience, so the most important reasoning surfaces in the prompt first when the token budget is tight.
Inner Monologue
Deliberation reasoning is framed as private inner thought. The agent thinks to itself in first person and explores autonomously before seeking user input.
Correct (inner thought)
- "I notice the dragon is attacking from the east..."
- "I recall that fire dragons are weak to water..."
- "Given my low health, engaging directly seems risky..."
- "I should look for a water source nearby."
Wrong (outward speech)
- "What do you plan to do?" — narrator voice
- "Did you manage to gather allies?" — addressing someone
- "Would you like me to try stealth?" — seeking guidance
- "Let me help you with that." — speaking to user
Act First, Ask Second
The agent uses its tools, memories, predictions, and learned associations before seeking external input. request_interaction is a last resort for genuine user-preference choices, not the default behavior.
In interactive mode, a thinking panel shows this monologue as a continuous stream across the session, each thought annotated with the bio-systems that enriched it.
ThoughtGate
A composite gate that decides whether the agent should deliberate on the current working memory state. It is a short-circuit cascade: a refractory cooldown stops it re-firing immediately after the last pass; an energy check refuses to think when the token budget is nearly spent; the head of working memory is then scored for salience; and finally that score is compared against an adaptive threshold.
The adaptive threshold adjusts based on whether past deliberations were useful — if thinking led to better actions, the threshold lowers (think more); if thinking was wasted, the threshold rises (act faster).
Entity Discovery
Deliberation needs something concrete to reason about, so the agent discovers its world through three complementary tools: sense_presence scans the surroundings for entities, separating the agent's own body from observed scene entities it cannot call; sense_tools finds the agent's own actions matching an intent; and sense reads the detailed sensor state of one entity before acting. When a percept names an entity the agent has never met, the imagination trigger instantiates it as a live entity with sensors and affordances, automatically — see the Imagination essay for that pipeline and the tools reference for each call.
Bio-Plausible Design
The prefrontal cortex maintains a persistent workspace — active representations that accumulate across recurrence cycles, not a FIFO that drops prior iterations. The basal ganglia (NAc) modulate which representations stay active based on predicted reward value. Hippocampus provides episodic context tagged with the goal that was active during encoding.
The deliberation system maps these to software: the transcript is the persistent workspace, computed salience is the activation modulation, bio-enrichment is the hippocampal recall + NAc prediction circuit, and the ThoughtGate is the basal ganglia's go/no-go decision on whether to engage the workspace.
Reference on pymaxim.bio
This page is the design story. Install steps, CLI flags, configuration, and the current evidence live in the docs: