agent-reasoning-mcp
This MCP server provides formal BDI strategic reasoning, multi-attribute expected utility decision-making, risk assessment, and fast System 1 primitives for autonomous agents.
Manage hierarchical goals, task DAGs, subgoals, progress, priorities, deadlines, and success criteria.
Evaluate multi-modal situations, rank candidate actions by expected utility, and recommend best actions.
Replan adaptively on blockers, events, or full replans, preserving completed subgoals where possible.
Assess quantitative risk for actions, plans, comparisons, and spatial rollouts.
Query learned heuristics, tactics, anti-patterns, and similar past situations.
Configure, inspect, activate, and nudge utility weight profiles such as aggression, caution, greed, efficiency, and exploration.
Retrieve explainable decision traces with rationale, utility breakdowns, and candidate rankings.
Manage structured beliefs with confidence, provenance, categories, TTL expiration, exponential decay, and spatial reconciliation.
Queue, dispatch, track, cancel, and resolve runtime behavior intentions for behavior-mcp execution.
Maintain the reasoning SQLite DB with stats, Merkle audits, diagnostics, snapshots, diffs, and restores.
Use System 1 fast decision tools: classify labels, ask_noul for boolean/probabilistic propositions, ask_choice for discrete choices, ask_score for continuous scoring, and gate_intention for HMAC-signed dispatch authorization.
@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 inspectRelated MCP server: Summon-MCP
π οΈ 15 Core MCP Tools
BDI Strategic Deliberation (10 Tools)
Tool | Actions | Purpose |
|
| Manage goal hierarchy, task DAGs, and success criteria |
|
| Score and rank candidate actions from environment snapshots |
|
| Adaptively reconstruct subgoals upon obstacles and abort stale intentions |
|
| Quantitative threat and risk calculation across candidate actions |
|
| Search learned heuristics, tactical knowledge, and past decision patterns |
|
| Configure utility weights (aggression, caution, greed, efficiency, exploration) |
|
| Explainable chain-of-thought rationale and latency telemetry |
|
| Structured belief state with exponential confidence decay ($C = C_0 e^{-\lambda t}$) |
|
| Wire contract directives queue for runtime execution engines |
|
| 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, andNoulprimitives 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 |
| Low-latency categorical labeling over multi-modal StatePacks |
|
| ~90,000 ops/s |
| Typed probabilistic hypothesis and Boolean verification ($p \in [0.0, 1.0]$) |
|
| ~127,000 ops/s |
| Discrete $1$-of-$N$ choice selection ($N \le 16$) with probability simplex |
|
| ~64,000 ops/s |
| Bounded numeric scalar scoring and calibrated utility rating |
|
| ~129,000 ops/s |
| Pre-dispatch blast-radius audit gate issuing signed HMAC dispatch tokens |
|
| ~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
π 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.jsonparameters 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 to1(orOFFLINE=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
Available Tools
15 toolsask_choiceARead-onlyIdempotent
Select 1 option from a discrete set of alternatives (N <= 16) with probability distribution and utility margin. Use ask_choice instead of classify when choosing the best action or alternative under active utility profiles rather than categorizing an entity.
Returns selected option ID, probability distribution, and utility margin.
Inputs: options (required), project (required), question (required), state_pack, +1 more.
ask_noulARead-onlyIdempotent
Evaluate whether a specific proposition is true given the current state pack with calibrated probability and abstain safeguards. Use ask_noul instead of ask_score when evaluating binary truth/falsehood rather than scoring an entity on a continuous scale.
Returns boolean answer, confidence probability, and abstain flag.
Inputs: project (required), statement (required), prior, state_pack.
ask_scoreARead-onlyIdempotent
Evaluate an entity, plan, or action on a bounded continuous scale against weighted criteria. Use ask_score instead of ask_noul when evaluating continuous numeric quality or fitness rather than binary truth.
Returns normalized score within scale bounds, criterion breakdown, and evaluation confidence.
Inputs: metric (required), target (required), project (required), scale, +2 more.
assess_riskARead-onlyIdempotent
Compute quantitative risk and threat assessment for candidate actions, plans, or 3D spatial rollouts against active utility weights (actions: action, plan, compare, spatial_rollout). Use assess_risk instead of evaluate_situation when estimating failure probability and threat exposure rather than ranking overall utility.
Returns risk score (0.0-1.0), threat breakdown, and comparative risk ratings.
Inputs: action (required), project, obstacles, parameters, +5 more.
classifyARead-onlyIdempotent
Assign semantic categorical labels to an entity, visual state, task, or state snapshot using deterministic System One calculus. Use classify instead of ask_choice when assigning predefined taxonomy labels rather than selecting among runtime decision alternatives.
Returns top class label, probability distribution, and classification margin.
Inputs: classes (required), project (required), target_type (required), target_id, +1 more.
evaluate_situationA
Ingest multi-modal situation snapshot, compute expected utilities against active weights, and output prioritized action recommendations (actions: snapshot, quick). Use evaluate_situation instead of assess_risk when ranking candidate actions across multi-attribute utility dimensions rather than calculating isolated threat probabilities.
Returns ranked candidate actions, expected utility scores, and top recommendation.
Inputs: action (required), project, snapshot, trace_id, +5 more.
gate_intentionARead-onlyIdempotent
Evaluate an intention before dispatching to behavior-mcp and issue a cryptographic HMAC dispatch token if approved. Use gate_intention instead of manage_intentions when verifying precondition safety and issuing execution authorization rather than tracking intention state.
Returns gate verdict (approved/rejected), risk evaluation, and HMAC dispatch token.
Inputs: project (required), proposed_action (required), state_pack, intention_id, +1 more.
get_decision_traceARead-onlyIdempotent
Retrieve explainable step-by-step chain-of-thought rationale, candidate utilities, and risk assessment for past decisions (actions: latest, get, list, explain). Use get_decision_trace instead of query_knowledge when performing deep forensic analysis of a specific historical decision.
Returns step-by-step reasoning trace, utility breakdown, candidate rankings, and explanation text.
Inputs: action (required), limit, goal_id, project, +1 more.
manage_beliefsADestructive
Maintain structured belief state with TTL expiration sweeps, exponential confidence decay, and category filtering (actions: update, query, expire, reconcile, reconcile_spatial). Use manage_beliefs instead of query_knowledge when managing dynamic agent epistemic state rather than static heuristic patterns.
Returns belief record, query matches, expired belief count, or reconciliation report.
Inputs: action (required), object, source, project, +12 more.
manage_intentionsA
Queue, dispatch, track, cancel, or resolve behavior directives for behavior-mcp runtime execution (actions: create, dispatch, get, list, cancel, resolve). Use manage_intentions instead of set_goal when dispatching immediate execution instructions to runtime behaviors rather than managing abstract objectives.
Returns intention record, dispatch status, wire contract payload, or intention list.
Inputs: action (required), result, status, goal_id, +9 more.
manage_reasoning_dbADestructive
Database maintenance, diagnostics, SHA-256 Merkle audit verification, and snapshot management (actions: stats, audit, doctor, snapshot, diff, restore). Use manage_reasoning_db instead of manage_beliefs when performing SQLite storage integrity verification or database snapshot restore.
Returns database diagnostics, Merkle audit tree, snapshot metadata, or diff reports.
Inputs: action (required), name, project, description.
query_knowledgeARead-onlyIdempotent
Search learned heuristic patterns, tactics, and past decision traces by context similarity (actions: search, patterns, similar_situations). Use query_knowledge instead of get_decision_trace when retrieving generalized patterns across sessions rather than inspecting a single execution trace.
Returns matching heuristics, anti-patterns, tactics, and similarity scores.
Inputs: action (required), limit, query, project, +2 more.
replanA
Regenerate sub-task DAG and adjust intentions upon unexpected obstacles or state changes (actions: blocker, event, full). Use replan instead of set_goal when recovering from execution blockers or environment shifts rather than creating new goals.
Returns replanned goal DAG, invalidated intentions, and newly synthesized subgoals.
Inputs: action (required), goal_id (required), project, trigger_event, +2 more.
set_goalA
Register, update, decompose, inspect, or abandon hierarchical goals and task DAGs (actions: create, update, decompose, get, list, abandon). Use set_goal instead of manage_intentions when formulating multi-step objectives and sub-goal DAGs rather than queueing concrete execution directives.
Returns goal record, sub-goal hierarchy, completion progress, or goal lists.
Inputs: action (required), id, limit, title, +11 more.
set_utility_weightsA
Configure, inspect, activate, or incrementally nudge multi-attribute utility weight profiles (actions: configure, get, list, activate, nudge). Use set_utility_weights instead of evaluate_situation when defining decision preferences (aggression, caution, greed, exploration) rather than evaluating actions.
Returns configured utility profile, active weight map, or profile directory.
Inputs: action (required), name, delta, project, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 15 tools
Most tools target distinct concepts, and the descriptions actively disambiguate with explicit 'use X instead of Y' guidance (e.g. assess_risk vs evaluate_situation, set_goal vs manage_intentions). However there is a dense cluster of risk/utility evaluation tools (assess_risk, evaluate_situation, ask_score, gate_intention) that an agent could still misselect among.
The set consistently uses snake_case verb_noun patterns (manage_beliefs, query_knowledge, get_decision_trace, set_utility_weights), with coherent families like ask_* and manage_*. Minor deviations are bare verbs (replan, classify) and an unusual token (ask_noul), but overall the convention is predictable.
15 tools sit at the upper edge of the comfortable 3-15 range but are justified by a genuinely broad cognitive-architecture domain (risk, beliefs, goals, intentions, knowledge, DB ops). It is slightly heavy but each tool maps to a real capability rather than being filler.
Coverage is strong: beliefs (update/query/expire/reconcile), goals (create/update/decompose/get/list/abandon), intentions (create/dispatch/get/list/cancel/resolve) and traces/knowledge all form coherent lifecycles. Gaps are minorβno obvious delete or bulk-export for some resourcesβbut core reasoning workflows are well covered.
Maintenance
Related MCP Connectors
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Human-agent interface for projects: you prioritize and decide, your AI agents execute. Over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceCampaign orchestration MCP server for AI agents β dependency DAGs, parallel fan-out, failure policies, and embedded notes.21GPL 3.0
- AlicenseNot gradedqualityDmaintenanceObjective-driven cognitive architecture engine that builds single experts, councils, or full autonomous organizations from user goals, generating deployment-ready superprompts and configurations.6 npmMIT
- -licenseNot gradedqualityNot gradedmaintenanceGoal-oriented narrative state machine for AI agents, exposing live world/scene context as MCP tools and resources.-
- FlicenseAqualityCmaintenanceEnables AI agents to hand high-level objectives to a decision-making core that autonomously reasons, plans, enforces deterministic policy, executes capabilities, evaluates outcomes, and persists semantic memory over stdio or Streamable HTTP.6-