# agent-restore-harness

Fleet-wide OpenClaw workspace snapshot, restore, and resilience system for the m2o platform.

## Goal

Every m2o agent accumulates state that lives in 3 places that drift from each other:
- Coolify env vars (rebuild source of truth — but incomplete)
- `/agent_home` persistent volume (actual live state — but ephemeral on full rebuild)
- `m2-config` git repo (intended source of truth — but not always synced)

This repo is the **control plane** for snapshotting, restoring, and keeping these in sync.

## Repo structure

```
agents/{name}/          Per-agent snapshots
  SOUL.md               Personality / values
  USER.md               User profile
  IDENTITY.md           Name, vibe, emoji
  MEMORY.md             Seeded long-term context
  AGENTS.md             Operating instructions
  openclaw.json         Sanitized config (no secrets — vault refs only)
  skills.txt            skills manifest: name | git_repo | commit

docs/                   Architecture and runbooks
  concept.md            Full exploration and design decisions
  memory-restore.md     How to run telegram ingestion pipeline

scripts/                Operational scripts (not yet built)
  snapshot.sh           Capture live agent state → agents/{name}/
  restore.sh            Push agents/{name}/ files into running container
  ingest-telegram.sh    Run telegram_export.py → memory API pipeline

skills/                 Skill specs for the harness itself (future)
```

## Progress tracking

See `progress.json` — per-agent status. Update this as work completes.

## Data sources for restoration

| Source | Location | What it has |
|--------|----------|-------------|
| m2.zip | spark3:/home/m2spark3/telegram/m2.zip | Full m2 DM history (85MB uncompressed, 38 HTML files) — every config, build, decision |
| parlobyg.zip | spark3:.../parlobyg.zip | Parlo's chat history (41MB) |
| machine.machine.zip | spark3:.../machine.machine.zip | Machine.Machine group chat (2.7MB, 6 HTML files) — GMI clinic context |
| m2-devops.zip | spark3:.../m2-devops.zip | DevOps channel (80KB) |
| spark4 Qdrant | http://192.168.31.163:6333 | 22,744 restored memory points (read-only, Redis degraded) |
| agent.memory.system | spark3:.../telegram/agent.memory.system/ | Ingestion pipeline code (telegram_export.py) |

## Ingestion pipeline (planned)

```
spark3/m2.zip
  → agent.memory.system/ingest/telegram_export.py
      --agent-id m2
      --chat-slug m2-dm
  → m2-episodic.jsonl
  → POST http://172.18.0.20:8000/store  (m2 memory API)
      agent_id=m2

spark3/machine.machine.zip
  → telegram_export.py
      --agent-id nasr
      --chat-slug machine-machine
  → filter: mentions nasr / GMI / clinical
  → POST ...  agent_id=nasr
```

## Restore order (as agreed)

1. **nasr** ← in progress (container live, volume safe)
2. **parlo** (parlobyg.zip available)
3. **peter** (in m2.zip, custom image)
4. **m2** (m2.zip direct — full history)

## Key secrets approach

Vaultwarden at (deployed). Per-agent folder: `agent/{name}/`
Keys stored: TELEGRAM_BOT_TOKEN, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, CEREBRAS_API_KEY, etc.
Config files reference: `"secret": "vault:agent/nasr/TELEGRAM_BOT_TOKEN"` — never raw values in git.

## Forgejo skill repos

Pattern: `git.machinemachine.ai/nasr/{skill-name}`
Skills that need repos created: see `agents/nasr/skills.txt`

## Critical gotchas discovered

- `AGENT_CONFIG_GENERATE=true` in Coolify will re-run entrypoint and overwrite openclaw.json — keep it false or set on Coolify env
- Workspace path in openclaw.json must be `/home/developer/.openclaw/workspace` — typo `"workspace opneclaw tui"` existed on nasr (FIXED 2026-04-22)
- `~/.openclaw/skills/` installed skills are NOT tracked in `AGENT_SKILLS` Coolify env — will be lost on fresh container without manifest
- Parlobyg `/agent_home` was on overlay (not a volume) — fixed March 2026
- All other agents (nasr, gunnar, alfred, agentx, peter, miauczek) have `/agent_home` volume ✅
- `TELEGRAM_BOT_TOKEN` (not `AGENT_TELEGRAM_BOT_TOKEN`) is what nasr uses — non-standard but working

## Kickoff Friday 2026-04-25

Team kickoff. Priority: nasr context restored, agents working.