AdaMAST

Your agent keeps making the same mistakes. AdaMAST learns what they are — from your agent's own work — and reminds it at the right moments.

AdaMAST rides along with the agent you already use — Codex, Claude Code, or your own harness. While the agent works, AdaMAST quietly checks the work at natural boundaries, records evidence when something goes wrong, and — after enough completed tasks — learns a failure-mode catalog (a "taxonomy") specific to your project. From then on, the agent is checked against its own known weaknesses instead of a generic list.

Paper: Fantastic Adaptive Taxonomies and How to Use Them · Docs: Website

🚀 Quickstart (zero configuration)

Requirements: Python 3.10+ and Codex or Claude Code.

pip install adamast

Then register AdaMAST with the host you use (once):

# Claude Code
adamast claude install --user-level

# Codex
adamast codex install --user-level

Fully quit and reopen Codex / Claude Code, then start a new conversation. That's it — no config file, no extra API key, no second login.

On your first message, AdaMAST opens its taxonomy picker and asks one question — where should this conversation start from?

Pick with one click (or one number in a terminal) — your held message then continues automatically.

💡 Check it worked: run adamast doctor any time. It validates your install and tells you exactly what to do if something is off.

🔄 What happens while you work

flowchart LR
    A["💬 You work with<br/>your agent as usual"] --> B["🛑 Checkpoints<br/>agent self-checks at<br/>natural boundaries"]
    B --> C["🧾 Traces<br/>each finished task<br/>is recorded"]
    C --> D["🧠 Learning<br/>after 5 traces: your<br/>project's taxonomy"]
    D --> E["♻️ Refinement<br/>reviewed after 10,<br/>then every 20 traces"]
    E -.->|"sharper failure modes"| B

1. You work normally. AdaMAST never takes over the task.
2. At checkpoints (finishing a sub-task, a failed tool, the final answer) the agent privately asks itself: what just happened, what caused it, does a known failure mode apply, continue or repair? Finding nothing wrong is a perfectly valid answer.
3. Each completed task becomes a trace. Traces are the raw material for learning.
4. At 5 traces, learning kicks in — a background worker drafts a taxonomy of your project's actual failure patterns, with verbatim evidence for every code. A separate reviewer must approve it before it activates. Your conversation never waits.
5. It keeps improving. The taxonomy is reviewed against new traces after 10 more, then every 20.

Watch it live: adamast dashboard opens a local monitor showing every checkpoint, the evidence behind it, and which failure modes fired.

🎛️ Make it yours

Everything above ran on defaults. Each step has one obvious knob when you want a custom setup:

Every field, flag, and default lives in the Configuration reference; deeper customization (prompts, gates, custom hooks) in Customization.

🧠 Why adaptive taxonomies?

Improvement needs feedback that preserves why something failed. Scalar rewards throw the reason away; free-form reflection doesn't aggregate; a fixed catalog can't know your agent's roles, tools, or domain in advance. AdaMAST learns a compact, evidence-grounded failure vocabulary from the target system's own traces — starting from the built-in 14-code adaptation of MAST ("Why Do Multi-Agent LLM Systems Fail?", Cemri et al., 2025) until the first learned taxonomy activates.

Learned codes are organized on three stable axes:

🏆 Results

Summaries, exact taxonomies, and reproduction notes live in runs/. Per-question rows and raw scorer output are not included, so the headline numbers cannot be independently recomputed from this repository alone.

📚 Learn more

🤝 Contributing

Development setup, verification commands, and package boundaries: CONTRIBUTING.md · Release steps: RELEASING.md

The original research pipeline lives on the paper-pipeline branch; a maintained, locally patched fork is vendored under adamast/learning/vendor/ with provenance in VENDORED.md.

📄 License

Apache-2.0. See LICENSE.