world-model-mcp
by putervision
README.md
# @putervision/world-model-mcp
[](https://www.npmjs.com/package/@putervision/world-model-mcp)
[](./CHANGELOG.md)
[](https://www.npmjs.com/package/@putervision/world-model-mcp)
[](https://github.com/putervision/world-model-mcp/actions/workflows/ci.yml)
[](https://nodejs.org)
[](https://www.typescriptlang.org)
[](https://putervision.com)
[](https://github.com/putervision/world-model-mcp/blob/main/LICENSE)
`@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`](https://github.com/putervision/vision-memory-mcp)) and reasoning/action ([`@putervision/state-memory-mcp`](https://github.com/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](https://putervision.com)
---
## ⚡ Quick Start & Installation
> **Prerequisites**: Node.js **>= 18.18.0**
```bash
# 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
```bash
# 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/`](docs/) directory:
| Guide | Description |
| :--- | :--- |
| 🏗️ **[Architecture & Codebase Distillation](docs/codebase-distillation.md)** | High-signal architectural overview, module inventory, data flows, and design decisions. |
| 💡 **[Features & Triad Overview](docs/features.md)** | PuterVision Autonomous Triad interaction, 3D WebGL scene visualizer, and evidence packs. |
| 📋 **[Spatial World Model Concepts](docs/concepts.md)** | Object Permanence ($C = C_0 \cdot e^{-\lambda t}$), Confidence Decay, Frustum Projection, and Spatial SDD. |
| ⚙️ **[Configuration & IDE Setup](docs/configuration.md)** | Auto-Initialization details, Environment Variables, and Editor Configs (Cursor, VS Code, Claude, Windsurf). |
| 🛠️ **[CLI Command Reference](docs/cli-usage.md)** | CLI flags (`init`, `run`, `view`, `stats`, `inspect`, `map`, `export`, `import`, `doctor`, `snapshot`, `spec`, `blackboard`). |
| 🧰 **[Tools & API Reference](docs/api-reference.md)** | Complete reference for all 15 Consolidated MCP Tools, legacy tool mapping, and parameter examples. |
| 🗄️ **[Database Schema](docs/database-schema.md)** | SQLite tables (`entities`, `spatial_relations`, `entity_history`, `spatial_specs`, `blackboard_items`, `evidence_packs`). |
| 🎮 **[Interactive 3D Game Arena Demo](docs/game-demo.html)** | Autonomous 3D browser arena with Three.js bridge diagnostics (`window.__WORLD_MODEL_BRIDGE`). |
| 🧭 **[Examples & Tutorials](docs/examples/)** | Deep-dive examples: [Spatial Navigation](docs/examples/spatial-navigation.md), [Perception Reconciliation](docs/examples/perception-reconciliation.md), and [Multi-Agent Blackboard](docs/examples/multi-agent-blackboard.md). |
---
## 📖 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)
2. Query & Locate ──▶ query_entities(query: "chest", radius: 15) + query_entities(entity_id: "...")
3. Plan & Simulate ──▶ simulate_movement(mode: "navigate") + manage_spatial_spec(action: "verify")
4. Execute & Ingest ──▶ generate_game_inputs(...) + ingest_observation(reconcile: true)
5. Record & Evidence ──▶ record_outcome(...) + create_evidence_pack(task_id: "...")
```
---
## 🧪 Testing
```bash
# 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](https://putervision.com). Released under the [MIT License](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.
TDQS
A4.2/5.0
Scored across 15 tools
Disambiguation4/5
The descriptions aggressively disambiguate with explicit 'Use X instead of Y when...' guidance, which helps a lot. However, there are still three entity-writing paths (update_entity, record_outcome, ingest_observation) and three reading/export paths (query_entities, get_spatial_map, get_expected_view) whose boundaries require careful reading, so some residual confusion remains.
Naming Consistency5/5
All 15 tools use snake_case verb-first naming (update_entity, query_entities, manage_snapshot, create_evidence_pack, wait_for_spatial_state). Even the multi-word variants (link_to_goal, wait_for_spatial_state) follow a predictable verb_noun/verb_prep_noun convention.
Tool Count5/5
15 tools sits at the top of the well-scoped range and each tool maps to a distinct capability (authoring, perception, querying, simulation, snapshots, coordination, verification, automation). For a spatial world-model server, this breadth is justified rather than padded.
Completeness4/5
The surface covers entity lifecycle (create/update, status-destroyed), relations, querying, export, simulation, perception ingest, snapshots, goal linking, blackboard coordination, spec verification, evidence packing, game inputs, and polling. Explicit deletion/region-management tools are absent, but the destroy-status pattern and region references mostly compensate.
Maintenance
ActivityMaintained
ResponsivenessNo issues