← Back to Overview
MAXIM
Usage Guide
Installing, Configuring, and Running Maxim
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
- Install from PyPI
pip install pymaxim
The package is called pymaxim on PyPI, but you import it as maxim.
- 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]'
- 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.
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.
{% include "_maxim_footer.html" %}
{% endblock %}