Migration

loadout-os consolidates three previously-separate tools into one binary. If you used any of ai-loadout, claude-memories, or claude-rules, this page maps the old commands to the new surface. The good news: the verbs are the same — they’ve just moved under one CLI.

Command mapping

Kernel — `ai-loadout X` → `loadout-os X`

The kernel verbs are flat — they keep their names with no namespace prefix:

Legacy	Unified
`ai-loadout resolve`	`loadout-os resolve`
`ai-loadout explain <entry-id>`	`loadout-os explain <entry-id>`
`ai-loadout usage <jsonl>`	`loadout-os usage <jsonl>`
`ai-loadout dead <index> <jsonl>`	`loadout-os dead <index> <jsonl>`
`ai-loadout overlaps <index>`	`loadout-os overlaps <index>`
`ai-loadout budget <index> [jsonl]`	`loadout-os budget <index> [jsonl]`
`ai-loadout validate <index>`	`loadout-os validate <index>`

Memories — `claude-memories X` → `loadout-os memories X`

The MEMORY.md adapter moves under the memories namespace:

Legacy	Unified
`claude-memories index <MEMORY.md>`	`loadout-os memories index <MEMORY.md>`
`claude-memories validate <MEMORY.md>`	`loadout-os memories validate <MEMORY.md>`
`claude-memories stats <MEMORY.md>`	`loadout-os memories stats <MEMORY.md>`
`claude-memories health`	`loadout-os memories health`

Rules — `claude-rules X` → `loadout-os rules X`

The CLAUDE.md adapter moves under the rules namespace:

Legacy	Unified
`claude-rules analyze <CLAUDE.md>`	`loadout-os rules analyze <CLAUDE.md>`
`claude-rules split [CLAUDE.md]`	`loadout-os rules split [CLAUDE.md]`
`claude-rules validate`	`loadout-os rules validate`
`claude-rules stats <CLAUDE.md>`	`loadout-os rules stats <CLAUDE.md>`

Why the namespacing

The three tools each shipped their own validate, which would collide under one binary. loadout-os resolves this by keeping the kernel validator flat (loadout-os validate <index> — validates a dispatch table’s structure) and namespacing the two linters (memories validate <MEMORY.md> and rules validate — lint a store or rules directory). All three coexist because only one is flat. See the Command reference for the full distinction.

What stays the same

The kernel library is unchanged and importable. @mcptoolshop/ai-loadout remains the published library — planLoad, matchLoadout, resolveLoadout, recordLoad, and the dispatch-table types all keep their signatures. If you import the kernel in code, nothing changes.
The dispatch-table format is unchanged. Indexes generated by the legacy tools are valid loadout-os indexes, and vice versa. Same LoadoutIndex shape, same priority tiers (core / domain / manual), same frontmatter contract.
The legacy bins keep working. During the consolidation, ai-loadout, claude-memories, and claude-rules continue to function. They are scheduled for retirement, but nothing breaks the day you switch — you can move command by command at your own pace.

What’s new

loadout-os adds capabilities that none of the three legacy bins had on their own:

loadout-os refresh — the Index Freshness Ritual (regenerate → validate → publish) as one command, with an andon halt and a backup compensator. Replaces the old manual three-step sequence.
loadout-os doctor — a read-only 8-check health screen across the whole system.
loadout-os report — usage / dead-entry / budget observability over the usage log.
loadout-os hook test — drive the runtime hook against a sample prompt in an isolated environment.

See Rituals for these in depth.

Recommended path

Install loadout-os and run loadout-os doctor to confirm the system is healthy.
Switch your day-to-day commands to the unified surface using the tables above.
Adopt the new rituals — use refresh instead of the manual index sequence, and run report periodically to tune keywords.
Keep importing @mcptoolshop/ai-loadout as a library wherever you depend on the kernel API; that contract is stable.