World Model MCP

@putervision/world-model-mcp

@putervision/world-model-mcp is a zero-infrastructure, deterministic Model Context Protocol (MCP) server that maintains a persistent 3D/2D spatial world model for AI agents. It bridges perception (@putervision/vision-memory-mcp) and reasoning/action (@putervision/state-memory-mcp) with durable entity tracking, object permanence with confidence decay, movement simulation with AABB collision avoidance, expected view frustum projection, and Playwright 3D game automation.

🌐 Official Documentation & Website: putervision.com

---

⚡ Quick Start & Installation

Prerequisites: Node.js >= 18.18.0

# 1. Install globally

npm install -g @putervision/world-model-mcp

2. Navigate to your project directory

cd your-project

3. Initialize world-model-mcp

Creates .world-model-mcp/, updates .gitignore, registers project,

and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.

world-model-mcp init

Done! Restart your IDE or Agent Manager to activate.

Alternative Options

# Run directly via binary (after global install)

world-model-mcp run

Launch interactive 3D WebGL Scene Visualizer

world-model-mcp view

Display database metrics and permanence confidence stats

world-model-mcp stats

---

🌟 Key Highlights

• 🌐 Deterministic 3D/2D Spatial Memory & Compact Slices: Zero LLM in the loop for spatial indexing; deterministic SQLite WAL queries with FTS5 search, 3D Euclidean proximity radius lookups, and sub-1KB observer-relative compact slices ($K \le 16$ nearest entities) for System 1 fast path evaluation.
• ⚡ 15 Production-Grade Consolidated MCP Tools: Full CRUD, topological spatial graphs (on, inside, contains, near), ray-AABB occlusion frustum culling, waypoint navigation, and time-travel rollback.
• ⏳ Object Permanence & Decay: Entities remain in persistent memory even when out of view, with configurable exponential confidence decay ($C = C_0 \cdot e^{-\lambda t}$) and status lifecycles (active → hidden → lost).
• 🚀 Collision & Movement Simulation: Predicts entity displacement trajectories, detects AABB obstacle collisions, and computes obstacle-avoiding navigation waypoints before actions execute.
• 🎮 Playwright Game Automation: Generates timed WASD / Arrow keyboard hold sequences (KeyW for 450ms, ArrowLeft for 290ms) and 3D↔2D coordinate screen projections.
• 🤝 Multi-Agent Spatial Blackboard: Topic-based coordination with TTL, mutex locks, and collision intent alerts across parallel subagents.
• 🛡️ Spatial Spec-Driven Development (Spatial SDD): Physical design contract baseline registration, live verification (clearance, bounds, containment), and cryptographic SHA-256 evidence bundles.
• 🎨 Interactive 3D WebGL Visualizer: Browser-based Three.js 3D viewport rendering active entities, orientation axes, frustum cones, and topological links (world-model-mcp view).
• 🔒 100% Local & Private: All spatial entities, relations, and history stay inside .world-model-mcp/ in your workspace.

---

🛠️ MCP Tool Suite

@putervision/world-model-mcp provides 15 production-grade consolidated MCP tools organized across 5 core workflow domains:

• Spatial Memory & Search: update_entity (entity CRUD, 3D bounds, properties, confidence), query_entities (FTS5 search, proximity radius, status/tags filter, history lookup), set_relation (topological graph links: on, inside, near, contains), get_spatial_map (JSON, GeoJSON, glTF 2.0, OBJ, summary, and format: "compact_slice").
• Simulation & Vision Integration: simulate_movement (displacement prediction, AABB collision checks, waypoint routing), ingest_observation (vision detection ingestion, Euclidean re-identification, frustum reconciliation), get_expected_view (observer pose, horizontal FOV cone, ray-AABB occlusion).
• Goal & State Integration: link_to_goal (associate entities/regions with State Memory tasks, extract spatial context slices), record_outcome (record execution results, position shifts, property changes, destruction).
• Spatial SDD & Proofs: manage_spatial_spec (register physical clearance/containment contracts, live verification scoring), create_evidence_pack (cryptographic SHA-256 evidence bundles linking spatial proofs to task nodes).
• Multi-Agent, Replay & Automation: use_spatial_blackboard (topic board, mutex claim/release, intent conflicts), manage_snapshot (checkpoints, snapshot diffing, time-travel undo), wait_for_spatial_state (async polling for target spatial condition), generate_game_inputs (Playwright WASD hold timings, 3D↔2D screen ray projection).

👉 For complete parameter specifications, return schemas, and example payloads, see the [API Reference Guide](docs/api-reference.md) and [Database Schema](docs/database-schema.md).

---

🚀 Architecture & Spatial Memory Lifecycle

                     Perception / Vision Detection

│ ▼ ┌─────────────────────────────────┐ │ Perception Ingestion & Re-ID │ ──▶ ingest_observation(reconcile: true) └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Durable Entity & Permanence │ ──▶ update_entity(...) │ (3D Bounding Boxes, Decay) │ ──▶ set_relation(relation: "on"|"inside") └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Simulation & Waypoint Routing │ ──▶ simulate_movement(mode: "navigate") │ (AABB Collision Avoidance) │ ──▶ get_expected_view(fov: 90) └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Playwright & Action Execution │ ──▶ generate_game_inputs(...) │ (WASD Sequences, Screen Rays) │ ──▶ record_outcome(action_type: "move") └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Spatial SDD & Cryptographic │ ──▶ manage_spatial_spec(action: "verify") │ Evidence Bundling to Tasks │ ──▶ create_evidence_pack(...) └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Persistent SQLite Engine │ ──▶ .world-model-mcp/world.db (WAL mode) │ Append-Only History Ledger │ ──▶ SHA-256 Cryptographic Audit Chain └─────────────────────────────────┘

---

📚 Documentation Directory

Explore dedicated guides and deep dives in the docs/ directory:

---

📖 Agent Playbook: 5-Step Canonical Workflow

When an autonomous AI agent enters a repository with world-model-mcp:

1. Orient & Explore   ──▶ get_spatial_map(format: "summary") + get_expected_view(fov: 90)

1. Query & Locate ──▶ query_entities(query: "chest", radius: 15) + query_entities(entity_id: "...")
2. Plan & Simulate ──▶ simulate_movement(mode: "navigate") + manage_spatial_spec(action: "verify")
3. Execute & Ingest ──▶ generate_game_inputs(...) + ingest_observation(reconcile: true)
4. Record & Evidence ──▶ record_outcome(...) + create_evidence_pack(task_id: "...")

---

🧪 Testing

# Run full unit, integration, and geometry stress test suite across 47 test files (206 tests)

npm test

Run multi-Node matrix test suite across Node.js 18, 20, and 22

npm run test:matrix

Run 3D geometry, projection, and Playwright game loop tests

npm run test:3d

---

⚖️ License & Disclaimers

Developed and maintained by PuterVision. Released under the MIT License.

• Local Storage Guarantee: All spatial coordinates, bounding volumes, and entity history remain 100% local in your workspace. No telemetry or project data is ever transmitted.
• Trademarks & Non-Affiliation: Product names (Cursor, Claude Code, Gemini, Windsurf, VS Code, GitHub, SQLite, Three.js, Playwright) are property of their respective owners and used solely for compatibility identification.