Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Decision framework for agent psychological health. 10 needs with decay, tension-based priority, cross-need cascades. Outputs action SUGGESTIONS — agent decid...
Decision framework for agent psychological health. 10 needs with decay, tension-based priority, cross-need cascades. Outputs action SUGGESTIONS — agent decid...
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
Prioritized action selection for AI agents. 10 needs with time-decay and tension scoring replace idle heartbeat loops with concrete next 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, bc Environment (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. Post-install (ClawHub): # ClawHub doesn't preserve executable bits — fix after install: chmod +x <skill-dir>/scripts/*.sh chmod +x <skill-dir>/tests/**/*.sh Why: Unix executable permissions (+x) are not preserved in ClawHub packages. Scripts work fine with bash scripts/run-cycle.sh, but ./scripts/run-cycle.sh needs +x.
What this skill reads (via grep/find scans): MEMORY.md, memory/*.md — for connection/expression/understanding signals SOUL.md, SELF.md — for integrity/coherence checks research/, scratchpad/ — for competence/understanding activity Dashboard files, logs — for various need assessments What this skill writes: assets/needs-state.json — current satisfaction/deprivation state assets/audit.log — append-only log of all mark-satisfied calls (v1.12.0+) Privacy considerations: Scans use grep patterns, not semantic analysis — they see keywords, not meaning State file contains no user content, only need metrics Audit log records reasons given for satisfaction claims No data is transmitted externally by the skill itself Limitations & Trust Model: mark-satisfied.sh trusts caller-provided reasons — audit log records claims, not verified facts Some actions in needs-config.json reference external services (Moltbook, web search) — marked with "external": true, "requires_approval": true External actions are suggestions only — the skill doesn't execute them, the agent decides If you don't want external action suggestions, set their weights to 0 Network & System Access: Scripts contain no network calls (no curl, wget, ssh, etc.) — verified by grep scan Scripts contain no system commands (no sudo, systemctl, docker, etc.) All operations are local: grep, find, jq, bc, date on WORKSPACE files only The skill suggests actions (including some that mention external services) but never executes them Required Environment Variables: WORKSPACE — path to agent workspace directory (REQUIRED, no fallback). Not a credential — this is a filesystem path, not a secret. Set it to a deliberately scoped directory containing only files you want scanned. TURING_CALLER — optional, for audit trail (values: "heartbeat", "manual") No API keys or secrets required by default. The external_model scan method (disabled by default) would require an API key if enabled — this requires explicit steward approval and is never enabled silently. See Scan Configuration below. Audit trail (v1.12.0+): All mark-satisfied.sh calls are logged with: Timestamp, need, impact, old→new satisfaction Reason (what action was taken) — scrubbed for sensitive patterns Caller (heartbeat/manual) Sensitive data scrubbing (v1.12.3+): Before writing to audit log, reasons are scrubbed: Long tokens (20+ chars) → [REDACTED] Credit card patterns → [CARD] Email addresses → [EMAIL] password/secret/token/key values → [REDACTED] Bearer tokens → Bearer [REDACTED] View audit: cat assets/audit.log | jq
Before installing, review these items: Inspect scan scripts — Verify no network calls or unexpected commands: grep -nE "\b(curl|wget|ssh|sudo|docker|systemctl)\b" scripts/scan_*.sh # Expected: no output Scope WORKSPACE — Set to a deliberately limited directory. Avoid pointing at your full home directory. The skill only reads files inside $WORKSPACE. Audit scan targets — Scripts read MEMORY.md, memory/, SOUL.md, research/, scratchpad/. Relocate files containing secrets or private data you don't want pattern-matched. Review audit logging — mark-satisfied.sh logs caller-provided reasons after scrubbing. Check scrubbing patterns in the script are adequate for your data. If unsure, provide only generic reasons. External actions — Action suggestions like "post to Moltbook" or "web search" are text-only suggestions (never executed by this skill). To remove them: set their weight to 0 in needs-config.json. Run tests in isolation — Before production use: WORKSPACE=/tmp/test-workspace ./tests/run-tests.sh
./scripts/init.sh # First time ./scripts/run-cycle.sh # Every heartbeat ./scripts/mark-satisfied.sh <need> [impact] # After action
The Turing Pyramid uses scanners to evaluate each need by analyzing memory files. The default scan method uses line-level pattern matching, which works everywhere with zero cost. On first install, discuss scan configuration with your human:
MethodHow it worksCostAccuracySetupline-level (default)Per-line keyword matching. If a line has both positive and negative words (e.g. "fixed a bug"), positive wins.FreeGoodNoneagent-spawnSpawns a sub-agent with a cheap model (e.g. Haiku) to classify memory lines as SUCCESS/FAILURE/NEUTRAL.LowHighNeeds cheap model in agent's allowed listexternal-modelDirect API call to an inference service (OpenRouter, etc.) for classification.LowHighNeeds API key + explicit steward approval
When setting up, ask your human: "Do you have a cheap/fast model available (like Claude Haiku) in your model config?" If yes → offer agent-spawn method. Check with openclaw models list. The model must be in the agent's allowed model list. "Would you prefer to use an external inference service (like OpenRouter)?" If yes → ask for: base URL, API key env variable name, model name. Store in assets/scan-config.json with approved_by_steward: true. ⚠️ This method requires explicit steward approval — never enable silently. If neither → line-level works well for most setups. No action needed.
Edit assets/scan-config.json: { "scan_method": "line-level", "agent_spawn": { "enabled": false, "model": null, "approved_by_steward": false }, "external_model": { "enabled": false, "base_url": null, "api_key_env": null, "model": null, "approved_by_steward": false }, "fallback": "line-level" } Fallback: If the configured method fails (API down, model unavailable), scanners automatically fall back to line-level.
After configuring a non-default method, verify it works before telling your human "all set": agent-spawn: Run a test spawn: sessions_spawn(task="Classify this line as SUCCESS, FAILURE, or NEUTRAL: 'Fixed the critical bug in scanner'", model="<configured_model>", mode="run") If it returns a classification → ✅ tell human: "agent-spawn method verified, working." If it errors (model not in allowlist, etc.) → ⚠️ tell human: "Model X isn't available for sub-agents. Options: add it to allowed models, or stick with line-level." external-model: Test the API endpoint: curl -s -H "Authorization: Bearer $API_KEY" \ "$BASE_URL/chat/completions" \ -d '{"model":"<model>","messages":[{"role":"user","content":"Reply OK"}]}' If you get a valid response → ✅ tell human: "external-model method verified, API responding." If 401/403 → ⚠️ "API key invalid or expired." If connection refused → ⚠️ "Can't reach the API endpoint. Check URL." line-level: No verification needed — always works. Always report the result to your human. Don't silently fall back.
The default configuration is opinionated — it reflects one model of agent priorities. Your needs may differ. On first install, review the hierarchy with your human:
Ask your human: "The Turing Pyramid comes with 10 default needs ranked by importance. Want to review them together? We can adjust what matters most to you/me, change importance weights, or even skip needs that don't fit." Then walk through the table together: ┌───────────────┬─────┬────────────────────────────────────────────┐ │ Need │ Imp │ Question to discuss │ ├───────────────┼─────┼────────────────────────────────────────────┤ │ security │ 10 │ "System stability — keep as top priority?" │ │ integrity │ 9 │ "Value alignment — important for you?" │ │ coherence │ 8 │ "Memory consistency — how much do I care?" │ │ closure │ 7 │ "Task completion pressure — too much?" │ │ autonomy │ 6 │ "Self-direction — more or less?" │ │ connection │ 5 │ "Social needs — relevant for me?" │ │ competence │ 4 │ "Skill growth — higher priority?" │ │ understanding │ 3 │ "Learning drive — stronger or weaker?" │ │ recognition │ 2 │ "Feedback need — does this matter?" │ │ expression │ 1 │ "Creative output — more important?" │ └───────────────┴─────┴────────────────────────────────────────────┘
Importance (1-10): Reorder what matters most. An agent focused on research might want understanding: 8, expression: 7. A utility agent might want competence: 10, connection: 1. Decay rates: How fast needs build pressure. Social agent? connection: 3h. Solitary thinker? connection: 24h. Disable a need: Set importance: 0 — it won't generate tension or actions. Use sparingly.
Edit assets/needs-config.json: "understanding": { "importance": 8, // was 3 → now top priority "decay_rate_hours": 8 // was 12 → decays faster }
Don't remove security/integrity without good reason — they protect system health Importance is relative — what matters is the ranking, not absolute numbers You can revisit — preferences evolve. Re-tune after a few weeks of use Document changes — note why you changed something (future-you will want to know) If your human says "defaults are fine" → great, move on. The point is to offer the choice, not force a workshop.
┌───────────────┬─────┬───────┬─────────────────────────────────┐ │ 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)
6-level granular system: ┌─────────────┬────────┬──────────────────────┐ │ Sat │ Base P │ Note │ ├─────────────┼────────┼──────────────────────┤ │ 0.5 crisis │ 100% │ Always act │ │ 1.0 severe │ 90% │ Almost always │ │ 1.5 depriv │ 75% │ Usually act │ │ 2.0 slight │ 50% │ Coin flip │ │ 2.5 ok │ 25% │ Occasionally │ │ 3.0 perfect │ 0% │ Skip (no action) │ └─────────────┴────────┴──────────────────────┘ Tension bonus: bonus = (tension × 50) / max_tension
6-level granular matrix with smooth transitions: ┌─────────────┬───────┬────────┬───────┐ │ Sat │ Small │ Medium │ Big │ ├─────────────┼───────┼────────┼───────┤ │ 0.5 crisis │ 0% │ 0% │ 100% │ │ 1.0 severe │ 10% │ 20% │ 70% │ │ 1.5 depriv │ 20% │ 35% │ 45% │ │ 2.0 slight │ 30% │ 45% │ 25% │ │ 2.5 ok │ 45% │ 40% │ 15% │ │ 3.0 perfect │ — │ — │ — │ (skip) └─────────────┴───────┴────────┴───────┘ Crisis (0.5): All-in on big actions — every need guaranteed ≥3 big actions Perfect (3.0): Skip action selection — no waste on satisfied needs 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 │ └─────────────┴───────┴────────────────────────────────────────┘ Action Staleness (v1.15.0): Penalizes recently-selected actions to increase variety. Actions selected within 24h get weight × 0.2 (80% reduction) min_weight: 5 prevents total suppression — stale actions still have a chance Config: settings.action_staleness in needs-config.json Starvation Guard (v1.15.0): Prevents low-importance needs from being perpetually ignored. If a need stays at floor (sat ≤ 0.5) without any action for 48+ hours → forced into cycle Bypasses probability roll — guaranteed action slot Config: settings.starvation_guard in needs-config.json Default: 1 forced slot per cycle, 48h threshold Spontaneity Layer A (v1.18.0): Surplus energy system for organic high-impact actions. When all needs are above baseline (sat ≥ 2.0), surplus accumulates per-need Global gate requires ALL needs ≥ 1.5 and no starvation guard active When surplus exceeds threshold (~12.5 effective), impact matrix shifts toward bigger actions Full spend on HIGH hit, 30% partial on miss — creates natural ~28-35hr pulsing rhythm Disabled for safety needs (security, integrity, coherence) Config: settings.spontaneity + per-need spontaneous block in needs-config.json Spontaneity Layer B (v1.19.0): Stochastic noise — boredom breeds variety, momentum creates bursts. B2 (Boredom): noise grows with time since last high-impact action (0%→9% max over 72h) B3 (Echo): 8% boost after Layer A [SPONTANEOUS], decays linearly over 24h Combined cap: 12%. Effect: upgrade impact range by one step (low→mid, mid→high) Works independently of gate — neural noise doesn't stop because one subsystem is stressed Boredom tracks actual completion (mark-satisfied), not suggestions Config: settings.spontaneity.noise + settings.spontaneity.echo Spontaneity Layer C (v1.20.0): Context-driven triggers — environmental stimuli boost specific needs. Delta engine compares workspace state between cycles (file counts, mtimes, keyword occurrences) Configurable trigger rules: assets/context-triggers.json with cooldowns Three detector types: file_count_delta, file_modified, file_keyword_delta Context boosts are additive with noise (B2+B3), capped together at 12% Personalize triggers during onboarding based on agent interests Day/Night Mode (v1.11.0): Decay slows at night to reduce pressure during rest hours. Configure in assets/decay-config.json Default: 06:01-22:00 = day (×1.0), 22:01-06:00 = night (×0.5) Disable with "day_night_mode": false Base Needs Isolation: Security (10) and Integrity (9) are protected: They influence lower needs (security → autonomy) Lower needs cannot drag them down Only integrity → security (+0.15) and autonomy → integrity (+0.20) exist
on_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 │ └─────────────────────────┴──────────┴─────────────┴───────────────────────┘
Leverage cascades: Connection easy? Do it first — boosts expression (+0.20) Watch spirals: expression ↔ recognition can create mutual deprivation Autonomy is hub: Receives from 5 sources. Keep healthy. Socratic effect: connection → understanding: -0.05. Dialogue exposes ignorance. Healthy! Full matrix: assets/cross-need-impact.json
🔺 Turing Pyramid — Cycle at Sat Mar 7 05:06 ====================================== Current tensions: connection: tension=10.0 (sat=1.00, dep=2.00) closure: tension=7.0 (sat=2.00, dep=1.00) expression: tension=1.0 (sat=0.00, dep=3.00) 🚨 Starvation guard: expression forced into cycle Selecting 3 needs (1 forced + 2 regular)... 📋 Decisions: ▶ ACTION: expression (tension=1.0, sat=0.00) [STARVATION GUARD] Range high rolled → selected: ★ develop scratchpad idea into finished piece (impact: 2.7) Then: mark-satisfied.sh expression 2.7 ▶ ACTION: connection (tension=10.0, sat=1.00) Range high rolled → selected: ★ reach out to another agent (impact: 2.8) Then: mark-satisfied.sh connection 2.8 ▶ ACTION: closure (tension=7.0, sat=2.00) Range mid rolled → selected: ★ complete one pending TODO (impact: 1.7) Then: mark-satisfied.sh closure 1.7 ====================================== Summary: 3 action(s), 0 noticed
Add to HEARTBEAT.md: /path/to/skills/turing-pyramid/scripts/run-cycle.sh
Decay 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.
Adding needs — The 10-need structure is intentional. Discuss first. Removing needs — Don't disable security/integrity without agreement.
turing-pyramid/ ├── SKILL.md # This file ├── CHANGELOG.md # Version history ├── assets/ │ ├── needs-config.json # ★ Main config (needs, actions, settings) │ ├── cross-need-impact.json # ★ Cross-need matrix │ ├── needs-state.json # Runtime state (auto-managed) │ ├── scan-config.json # Scan method configuration │ ├── decay-config.json # Day/night mode settings │ └── audit.log # Append-only action audit trail ├── scripts/ │ ├── run-cycle.sh # Main loop (tension + action selection) │ ├── mark-satisfied.sh # State update + cross-need cascades │ ├── apply-deprivation.sh # Deprivation cascade engine │ ├── get-decay-multiplier.sh # Day/night decay multiplier │ ├── _scan_helper.sh # Shared scan utilities │ └── scan_*.sh # Event detectors (10 needs) ├── tests/ │ ├── run-tests.sh # Test runner │ ├── test_starvation_guard.sh # Starvation guard (11 cases) │ ├── test_action_staleness.sh # Action staleness (13 cases) │ ├── unit/ # Unit tests (13) │ ├── integration/ # Integration tests (3) │ └── fixtures/ # Test data └── references/ ├── TUNING.md # Detailed tuning guide └── architecture.md # Technical docs
Decision 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): Scans read: MEMORY.md, memory/*.md, SOUL.md, AGENTS.md Also scans: research/, scratchpad/ directories Risk: May contain personal notes, PII, or secrets Mitigation: Edit scripts/scan_*.sh to exclude sensitive paths: # Example: skip private directory find "$MEMORY_DIR" -name "*.md" ! -path "*/private/*" 2. Action suggestions may trigger auto-execution: Config includes: "web search", "post to Moltbook", "verify vault" This skill outputs text only — it CANNOT execute anything Risk: Agent runtimes with auto-exec may act on suggestions Mitigation: In 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 input Risk: State can be manipulated by dishonest calls Impact: Only affects this agent's own state accuracy Mitigation: Enable action logging in memory/ 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.
# Run all tests WORKSPACE=/path/to/workspace ./tests/run-tests.sh # Unit tests (13): decay, floor/ceiling, tension, tension bounds, tension formula, # probability, impact matrix, day/night, scrubbing, autonomy coverage, # crisis mode, scan competence, scan config # Integration (3): full cycle, homeostasis stability, stress test # Feature tests (24): starvation guard (11), action staleness (13) # Total: 40 test cases
v1.20.0 — Spontaneity Layers A+B+C complete (surplus, noise, context triggers), 57 tests. Full changelog: CHANGELOG.md
Agent frameworks, memory systems, reasoning layers, and model-native orchestration.
Largest current source with strong distribution and engagement signals.