{% extends "base.html" %} {% block title %}Deliberation — Maxim Docs | PFC Inner Monologue & Thought Stream{% endblock %} {% block meta_description %}Maxim's PFC deliberation system — multi-cycle inner monologue with bio-system enrichment, computed salience, and a continuous thought stream display. The agent thinks before it acts.{% endblock %} {% block meta_keywords %}Maxim deliberation, PFC cycle, inner monologue, thought stream, computed salience, bio-enrichment, ThoughtGate, working memory{% endblock %} {% block meta_author %}Maxim Project{% endblock %} {% block og_site_name %}Maxim{% endblock %} {% block og_type %}article{% endblock %} {% block structured_data %}
{% endblock %} {% block content %}
← Back to Overview

## 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: refractory cooldown, energy budget, salience scoring, adaptive threshold.

### 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 `ready_to_act: false`, reasoning feeds back to step 2 for another cycle.

### 4. Act

When `ready_to_act: true` or cycles converge (Jaccard ≥ 0.8), the agent executes the chosen action.

## 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 uses a proportional token budget: `min(2000, available × 0.3)`. On 4K local models this gives ~891 tokens; on 8K+ models it caps at 2000. Oldest entries are dropped first when the budget is exceeded.

## Computed Salience

Each thought receives a computed salience score (0.0–1.0) based on how strongly the bio-systems responded to it.

Component | Weight | Signal
--- | --- | ---
Section count | 0.3 | More bio-systems activated = more cross-system relevance
Recall depth | 0.3 | More memories recalled = stronger associative resonance
Novelty | 0.4 | Novel thoughts (low Jaccard with previous) are more informative

### High Salience (~0.6–0.9)

Novel thought that triggered multiple bio-systems. Typically cycle 1 (maximum novelty) or a thought that surfaces a surprising memory.

### Low Salience (~0.2–0.4)

Converging thought that repeats prior reasoning. The agent is refining, not discovering. Important for reaching a conclusion but less informative.

The `top_by_salience` query on WorkingMemorySet returns the highest-salience thoughts first, so the most important reasoning surfaces in the prompt when token budget is tight.

## The Thinking Panel

In interactive mode, the thinking panel shows a continuous stream of the agent's inner thoughts across the entire session.

    Cycle 1/3  8.2s  enriched: hippocampus, nac
    I notice the dragon is approaching from the east. My memory
    recalls that fire dragons are vulnerable to water attacks.
    —— hippocampus, nac s=0.69
    Given my earlier success with the water spell, I should try
    to find the river to the north before engaging directly.
    —— hippocampus s=0.54
    The villagers mentioned a well near the town square. I recall
    wells can be used as water sources too — closer than the river.

Key | Action
--- | ---
`Left arrow` | Enter thinking panel for scrolling
`Up/Down arrows` | Scroll through thought history
`Right arrow` | Exit thinking panel, auto-follow latest thought
`Option+Up/Down` | Resize thinking panel (more/less space)

## 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.

## ThoughtGate

A composite gate that decides whether the agent should deliberate on the current working memory state.

    Short-circuit cascade:
    1. Refractory    — don't re-fire within 2 ticks of last pass
    2. Energy        — don't think below 15% of token budget
    3. Salience      — score working memory head via SalienceScorer
    4. Threshold     — score vs adaptive threshold (learns from outcomes)

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

The agent discovers its world through three complementary tools:

### sense_presence

Scan surroundings for entities — shows [YOU] for your body and [SCENE] for observed entities. Scene entity capabilities are labeled "observed (not callable)." Also triggers imagination for novel entity phrases.

Use when: arriving somewhere new, wondering what exists

### sense_tools

Find YOUR specific actions matching intent. Searches self-entity affordances only — scene entities are excluded. Provides hints when a query matches a scene entity. `sense_tools("attack")`

Use when: know what you want to do, need the right tool

### sense

Read detailed sensor state of a specific entity. Health, stamina, durability, position — everything the entity's sensors expose.

Use when: need precise state before acting

### Imagination Pipeline

When the agent perceives an entity it hasn't encountered before (e.g., "dragon" in a combat scenario), the imagination trigger extracts the entity phrase from the percept, checks the ComponentIndex for matching seed components (65 across 7 categories), and instantiates the entity as a live SEM object with sensors and affordances. This happens automatically on each percept.

## 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.

## Architecture

    ThoughtGate.should_think()
      ↓  (refractory → energy → salience → adaptive threshold)
    BioEnrichmentPipeline.enrich(percept_text)
      ↓  (hippocampus, NAc, EC, cerebellum, SCN)
    _compute_thought_salience(sections, memories, jaccard)
      ↓
    WMS.add(THOUGHT, salience=computed)
      ↓
    LLM prompt ← deliberation transcript + enrichment
      ↓
    LLM response: {ready_to_act, action, reasoning}
      ↓
      ready_to_act=true → execute action
      ready_to_act=false → feed reasoning back → cycle 2+

File | Role
--- | ---
runtime/agent_loop.py | _run_deliberation_cycles, _compute_thought_salience
runtime/thought_gate.py | ThoughtGate composite gate
integration/bio_enrichment.py | BioEnrichmentPipeline
agents/prompt_builder.py | Transcript section, bio-enrichment suppression
agents/exec_prompts.py | PFC_PREAMBLE (inner monologue framing)
agents/working_memory.py | WorkingMemorySet.top_by_salience
interactive/display.py | Thinking panel, thought stream

{% endblock %}