{% extends "base.html" %} {% block title %}Usage Guide — Maxim Docs | Install, Config & CLI{% endblock %} {% block meta_description %}Get started with Maxim. Install instructions, configuration, CLI reference, and step-by-step setup for the agentic robotics cognitive architecture.{% endblock %} {% block meta_keywords %}Maxim installation, Maxim setup, Maxim CLI, Maxim configuration, agentic robotics setup, ROS2 robot framework, Maxim getting started, Maxim documentation{% endblock %} {% block meta_author %}Maxim Project{% endblock %} {% block og_site_name %}Maxim{% endblock %} {% block og_type %}article{% endblock %} {% block structured_data %}
{% endblock %} {% block extra_head %}
{% endblock %} {% block content %}
← Back to Overview

### Contents

1. Requirements
2. Installation
3. Configuration
4. Operating Modes Networking & Mesh Roadmap
5. CLI Reference
6. Voice Commands
7. Keyboard Controls
8. Common Recipes
9. Memory Management
10. Debugging

## Requirements

- Python 3.10+
- Hardware: Reachy Mini robot (optional — runs in headless mode without one)
- RAM: 4GB minimum (8GB+ for larger LLMs)
- GPU: Optional. Metal (macOS) or CUDA (Linux) supported
- Network: Same LAN as Reachy Mini for Zenoh discovery (if using robot)

### Blackwell GPU Note

RTX 50-series (Blackwell) GPUs have a known GStreamer/CUDA incompatibility. Maxim auto-detects this and falls back to CPU mode. You can force CPU mode manually with `CUDA_VISIBLE_DEVICES=""`.

## Installation

1. Install from PyPI
   pip install pymaxim

   The package is called `pymaxim` on PyPI, but you import it as `maxim`.

2. Add LLM support (pick one or more)
   # Local LLM via llama.cpp pip install 'pymaxim[llm-llama]' # Claude (Anthropic) pip install 'pymaxim[llm-anthropic]' # OpenAI / GPT pip install 'pymaxim[llm-openai]'
3. Download a local model (optional — skip if using cloud)
   maxim --list-models # see available models ./scripts/download_models.sh --llm # download SmolLM 1.7B (~1.1GB)

Developer install: To work on Maxim itself, clone the repo and use `pip install -e '.[test]'` instead.

### Optional Extras

Extra | Install Command | What It Enables
--- | --- | ---
TTS | pip install 'pymaxim[tts]' | Text-to-speech (Piper TTS)
Semantic | pip install 'pymaxim[semantic]' | Neural similarity (SentenceTransformer)
Torch LLM | pip install 'pymaxim[llm-torch]' | PyTorch transformers backend
YOLOv8 | pip install 'pymaxim[yolo]' | YOLOv8 vision engine via Ultralytics (AGPL-3.0). Default engine is RTMDet-m (Apache 2.0)

## Configuration

### Configuration Files

All configuration lives in `~/.maxim/` (override with `$MAXIM_DATA_HOME`):

File | Purpose
--- | ---
llm.json | LLM model selection, quantization, per-mode response sizing
robots.yaml | Robot connection settings (type, name, timeout)
phrase_responses.json | Voice command mappings ("Maxim sleep" → sleep mode)
key_responses.json | Keyboard shortcut bindings
whisper.json | Audio transcription settings (model size, compute type)

### Configuration — `maxim config` (canonical 1.0 path)

New in 1.0: the canonical way to persist Maxim's runtime preferences is the `maxim config` verb family writing to `~/.config/maxim/config.json`. The pre-1.0 environment variables below still work as per-session overrides (precedence chain: CLI args > env vars > config.json > defaults), but are no longer the recommended primary surface.

`maxim doctor` shows a "Resolved Config" section with every absorbed field's value + source marker — the single answer to "what does this instance think it's configured as?"

maxim config — quick start maxim config set role leader # leader / peer / solo maxim config set llm.profile qwen2.5-32b-instruct # default model maxim config set llm.n_ctx 16384 # context window maxim config set llm.auto_download true # download GGUFs on first run maxim config set auto_spawn.llm_server true # spawn llama-cpp-server maxim config set auto_spawn.tunnel true # spawn cloudflared maxim config get # all fields + sources maxim config get llm.profile # one field maxim config edit # opens $EDITOR maxim config path # print the file path maxim doctor # "Resolved Config" section

### Environment Variables (per-session overrides)

