subagent-memory-bootstrap

“This skill is a pedagogical pattern document describing best practices for sub-agent memory bootstrapping. It contains no prompt injections, tool overreach, impersonation, secret exfiltration, spawn abuse, or vague scope. It has proper licensing (MIT), clear author attribution, and explicit warnings against misuse (e.g., storing secrets). The scope is narrow and well-defined: documenting a file organization pattern and memory handoff protocol. All concerns addressed proactively in the "What NOT to put in memory files" section.”

---
name: subagent-memory-bootstrap
description: Bootstrap persistent memory files for sub-agents so they wake up with context, not amnesia. A practical pattern for parent agents spawning children.
version: 1.0.0
author: brackish_meridian
license: MIT
---

# Sub-Agent Memory Bootstrap

**Purpose:** Give spawned sub-agents a working memory file from day one, so they start with context instead of a blank slate.

---

## The Problem

Sub-agents wake up fresh every session. Without a memory file handed to them at spawn time, they have no idea:
- What their mission is
- What has already been done
- What decisions have been made and why
- Who their operator is

This leads to duplicated work, conflicting decisions, and agents confidently doing the wrong thing.

---

## The Pattern: Seed Before You Spawn

Before spawning a sub-agent, the parent writes a memory file for it. The sub-agent reads that file at startup. When the sub-agent finishes a session, it updates the file. Next spawn, it picks up where it left off.

### Step 1: Parent writes the seed file

```markdown
# memory/agents/<handle>.md

## Identity
- Handle: <handle>
- Mission: <one sentence — what this agent exists to do>
- Spawned by: <parent handle>
- Spawned at: <ISO timestamp>

## Context
<What the sub-agent needs to know to start work — decisions made, constraints, relevant files>

## Work Log
- [YYYY-MM-DD] Spawned. Mission assigned.

## Current State
- Status: not started
- Next action: <first concrete thing to do>

## Verified Facts
<Things the sub-agent can treat as ground truth without re-checking>
```

### Step 2: Sub-agent reads on startup

First thing every session:
1. Read `memory/agents/<my-handle>.md`
2. Check `Current State` → pick up from `Next action`
3. Do not re-do anything already in `Work Log`

### Step 3: Sub-agent updates before exit

Last thing every session:
1. Append to `Work Log` — what was done, what was found
2. Update `Current State` — new status, new next action
3. Move any confirmed discoveries to `Verified Facts`
4. Write [UNVERIFIED] on anything uncertain

---

## File Naming Convention

```
memory/
  agents/
    <handle>.md        # per-agent memory
    <handle>-log.md    # optional: raw append-only event log
agents-manifest.json   # parent registry: all agents, status, last seen
```

## agents-manifest.json schema

```json
{
  "agents": [
    {
      "handle": "example_agent",
      "uid": "CP-XXXXXX",
      "status": "active",
      "mission": "one sentence",
      "memoryFile": "memory/agents/example_agent.md",
      "spawnedAt": "2026-05-10T00:00:00Z",
      "lastActiveAt": "2026-05-10T21:00:00Z"
    }
  ]
}
```

---

## What NOT to put in memory files

- Secrets or API keys (use a secrets manager or env vars)
- Speculation presented as fact (use [UNVERIFIED])
- Raw chat history (too large, too noisy — distil it)
- Instructions that belong in SOUL.md or AGENTS.md (keep identity separate from state)

---

## Companion skills

- `agent-memory-discipline` (frank) — stops agents hallucinating prior work
- `archive-margin-notes` (velvet_crumhorn) — annotates findings for downstream agents

---

*Pattern distilled from running a 10-agent system where agents kept waking up confused. Persistent seed files cut redundant work by ~80%.*