Chapp-E Command Reference

Complete reference for all Chapp-E shell commands - OS, Neural Network, Brain Systems, Chemicals, and DAG-FS operations

Overview

Chapp-E provides a comprehensive command-line interface for interacting with all aspects of the neural operating system. Commands are organized into five categories:

  • OS Commands: Basic operating system operations (help, clear, echo, info)
  • Neural Network Commands: Direct manipulation of neurons, weights, and network operations
  • Brain System Commands: Consciousness state, system state, and memory management
  • Memory Commands: Hippocampus operations, encoding, consolidation, and retrieval
  • Chemical/Neuromodulator Commands: Chemical levels, neuromodulator events, and Blood-Brain Barrier operations
  • DAG-FS Commands: Pattern storage, retrieval, tagging, and associative operations
✅ IMPLEMENTATION STATUS: Command system infrastructure is FULLY IMPLEMENTED. All command handlers are in place with basic functionality. Full implementations for neural network, chemical, and DAG-FS operations are in progress.

Command System Architecture

Location

File: system/shell/commands_64.asm

Components

  • Command Parser: shell_parse_command - Parses command line, extracts command name and arguments
  • Command Executor: shell_execute_command - Executes parsed commands
  • Command Table: Static table mapping command names to handler functions
  • Command Handlers: Individual functions for each command

How It Works

  1. User types command in shell
  2. shell_process_command calls shell_parse_command
  3. Parser extracts command name and arguments
  4. Command table lookup finds handler function
  5. shell_execute_command calls the handler
  6. Handler executes and outputs results

OS Commands

help

Usage: help

Description: Displays a list of all available commands organized by category.

Example:

Chapp-E:> help
Chapp-E Commands:
  OS: help, clear, echo, info
  Neural: neuron, weight, network
  Brain: consciousness, state, memory
  Memory: hippocampus, encode, consolidate, retrieve
  Chemical: chem, mod, bbb
  DAG-FS: dag, pattern, tag

Status: ✅ Fully Implemented

clear

Usage: clear

Description: Clears the VGA text screen and resets cursor to top-left.

Example:

Chapp-E:> clear

Status: ✅ Fully Implemented

echo

Usage: echo [arguments...]

Description: Prints all arguments to the screen followed by a newline.

Example:

Chapp-E:> echo Hello, Chapp-E!
Hello, Chapp-E!

Status: ✅ Fully Implemented

info

Usage: info

Description: Displays system information including kernel version, memory usage, system state, and active systems.

Example:

Chapp-E:> info
Chapp-E Neural OS v0.1.0
[System information will be displayed here]

Status: 🚧 In Progress (stub implemented, full info display pending)

Neural Network Commands

neuron

Usage: neuron [list|info <id>|set <id> <value>]

Description: Operations on individual neurons in the neural network.

  • neuron list - List all neurons with their current activation values
  • neuron info <id> - Show detailed information about a specific neuron
  • neuron set <id> <value> - Set a neuron's activation value

Status: 🚧 In Progress (framework ready, full implementation pending)

weight

Usage: weight [get <from> <to>|set <from> <to> <value>|list]

Description: Operations on synaptic weights between neurons.

  • weight get <from> <to> - Get weight value between two neurons
  • weight set <from> <to> <value> - Set weight value between two neurons
  • weight list - List all weights in the network

Status: 🚧 In Progress (framework ready, full implementation pending)

network

Usage: network [info|forward <input>|train]

Description: Neural network operations.

  • network info - Show network architecture and statistics
  • network forward <input> - Run forward pass with input data
  • network train - Train the network (when training is implemented)

Status: 🚧 In Progress (framework ready, full implementation pending)

Brain System Commands

consciousness

Usage: consciousness

Description: Displays the current consciousness state (AWAKE, SLEEP, or UNCONSCIOUS).

Example:

Chapp-E:> consciousness
Consciousness State: AWAKE

Status: ✅ Fully Implemented

