Skip to main content
Glama
agent-reasoning-mcp

agent-reasoning-mcp

by putervision

@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

# 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

Related MCP server: Summon-MCP

πŸ› οΈ 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.


πŸ›οΈ 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:

{
  "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

Available Tools

15 tools
ask_choiceA
Read-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_noulA
Read-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_scoreA
Read-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_riskA
Read-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.

classifyA
Read-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_intentionA
Read-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_traceA
Read-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_beliefsA
Destructive

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_dbA
Destructive

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_knowledgeA
Read-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

    A4.1/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Objective-driven cognitive architecture engine that builds single experts, councils, or full autonomous organizations from user goals, generating deployment-ready superprompts and configurations.
      6 npm
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Goal-oriented narrative state machine for AI agents, exposing live world/scene context as MCP tools and resources.
      -