PuterVision
Strategic BDI Reasoning & Decision Intelligence
Hierarchical goal decomposition, multi-attribute expected utility theory (\(E[U] = \sum w_i u_i\)), exponential belief decay, and reactive replanning for autonomous AI agents.
*Functional agency and closed-loop automation — not consciousness, sentience, or AGI.*
⚡ Interactive Utility Weight Simulator
Adjust the agent's utility scoring profile sliders to observe real-time dynamic action ranking and risk assessment.
Ranked Candidate Actions
🛠️ Consolidated MCP Tools (15 Tools)
Complete cognitive toolkit: 10 strategic BDI deliberation tools paired with 5 ultra-low-latency System 1 fast decision primitives (inspired by TypeSafe's Jev pattern).
🏛️ BDI Strategic Deliberation (Tools 1–10)
set_goal
Manage hierarchical objectives, decompose into sub-goals, and propagate progress across DAGs.
evaluate_situation
Score environment snapshots against active utility weights and recommend top candidate actions.
replan
Adaptively regenerate goal DAGs and abort invalidated intentions upon unexpected obstacles.
assess_risk
Quantitative failure severity, reversibility, and blast-radius risk calculation for actions.
query_knowledge
Search learned heuristics, domain tactics, and historical decision outcomes.
set_utility_weights
Configure multi-attribute utility profiles (aggression, caution, greed, exploration, efficiency, cooperation).
get_decision_trace
Explainable chain-of-thought rationale playback, scoring breakdowns, and execution latency stats.
manage_beliefs
Maintain structured beliefs with exponential confidence decay and automated TTL cleanup sweeps.
manage_intentions
Queue, dispatch, prioritize, and track executable behavior directives for runtime engines.
manage_reasoning_db
Database maintenance, diagnostics, point-in-time snapshots, and SHA-256 Merkle audit verification.
⚡ System 1 Fast Decision Layer (Tools 11–15, <2ms SLA)
classify
< 2ms SLA
Deterministic categorical semantic labeling over StatePacks. p50: 7.5 µs (~90,000 ops/s).
ask_noul
< 2ms SLA
Typed probabilistic Boolean verification (p ∈ [0, 1]). p50: 4.9 µs (~127,000 ops/s).
ask_choice
< 2ms SLA
Discrete 1-of-N choice selection with probability simplex (N ≤ 16). p50: 13.8 µs (~64,000 ops/s).
ask_score
< 2ms SLA
Bounded numeric continuous utility scoring. p50: 5.7 µs (~129,000 ops/s).
gate_intention
< 1ms SLA
Blast-radius audit gate issuing signed HMAC dispatch tokens. p50: 70.9 µs (~12,000 ops/s).
🚀 Performance & Throughput Benchmarks
Empirical decision latency metrics measured across 1,000 iterations on Node.js v22 (x86_64 Linux).
| System 1 Tool | Spec SLA | Cold Eval (Mean) | L1 Cache (p50) | L1 Cache (p95) | Throughput | Status |
|---|---|---|---|---|---|---|
ask_noul |
< 2.0 ms | 0.0436 ms | 0.0049 ms (4.9 µs) | 0.0114 ms | 127,272 ops/s | ✅ PASSED |
classify |
< 2.0 ms | 0.0586 ms | 0.0075 ms (7.5 µs) | 0.0165 ms | 90,333 ops/s | ✅ PASSED |
ask_choice |
< 2.0 ms | 0.0627 ms | 0.0138 ms (13.8 µs) | 0.0314 ms | 63,829 ops/s | ✅ PASSED |
ask_score |
< 2.0 ms | 0.0393 ms | 0.0057 ms (5.7 µs) | 0.0099 ms | 129,296 ops/s | ✅ PASSED |
gate_intention |
< 1.0 ms | 0.1106 ms | 0.0709 ms (70.9 µs) | 0.1185 ms | 12,392 ops/s | ✅ PASSED |
🏛️ BDI Cognitive Architecture
A mathematically rigorous, explainable BDI (Belief-Desire-Intention) loop designed to bridge sensory perception and high-frequency execution.
📡 1. Belief Maintenance
Structured belief state where every fact carries confidence that decays exponentially over time: B(t) = B₀ · e^(-λt). Perceptions refresh confidence; stale assumptions are culled automatically via TTL sweeps.
🎯 2. Hierarchical Goal DAGs
Complex objectives decompose into directed acyclic graphs of sub-goals. Progress dynamically rolls up from leaves to roots, preventing duplicated effort and circular dependencies.
⚖️ 3. Expected Utility Theory
Candidate actions are ranked using multi-attribute expected utility: E[U] = ∑ wᵢ · uᵢ across calibrated weights (Aggression, Caution, Greed, Exploration, Efficiency, and Cooperation).
🛡️ 4. Quantitative Risk Assessment
Every proposal undergoes risk evaluation measuring failure probability, reversibility penalty, and worst-case blast radius before selection, preventing catastrophic actions.
⚡ 5. Intention Dispatch Queue
Selected top actions become firm intentions dispatched via wire contract to runtime behavior engines (such as behavior-mcp) with priority preemption and execution timeouts.
🔄 6. Reactive Replanning & Audit
When environmental blockers invalidate assumptions, the replanner recalculates alternative paths, culls unviable intentions, and logs decisions to a tamper-evident SHA-256 Merkle audit trail.
🚀 Quickstart & Client Integration
Add agent-reasoning-mcp to your AI coding assistant with zero external dependencies.
1. Global Installation
Install globally via npm for CLI and server usage:
2. Client Configurations
Claude Code CLI
Cursor IDE (.cursor/mcp.json)
Gemini CLI
3. Health & Database Verification
Verify installation and audit SQLite database health: