agent-restore-harness/docs/concept.md

Restore Harness — Concept & Architecture

Explored 2026-04-22. Kickoff Friday 2026-04-25.

The problem

OpenClaw agent state lives in 3 layers that drift from each other:

Layer 1: Coolify env vars     → rebuild source but incomplete, no skill manifest
Layer 2: /agent_home volume   → actual live state, ephemeral if volume lost
Layer 3: m2-config git repo   → intended source but not always synced

On Nasr's container: 18+ skills installed manually, not in any env var or git. On rebuild: those skills vanish. Projects, SOUL.md etc. survive (volume), memory doesn't.

3 restoration tracks

Track 1: Memory (episodic context)

Data sources (all on spark3:/home/m2spark3/telegram/):

• m2.zip — 85MB uncompressed, 38 HTML files — FULL m2 DM history from day 1
• parlobyg.zip — 41MB — Parlo's full chat
• machine.machine.zip — 2.7MB — Machine.Machine group chat (GMI clinic context)
• m2-devops.zip — 80KB — devops channel

Tool already exists: agent.memory.system/ingest/telegram_export.py (stdlib only) Outputs JSONL matching the memory API schema.

Pipeline per agent:

# On spark3
cd /home/m2spark3/telegram
python3 -m ingest.telegram_export m2.zip m2-all.jsonl --agent-id m2 --chat-slug m2-dm

# Filter for agent-specific context, then POST to memory API:
curl -s http://172.18.0.20:8000/store -X POST \
  -H "Content-Type: application/json" \
  -d @m2-filtered.jsonl

spark4 also has 22,744 restored points (read-only, Redis degraded) — can be queried and selectively copied to m2 memory API per agent_id.

Track 2: Workspace files (config-as-code)

Already have snapshot for Nasr in agents/nasr/ (done 2026-04-22).

snapshot.sh (to build):

# Run from m2 against any named agent
AGENT=nasr
CONTAINER=$(docker ps --filter name=$AGENT --format '{{.Names}}' | head -1)
for f in SOUL.md USER.md IDENTITY.md MEMORY.md AGENTS.md; do
  docker cp $CONTAINER:/home/developer/.openclaw/workspace/$f agents/$AGENT/$f
done
# Export sanitized openclaw.json (strip secrets)
docker exec $CONTAINER cat ~/.openclaw/openclaw.json | \
  python3 scripts/sanitize-config.py > agents/$AGENT/openclaw.json
# Skills manifest
docker exec $CONTAINER ls ~/.openclaw/skills/ > agents/$AGENT/skills.txt

restore.sh (to build):

AGENT=nasr
CONTAINER=$(docker ps --filter name=$AGENT --format '{{.Names}}' | head -1)
for f in SOUL.md USER.md IDENTITY.md MEMORY.md AGENTS.md; do
  docker cp agents/$AGENT/$f $CONTAINER:/home/developer/.openclaw/workspace/$f
done
# Inject secrets from Vaultwarden, then restart gateway
docker exec $CONTAINER supervisorctl restart openclaw-gateway

Track 3: Secrets (Vaultwarden)

Vaultwarden is already deployed. Pattern:

• Collection: "fleet-agents"
• Item per agent: agent/nasr with fields:
  • TELEGRAM_BOT_TOKEN
  • ANTHROPIC_API_KEY
  • OPENROUTER_API_KEY
  • CEREBRAS_API_KEY
  • (nasr-specific) MINIMAX_API_KEY, ZAI_API_KEY

In sanitized openclaw.json, reference: "token": "vault:agent/nasr/TELEGRAM_BOT_TOKEN" Restore script fetches via: bw get password "agent/nasr/TELEGRAM_BOT_TOKEN"

Skills git strategy

Skills without repos (all of Nasr's custom ones):

• clinical-pathway, patient-pathway, quantum-trading, trading-app-dev
• 2dexy-sync, ml-training, xcode-remote, build-verify, cursor-agent

Create under: git.machinemachine.ai/nasr/{skill-name} Each skill dir: SKILL.md + executable script(s)

Skills with likely existing repos (fleet-wide, in machine-machine org):

• m2-memory, rlm-memory, unified-search, agency-agents, harness-engine
• intent-elicit, intent-router, spec-discovery, mm-pdf

GMI agent (Nasr's proposal)

machine.machine.zip has the Machine.Machine group chat — this is where GMI clinic discussions happened. Nasr has a GMI-Cancer-Pathways/ project on disk with:

• Breast-Cancer-Pathway.md + Visual.html
• Colorectal-Cancer-Pathway.md + Visual.html
• NSCLC-Pathway.md

A dedicated GMI sub-agent inside Smithers (or a separate OpenClaw agent) could:

1. Hold GMI-specific context in its memory collection
2. Handle clinical pathway queries
3. Interface with any GMI-specific tools

First step: ingest machine.machine.zip filtered for GMI context into agent_memory_nasr.

Restore order

1. nasr — container live, workspace files snapshotted ✅, memory pending
2. parlo — parlobyg.zip ready, container live
3. peter — in m2.zip, custom image container live
4. m2 — m2.zip is the primary source, full history

Open questions for Friday kickoff

1. Nasr-specific Telegram export? (separate @nasr_s_bot history zip)
2. Vaultwarden admin access from m2 (bw CLI setup)
3. Forgejo token for creating skill repos (m2 user, id=1)
4. spark4 Redis fix — make it writable again or retire as archive-only
5. Which skills were created vs cloned — affects whether we need to export code to git