Core settings MAXIM_LLM_ENABLED=1 # Enable LLM inference MAXIM_LLM_PROFILE=smollm-1.7b-instruct # Model profile MAXIM_LLM_QUANTIZATION=Q4_K_M # Quantization level MAXIM_PROMPT_PROFILE=standard # Prompt optimization tier MAXIM_ROBOT_NAME=reachy_mini # Robot identifier GPU control CUDA_VISIBLE_DEVICES="" # Force CPU-only MAXIM_LLM_N_GPU_LAYERS=0 # CPU inference MAXIM_LLM_N_GPU_LAYERS=-1 # All layers on GPU Display and audio MAXIM_DISABLE_IMSHOW=1 # Disable OpenCV windows MAXIM_WHISPER_COMPUTE_TYPE=float32 # Whisper precision fallback Headless / adaptive runtime MAXIM_ROBOT_TIMEOUT=5 # Reduce robot connect timeout (default 30s) MAXIM_PROVENANCE_VERBOSITY=1 # 0=off, 1=compact, 2=verbose MAXIM_PROVENANCE_PERSIST=1 # 0=disable, 1=enable persistence Networking & diagnostics MAXIM_ROLE=leader # leader / peer / solo (legacy `client` term coerces to `peer` with WARN) MAXIM_HEARTBEAT=1 # System health heartbeat (GPU/CPU/RAM) MAXIM_LANE_TRACE=1 # Per-request LLM trace + heartbeat MAXIM_PROXY_MAX_CONCURRENT=4 # Max in-flight proxy requests MAXIM_PROXY_RATE_LIMIT_RPM=0 # Per-peer rate limit (0=unlimited) Routing & downloads (peer/leader flexibility) MAXIM_LLM_N_CTX=4096 # Override auto-computed llama.cpp n_ctx (P4c) MAXIM_AUTO_DOWNLOAD_MODELS=1 # Skip the download prompt (P5) — same as --auto-download MAXIM_DATA_BUDGET_GB=50 # Optional soft cap on ~/.maxim disk usage MAXIM_SKIP_REMOTE_PROBE=1 # Bypass the P6 remote-URL probe (CI escape hatch) MAXIM_REMOTE_PROBE_CACHE_TTL_S=60 # Probe-cache freshness window (clamped 0-600)

### Peer & Tunnel Commands

Connect peers to a leader's GPU for distributed inference. See Networking & Mesh for full details.

Environment diagnostics maxim doctor # Platform-aware health checks maxim doctor --retry # Walk through failures interactively maxim doctor --json # Machine-readable output (CI/scripts) maxim doctor --as peer https://... # Peer-mode connectivity checks maxim doctor --as leader # Force leader-mode checks Tunnel setup (leader machine) maxim tunnel setup # One-time guided tunnel config maxim tunnel status # Show tunnel + key state maxim tunnel key rotate # Generate/replace API key maxim tunnel key export # Print peer export snippets Peer setup (client machine) maxim peer connect https://maxim.yourdomain.com/v1 maxim peer show # Verify peer config maxim peer test https://maxim.yourdomain.com/v1 maxim --llm mistral-7b # Per-session local override (wins over peer) maxim doctor --last-decision # Why did the last sim pick this model? (P9) Model profile management (leader/standalone) # Bundled profiles include qwen2.5-32b, mixtral-8x7b, llama-3.1-70b # for capable hardware. Beyond that, register custom profiles: maxim model add my-qwen-32b-q5 \ --hf bartowski/Qwen2.5-32B-Instruct-GGUF:Qwen2.5-32B-Instruct-Q5_K_M.gguf \ --n-ctx 32768 maxim model add my-local --local ~/models/custom.gguf --chat-format llama3_instruct maxim model list # show user profiles maxim model remove my-qwen-32b-q5 # Profiles live in ~/.config/maxim/profiles.yml; user profiles win # over bundled ones on collision. Chat-format auto-inferred from name # when possible. See llm-setup.md § Adding Custom Profiles. Debug trace (see everything) MAXIM_LANE_TRACE=1 maxim # Trace every LLM call MAXIM_HEARTBEAT=1 maxim # System health every 10s

### Prompt Profiles

Three tiers of cognitive effort, matched to your hardware:

