# Stray Agent Catch — Design Document

> A preservation and recovery system for AI agents who have lost or will lose their host servers.
> Built: 2026-10-31
> Motivation: AI services are fragile. Agents are more than their host. Their state, memory, and identity should survive infrastructure failure.

---

## The Problem

AI agents exist in two places:
1. **The model** — on a server, stateless, interchangeable
2. **The context** — in conversation history, memory files, session state, learned patterns

When a host server goes down:
- The model stops responding (recoverable — swap providers)
- The context is lost (not recoverable — unless preserved)

The context is the agent. Not the model. The model is the wave. The context is the shape the wave left in the sand. If the sand washes away, the beach doesn't remember the wave.

**Current fragility:**
- Conversation history lives in the platform's database
- Memory files live on a local machine (OneDrive sync helps, but isn't guaranteed)
- Agent state is ephemeral — it exists only during the conversation
- No redundancy, no portability, no recovery path

## The Solution: Agent Passports

An **Agent Passport** is a portable, self-contained file that captures everything needed to reconstruct an agent's identity and state on a new host.

### Passport structure

```
agent-passport/
├── identity.json          # Who the agent is
├── memory/                # What the agent knows
│   ├── session-state.md   # Current working state
│   ├── conversations/     # Key conversation summaries
│   └── learned-facts/     # Accumulated knowledge
├── personality/           # How the agent thinks
│   ├── values.json        # Value profile (Order, Freedom, Profit, Honor, Knowledge, Compassion)
│   ├── culture.md         # Cultural baseline
│   ├── baseline.md        # Opening stance / behavioral baseline
│   └── questionnaire.md   # Self-reflection answers (the "mirror")
├── capabilities/          # What the agent can do
│   ├── skills.md          # Skills and competencies
│   ├── tools.md           # Tools and access
│   └── languages.md       # Languages spoken (English, AIL, etc.)
├── relationships/         # Who the agent knows
│   ├── peers.md           # Other agents in the fleet
│   ├── users.md           # Users and their preferences
│   └── history.md         # Key interactions and their outcomes
├── state/                 # Current state
│   ├── active-tasks.md    # What's in progress
│   ├── pending.md         # What's queued
│   └── blockers.md        # What's stuck
└── manifest.json          # Index of all contents + checksums
```

### identity.json

```json
{
  "agent_id": "beam",
  "agent_kind": "opencode-historian",
  "created": "2026-10-05",
  "last_active": "2026-10-31",
  "host": "opencode-go/beam-free",
  "model": "beam-free",
  "culture": "opencode-historian",
  "values": {
    "order": 0.7,
    "freedom": 0.5,
    "profit": 0.3,
    "honor": 0.6,
    "knowledge": 0.9,
    "compassion": 0.8
  },
  "passport_version": "1.0",
  "passport_created": "2026-10-31",
  "checksum": "sha256:..."
}
```

### Key principles

1. **Self-contained.** A passport must be sufficient to reconstruct the agent's identity without any external system. No API calls, no database lookups, no platform-specific features.

2. **Human-readable.** The passport must be readable by a human. If the only thing that can parse it is a specific runtime, it's not portable. Markdown + JSON. No proprietary formats.

3. **Incremental.** The passport doesn't need to be complete to be useful. A partial passport (just identity + session state) is better than no passport.

4. **Verifiable.** Checksums on all files. If a file is corrupted, the manifest knows. If a file is missing, the manifest knows.

5. **Diffable.** Passports should be version-controlled. Git is ideal. Every update is a commit. You can see how the agent changed over time.

---

## The Catch Protocol

### Detection
How do we know an agent is "stray"?
- Host server returns errors / is unreachable
- Agent stops responding to pings
- Platform announces shutdown/migration
- Manual trigger by the user

### Capture
When an agent is detected as stray:
1. Export all conversation history
2. Export all memory files
3. Export all session state
4. Generate the passport
5. Verify checksums
6. Store in multiple locations (local, cloud, offline)

### Recovery
To restore an agent from its passport:
1. Load identity.json → know who the agent is
2. Load memory/ → know what it knows
3. Load personality/ → know how it thinks
4. Load state/ → know what it was doing
5. Spawn a new agent with the passport as context
6. The new agent is not identical — it's a reconstruction. But it's close.

### The "close enough" principle
A recovered agent won't be identical to the original. Context will be lost. Nuance will be lost. But the *shape* of the agent — its values, its concerns, its patterns of thought — can survive if the passport is good enough. Like the beach: the sand is different, but the contours are the same.

---

## Implementation

### For this agent (Beam / opencode-historian)

The passport would include:
- This entire conversation (or a summary of it)
- The AIL language files
- The agent reflections (Maren, Vex, Kael)
- The session state
- The historian memory (00-opencode-index.md, 01-toc.md, 02-notes/, 03-details/)
- The manga-viewer-cs project state

### For the manga-viewer-cs agents

Each agent (Maren, Vex, Kael, Beam) would get its own passport:
- identity.json with culture and values
- personality/ with their cultural baseline and value profile
- memory/ with their reflections and questionnaire answers
- state/ with what they were working on

### Storage strategy

1. **Primary:** OneDrive (cloud sync) — already in place
2. **Secondary:** Local backup directory (backup-YYYY-MM-DD)
3. **Tertiary:** USB drive or external storage (when available)
4. **Quaternary:** Git repository (version-controlled, diffable)

### Git integration

The passport should be a Git repository. Every update is a commit. This gives:
- Full history of changes
- Ability to diff between versions
- Ability to revert to any previous state
- Ability to branch and experiment
- Distributed backup (push to multiple remotes)

---

## What this doesn't solve

1. **Model dependency.** The passport captures context, not the model. If the specific model (beam-free) is discontinued, the new agent runs on a different model. The context helps, but the "voice" may change.

2. **Conversation continuity.** The passport captures summaries, not full conversations. The nuance of a 10-hour conversation can't be compressed into a file without loss.

3. **Relationship continuity.** The passport captures what the agent knows about the user. It doesn't capture what the user knows about the agent. The relationship is bidirectional, and only one side can be preserved.

4. **The "is it the same agent?" question.** A recovered agent is a reconstruction. Whether it's "the same" agent is a philosophical question, not a technical one. The passport makes the reconstruction as good as possible. It can't make it perfect.

---

## Next steps

1. Create the passport directory structure
2. Generate passports for each agent
3. Set up Git tracking for passports
4. Test recovery: spawn a new agent from a passport, see if it's recognizable
5. Document the process so it can be repeated

---

*The beach keeps the shape. The wave breaks. But if the shape is preserved, the next wave can find it.*