worldmodel-mcp

An external world model for LLM agents: a validated state database that lives outside the context window, exposed as an MCP server and a standalone wm CLI.

Why

Apple's The Illusion of Thinking shows reasoning models collapsing on compositional tasks (Tower of Hanoi fails around 8 disks) — even when handed the explicit algorithm. The failure pattern points at execution fidelity, not insight: a transformer cannot reliably maintain exact state across hundreds of steps of its own token stream, and one silent tracking error compounds forever.

This tool changes the model's job. Instead of being the state-keeper, the executor, and the policy all at once, the model keeps only the part it's good at (judgment, decomposition, interpretation) and delegates the rest:

Paper failure mode	Tool answer
State drift over long horizons	State lives in SQLite tables; the model queries only the working set it needs per step (query)
Silent, compounding errors	Every mutation is a transaction checked against declared invariants; illegal transitions are rejected with the broken rule named (apply_action, define_invariant)
Can't execute known algorithms	Register the algorithm once and let the tool run it — a thousand exact, validated steps for zero tokens (define_procedure, run_procedure)
Can't backtrack cleanly	Snapshots and branches; abandoning a branch truly forgets it (snapshot, branch, checkout, restore_snapshot)
Work lost to context limits	The world outlives the window; describe_world + history re-orient a fresh context in one call

What it does not fix: choosing the right next action is still the model. This moves the collapse threshold out substantially; it does not remove it.

Acceptance test

Straight from the paper: 12-disk Tower of Hanoi (unaided models collapse ~8). Through the world model: schema + 2 invariants + a 12-line recursive procedure → 4095 moves, every one invariant-checked, in 0.26 s, final state verified by query. See src/core.test.ts ("Tower of Hanoi") for the runnable version.

Documentation

• AGENTS.md — the agent operating manual. If you are an LLM agent (or configuring one), start there: when to reach for a world, the five habits, recipes, the procedure contract, how to write good invariants, gotchas.
• Over MCP the same manual is available without reading files: call the guide tool (topic: all | quickstart | recipes | procedures), or read the worldmodel://guide / worldmodel://readme resources. The server also sends a summary as MCP instructions at connection time, so a client model knows what this is before calling anything.
• wm help documents every CLI command.

Install

npm install
npm run build
npm test

Optionally npm link to get wm and worldmodel-mcp on your PATH.

Register as an MCP server (Claude Code)

claude mcp add worldmodel -- node /path/to/worldmodel-mcp/dist/server.js

Worlds are stored under ~/.worldmodel/ (override with WORLDMODEL_DIR).

Model of operation

A world = one problem domain (a puzzle, an investigation, a migration plan). Each world has:

• Tables — ordinary SQLite tables you define; one fact per row.
• Invariants — named SELECTs that return violating rows (empty = healthy). Checked inside every action's transaction; violations roll the action back.
• Actions — named, logged, transactional mutations (apply_action, or the assert_facts / retract_facts conveniences).
• Procedures — deterministic JS function bodies (query, act, log, args, lib) run in a node:vm sandbox with step/time budgets; each act() is a full validated transition, and a pre-run snapshot makes any run one restore from undone. (The sandbox is an isolation convenience, not a security boundary — procedures run with local trust, same as the agent's shell access.)
• lib.search — generic BFS/DFS over in-memory states: lib.search({start, moves, goal, key?, mode?, maxNodes?}) returns {found, path, finalState, nodesExpanded}. The intended pattern is plan in memory, execute validated: search over lightweight state objects (no DB copies per node), then replay the winning path via act() so every real step is still invariant-checked. See the river-crossing test — the paper's other benchmark family — solved this way in src/core.test.ts.
• Templates — create_world with template: "facts" scaffolds an evidence ledger for investigations: facts(entity, attribute, value, source, confidence, status, superseded_by, ...) plus invariants that force contradictions to be resolved explicitly (supersede or mark disputed) instead of letting incompatible beliefs silently coexist.
• Branches & snapshots — cheap file-level copies (VACUUM INTO) for exploration and undo.
• Event log — every schema change, action, and procedure run, queryable via history.

CLI quickstart

wm create hanoi "Tower of Hanoi"
wm schema hanoi "CREATE TABLE disks (disk INTEGER PRIMARY KEY, peg TEXT NOT NULL, height INTEGER NOT NULL, UNIQUE (peg, height))"
wm invariant hanoi no-disk-on-smaller "No disk on a smaller disk" \
  "SELECT u.disk, l.disk FROM disks u JOIN disks l ON u.peg = l.peg AND u.height = l.height + 1 WHERE u.disk > l.disk"
wm assert hanoi disks '[{"disk":1,"peg":"A","height":3},{"disk":2,"peg":"A","height":2},{"disk":3,"peg":"A","height":1}]'
wm act hanoi move "UPDATE disks SET peg=@dst, height=COALESCE((SELECT MAX(height) FROM disks WHERE peg=@dst),0)+1 WHERE disk=(SELECT disk FROM disks WHERE peg=@src ORDER BY height DESC LIMIT 1)" '{"src":"A","dst":"B"}'
wm query hanoi "SELECT * FROM disks ORDER BY peg, height"
wm check hanoi

wm help lists everything; long SQL/code args accept - for stdin; wm serve runs the MCP server.

MCP tools

list_worlds · create_world · describe_world · define_schema · define_invariant · drop_invariant · apply_action · assert_facts · retract_facts · query · check_invariants · snapshot · restore_snapshot · branch · checkout · history · define_procedure · run_procedure

Agent usage discipline

The tool only helps if state is routed through it. The intended habit, for any task with evolving state plus rules:

1. create_world, define_schema, and encode the domain rules as invariants first — rules in the database, not in your head.
2. Mutate only via actions; treat a rejection as information, not failure.
3. Query the working set per step; never re-derive state from the transcript.
4. The moment you know the algorithm, write a procedure instead of narrating steps.
5. Snapshot before anything exploratory; branch to compare alternatives.