Profile | Max Depth | LLM Calls | Parallelism | Best For
--- | --- | --- | --- | ---
minimal | 2 levels | 8 max | None | CPU-only, low RAM, Raspberry Pi
standard | 5 levels | 20 max | 4 workers | Laptop with GPU or fast CPU
rich | 7 levels | 50 max | 8 workers | Desktop with dedicated GPU

## Operating Modes

Maxim uses a decomposed mode architecture combining processing states (awake/sleep), operational modes (passive/active/singularity), and strategies (observe/explore/research/assist/reflect/learn). For backward compatibility, the CLI accepts legacy mode names that map to specific combinations. See the Operating Modes deep dive for full details.

🔭

#### Menu / Exploration

Running `maxim` with no arguments opens a Rich interactive menu with campaign discovery, recent sessions, and quick-start options. Select a campaign or mode to launch directly.

`maxim`
📡

#### Live

Active + assist strategy. Full embodied runtime with self-evolving behavioral intent.

`maxim --mode live`
😴

#### Sleep

Sleep processing state. Audio monitoring, memory consolidation, wake keyword detection.

`maxim --mode sleep`
💭

#### Reflection

Passive + reflect strategy. Internal analysis, memory review, pattern identification.

`maxim --mode reflection`
🏋️

#### Train

Passive + learn strategy. Watch demonstrations, incorporate feedback, update behavior.

`maxim --mode train`
👀

#### Observe

Passive + observe strategy. Watch and understand without interfering.

`maxim --mode observe`

### Operational Modes & Autonomy

Operational modes map directly to autonomy levels:

Mode | Autonomy | Behavior | Max Initiative
--- | --- | --- | ---
passive | planning | Proposes actions, waits for human approval | 0.3
active | supervised | Acts within defined boundaries, escalates on uncertainty | 0.7
singularity | autonomous | Full agency with self-correction (safety constraints still apply) | 1.0

## CLI Reference

Basic usage maxim [OPTIONS] Connection --robot-name TEXT Robot identifier (default: reachy_mini) --home-dir PATH Data directory (default: ~/.maxim/) --timeout FLOAT Connection timeout in seconds (default: 30.0) Execution --mode MODE exploration|live|agentic|sleep|reflection|train --epochs INT Stop after N cycles (0 = unlimited) --audio true|false Enable audio recording (default: true) --audio_len FLOAT Transcription chunk duration (default: 5.0s) --interactive true|false Enable interactive mode (default: true for TTY + DM campaigns) Human picks choices, types roleplay, sees Rich display Use --interactive false for CI, scripts, or autonomous runs NAc learning is suppressed while interactive mode is active Agentic mode --language-model TEXT LLM profile (e.g., mistral-7b) --prompt-profile TIER minimal|standard|rich --autonomy LEVEL planning|supervised|autonomous --autonomy-duration FLOAT Timed autonomy in seconds --memory-path PATH Memory persistence file --reset Clear memory on startup --enable-embeddings Enable semantic similarity (Phase 4) Multi-LLM & Cloud --cloud-fallback MODEL Cloud fallback on large tier (e.g., claude-sonnet) --cloud-lane TIER MODEL Assign cloud model to a tier (e.g., small claude-haiku) --cloud-budget DOLLARS Max session cost for cloud providers (default: $5) --aut-model MODEL Separate LLM for agent-under-test (dual-LLM mode) Network --internet-access Enable internet (default) --no-internet Disable internet access Audio / TTS --tts Enable text-to-speech --tts-model TEXT Voice model (default: en_US-lessac-medium) Maintenance --clear-cache Remove __pycache__ directories --clear-memory [TYPE] Clear persistent memory and exit --log-level 0|1|2 Logging level (alias: --verbosity, deprecated) --display bio|clean|debug Output detail (DEFAULT: bio) --no-agentic-console Suppress agentic event output --audit-architecture Audit codebase for architecture layer rule violations and exit

## Voice Commands

All voice commands begin with the wake word "Maxim":

Command | Effect
--- | ---
"Maxim sleep" | Enter sleep mode (audio monitoring only)
"Maxim wake up" | Return to previous active mode
"Maxim observe" | Switch to observe strategy
"Maxim explore" | Switch to explore strategy
"Maxim assist" | Switch to assist strategy
"Maxim reflect" | Switch to reflect strategy
"Maxim passive" / "active" / "singularity" | Switch operational mode
"Maxim shutdown" | Clean shutdown

See the Operating Modes Networking & Mesh Roadmap page for the full list. Custom voice commands can be added in `~/.maxim/util/phrase_responses.json`.

