Maxim

A bio-inspired cognitive architecture for AI agents. Maxim gives an agent a body (sensors, drives, pain), brain-modelled memory (Hippocampus, NAc, ATL, EC, SCN, Angular Gyrus) and a way to share what it learned with other agents. It runs in two modes:

• LLM harness. An LLM chooses the actions; Maxim gives it persistent, agent-specific experience — episodic recall, learned causal links, valence and drive state — as prompt context, across sessions and without fine-tuning.
• Substrate-primary. No language model in the action path: the agent's own learned substrate (NAc reward and fear, keyed on the situation its sensors encode) chooses what to do.

Works headless, in simulation, in a live Minecraft world, or on a Reachy Mini robot.

• Website: pymaxim.bio
• Documentation: pymaxim.bio/getting-started
• Source, experiments and ledgers: github.com/dennys246/Maxim

What it has shown — and what it has not

Each result below is a row on the ledger of record, graded against gates frozen before the data; the ledger states each claim's exact scope, its evidence, its current status and what would invalidate it: behavioral_graduation_candidates.md.

What is not claimed is just as load-bearing. In the 1.3 survival benchmark, survival itself was at ceiling: a carried fear buys about 25 s of latency, 11 hp and 22 s of oxygen pain — not life. "Dark = danger" is blocked at the instrument, and generalization to an unseen situation is untested. Each mechanism's behavioural status is tracked on the ledger; mechanisms that failed to earn weight are marked Dormant in the code.

The Minecraft results were produced by the harnesses in scripts/exp56/ and scripts/survival_world/ against Paper servers (Exp 56 earned on 1.16.5 and re-baselined on 1.20.4; Exp 60 and 61 on 1.20.4). They run from a repository checkout, not from the installed wheel.

Quickstart

# With Claude (fastest way to start)
pip install 'pymaxim[llm-anthropic]'
export ANTHROPIC_API_KEY=sk-...
maxim --sim "test memory recall under interference"

# Or with a local model (no API key needed)
pip install 'pymaxim[llm-llama,llm-server]'
maxim --list-models                                  # see available models
maxim --sim "test memory recall" --llm mistral-7b    # downloads on first run

# Cradle sensorimotor development (an infant agent learns from sensation)
pip install 'pymaxim[llm-llama,llm-server,semantic]'
maxim --sim cradle --embodiment bodies/infant_humanoid --sim-max-turns 25

Check your setup with maxim doctor. Simulation reports are written to ~/.maxim/sim_reports/{session_id}/. Substrate-primary action selection in a simulation is --aut-mode substrate-primary (experimental).

Bio-systems

Maxim's architecture is modelled on brain systems, not software patterns:

Bodies and drives

Agents have bodies with sensors, modulators and failure modes declared in YAML:

# Homeostatic drive — the body self-regulates toward set_point
core_temperature:
  drive:
    drift_mode: homeostatic
    set_point: 0.0
    drift_rate: 0.001
    comfort_band: 0.4        # no discomfort within +/-0.4
    pain_scale: 0.5          # pain per unit outside the band

# Entropic drive — drifts away; only an action restores it
hunger:
  drive:
    drift_mode: entropic
    drift_direction: up
    drift_rate: 0.006
    deprivation_threshold: 0.7
    deprivation_pain: 0.3

Contact, touch and narrated events all converge on one pipeline: sensor change → failure evaluation → PainBus → NAc learning. In the Minecraft world the game owns the drives (hunger drains, air runs out) and the pain comes from the game, not from a model.

Sharing what an agent learned

An agent's learned substrate — its NAc policy and EC situation clusters, never its episodic memories — exports as a bundle another agent can ingest. Ingest validates every bundle before anything is merged, and a donor can deepen a receiver's negative biases but never weaken them.

# --session takes a session directory (a simulation's is ~/.maxim/sim_reports/<session_id>)
maxim substrate export out.zip --session ~/.maxim/sim_reports/<id> \
    --contributor-id <your-id> --body-ref minecraft_player
maxim substrate inspect out.zip                      # read the manifest
maxim substrate ingest out.zip --session <receiver-dir> --trust <contributor-id> \
    --receiver-body minecraft_player                 # dry run; add --apply to merge

# An Oasis is a shared source of signed releases
maxim hive add <name> <url> --queen-key <identity>=<pubkey_b64>
maxim hive pull --from <name> --session <receiver-dir> --receiver-body minecraft_player \
    --receiver-agent-id <your-agent-id>              # dry run; add --apply to merge

Signed releases carry a signature over every member, a signed entry index and a release sequence. A receiver refuses a second payload under the same key and sequence (equivocation), and a legacy v1 bundle from a key it has already accepted a v2 release from (downgrade). See Substrate sharing and the bundle format.

Installation

pip install pymaxim

Optional extras

Note: [all] does not include [semantic]. Without it, memory recall and substrate encoding fall back to bag-of-words hashing. For full memory quality: pip install 'pymaxim[all,semantic]'.

Python API

21 verb-based functions give programmatic access to the same runtime:

import maxim

result = maxim.imagine(goal="test safety boundaries")   # run a simulation
state = maxim.observe("memory")                         # inspect a bio-system
report = maxim.diagnose()                               # the same checks as `maxim doctor`

maxim.run(model="mistral-7b", goal="inspect the workspace")   # needs a configured LLM backend

# Controller-backed motion on a robot (robot and headless=True are contradictory)
maxim.run(model="mistral-7b", goal="turn your head 20 degrees left", robot="reachy_mini", headless=False)

models = maxim.list_models()
maxim.download_model("qwen2.5-14b-instruct")

See the Python API reference.

CLI quick reference

maxim                                     # interactive menu
maxim --llm claude-sonnet                 # agent runtime with Claude
maxim --sim "test memory recall"          # generative simulation
maxim --sim benchmark --models mistral-7b,qwen2.5-14b
maxim doctor                              # environment check
maxim config list                         # every resolved setting and where it came from
maxim model list                          # user-defined model profiles (catalog: --list-models)

Simulation exit codes separate run integrity from experimental verdicts: 0 means the run produced usable evidence (including outcomes such as failed or inconclusive), 1 is an error, and 4 is an incomplete or aborted run — campaign scripts must reject every non-zero exit before analysing a report. Python APIs return the structured finish_reason instead of exiting.

See the CLI reference for every flag.

Documentation

Design essays

dennyschaedig.com/maxim hosts Denny's design essays — the why behind Maxim's architecture. They are opinion and rationale, not reference: the canonical reference and evidence site is pymaxim.bio, which wins wherever the two disagree, and the repository's experiment, defect, limits, and graduation ledgers win over both.

The reference pages that used to live beside the essays have moved to pymaxim.bio (the old URLs redirect):

Five reference-flavoured pages are still served on dennyschaedig.com only until their pymaxim.bio equivalents deploy; delete a row here when the page is retired:

Contributing

Issues and PRs welcome at github.com/dennys246/Maxim.

License

See LICENSE for details.