@putervision/world-model-mcp weekly downloads statistics

@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

Alternative Options

🌟 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

📚 Documentation Directory

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

| Guide | Description |

| 🏗️ Architecture & Codebase Distillation | High-signal architectural overview, module inventory, data flows, and design decisions. | | 💡 Features & Triad Overview | PuterVision Autonomous Triad interaction, 3D WebGL scene visualizer, and evidence packs. | | 📋 Spatial World Model Concepts | Object Permanence ($C = C_0 \cdot e^{-\lambda t}$), Confidence Decay, Frustum Projection, and Spatial SDD. | | ⚙️ Configuration & IDE Setup | Auto-Initialization details, Environment Variables, and Editor Configs (Cursor, VS Code, Claude, Windsurf). | | 🛠️ CLI Command Reference | CLI flags (init, run, view, stats, inspect, map, export, import, doctor, snapshot, spec, blackboard). | | 🧰 Tools & API Reference | Complete reference for all 15 Consolidated MCP Tools, legacy tool mapping, and parameter examples. | | 🗄️ Database Schema | SQLite tables (entities, spatial_relations, entity_history, spatial_specs, blackboard_items, evidence_packs). | | 🎮 Interactive 3D Game Arena Demo | Autonomous 3D browser arena with Three.js bridge diagnostics (window.__WORLD_MODEL_BRIDGE). | | 🧭 Examples & Tutorials | Deep-dive examples: Spatial Navigation, Perception Reconciliation, and Multi-Agent Blackboard. |

📖 Agent Playbook: 5-Step Canonical Workflow

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

🧪 Testing

⚖️ License & Disclaimers

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

Description from the npm listing.