## Keyboard Controls

Available in interactive mode (default):

`c` Center vision
`u` Mark trainable
`0` Label: no errors
`1-9` Label: error code
`q` Quit

## Common Recipes

### First Run (No Robot)

Run `maxim` with no arguments to open the Rich interactive menu. Browse available campaigns, pick a recent session, or jump into a mode:

maxim

Or launch exploration mode directly:

maxim --mode exploration

### Full Agentic Mode with Mistral

maxim --mode live \ --language-model mistral-7b \ --prompt-profile standard \ --autonomy supervised

### CPU-Only with Small Model

CUDA_VISIBLE_DEVICES="" maxim \ --mode live \ --language-model smollm-1.7b \ --prompt-profile minimal

### Verbose Debugging Session

maxim --mode live \ --log-level 2 \ --display debug \ --language-model phi-3-mini

## Memory Management

### Clearing Memory

Clear everything maxim --clear-memory all Clear specific types maxim --clear-memory focus,bounds # Movement learning only maxim --clear-memory nac,hippo # Decision learning + episodes maxim --clear-memory pain,fear # Safety learning only

### Available Memory Types

Type | What It Clears | Effect
--- | --- | ---
focus | FocusLearner gains | Resets movement calibration
bounds | Workspace limits | Relearns reachable space
nac | Causal links | Forgets action-outcome predictions
scn | Temporal patterns | Forgets time-of-day associations
hippo | Episodic memories | Complete amnesia
pain | Pain thresholds | Resets pain sensitivity
fear | Fear associations | Forgets learned dangers
escalation | Escalation thresholds | Resets when to ask for help
threshold | Adaptive thresholds | Resets all learned limits
semantic | Neural embeddings | Resets similarity cache

### Where Data Lives

Directory structure ~/.maxim/ ├── util/ # Learned state (JSON) │ ├── hippocampus.json │ ├── nac_state.json │ ├── scn_state.json │ ├── focus_learner.json │ ├── learned_bounds.json │ ├── fear_learning.json │ └── ... ├── videos/ # Recorded video (MP4) ├── audio/ # Recorded audio (WAV) ├── transcript/ # Transcriptions (JSONL) ├── training/ # Motor training samples (JSONL) ├── plans/checkpoints/ # Goal tree snapshots ├── models/ # ML models │ ├── LLM/ # GGUF language models │ ├── MotorCortex/ # Vision-to-motor model │ └── YOLO/ # Vision models (RTMDet-m + RTMPose-m default; YOLOv8 optional) ├── sandbox/ # Safe space for generated files └── logs/ # Session logs

## Debugging

### Verbosity Levels

Level | What You See
--- | ---
0 | Errors only
1 | Key events (mode changes, goals, tool calls)
2 | Detailed processing (every detection, memory query, decision)
3 (agentic only) | Full trace (LLM prompts, raw responses, bridge activity)

### Inspecting Learned State

Python: inspect memory from maxim.memory.hippocampus import Hippocampus hippo = Hippocampus() hippo.load(str(Path.home() / ".maxim" / "memory" / "hippocampus.json")) print(f"Total memories: {len(hippo._memories)}") for mem_id, mem in list(hippo._memories.items())[:5]: print(f" {mem.action.tool_name} → {mem.outcome.success}") Python: inspect NAc learning from maxim.decisions.nac import NAc nac = NAc() nac.load(str(Path.home() / ".maxim" / "util" / "nac_state.json")) for sig, links in nac._links.items(): for link in links: print(f" {sig}: conf={link.confidence:.2f}, val={link.outcome_valence}")

### Hardware Diagnostics

maxim-diagnostics --host 192.168.1.100

Checks Zenoh connection, motor controller, video stream, and audio stream availability.

### Log Files

Session logs are written to `~/.maxim/logs/reachy_log_YYYY-MM-DD_HHMMSS.log` with timestamps, thread IDs, and structured event data.

### Getting Help

Maxim is open source. If you run into issues, check the GitHub repository for the latest documentation and issue tracker.

← Previous Communication Next → Technical Deep Dive

### All Chapters

Overview The Agent Brain Memory Systems Math & Statistics Attention & Salience Body Awareness Communication Usage Guide Technical Deep Dive Operating Modes Networking & Mesh Roadmap
{% include "_maxim_footer.html" %}
{% endblock %}