Usage Guide

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 / client / solo 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)

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) Debug trace (see everything) MAXIM_LANE_TRACE=1 maxim # Trace every LLM call MAXIM_HEARTBEAT=1 maxim # System health every 10s

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|observe|sleep|reflection|train|research --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

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

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

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.valence}") Python: inspect NAc learning from maxim.decisions.nac import NAc nac = NAc.load_from_file(str(Path.home() / ".maxim" / "util" / "nac_state.json")) for sig, pred in nac._learned_associations.items(): print(f" {sig}: conf={pred.confidence:.2f}, val={pred.valence}")