agent-reasoning-mcp

# @putervision/agent-reasoning-mcp [](https://www.npmjs.com/package/@putervision/agent-reasoning-mcp) [](./CHANGELOG.md) [](https://github.com/putervision/agent-reasoning-mcp/actions/workflows/ci.yml) [](https://nodejs.org) [](https://opensource.org/licenses/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](https://putervision.com) • [Interactive Web Docs](docs/index.html) --- ## ⚡ 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](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`: ```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 ``` --- ## 📄 License MIT © PuterVision