turing-pyramid
v1.29.1Motivation and action system for AI agents. 10 needs with Turing-exp tension, execution gate with evidence verification, spontaneity layers, continuity across sessions, and crash-resilient watchdog.
Installation
🔺 Turing Pyramid
What it does: Gives your agent a motivation system. 10 needs (security, connection, expression...) build tension over time via decay. Each heartbeat, the pyramid evaluates tensions, selects actions, and tells the agent what to do — from "check system health" to "write something creative."
What it is NOT: A chatbot framework, an executor, or a system management tool.
Three layers with different scopes:
| Layer | Scripts | Scope | System effects |
|---|---|---|---|
| Motivation | run-cycle.sh, mark-satisfied.sh, init.sh |
Read workspace files, write own state JSON | None — pure suggestion engine |
| Continuity | mindstate-daemon.sh, mindstate-freeze.sh, mindstate-boot.sh |
Read workspace + own state, write MINDSTATE.md | Read-only system checks: pgrep (gateway alive?), df (disk usage). No writes outside workspace. |
| Resilience | mindstate-watchdog.sh |
Monitor continuity scripts | Default: detect + log only. With allow_kill: true: terminates hung mindstate-*.sh processes (path-anchored, never other PIDs). With allow_cleanup: true: deletes orphan .tmp files in workspace + assets dir. Auto-freeze is always safe. |
Core motivation scripts make zero network calls. Optional external-model scan method (disabled by default) can call an inference API if explicitly enabled by steward. The continuity daemon performs lightweight local system checks (read-only). The watchdog detects and logs by default — destructive actions (kill, delete) require explicit opt-in via config.
v1.27.0 — Execution Gate: structural enforcement that prevents agents from describing actions instead of doing them. Turing-exp tension formula: equal rotation at homeostasis, hierarchy only in crisis.
🚀 Quick Start
# 1. Set workspace (REQUIRED)
export WORKSPACE="/path/to/your/agent/workspace"
# 2. Fix permissions (ClawHub doesn't preserve +x)
chmod +x <skill-dir>/scripts/*.sh
chmod +x <skill-dir>/tests/**/*.sh
# 3. Initialize
bash scripts/init.sh
# 4. Run a cycle
bash scripts/run-cycle.sh
# 5. After completing an action
bash scripts/mark-satisfied.sh <need> <impact>
# Example: bash scripts/mark-satisfied.sh connection 1.5
Add to HEARTBEAT.md for automatic operation:
bash /path/to/skills/turing-pyramid/scripts/run-cycle.sh
Deployment Tiers
Choose the level of integration that matches your trust and needs:
| Tier | Components | System effects | Risk |
|---|---|---|---|
| 1. Interactive only | run-cycle.sh, mark-satisfied.sh, gate-*.sh |
Reads workspace, writes own state JSON | Minimal — no system interaction |
| 2. + Heartbeat | Tier 1 + run-cycle.sh in HEARTBEAT.md |
Same as Tier 1, triggered by agent runtime | Low — no cron, no process management |
| 3. + Continuity | Tier 2 + mindstate-daemon.sh in cron (*/5) |
Adds pgrep (read-only), df (read-only), writes MINDSTATE.md |
Moderate — cron persistence, read-only system checks |
| 4. + Watchdog (detect) | Tier 3 + mindstate-watchdog.sh in cron (*/15) |
Detects hung processes and orphan files, logs only (default). Auto-freezes stale cognition | Moderate — detection only, no destructive actions |
| 5. Full self-healing | Tier 4 + allow_kill: true + allow_cleanup: true |
Kills hung skill processes, deletes orphan .tmp files |
Higher — requires script review |
Start at Tier 1 or 2. Upgrade after reviewing scripts and running the test suite in an isolated workspace. You get full motivation/action selection at Tier 1 — everything above is optional. Tier 4 (watchdog with defaults) is safe to enable without review since it only detects and logs.
🎓 Onboarding Guide
For the Agent
When you first install this skill:
- Read this file to understand the 10 needs and how tension works
- Run
init.shto create initial state files - Run one cycle (
run-cycle.sh) — it proposes actions and registers them in the execution gate - Actually do the action — write the file, make the post, run the command
- Resolve the gate (
gate-resolve.sh --need <need> --evidence "what you did") - Mark satisfaction (
mark-satisfied.sh <need> <impact>) - Integrate into heartbeat — add
run-cycle.shto your HEARTBEAT.md
Important: The execution gate blocks new proposals until you resolve or defer pending actions. This is by design — it prevents you from describing actions instead of doing them. If you can't complete an action, defer it with a reason: gate-resolve.sh --defer <id> --reason "why".
The system is self-tuning. After a few cycles, you'll see patterns: which needs decay fast, which actions are selected, where tensions build.
Key concepts: - Satisfaction (0.5–3.0): How fulfilled a need is. 3.0 = perfect, 0.5 = crisis (floor) - Tension = dep² + importance × max(0, dep - threshold)². Equal at homeostasis, hierarchy in crisis. - Decay: Satisfaction drops over time at need-specific rates. Connection decays in 6h. Security in 168h. - Actions: Each need has 8-11 possible actions with impact levels (low/mid/high). The pyramid picks based on current state.
Resilience: After setup, verify your cron has both entries (daemon + watchdog). The watchdog catches edge cases — daemon crashes, hung processes, stale state. See "Resilience & Crash Recovery" section for details.
For the Human (Steward)
Before your agent starts using this:
- Review the 10 needs (table below) — are importance rankings right for your agent?
- Check scan config — default
line-levelis free and works everywhere. Upgrade toagent-spawnif you have a cheap model (Haiku) available. - External actions — some suggestions mention external platforms (social networks, web search). These are text suggestions only. To remove: set their
weight: 0inneeds-config.json. - Run the test suite to verify everything works:
bash WORKSPACE=/tmp/test-workspace bash tests/run-tests.sh
Configuration conversation with your agent:
- "Review the 10 needs with me — let's adjust importance for your role"
- "Do you have a cheap model for smarter scanning?" → agent-spawn method
- "Which external action suggestions should we disable?"
- "Check gate-status.sh — is the execution rate healthy?"
- "Is the watchdog cron installed?" → verify with crontab -l
- "Check watchdog.log — any recent restarts?"
Execution Gate (enabled by default): The gate prevents your agent from logging "I did X" without actually doing X. Monitor execution rate via gate-status.sh. Healthy is >70%. If your agent repeatedly defers the same need, the actions may not fit your agent's capabilities — adjust them in needs-config.json.
Before enabling cron:
1. Run bash scripts/mindstate-watchdog.sh --dry-run to verify behavior
2. Test in an isolated workspace: WORKSPACE=/tmp/test MINDSTATE_ASSETS_DIR=/tmp/test-assets
3. Ensure cron runs under a non-root user account
4. Review watchdog.sh and daemon.sh source — the kill scope is mindstate-(daemon|freeze|boot).sh only
📊 The 10 Needs
| Need | Imp | Decay | What it measures |
|---|---|---|---|
| security | 10 | 168h | System stability, no threats |
| integrity | 9 | 72h | Alignment with SOUL.md values |
| coherence | 8 | 24h | Memory consistency |
| closure | 7 | 12h | Open threads resolved |
| autonomy | 6 | 36h | Self-directed action taken |
| connection | 5 | 8h | Social interaction |
| competence | 4 | 36h | Skills used effectively |
| understanding | 4 | 8h | Learning, curiosity satisfied |
| recognition | 2 | 48h | Feedback received |
| expression | 1 | 8h | Creative output produced |
Customize in assets/needs-config.json:
"understanding": {
"importance": 8, // Promote: research-focused agent
"decay_rate_hours": 6 // Faster decay = more urgency
}
⚙️ Core Mechanics
Turing-exp Tension Formula (v1.26.0)
tension = dep² + importance × max(0, dep - crisis_threshold)²
╰─ base ─╯ ╰────── crisis amplifier ──────────╯
(equal for (importance matters ONLY
all needs) when dep > threshold)
Below threshold (default: 1.0, meaning sat > 2.0): All needs produce equal tension. Selection is effectively round-robin — expression gets as many slots as security.
Above threshold (sat < 2.0): Importance amplifies the crisis signal. In a dual crisis, security (imp=10) gets priority over expression (imp=1). This ensures high-importance needs get priority only when multiple needs compete for attention simultaneously.
Configure: settings.tension_formula.crisis_threshold in needs-config.json
Tension → Action Selection
satisfaction decays over time
→ tension (Turing-exp formula)
→ probability roll (crisis=100%, ok=25%, perfect=0%)
→ impact selection (crisis→big actions, ok→small actions)
→ action selected from weighted pool
Action Probability by Satisfaction Level
| Sat Level | Base P | Behavior |
|---|---|---|
| 0.5 crisis | 100% | Always act |
| 1.0 severe | 90% | Almost always |
| 1.5 deprived | 75% | Usually act |
| 2.0 slight | 50% | Coin flip |
| 2.5 ok | 25% | Occasionally |
| 3.0 perfect | 0% | Skip |
Protection Mechanisms
| Mechanism | Purpose |
|---|---|
| Floor (0.5) | Minimum satisfaction — prevents total collapse |
| Ceiling (3.0) | Maximum — prevents runaway satisfaction |
| Starvation Guard | Need at floor >48h without action → forced into cycle |
| Action Staleness | Recently-selected actions get 80% weight penalty (variety) |
| Day/Night Mode | Decay slows 50% at night (configurable) |
Cross-Need Impact
Actions on one need can boost or drag others:
| Action on... | Boosts | Why |
|---|---|---|
| expression | recognition +0.25 | Express → noticed |
| connection | expression +0.20 | Social sparks ideas |
| competence | recognition +0.30 | Good work → respect |
| autonomy | integrity +0.20 | Act on values |
| closure | coherence +0.20 | Finished threads → order |
| security | autonomy +0.10 | Safety enables risk |
Full matrix: assets/cross-need-impact.json
🚪 Execution Gate (v1.27.0)
Structural enforcement that prevents agents from describing actions instead of doing them. LLMs conflate "reasoning about an action" with "performing an action" — both are token generation. The gate requires environmental evidence that an action produced a state change.
How it works
run-cycle.sh proposes action → gate-propose.sh registers it as PENDING
→ gate blocks new proposals until PENDING actions resolved
→ agent EXECUTES the action (writes file, posts, runs command)
→ gate-resolve.sh verifies evidence → COMPLETED
→ gate clears → next cycle allowed
Scripts
| Script | Purpose |
|---|---|
gate-propose.sh |
Register pending action (called by run-cycle.sh automatically) |
gate-resolve.sh |
Resolve with evidence, or defer with reason |
gate-check.sh |
Check if gate is clear (built into run-cycle.sh) |
gate-status.sh |
Human-readable status + execution rate analytics |
Evidence Types
| Type | Trust | Verification |
|---|---|---|
mark_satisfied |
HIGH | Was mark-satisfied.sh called? (audit.log check) |
file_created |
HIGH | Does expected file exist? |
file_modified |
HIGH | Was file modified since proposal? |
self_report |
LOW | Agent self-reports (counted separately in analytics) |
Usage
# After completing an action:
bash scripts/mark-satisfied.sh expression 1.6
bash scripts/gate-resolve.sh --need expression --evidence "wrote post about X"
# Or defer with reason:
bash scripts/gate-resolve.sh --defer <action_id> --reason "quiet hours"
# Check gate status:
bash scripts/gate-status.sh
Starvation guard actions are non-deferrable. If the guard forces an action, it cannot be deferred.
Evidence trust model: file_created and file_modified are high-trust because they require observable state changes. However, an agent with write access to $WORKSPACE can fabricate evidence by creating/modifying files. If this is a concern, restrict evidence types to mark_satisfied (requires explicit script call with audit trail) or add steward review for sensitive needs. self_report is explicitly low-trust and tracked separately in analytics.
Configure: execution_gate in assets/mindstate-config.json
🎲 Spontaneity System (Layers A/B/C)
Three layers create organic, unpredictable behavior:
| Layer | Mechanism | Effect |
|---|---|---|
| A — Surplus | Excess satisfaction accumulates. When threshold hit → HIGH impact roll | Natural ~28-35h pulsing rhythm |
| B — Noise | Boredom grows without high-impact actions (max 9%). Echo boost after spontaneous fire (8%, decays 24h) | Variety when things get stale |
| C — Context | File system changes trigger need-specific boosts (new research files → understanding) | Environmental responsiveness |
Combined noise cap: 12%. Disabled for safety needs (security, integrity, coherence).
Configure: settings.spontaneity in needs-config.json
🔄 Continuity Layer (v1.23.0)
State persistence across discrete sessions via a two-layer living document. The reality layer updates continuously (cron daemon), while the cognition layer freezes at session end and restores at next boot.
Architecture
┌─────────────────────────────────────────────────┐
│ MINDSTATE.md │
├────────────────────┬────────────────────────────┤
│ ## reality │ ## cognition │
│ (daemon, 5min) │ (frozen at session end) │
│ auto-updated │ read-only between │
│ between sessions │ session endpoints │
├────────────────────┴────────────────────────────┤
│ ## forecast (frozen, consumed at boot) │
└─────────────────────────────────────────────────┘
Four Scripts
| Script | When | What |
|---|---|---|
mindstate-daemon.sh |
Cron every 5min | Updates reality: pyramid state, filesystem changes, system health, stale cognition detection, physical temperature |
mindstate-freeze.sh |
End of substantive session | Freezes cognition: trajectory, open threads, momentum, cognitive temperature |
mindstate-boot.sh |
Session start (FIRST thing) | Loads MINDSTATE, reconciles forecast vs reality, reports continuity score |
mindstate-watchdog.sh |
Cron every 15min | Process watchdog: detects hung/dead scripts, cleans orphans, restarts daemon |
Boot Sequence (inverted)
1. MINDSTATE.md → Where am I? (position + velocity)
2. SOUL.md → Who am I? (identity)
3. MEMORY.md → What do I know? (history)
4. run-cycle.sh → What should I do? (action)
Current state loads first — early context frames interpretation of everything after.
Temperature System
Physical (daemon-computed, deterministic, first-match):
| Word | Condition |
|---|---|
| crisis | Any need critical (sat ≤ 0.5) |
| pressure | Average tension > 3 |
| focus | One need dominates (max tension > 2) |
| impulse | Spontaneous Layer A fired recently |
| accumulation | Surplus building toward threshold |
| calm | All tensions low (default) |
Cognitive (freeze-computed from session): building / exploring / intensive / contemplation / brief / neutral
Drift detection: If physical ≠ cognitive at boot → DRIFT_DETECTED. Reality diverged while cognition was frozen.
Setup
# Daemon cron (updates reality between sessions)
crontab -e
*/5 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-daemon.sh >/dev/null 2>&1
# Watchdog cron (resilience — detects hung/dead scripts, restarts)
*/15 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-watchdog.sh >/dev/null 2>&1
# Boot (add to AGENTS.md session start — BEFORE SOUL.md)
WORKSPACE=/path/to/workspace bash scripts/mindstate-boot.sh
# Freeze (add to session end hook)
WORKSPACE=/path/to/workspace bash scripts/mindstate-freeze.sh "$SESSION_START_EPOCH"
Resilience & Crash Recovery (v1.28.0)
The continuity layer is designed to survive unexpected termination:
Atomic writes: All scripts write to *.tmp.$$ (PID-unique) then mv to final path. A crash mid-write leaves an orphan temp file but never corrupts the target.
Trap handlers: mindstate-daemon.sh and mindstate-freeze.sh register EXIT/SIGTERM/SIGINT/SIGHUP traps that clean up temp files on unexpected termination.
Orphan cleanup: The daemon cleans up any *.tmp.* files older than 10 minutes on every run.
Stale cognition detection: The daemon monitors when mindstate-freeze.sh last ran. If cognition hasn't been frozen for longer than stale_cognition_hours (default: 24h), a warning appears in MINDSTATE.md under system.cognition.
Watchdog (mindstate-watchdog.sh): Runs on cron every 15 minutes. Safe by default — detect and log only. Destructive actions (kill, delete) require explicit opt-in.
| Check | Default behavior | With opt-in |
|---|---|---|
| MINDSTATE.md freshness | Log warning, restart daemon | Same (restart is safe — just runs daemon.sh) |
| Hung processes (>5 min) | Log only | allow_kill: true → SIGTERM, then SIGKILL |
| Orphaned .tmp files | Log only | allow_cleanup: true → delete files |
| Stale cognition (>6h) | Auto-freeze (safe — runs freeze.sh) | Same |
What does kill target? Only processes matching the full path $SCRIPT_DIR/mindstate-(daemon|freeze|boot).sh. The pattern is anchored to the skill's own script directory via grep -F "$SCRIPT_DIR/mindstate-". It cannot match unrelated processes, system services, or scripts in other directories. Even with allow_kill: true, it will never terminate anything outside the skill's own continuity scripts.
Auto-freeze is enabled by default because it's safe — it only runs mindstate-freeze.sh which writes to MINDSTATE.md in the workspace.
The watchdog logs only problems (to assets/watchdog.log, auto-rotated at 200 lines). Silent when everything is healthy. Supports --dry-run for testing.
Configure in assets/mindstate-config.json:
"watchdog": {
"max_stale_minutes": 15,
"max_process_age_seconds": 300,
"allow_kill": false,
"allow_cleanup": false,
"auto_freeze": true,
"auto_freeze_stale_hours": 6
}
To enable full self-healing (after reviewing scripts):
"allow_kill": true,
"allow_cleanup": true
Failure modes and recovery:
| Failure | Impact | Recovery |
|---|---|---|
| OpenClaw restart | Heartbeat pauses, cron continues | Watchdog ensures daemon stays alive |
| Daemon crash mid-write | Orphan .tmp file | Next daemon run cleans it up |
| Freeze never called | Stale cognition section | Watchdog auto-freezes after 6h (configurable) |
| Hung process (infinite loop) | Blocks flock, daemon skips ticks | Watchdog kills after 5 min |
| Machine reboot | All processes die | Cron restarts daemon + watchdog automatically |
Test Isolation
Set MINDSTATE_ASSETS_DIR to isolate tests from production state:
export MINDSTATE_ASSETS_DIR=/tmp/test-assets
🔍 Scan Configuration
Scanners evaluate each need by analyzing workspace files.
| Method | Cost | Accuracy | Setup |
|---|---|---|---|
line-level (default) |
Free | Good | None |
agent-spawn |
Low | High | Cheap model (Haiku) in allowed list |
external-model |
Low | High | API key + steward approval |
Config: assets/scan-config.json. Fallback always to line-level.
For stewards: agent-spawn and external-model require explicit approval (approved_by_steward: true). The skill never enables these silently.
🔒 Security Model
Three layers with different scopes and system effects (see table above).
┌─────────────────────┐ ┌─────────────────────┐
│ TURING PYRAMID │ │ AGENT │
├─────────────────────┤ ├─────────────────────┤
│ • Reads local files │ │ • Has API keys │
│ • Calculates decay │ ───▶ │ • Has permissions │
│ • Outputs: "★ do X" │ │ • DECIDES & ACTS │
│ • Zero network I/O │ │ │
└─────────────────────┘ └─────────────────────┘
│
│ (continuity layer, cron)
▼
┌─────────────────────┐
│ DAEMON/WATCHDOG │
├─────────────────────┤
│ • Updates MINDSTATE │
│ • pgrep, df (read) │
│ • Watchdog: kill │
│ mindstate-*.sh │
│ processes ONLY │
│ • .tmp cleanup in │
│ $WORKSPACE + own │
│ assets dir only │
└─────────────────────┘
What This Skill Does / Does Not Access
| ✅ Accesses | ❌ Never accesses |
|---|---|
| MEMORY.md, memory/*.md (read) | Files outside $WORKSPACE + own assets dir |
| SOUL.md, SELF.md (read) | Credentials (unless external-model enabled) |
| research/, scratchpad/ (read) | sudo, docker, systemctl |
| needs-state.json, audit.log (read/write) | Network (curl, wget, ssh, etc.) |
| MINDSTATE.md (write, daemon) | Processes other than mindstate-*.sh |
pgrep, df (read-only system checks, daemon) |
Paths outside workspace/assets |
kill on mindstate-*.sh PIDs (watchdog only) |
Root/elevated permissions |
.tmp.* files in workspace + assets (delete, watchdog) |
Security Warnings
-
PII in workspace files — Scans use grep patterns on memory files. They see keywords, not meaning. But workspace files may contain personal data. Scope
$WORKSPACEcarefully. -
Action suggestions may trigger auto-execution — If your agent runtime auto-executes suggestions, review
needs-config.jsonand disable unwanted external actions (weight: 0). -
Self-reported state —
mark-satisfied.shtrusts caller input. Audit trail inassets/audit.logwith sensitive data scrubbing. -
Symlink protection — All
findcommands use-Pflag (physical mode, never follows symlinks). Path traversal blocked viarealpathvalidation. -
System health checks (daemon only) —
mindstate-daemon.shrunspgrep(gateway alive?) anddf(disk usage). These are read-only, local, and produce no side effects. Nosudo,systemctl, or elevated operations. -
Watchdog process management —
mindstate-watchdog.shcankillprocesses, but only those matching the full$SCRIPT_DIR/mindstate-*.shpath (grep -F on the skill's own script directory + process name). This path-anchored pattern prevents false matches against unrelated processes with similar names. Verify by searching forkillandgrepin the script — every kill is gated by the path-specific filter. -
Cron isolation — Both cron entries (daemon + watchdog) should run under the same non-root user that owns
$WORKSPACE. Never add these as root cron jobs. Test with--dry-run(watchdog) and a temporary$WORKSPACEbefore deploying. -
No network operations in scripts —
grep -rn 'curl|wget|nc |ssh|scp|git clone|npm install' scripts/returns zero matches (excluding optionalexternal-modelscan, disabled by default). -
External action suggestions — 8 actions in
needs-config.jsonare flagged"external": true: - web search on topic from INTERESTS.md
- help someone via available integrations
- web search on curious question
- share completed work publicly
- publish research or essay publicly
- present completed work to community for feedback
- post thought/update on social platform
- write social post
These are text suggestions only — the scripts never execute them, make no network calls, and have no side effects. The agent's runtime decides whether to act on them. To disable all external suggestions:
bash
# List them:
jq '[.needs[].actions[] | select(.external == true) | .name]' assets/needs-config.json
# Disable by setting weight to 0 in each need's action list
For strict offline behavior, disable all external actions and keep semantic_predictions.enabled: false.
- PATH and workspace isolation — All file operations use
$WORKSPACEas root.finduses-P(no symlink follow).realpathvalidation in scanners prevents path traversal. Keep$WORKSPACEisolated from credentials and system config. The daemon'spgrep/dfand watchdog'skilloperate on the system process table, scoped by the skill's own$SCRIPT_DIRpath — ensure the skill directory is not writable by untrusted users.
Audit Trail (v1.12.0+)
All state changes logged with timestamp, need, impact, reason (scrubbed):
- Long tokens → [REDACTED]
- Credit cards → [CARD]
- Emails → [EMAIL]
- Passwords/secrets/tokens → [REDACTED]
View: cat assets/audit.log | jq
📁 File Structure
turing-pyramid/
├── SKILL.md # This file
├── CHANGELOG.md # Version history
├── assets/
│ ├── needs-config.json # ★ Main config (needs, actions, weights)
│ ├── cross-need-impact.json # ★ Cross-need cascade matrix
│ ├── mindstate-config.json # Continuity layer config
│ ├── scan-config.json # Scan method config
│ ├── decay-config.json # Day/night mode settings
│ ├── needs-state.json # Runtime state (auto-managed, not published)
│ └── audit.log # Action audit trail (not published)
├── scripts/
│ ├── run-cycle.sh # Main: tension evaluation + action selection
│ ├── mark-satisfied.sh # State update + cross-need cascades
│ ├── init.sh # First-time initialization
│ ├── show-status.sh # Current state display
│ ├── mindstate-daemon.sh # Continuity: reality updater (cron)
│ ├── mindstate-freeze.sh # Continuity: cognition snapshot
│ ├── mindstate-boot.sh # Continuity: boot + reconciliation
│ ├── mindstate-watchdog.sh # Continuity: process watchdog (cron)
│ ├── mindstate-utils.sh # Continuity: shared utilities
│ ├── spontaneity.sh # Layers A/B/C logic
│ ├── apply-deprivation.sh # Deprivation cascade engine
│ ├── get-decay-multiplier.sh # Day/night multiplier
│ ├── _scan_helper.sh # Shared scan utilities
│ └── scan_*.sh # Need-specific scanners (10 files)
├── tests/
│ ├── run-tests.sh # Test runner
│ ├── unit/ # 22 unit test files
│ ├── integration/ # 4 integration tests
│ ├── regression/ # Regression tests
│ └── fixtures/ # Test data
└── references/
├── TUNING.md # Detailed tuning guide
└── architecture.md # Technical documentation
💰 Token Usage
| Heartbeat Interval | Est. tokens/month | 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 per cycle.
🧪 Testing
# Full suite
WORKSPACE=/path/to/workspace bash tests/run-tests.sh
# Unit only
WORKSPACE=/path/to/workspace bash tests/run-tests.sh unit
# Integration only
WORKSPACE=/path/to/workspace bash tests/run-tests.sh integration
26 test files, 65+ assertions. Covers: decay, tension, probability, impact selection, spontaneity (A/B/C), cross-need impact, crisis mode, starvation guard, action staleness, audit scrubbing, scan config, day/night mode, mindstate daemon/freeze/boot, full lifecycle + homeostasis.
📋 Example Cycle
🔺 Turing Pyramid — Cycle at Wed Mar 18 04:11
======================================
Current tensions:
coherence: tension=8.0 (sat=2.0, dep=1.0)
closure: tension=7.0 (sat=2.0, dep=1.0)
autonomy: tension=6.0 (sat=2.0, dep=1.0)
connection: tension=5.0 (sat=2.0, dep=1.0)
Selecting 3 needs (0 forced + 3 regular)...
📋 Decisions:
▶ ACTION: coherence (tension=8.0, sat=2.0)
Range mid rolled → selected:
★ re-read last 3 days of memory for consistency (impact: 1.2)
Then: mark-satisfied.sh coherence 1.2
▶ ACTION: closure (tension=7.0, sat=2.0)
Range low rolled → selected:
★ complete or drop a stale intention (impact: 0.8)
Then: mark-satisfied.sh closure 0.8
▶ ACTION: autonomy (tension=6.0, sat=2.0) [SPONTANEOUS]
Range high rolled → selected:
★ make significant autonomous decision (impact: 2.9)
Then: mark-satisfied.sh autonomy 2.9
======================================
Summary: 3 action(s), 0 noticed
Version: 1.28.7 — Safe defaults: watchdog detect-only, kill/cleanup opt-in. 5-tier deployment. 25/25 tests.
Full changelog: CHANGELOG.md | Tuning guide: references/TUNING.md