turing-pyramidDecision framework for agent psychological health. 10 needs with decay, tension-based priority, cross-need cascades. Outputs action SUGGESTIONS β agent decid...
Install via ClawdBot CLI:
clawdbot install TensusDS/turing-pyramid10-need psychological hierarchy for AI agents. Run on heartbeat β get prioritized actions.
Customization: Tune decay rates, weights, patterns. Defaults are starting points. See TUNING.md.
Ask your human before: Changing importance values, adding/removing needs, enabling external actions.
System binaries (must be in PATH):
bash, jq, grep, find, date, wc, bcEnvironment (REQUIRED β no fallback):
# Scripts will ERROR if WORKSPACE is not set
export WORKSPACE="/path/to/your/workspace"β οΈ No silent fallback. If WORKSPACE is unset, scripts exit with error.
This prevents accidental scanning of unintended directories.
./scripts/init.sh # First time
./scripts/run-cycle.sh # Every heartbeat
./scripts/mark-satisfied.sh <need> [impact] # After actionβββββββββββββββββ¬ββββββ¬ββββββββ¬ββββββββββββββββββββββββββββββββββ
β Need β Imp β Decay β Meaning β
βββββββββββββββββΌββββββΌββββββββΌββββββββββββββββββββββββββββββββββ€
β security β 10 β 168h β System stability, no threats β
β integrity β 9 β 72h β Alignment with SOUL.md β
β coherence β 8 β 24h β Memory consistency β
β closure β 7 β 12h β Open threads resolved β
β autonomy β 6 β 24h β Self-directed action β
β connection β 5 β 6h β Social interaction β
β competence β 4 β 48h β Skill use, effectiveness β
β understanding β 3 β 12h β Learning, curiosity β
β recognition β 2 β 72h β Feedback received β
β expression β 1 β 8h β Creative output β
βββββββββββββββββ΄ββββββ΄ββββββββ΄ββββββββββββββββββββββββββββββββββSatisfaction: 0.0β3.0 (floor=0.5 prevents paralysis)
Tension: importance Γ (3 - satisfaction)
βββββββββ¬βββββββββ¬βββββββββββββββββββββββ
β Sat β Base P β Note β
βββββββββΌβββββββββΌβββββββββββββββββββββββ€
β 3 β 5% β Maintenance mode β
β 2 β 20% β Routine checks β
β 1 β 75% β Needs attention β
β 0 β 100% β Critical β always β
βββββββββ΄βββββββββ΄βββββββββββββββββββββββTension bonus: bonus = (tension Γ 50) / max_tension
βββββββββββ¬ββββββββ¬βββββββββ¬ββββββββ
β Sat β Small β Medium β Big β
βββββββββββΌββββββββΌβββββββββΌββββββββ€
β 0 crit β 5% β 15% β 80% β
β 1 low β 15% β 50% β 35% β
β 2 ok β 70% β 25% β 5% β
βββββββββββ΄ββββββββ΄βββββββββ΄ββββββββACTION = do it, then mark-satisfied.sh
NOTICED = logged, deferred
βββββββββββββββ¬ββββββββ¬βββββββββββββββββββββββββββββββββββββββββ
β Mechanism β Value β Purpose β
βββββββββββββββΌββββββββΌβββββββββββββββββββββββββββββββββββββββββ€
β Floor β 0.5 β Minimum sat β prevents collapse β
β Ceiling β 3.0 β Maximum sat β prevents runaway β
β Cooldown β 4h β Deprivation cascades once per 4h β
β Threshold β 1.0 β Deprivation only when sat β€ 1.0 β
βββββββββββββββ΄ββββββββ΄βββββββββββββββββββββββββββββββββββββββββBase Needs Isolation: Security (10) and Integrity (9) are protected:
integrity β security (+0.15) and autonomy β integrity (+0.20) existon_action: Completing A boosts connected needs
on_deprivation: A staying low (sat β€ 1.0) drags others down
βββββββββββββββββββββββββββ¬βββββββββββ¬ββββββββββββββ¬ββββββββββββββββββββββββ
β Source β Target β on_actionβ on_deprived β Why β
βββββββββββββββββββββββββββΌβββββββββββΌββββββββββββββΌββββββββββββββββββββββββ€
β expression β recognitionβ +0.25 β -0.10 β Express β noticed β
β connection β expression β +0.20 β -0.15 β Social sparks ideas β
β connection β understand β -0.05 β β β Socratic effect β
β competence β recognitionβ +0.30 β -0.20 β Good work β respect β
β autonomy β integrity β +0.20 β -0.25 β Act on values β
β closure β coherence β +0.20 β -0.15 β Threads β order β
β security β autonomy β +0.10 β -0.20 β Safety enables risk β
βββββββββββββββββββββββββββ΄βββββββββββ΄ββββββββββββββ΄ββββββββββββββββββββββββFull matrix: assets/cross-need-impact.json
πΊ Turing Pyramid β Cycle at Tue Feb 25 05:36
======================================
β οΈ Deprivation cascades:
autonomy (sat=0.5) β integrity: -0.25 (now: 1.75)
autonomy (sat=0.5) β expression: -0.20 (now: 0.80)
Current tensions:
closure: tension=21 (sat=0, dep=3)
connection: tension=15 (sat=0, dep=3)
π Decisions:
βΆ ACTION: closure (tension=21, sat=0.00)
β coherence: +0.20, competence: +0.15, autonomy: +0.10
βΆ ACTION: connection (tension=15, sat=0.00)
β expression: +0.20, recognition: +0.15
β understanding: -0.05 (Socratic effect)Add to HEARTBEAT.md:
/path/to/skills/turing-pyramid/scripts/run-cycle.shDecay rates β assets/needs-config.json:
"connection": { "decay_rate_hours": 4 }Lower = decays faster. Higher = persists longer.
Action weights β same file:
{ "name": "reply to mentions", "impact": 2, "weight": 40 }Higher weight = more likely selected. Set 0 to disable.
Scan patterns β scripts/scan_*.sh:
Add your language patterns, file paths, workspace structure.
turing-pyramid/
βββ SKILL.md # This file
βββ CHANGELOG.md # Version history
βββ assets/
β βββ needs-config.json # β
Main config (tune this!)
β βββ cross-need-impact.json # β
Cross-need matrix
β βββ needs-state.json # Runtime state (auto)
βββ scripts/
β βββ run-cycle.sh # Main loop
β βββ mark-satisfied.sh # State + cascades
β βββ apply-deprivation.sh # Deprivation cascade
β βββ scan_*.sh # Event detectors (10)
βββ references/
βββ TUNING.md # Detailed tuning guide
βββ architecture.md # Technical docsDecision framework, not executor. Outputs suggestions β agent decides.
βββββββββββββββββββββββ βββββββββββββββββββββββ
β TURING PYRAMID β β AGENT β
βββββββββββββββββββββββ€ βββββββββββββββββββββββ€
β β’ Reads local JSON β β β’ Has web_search β
β β’ Calculates decay β ββββΆ β β’ Has API keys β
β β’ Outputs: "β
do X" β β β’ Has permissions β
β β’ Zero network I/O β β β’ DECIDES & EXECUTESβ
βββββββββββββββββββββββ βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β THIS SKILL READS WORKSPACE FILES THAT MAY CONTAIN PII β
β AND OUTPUTS ACTION SUGGESTIONS THAT CAPABLE AGENTS MAY β
β AUTO-EXECUTE USING THEIR OWN CREDENTIALS. β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ1. Sensitive file access (no tokens required):
MEMORY.md, memory/*.md, SOUL.md, AGENTS.mdresearch/, scratchpad/ directoriesscripts/scan_*.sh to exclude sensitive paths:
# Example: skip private directory
find "$MEMORY_DIR" -name "*.md" ! -path "*/private/*"2. Action suggestions may trigger auto-execution:
assets/needs-config.json, remove or disable external actions:
{"name": "post to Moltbook", "impact": 2, "weight": 0}Or configure your agent runtime to require approval for external actions.
3. Self-reported state (no verification):
mark-satisfied.sh trusts caller inputmemory/ to audit completions:
# run-cycle.sh already logs to memory/YYYY-MM-DD.md
# Review logs periodically for consistency*scan_.sh files verified β NO network or system access:**
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β curl, wget, ssh, nc, fetch β NOT FOUND β
β β /etc/, /var/, /usr/, /root/ β NOT FOUND β
β β .env, .pem, .key, .credentials β NOT FOUND β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β Used: grep, find, wc, date, jq β local file ops only β
β β find uses -P flag (never follows symlinks) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββSymlink protection: All find commands use -P (physical) mode β symlinks pointing outside WORKSPACE are not followed.
Scan confinement: Scripts only read paths under $WORKSPACE. Verify with:
grep -nE "\b(curl|wget|ssh)\b" scripts/scan_*.sh # network tools
grep -rn "readlink\|realpath" scripts/ # symlink resolutionββββββββββββββββ¬ββββββββββββββ¬βββββββββββββ
β Interval β Tokens/mo β Est. cost β
ββββββββββββββββΌββββββββββββββΌβββββββββββββ€
β 30 min β 1.4M-3.6M β $2-6 β
β 1 hour β 720k-1.8M β $1-3 β
β 2 hours β 360k-900k β $0.5-1.5 β
ββββββββββββββββ΄ββββββββββββββ΄βββββββββββββStable agent with satisfied needs = fewer tokens.
v1.10.1 β Bug fixes, cleaned docs. Full changelog: CHANGELOG.md
Generated Feb 26, 2026
An AI agent handling customer inquiries uses the Turing Pyramid to prioritize responses based on urgency and satisfaction levels, ensuring critical issues like security threats are addressed first while maintaining coherence in conversation threads.
A personal AI assistant manages daily tasks by balancing needs like closure for completed items and autonomy for self-directed actions, preventing burnout through decay rates and cross-need impacts.
An AI tutor adapts learning sessions using the hierarchy to focus on competence and understanding needs, leveraging the Socratic effect from social interactions to enhance curiosity and skill development.
A content-generation AI uses the pyramid to prioritize creative expression and recognition needs, optimizing output based on tension bonuses and impact selection to maintain engagement and quality.
An AI in healthcare monitors patient data, prioritizing security and integrity needs to ensure system stability and alignment with protocols, while managing coherence for consistent health records.
Offer the Turing Pyramid as a cloud-based service for AI developers, with tiered pricing based on customization features like decay rate tuning and cross-need impact matrices, generating recurring revenue.
Sell licenses to large organizations for integrating the skill into proprietary AI systems, with support and training packages for tuning needs like security and autonomy in complex workflows.
Provide a free version with default settings for individual users or small projects, while charging for advanced features such as external action enablement and detailed analytics on need satisfaction.
π¬ Integration Tip
Set the WORKSPACE environment variable carefully to avoid errors, and regularly run mark-satisfied.sh after actions to update need satisfaction levels accurately.
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Search and analyze your own session logs (older/parent conversations) using jq.
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.
Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vibe-coding ready.
Headless browser automation CLI optimized for AI agents with accessibility tree snapshots and ref-based element selection