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.