Finite State Machine (FSM) System

Basal Ganglia - State Management and Working Memory

Overview

The Finite State Machine (FSM) manages shell input states to prevent prompt repetition and handle command processing. It's mapped to the Basal Ganglia in Chapp-E's brain architecture, which controls state transitions and working memory.

✅ BRAIN MAPPING: The FSM corresponds to the Basal Ganglia, which in the human brain acts as a "projectionist" - selecting one procedural memory at a time and holding patterns active for sustained behavior.

FSM States

The FSM has three primary states:

Value Constant Description
0 FSM_STATE_READY Ready for new command, show prompt
1 FSM_STATE_TYPING User is typing, accumulate input
2 FSM_STATE_PROCESSING Command received, processing

State Transitions

READY → TYPING (when user starts typing)
TYPING → PROCESSING (when Enter is pressed)
PROCESSING → READY (when command completes)

Memory Layout

The FSM uses memory at address 0x0500:

Address Size Description
0x0500 1 byte Current state (FSM_STATE_READY, etc.)
0x0501 1 byte Reserved
0x0502 2 bytes Buffer position (current input length)
0x0504 128 bytes Input buffer (command storage)

API Reference

fsm_init

Initializes the FSM to READY state and clears the buffer.

; Initialize FSM
call fsm_init

; Sets:
; - State to FSM_STATE_READY
; - Buffer position to 0
; - Clears input buffer

fsm_get_state

Gets the current FSM state.

; Get current state
call fsm_get_state
; Output: AL = current state (0=READY, 1=TYPING, 2=PROCESSING)

fsm_set_state

Sets the FSM to a specific state.

; Set state
mov al, FSM_STATE_TYPING
call fsm_set_state

fsm_to_ready

Transitions to READY state and clears buffer.

; Reset to ready
call fsm_to_ready

; Sets state to READY and clears input buffer

fsm_to_typing

Transitions to TYPING state (user is entering input).

; Start typing state
call fsm_to_typing

; Sets state to TYPING, ready to accumulate input

fsm_to_processing

Transitions to PROCESSING state (command received).

; Start processing
call fsm_to_processing

; Sets state to PROCESSING, command will be executed

Brain Architecture

Basal Ganglia Mapping

In the human brain, the Basal Ganglia:

  • Selects one procedural memory at a time - Like FSM selecting one state
  • Holds patterns active - Like FSM maintaining state during typing
  • Controls behavior transitions - Like FSM managing state transitions
  • Acts as a "projectionist" - Like FSM routing input to appropriate handlers

System ID

The FSM is registered with Brain Controller as:

  • System ID: SYS_ID_FSM (0x02)
  • Brain Region: Basal Ganglia

Integration

Shell Integration

The FSM is used by the shell to:

  • Prevent prompt repetition during typing
  • Accumulate user input in the buffer
  • Manage command processing lifecycle
  • Control when to show the prompt

Brain Controller Integration

The FSM communicates through the Brain Controller:

  • Receives input messages via Brain Controller
  • Sends state change notifications
  • Coordinates with other systems (GCS, Consciousness)

File Locations

  • 16-bit Implementation: neural/basal_ganglia/fsm/fsm.asm
  • Brain Region: Basal Ganglia (State Management)

Related Documentation