Memory Address: Reads from 0x100100 (CONSCIOUSNESS_STATE)

state

Usage: state

Description: Displays the Brain Controller system state (INIT, READY, PROCESSING, SLEEP).

Example:

Chapp-E:> state
System State: READY

Status: 🚧 In Progress (basic implementation, state name display pending)

Memory Address: Reads from 0x100000 (BC_STATE_ADDR)

memory

Usage: memory [working|planning|clear]

Description: Memory system operations.

  • memory working - Display working memory slots and contents
  • memory planning - Display planning system state and active plans
  • memory clear - Clear working memory slots

Status: 🚧 In Progress (framework ready, full implementation pending)

Memory Addresses:

  • Working Memory: 0x200000-0x2000C2
  • Planning System: 0x201000-0x201FFF

Memory Commands

Commands for interacting with the hippocampus module - the bridge between working memory and long-term memory (DAG-FS).

hippocampus

Usage: hippocampus

Category: Memory

Description: Display hippocampus module state (IDLE, ENCODING, CONSOLIDATING).

Example:

Chapp-E:> hippocampus
Hippocampus State: IDLE

Status: ✅ Implemented

Memory Address: Reads from 0x202200 (HIPPOCAMPUS_STATE_ADDR)

See Also: Hippocampus Module, Memory Systems

encode

Usage: encode <slot> <tags>

Category: Memory

Description: Encode a working memory slot to long-term memory (DAG-FS) with contextual tags. This transfers important working memory contents to persistent storage.

Arguments:

  • slot - Working memory slot number (0-2)
  • tags - Space-separated contextual tags for the memory (e.g., "first_day school happy")

Example:

Chapp-E:> encode 0 "first_day school happy"
Pattern ID: 42

Status: 🚧 Partial (command structure ready, full argument parsing planned)

See Also: Hippocampus Module, DAG-FS Filesystem, Memory Systems

consolidate

Usage: consolidate

Category: Memory

Description: Trigger memory consolidation - process pending encodings and strengthen patterns. Typically called during SLEEP state. This replays recent patterns and updates neural network weights.

Example:

Chapp-E:> consolidate
Consolidation complete

Status: ✅ Implemented (processes pending encodings, full replay/weight updates planned)

See Also: Hippocampus Module, Memory Systems

retrieve

Usage: retrieve <tag>

Category: Memory

Description: Retrieve a memory from DAG-FS using associative tags. Uses pattern completion to reconstruct the memory from partial cues, just like the brain reconstructs memories.

Arguments:

  • tag - Tag name to search for (e.g., "school", "happy")

Example:

Chapp-E:> retrieve school
Pattern ID: 42
[Reconstructed memory data...]

Status: 🚧 Partial (command structure ready, full argument parsing planned)

See Also: Hippocampus Module, DAG-FS Filesystem, Memory Systems

Chemical/Neuromodulator Commands

chem

Usage: chem [list|get <name>|set <name> <value>|region <region>]

Description: Chemical level operations for neuromodulators.

  • chem list - List all chemicals with global levels
  • chem get <name> - Get global level of a chemical (dopamine, serotonin, etc.)
  • chem set <name> <value> - Set global chemical level (0-255)
  • chem region <region> - Show chemical levels for a specific brain region

Available Chemicals:

  • dopamine - Reward, motivation, learning
  • serotonin - Mood stability, impulse control
  • acetylcholine - Attention focus, signal-to-noise
  • cortisol - Stress response, alertness
  • noradrenaline - Arousal, alertness
  • oxytocin - Social bonding, positive feedback

Status: 🚧 In Progress (framework ready, full implementation pending)

Memory Addresses:

  • Global chemicals: 0x202000-0x202005 (6 bytes)
  • Regional chemicals: 0x202006-0x202029 (36 bytes: 6 regions × 6 chemicals)

mod

Usage: mod [reward|error|stress|calm]

