World Model Mcp Claude Code Starter

A cloneable, immediately-usable reference showing how to wire world-model-mcp into a real Python project running under Claude Code.

Fork this, install, and see the memory layer catch a constraint violation on your first edit.

What you get in 60 seconds

• 5 learned constraints already in the graph, enforced at PreToolUse
• 1 bug-fix reflection already indexed, injected at PostCompact
• Working FastAPI + SQLAlchemy demo app
• .mcp.json + .claude/settings.json correctly wired for Claude Code
• Hooks capture every file edit, tool call, and session boundary

Quickstart

git clone https://github.com/SaravananJaichandar/world-model-mcp-claude-code-starter
cd world-model-mcp-claude-code-starter
pip install -r requirements.txt
world-model setup --no-prompt
python scripts/seed_starter_facts.py

Open the folder in Claude Code (the .mcp.json auto-registers the memory server). Try any of the workflows in docs/WHAT_TO_TRY.md.

What to try

The seeded facts make the memory layer visible on the first edit:

1. Ask Claude Code to add a print() statement in app/main.py. The logger-not-print constraint fires at PreToolUse.
2. Ask Claude Code to touch app/auth.py. The timing-attack bug_fix reflection injects into context before the edit.
3. Ask Claude Code to add a new POST route. The use-status-201-on-create constraint validates the return status.
4. Ask Claude Code to add a try: ... except: (bare except) somewhere. The no-bare-except constraint fires.
5. Ask Claude Code to write an async DB call without await. The always-await-async-db constraint fires.

Full walkthrough in docs/WHAT_TO_TRY.md.

Repo layout

world-model-mcp-claude-code-starter/
├── .mcp.json                    # Claude Code MCP server registration
├── .claude/
│   ├── settings.json            # PreToolUse / PostToolUse / PostCompact / SessionStart hooks
│   └── world-model/             # created by `world-model setup`; SQLite fact graph lives here
├── app/                         # FastAPI + SQLAlchemy demo app
│   ├── main.py
│   ├── auth.py
│   ├── db.py
│   └── routes/{users,health}.py
├── tests/test_auth.py
├── scripts/seed_starter_facts.py
├── requirements.txt             # pins world-model-mcp==0.12.13
└── docs/
    ├── SETUP.md                 # detailed install path
    └── WHAT_TO_TRY.md           # 5 concrete workflows

What NOT to expect

• Not a benchmark suite. For the contradiction-resolution and Coach-Player benchmarks see benchmarks/ in the main repo.
• Not a production reference. Auth is illustrative, not battle-tested. Do not deploy this app.
• Not the install path itself. This is a "here is what it looks like when configured correctly" showcase for developers evaluating whether the memory layer fits their workflow.

Getting help

• Main repo issues: https://github.com/SaravananJaichandar/world-model-mcp/issues
• Case study on how the memory layer catches its own bugs: v011-dogfooding/CASE_STUDY.md
• Run world-model doctor --project-dir . if hooks are silently failing on your machine

License

MIT. Same as the main project.