Turing Pyramid

Turing Pyramid

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.

Requirements

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.

Data Access & Transparency

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

Pre-Install Checklist

Before installing, review these items:

1. 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
   

2. Scope WORKSPACE — Set to a deliberately limited directory. Avoid pointing at your full home directory. The skill only reads files inside $WORKSPACE.

3. 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.

4. 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.

5. 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.

6. Run tests in isolation — Before production use:

   WORKSPACE=/tmp/test-workspace ./tests/run-tests.sh
   

Quick Start

./scripts/init.sh                        # First time
./scripts/run-cycle.sh                   # Every heartbeat  
./scripts/mark-satisfied.sh <need> [impact]  # After action

Scan Configuration (First-Time Setup)

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:

Available Scan Methods

Setup Conversation

When setting up, ask your human:

1. "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.

2. "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.

3. If neither → line-level works well for most setups. No action needed.

Configuration File

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.

Verification After Setup

After configuring a non-default method, verify it works before telling your human "all set":

1. 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."

2. 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."

3. line-level: No verification needed — always works.

Always report the result to your human. Don't silently fall back.

Needs Customization (First-Time Setup)

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:

The Conversation

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?"        │
└───────────────┴─────┴────────────────────────────────────────────┘

What You Can Change Together

1. 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.

2. Decay rates: How fast needs build pressure. Social agent? connection: 3h. Solitary thinker? connection: 24h.

3. Disable a need: Set importance: 0 — it won't generate tension or actions. Use sparingly.

How to Apply

Edit assets/needs-config.json:

"understanding": {
  "importance": 8,        // was 3 → now top priority
  "decay_rate_hours": 8   // was 12 → decays faster
}

Guidelines

• 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.

The 10 Needs

┌───────────────┬─────┬───────┬─────────────────────────────────┐
│ 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                 │
└───────────────┴─────┴───────┴─────────────────────────────────┘

Core Logic

Satisfaction: 0.0–3.0 (floor=0.5 prevents paralysis)
Tension: importance × (3 - satisfaction)

Action Probability (v1.13.0)

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

Impact Selection (v1.13.0)

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

Protection Mechanisms

┌─────────────┬───────┬────────────────────────────────────────┐
│ 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

Cross-Need Impact

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   │
└─────────────────────────┴──────────┴─────────────┴───────────────────────┘

Tips

• 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

Example Cycle

🔺 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

Integration

Add to HEARTBEAT.md:

/path/to/skills/turing-pyramid/scripts/run-cycle.sh

Customization

You Can Tune (no human needed)

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.

Ask Your Human First

• Adding needs — The 10-need structure is intentional. Discuss first.
• Removing needs — Don't disable security/integrity without agreement.

File Structure

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

Security Model

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│
└─────────────────────┘      └─────────────────────┘

⚠️ Security Warnings

┌────────────────────────────────────────────────────────────────┐
│ 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
  

Script Audit (v1.14.4)

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

Token Usage

┌──────────────┬─────────────┬────────────┐
│ 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.

Testing

# 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

Version

v1.21.0 — Race condition fix (flock skip-and-exit), action dedup guard, scanner false-positive fix, 22 tests green. Full changelog: CHANGELOG.md