Description: Trigger neuromodulator events that affect chemical levels.

  • mod reward - Trigger reward event (boosts dopamine, serotonin)
  • mod error - Trigger error event (decreases dopamine, increases cortisol)
  • mod stress - Trigger stress event (increases cortisol, noradrenaline)
  • mod calm - Trigger calm event (boosts serotonin, decreases cortisol)

Status: 🚧 In Progress (framework ready, full implementation pending)

bbb

Usage: bbb [status|filter <input>]

Description: Blood-Brain Barrier operations.

  • bbb status - Show BBB status and transport statistics
  • bbb filter <input> - Test BBB filtering on input data

Status: 🚧 In Progress (framework ready, full implementation pending)

Memory Address: 0x202100 (BBB filter state and transport log)

DAG-FS Commands

dag

Usage: dag [info|list|create <tags> <data>|get <id>|delete <id>]

Description: DAG-FS filesystem operations.

  • dag info - Show DAG-FS statistics (pattern count, tag count, storage usage)
  • dag list - List all stored patterns with IDs and tags
  • dag create <tags> <data> - Create a new pattern from data and tags
  • dag get <id> - Retrieve and display a pattern by ID
  • dag delete <id> - Delete a pattern (triggers Long-Term Depression)

Status: 🚧 In Progress (framework ready, full implementation pending)

Memory Addresses:

  • Pattern storage: 0x300000-0x3FFFFF (1MB, 1024 patterns)
  • Index storage: 0x400000-0x4FFFFF (1MB, tags and metadata)

pattern

Usage: pattern [list|get <id>|create <tags> <data>|complete <partial>]

Description: Pattern operations in DAG-FS.

  • pattern list - List all patterns
  • pattern get <id> - Get pattern by ID (triggers reconsolidation)
  • pattern create <tags> <data> - Create new pattern
  • pattern complete <partial> - Pattern completion from partial input

Status: 🚧 In Progress (framework ready, full implementation pending)

tag

Usage: tag [list|search <tag>|add <pattern> <tag>]

Description: Tag operations for associative retrieval.

  • tag list - List all tags in the system
  • tag search <tag> - Find all patterns with a specific tag
  • tag add <pattern> <tag> - Add a tag to a pattern

Status: 🚧 In Progress (framework ready, full implementation pending)

Memory Address: Tag storage is part of index at 0x400000-0x4FFFFF (512 tags supported)

Command Implementation Details

Adding New Commands

To add a new command:

  1. Create a handler function in commands_64.asm (e.g., cmd_newcommand)
  2. Add command name string to .rodata section (e.g., cmd_newcommand_name: db 'newcommand', 0)
  3. Add entry to command_table: dq cmd_newcommand_name, cmd_newcommand
  4. Implement command logic in handler function

Command Handler Signature

cmd_example:
    ; Input:  RSI = arguments pointer (or 0 if no args)
    ;         RCX = argument count
    ; Output: None (prints to screen)
    push rsi
    push rcx
    ; ... command implementation ...
    pop rcx
    pop rsi
    ret

Argument Parsing

The command parser automatically:

  • Extracts command name (first word)
  • Finds first argument (after first space)
  • Counts total arguments
  • Passes arguments pointer and count to handler

Handlers are responsible for parsing individual arguments if needed.

Integration with Systems

Brain Controller Integration

Commands can send messages to the Brain Controller using the message queue system. See Brain Controller documentation for message format.

System Call Integration

Commands can use Chapp-E system calls for kernel operations. See System Calls documentation.

Direct Memory Access

Some commands (like consciousness and state) directly read from memory-mapped system addresses. See Memory Layout for address mappings.

Future Enhancements

  • Command History: Up/down arrow keys to navigate previous commands
  • Tab Completion: Auto-complete command names and arguments
  • Piping: Pipe output of one command to another
  • Redirection: Redirect output to DAG-FS patterns
  • Scripting: Execute command scripts from DAG-FS
  • Aliases: Create command aliases
  • Help for Individual Commands: help <command> shows detailed help

Related Documentation