Strategic Agent Reasoning MCP

io.github.putervisionPublished by GitHub account putervisionv0.4.1Updated Nov 1, 2026

Strategic BDI reasoning engine for autonomous AI agents with spatial utility and replanning.

VerifiedSTDIODesktop onlyKnowledge & MemoryAI & ML

Overview

AI-generated overview

Local MCP server giving an AI agent a BDI reasoning engine: goal hierarchies, expected-utility scoring, risk assessment, replanning and fast heuristic…

What you can do
  • Manage goals and intentions: create, decompose, update or abandon goal hierarchies, and queue or cancel dispatch directives
  • Evaluate and adapt: score candidate actions from situation snapshots, assess or compare risk, and replan around blockers and events
  • Tune and explain decisions: configure utility weights, retrieve decision traces and rationale, and search learned heuristics and past situations
  • Track beliefs: update, query, expire and reconcile belief states with confidence decay
  • Run fast System 1 checks: classify states, ask typed probabilistic or choice questions, score options, and gate intentions before dispatch
  • Maintain the reasoning database: statistics, Merkle audit, snapshot and…
When to use it
Useful when you want an agent's planning to be explicit and inspectable — multi-step goals, trade-offs between options, risk checks before acting, or replanning when something blocks progress — rather than improvised in the conversation.
Requirements
Runs locally over stdio, typically via npx of the npm package; a CLI provides init, doctor and inspect commands. A local reasoning database (SQLite) is initialized first. The README's client config sets PENTAD_HMAC_SECRET and DISPATCH_TOKEN_TTL_MS; optional SKIP_MODEL_LOAD or OFFLINE force air-gapped deterministic evaluation. Desktop client only.
Before you install
The README asks for a shared HMAC secret (PENTAD_HMAC_SECRET) used to sign intention dispatch tokens; treat it as a credential and keep it out of shared configs. Tools write to a local reasoning database and can create, cancel or dispatch intentions, so state changes should be reviewed. Snapshot and restore can roll back stored reasoning data.

Installation

In SourceWeft

  1. Open Strategic Agent Reasoning MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@putervision/agent-reasoning-mcp

[npm version] [version] [CI] [Node] [License: MIT]

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 profilesnpx @putervision/agent-reasoning-mcp init
# 2. Run health diagnostics and Merkle audit checksnpx @putervision/agent-reasoning-mcp doctor
# 3. Inspect active goals, intentions, and belief statesnpx @putervision/agent-reasoning-mcp inspect

🛠️ 15 Core MCP Tools

BDI Strategic Deliberation (10 Tools)

ToolActionsPurpose
set_goalcreate, update, decompose, get, list, abandonManage goal hierarchy, task DAGs, and success criteria
evaluate_situationsnapshot, quickScore and rank candidate actions from environment snapshots
replanblocker, event, fullAdaptively reconstruct subgoals upon obstacles and abort stale intentions
assess_riskaction, plan, compareQuantitative threat and risk calculation across candidate actions
query_knowledgesearch, patterns, similar_situationsSearch learned heuristics, tactical knowledge, and past decision patterns
set_utility_weightsconfigure, get, list, activateConfigure utility weights (aggression, caution, greed, efficiency, exploration)
get_decision_tracelatest, get, list, explainExplainable chain-of-thought rationale and latency telemetry
manage_beliefsupdate, query, expire, reconcileStructured belief state with exponential confidence decay ($C = C_0 e^{-\lambda t}$)
manage_intentionscreate, dispatch, get, list, cancel, resolveWire contract directives queue for runtime execution engines
manage_reasoning_dbstats, audit, snapshot, restoreReasoning 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.

ToolPurposeLatency TargetL1 Cache (p50)Throughput
classifyLow-latency categorical labeling over multi-modal StatePacks<2ms0.0075 ms~90,000 ops/s
ask_noulTyped probabilistic hypothesis and Boolean verification ($p \in [0.0, 1.0]$)<2ms0.0049 ms~127,000 ops/s
ask_choiceDiscrete $1$-of-$N$ choice selection ($N \le 16$) with probability simplex<2ms0.0138 ms~64,000 ops/s
ask_scoreBounded numeric scalar scoring and calibrated utility rating<2ms0.0057 ms~129,000 ops/s
gate_intentionPre-dispatch blast-radius audit gate issuing signed HMAC dispatch tokens<1ms0.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.

🏛️ 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

🔗 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 suitesnpm test
# Run System 1 fast decision layer benchmark suite (throughput & latency percentiles)npm run benchmark
# Run air-gapped verificationOFFLINE=1 SKIP_MODEL_LOAD=1 npm test

📄 License

MIT © PuterVision

Source: README.md at commit cdf9b5f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

5
  1. v0.4.1LatestOct 3, 2026
  2. v0.4.0Oct 2, 2026
  3. v0.3.1Sep 29, 2026
  4. v0.3.0Sep 26, 2026
  5. v0.2.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts