Star on GitHub
RELEASE v0.6.1 • LOCAL-FIRST SQLITE WAL • 15 CONSOLIDATED MCP TOOLS

Deterministic 3D/2D Spatial World Model for AI Agents

Bridges perception and action with persistent entity tracking, topological spatial relationships, object permanence with confidence decay, movement simulation, spatial SDD, and Playwright 3D game navigation.

Explore Live Spatial Radar 🎮 Movement & Nav Simulator 3D Arena Demo ↗ View 15 Tools

The PuterVision Autonomous Pentad Ecosystem

world-model-mcp operates as the durable spatial foundation linking raw sensory perception, workflow execution, cognitive reasoning, and high-frequency behavior execution.

👁️ Perception Layer

vision-memory-mcp ↗

Visual state cache, layout grounding, AX tree coordinate mappings, diff detection, and video timeline keyframes.

🌐 Spatial World Model

world-model-mcp (This Server)

Persistent 3D/2D coordinate store, topological graphs (on, inside, near), object permanence, movement collision simulation, and FOV expected view cones.

🧠 Workflow Memory

state-memory-mcp ↗

Task execution DAGs, decisions, blockers, SDD design contracts, milestone verification, and multimodal trajectory audit trail.

🎯 Strategic Reasoning

agent-reasoning-mcp ↗

Hierarchical BDI goal decomposition, multi-attribute utility scoring, exponential belief decay, and reactive replanning.

⚡ Behavior Runtime

behavior-mcp ↗

High-frequency ~60Hz in-browser behavior tree execution, reactive preemption triggers, telemetry, and 5-layer safety guardrails.

📦

Durable Entity Tracking

Stores 3D positions, Euler orientations, AABB bounding volumes, properties, and tags in a local SQLite WAL engine.

🔗

Topological Spatial Relations

Maintains bidirectional spatial relationships (contains ↔ inside, above ↔ below, connected_to) with BFS path traversal.

⏳

Object Permanence & Decay

Entities stay in memory even when out of view, with configurable time-based confidence decay and status lifecycles (active → hidden → lost).

🚀

Collision & Movement Simulation

Predicts entity displacement trajectories and tests for AABB obstacle collisions before executing real-world agent actions.

📐

Frustum & Expected Views

Calculates visible entities from camera/observer pose and horizontal FOV cones, diffing observations to detect appeared or displaced items.

🎯

Goal Alignment Bridge

Directly links target entities and destination regions to active state-memory-mcp tasks, extracting goal-relevant spatial slices.

Interactive Spatial Radar & Frustum Visualizer

Test real-time frustum projection (get_expected_view) and spatial proximity queries (query_entities). Drag the observer or rotate the heading cone!

Interactive Movement Simulation & Playwright Generator

Test real-time AABB collision avoidance (simulate_movement) and Playwright WASD automated action sequence generation (generate_game_inputs). Click anywhere to move the Target Goal or drag the Agent & Obstacles!

🎮 Launch 3D Game Arena ↗
Collision Detection: ✅ Clear Corridor
Nav Waypoints: 2 Waypoints
Estimated Action Time: ~620ms 
// Calculating action stream...

15 Consolidated MCP Tools

Complete tool reference categorized into Spatial Memory, Simulation & Vision Integration, Goal Integration, Spatial SDD & Proofs, and Multi-Agent & Replay.

Tool Name Category Type Key Parameters Description
update_entity Spatial Memory Mutating name, type, position, bounding_box, properties Create or update an entity (position, orientation, bounding box, properties, confidence)
query_entities Spatial Memory Read-Only query, type, near_position, entity_id, include_history Search entities by keyword (FTS5), proximity radius, tags, status, or fetch specific entity location & trajectory history
set_relation Spatial Memory Mutating source_id, relation, target_id, offset Record or remove spatial relationships (on, inside, next_to, above, below, near, contains)
get_spatial_map Spatial Memory Read-Only region_id, format, min_confidence Export structured spatial layout (JSON, GeoJSON, glTF 2.0, OBJ) or high-level summary (format: "summary")
simulate_movement Simulation Read-Only entity_id, delta_position, mode, check_collisions Predict trajectory, test for AABB obstacle collisions, or compute waypoint navigation paths (mode: "navigate")
ingest_observation Perception Mutating observer_pose, detections, visual_state_id, reconcile Ingest structured perception detections into world model; re-identify entities and reconcile frustum view (reconcile: true)
get_expected_view Perception Read-Only observer_position, observer_orientation, fov Calculate visible entities from observer pose with 3D ray-AABB occlusion culling
link_to_goal Goal Integration Mutating action, task_id, entity_id, relationship Associate entities/regions with state-memory task IDs, or extract goal-relevant spatial context slices (action: "get_context")
record_outcome Goal Integration Mutating action_name, success, resulting_position Update world model after action execution completes (position, properties, destruction)
manage_spatial_spec Spatial SDD Mutating action, name, constraints, bounds Register and verify physical design constraints (clearance, bounds, containment)
create_evidence_pack Proofs Mutating task_id, entity_ids, observation_ids Generate SHA-256 cryptographic spatial evidence bundles for state-memory artifacts
use_spatial_blackboard Multi-Agent Mutating action, topic, sender, payload, ttl Topic-based multi-agent coordination with TTL, mutex locks, and collision intent alerts
manage_snapshot Replay & Snapshots Mutating action, name, snapshot_a, snapshot_b, entity_id Unified snapshot and time-travel management: checkpoints, diffs, undo mutations, and historical replay
generate_game_inputs Playwright & Games Read-Only action, entity_id, target_position, camera, viewport Translate 3D waypoints into Playwright keyboard/mouse inputs or project/unproject screen coordinates
wait_for_spatial_state Async Polling Read-Only entity_id, condition, threshold, timeout_ms Poll and wait until target spatial condition is satisfied (exists, active, confidence threshold, region)

Installation & Client Configuration

Configure world-model-mcp into your IDE or autonomous coding agent framework. 

# Scaffold world-model-mcp and generate IDE agent rules in current workspace
npx @putervision/world-model-mcp init

# Launch standalone Three.js 3D WebGL scene visualizer (port 8090)
npx @putervision/world-model-mcp view

# Check health, graph invariants, and event audit chain
npx @putervision/world-model-mcp doctor

# Inspect active entities in an ASCII table
npx @putervision/world-model-mcp inspect

# Verify Spatial SDD physical constraints
npx @putervision/world-model-mcp spec list

# Post and read multi-agent spatial blackboard
npx @putervision/world-model-mcp blackboard list

# Export scene to standard 3D formats (glTF 2.0, OBJ, GeoJSON)
npx @putervision/world-model-mcp export -o scene.gltf gltf
// .cursor/mcp.json
{
  "mcpServers": {
    "world-model-mcp": {
      "command": "world-model-mcp",
      "args": ["run"],
      "env": {
        "WORLD_MODEL_MCP_PROJECT": "my-project"
      }
    }
  }
}
// .vscode/mcp.json
{
  "servers": {
    "world-model-mcp": {
      "type": "stdio",
      "command": "world-model-mcp",
      "args": ["run"],
      "env": {
        "WORLD_MODEL_MCP_PROJECT": "my-project"
      }
    }
  }
}
// ~/.gemini/config/mcp_config.json
{
  "mcpServers": {
    "world-model-mcp": {
      "command": "world-model-mcp",
      "args": ["run"]
    }
  }
}
import { getDb, EntityStore, SpatialGraph, FrustumEngine } from "@putervision/world-model-mcp/lib";

const db = getDb("my-sim");

// Create 3D entity
const chest = EntityStore.addEntity(db, {
  project: "my-sim",
  name: "Treasure Chest",
  type: "container",
  position: { x: 12, y: 0, z: 8 },
  properties: { is_locked: true },
});

// Check visibility from observer
const expected = FrustumEngine.getExpectedView(db, {
  project: "my-sim",
  observer_position: { x: 0, y: 0, z: 0 },
  observer_orientation: { yaw: 35 },
  fov_degrees: 90,
});

console.log("Visible Entities:", expected.visible_entities);