Strategic Agent Reasoning MCP

@putervision/agent-reasoning-mcp

Strategic BDI Reasoning, Multi-Attribute Expected Utility Theory & Decision Intelligence for Autonomous AI Agents

@putervision/agent-reasoning-mcp is a formal Model Context Protocol (MCP) server that provides strategic belief-desire-intention (BDI) reasoning, hierarchical goal decomposition, multi-attribute expected utility calculation (\(E[U] = \sum w_i u_i\)), exponential belief decay, quantitative risk evaluation, and reactive replanning across multi-modal memory bridges.

🌐 Official Documentation: putervision.com • Interactive Web Docs

---

⚡ 15-Second Quick Start

# 1. Initialize reasoning database & seed default utility profiles

npx @putervision/agent-reasoning-mcp init

2. Run health diagnostics and Merkle audit checks

npx @putervision/agent-reasoning-mcp doctor

3. Inspect active goals, intentions, and belief states

npx @putervision/agent-reasoning-mcp inspect

---

🛠️ 15 Core MCP Tools

BDI Strategic Deliberation (10 Tools)

System 1 Fast Decision Layer (5 Tools)

Inspired by the typed System 1 pattern pioneered by TypeSafe's Jev (evaluating typed Choice, Score, and Noul primitives over compact state without token generation), implemented locally via in-memory LRU caches and deterministic heuristics (<2ms) without external API calls.

See [docs/benchmarks.md](docs/benchmarks.md) for full benchmark reproduction commands, latency percentiles (p50/p95/p99), and multi-tier caching architecture details.

---

🏛️ PuterVision Pentad Multi-Modal Ecosystem

agent-reasoning-mcp coordinates the closed-loop PuterVision Super-Loop:

• 🧠 `agent-reasoning-mcp`: Decides *what* to do (BDI Strategic Reasoning, Utility Theory, Replanning)
• ⚡ `behavior-mcp`: Executes *how* to act at ~60Hz in browser runtimes
• 📊 `state-memory-mcp`: Durable workflow memory, tasks, blockers, decisions
• 👁️ `vision-memory-mcp`: Perceptual caching, visual grounding, video timelines
• 🌐 `world-model-mcp`: 3D/2D spatial layout, entity permanence, collision simulation

---

📚 Deep Documentation Guides

• 📖 [Formal API Reference](docs/api-reference.md): Full parameter tables, type definitions, and tool schemas for all 15 tools.
• 🚀 [Performance Benchmarks](docs/benchmarks.md): Empirical throughput and microsecond latency metrics across all 5 System 1 tools.
• 💡 [Core Architecture & Concepts](docs/concepts.md): BDI model, utility formulation, and belief decay dynamics.
• 🖥️ [CLI Usage Guide](docs/cli-usage.md): Complete CLI command reference (init, doctor, inspect, run).
• 💾 [Database Schema](docs/database-schema.md): SQLite table structures, indexes, and Merkle audit ledger.
• ⚙️ [Configuration Reference](docs/configuration.md): .agent-reasoning-mcp.json parameters and environment variables.

---

🔗 Client Configuration & Environment

Add to .cursor/mcp.json or .vscode/mcp.json:

{

"mcpServers": { "agent-reasoning-mcp": { "command": "agent-reasoning-mcp", "args": ["run"], "env": { "PENTAD_HMAC_SECRET": "your-secure-shared-secret-here", "DISPATCH_TOKEN_TTL_MS": "30000" } } } }

Key Environment Variables

• PENTAD_HMAC_SECRET: 256-bit shared key for cryptographic intention dispatch token signing.
• DISPATCH_TOKEN_TTL_MS: Dispatch token expiration window (default: 30,000ms).
• SKIP_MODEL_LOAD: Set to 1 (or OFFLINE=1) to force air-gapped L1/L2 deterministic evaluation.

---

🧪 Testing & Benchmarks

# Run full unit and integration test suites

npm test

Run System 1 fast decision layer benchmark suite (throughput & latency percentiles)

npm run benchmark

Run air-gapped verification

OFFLINE=1 SKIP_MODEL_LOAD=1 npm test

---

📄 License

MIT © PuterVision