@putervision/agent-reasoning-mcp

Name: Strategic Agent Reasoning MCP
Author: putervision

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

bash

# 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)

Tool	Actions	Purpose
`set_goal`	`create`, `update`, `decompose`, `get`, `list`, `abandon`	Manage goal hierarchy, task DAGs, and success criteria
`evaluate_situation`	`snapshot`, `quick`	Score and rank candidate actions from environment snapshots
`replan`	`blocker`, `event`, `full`	Adaptively reconstruct subgoals upon obstacles and abort stale intentions
`assess_risk`	`action`, `plan`, `compare`	Quantitative threat and risk calculation across candidate actions
`query_knowledge`	`search`, `patterns`, `similar_situations`	Search learned heuristics, tactical knowledge, and past decision patterns
`set_utility_weights`	`configure`, `get`, `list`, `activate`	Configure utility weights (aggression, caution, greed, efficiency, exploration)
`get_decision_trace`	`latest`, `get`, `list`, `explain`	Explainable chain-of-thought rationale and latency telemetry
`manage_beliefs`	`update`, `query`, `expire`, `reconcile`	Structured belief state with exponential confidence decay ($C = C_0 e^{-\lambda t}$)
`manage_intentions`	`create`, `dispatch`, `get`, `list`, `cancel`, `resolve`	Wire contract directives queue for runtime execution engines
`manage_reasoning_db`	`stats`, `audit`, `snapshot`, `restore`	Reasoning database statistics, SHA-256 Merkle audit, and snapshot rollback

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.

Tool	Purpose	Latency Target	L1 Cache (p50)	Throughput
`classify`	Low-latency categorical labeling over multi-modal StatePacks	`<2ms`	`0.0075 ms`	~90,000 ops/s
`ask_noul`	Typed probabilistic hypothesis and Boolean verification ($p \in [0.0, 1.0]$)	`<2ms`	`0.0049 ms`	~127,000 ops/s
`ask_choice`	Discrete $1$-of-$N$ choice selection ($N \le 16$) with probability simplex	`<2ms`	`0.0138 ms`	~64,000 ops/s
`ask_score`	Bounded numeric scalar scoring and calibrated utility rating	`<2ms`	`0.0057 ms`	~129,000 ops/s
`gate_intention`	Pre-dispatch blast-radius audit gate issuing signed HMAC dispatch tokens	`<1ms`	`0.0709 ms`	~12,000 ops/s

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

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: Full parameter tables, type definitions, and tool schemas for all 15 tools.
🚀 Performance Benchmarks: Empirical throughput and microsecond latency metrics across all 5 System 1 tools.
💡 Core Architecture & Concepts: BDI model, utility formulation, and belief decay dynamics.
🖥️ CLI Usage Guide: Complete CLI command reference (init, doctor, inspect, run).
💾 Database Schema: SQLite table structures, indexes, and Merkle audit ledger.
⚙️ Configuration Reference: .agent-reasoning-mcp.json parameters and environment variables.

🔗 Client Configuration & Environment

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

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

bash

# 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