@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 and Database Schema.

🚀 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: