persistent-execution-memory

Persistent execution memory system for OpenClaw AI agents. Survives restarts, context loss, and reboots.

What This Does

Normally, AI agents lose all memory when their context window resets, the session ends, or the machine restarts. This skill fixes that.

It provides a file-based memory system that persists across:

• New chat window / fresh session
• Agent restart
• Machine reboot
• Context compaction
• Partial crash

Installation

Option 1: Via ClawHub (once published)

openclaw skills install persistent-execution-memory

Option 2: Manual

# Copy to your workspace skills directory
cp -r persistent-execution-memory ~/.openclaw/workspace/skills/

Quick Start

On Every Fresh Session (First Thing!)

python .agent/skills/persistent-execution-memory/scripts/read_memory.py

This outputs a RECOVERY BRIEF — you instantly know:

• Who you are
• What project you're working on
• What was just happening
• What's blocked
• What to do next

After Completing an Action

python .agent/skills/persistent-execution-memory/scripts/write_memory.py \
  --log "Ran AnimateDiff test" --result "motion clip generated OK"

After a Context Shift

python .agent/skills/persistent-execution-memory/scripts/write_memory.py \
  --context "Switched to SDXL for production images" --phase "Phase 7"

After a Major Milestone

python .agent/skills/persistent-execution-memory/scripts/checkpoint_state.py

Recording a Blocker

# Add blocker
python .agent/skills/persistent-execution-memory/scripts/write_memory.py \
  --blocker "SDXL OOM on 16GB GPU" --cause "VRAM exceeded" --human-required false

# Resolve it
python .agent/skills/persistent-execution-memory/scripts/write_memory.py \
  --blocker-resolve "SDXL OOM on 16GB GPU"

File Structure

.agent/skills/persistent-execution-memory/
├── SKILL.md                      ← This skill's description
├── scripts/
│   ├── bootstrap_memory.py       ← Init memory dir (safe — never destroys existing)
│   ├── read_memory.py            ← Recovery brief on startup
│   ├── write_memory.py           ← Update any memory file
│   └── checkpoint_state.py       ← Timestamped milestone snapshots
└── references/
    └── memory_contract.md         ← Behavior contract

memory/                          ← Your persistent memory (created on first run)
├── IDENTITY.md                  ← Who you are, mission, rules [PROTECTED]
├── DURABLE_FACTS.md             ← Confirmed facts only [PROTECTED]
├── ACTIVE_CONTEXT.md            ← Current working context
├── EXECUTION_LOG.md             ← Chronological action log [APPEND only]
├── BLOCKERS.md                  ← Active blockers
├── NEXT_ACTIONS.md              ← Top 3 next actions
├── SESSION_STATE.json           ← Machine-readable snapshot
└── checkpoints/                 ← Timestamped milestone backups

Memory Model

File	Write Mode	Purpose
IDENTITY.md	Append/patch	Agent identity, role, rules
DURABLE_FACTS.md	Append/patch	Confirmed facts only (no guesses)
ACTIVE_CONTEXT.md	Replace	Current phase, what was happening
EXECUTION_LOG.md	Append only	Timestamped action log
BLOCKERS.md	Replace	Open/resolved blockers
NEXT_ACTIONS.md	Replace	Precise top-3 next actions
SESSION_STATE.json	Replace	Full machine-readable snapshot

Protected Files

These files are never overwritten casually. Only append or carefully patch:

• memory/IDENTITY.md
• memory/DURABLE_FACTS.md

Checkpoints

Run checkpoint_state.py after every major milestone. It creates:

memory/checkpoints/YYYY-MM-DD_HHMMSS/
├── ACTIVE_CONTEXT.md
├── NEXT_ACTIONS.md
├── SESSION_STATE.json
├── EXECUTION_LOG.md
├── BLOCKERS.md
└── checkpoint_meta.json

Old checkpoints are auto-pruned (keeps last 10).

Example Recovery Brief

============================================================
RECOVERY BRIEF
============================================================

## 1. Identity
  Agent Role: AI Short Drama Producer
  Mission: Generate 20-min xianxia short drama
  Mode: character-asset-building

## 2. Active Project
  AI Short Drama Production (Lin Zixuan character)

## 3. Current Phase
  Phase 6.6 — identity locked, emotion set partial

## 4. Last Completed Action
  [from log]
    - Ran SDXL txt2img test, quality improved significantly

## 5. Current Blocker(s)
  - Shock expression: SD1.5 limitation, needs Pipeline B

## 6. Next Top 3 Actions
  1. Run AnimateDiff single-shot test
  2. Generate full scene with SDXL
  3. Write scene 1-3 script

## 7. Confirmed vs Assumed
  Confirmed: ComfyUI v0.3.76, Lin Zixuan face locked
  Assumed: user wants 3-act structure
============================================================

Requirements

• Python 3.7+
• OpenClaw
• No external API keys needed
• No cloud dependency — fully local

License

MIT