# Memory & Scratchpad

Squadron gives missions two kinds of file storage:

| Kind | What it's for | Lifetime | Slot name agents use |
|------|---------------|----------|-----------------------|
| **Shared memory** | Reference or output data many missions touch | Persists | the HCL label |
| **Mission memory** | A mission's own long-lived state — archives, accumulated output | Persists | `"memory"` |
| **Mission scratchpad** | Working space for one mission run — intermediate files, drafts | One per run, auto-deleted after 7 days | `"scratchpad"` |

Agents reach all three through the same `file_list`, `file_read`, `file_create`, `file_delete`, `file_search`, and `file_grep` tools, naming the slot on each call via the `slot` parameter. **Every slot is writable** — there is no read-only mode.

> **No `path` attribute.** Squadron owns the on-disk layout — you declare what storage you need and Squadron picks the path. Everything lives under `<squadron_home>/`.

## Shared Memory

Declared at the top level so multiple missions can share the same data:

```hcl
memory "research" {
  description = "Shared research documents"
}

memory "reference" {
  description = "Reference materials"
}
```

| Attribute | Type | Description |
|-----------|------|-------------|
| `description` | string (required) | Human-readable description shown to agents |

Missions opt in by listing them, then refer to them by name in tool calls:

```hcl
mission "analyze" {
  memories = [memories.research, memories.reference]
  # agents call e.g. file_read with slot = "research"
}
```

The names `"memory"` and `"scratchpad"` are reserved — a shared `memory "memory"` or `memory "scratchpad"` block is rejected.

## Mission Memory

The mission's own dedicated long-lived slot. Use it for things you want to keep around: a running log, an archive of finished reports, accumulated state across runs.

```hcl
mission "analyze" {
  memory {
    description = "Cumulative analysis output across every run"
  }
}
```

Same shape as the top-level memory block (just a required `description`) — no label because the slot name is always `"memory"`. Agents reach it under that name:

```json
{ "slot": "memory", "path": "2026-04-23/report.md", "content": "..." }
```

| Attribute | Type | Description |
|-----------|------|-------------|
| `description` | string (required) | What this mission's memory is for |

A mission with no `memory { ... }` block has no `"memory"` slot — agents only see whatever shared memories the mission lists (plus the scratchpad, if enabled).

## Mission Scratchpad

A clean workspace for one mission run. Each invocation gets its own subdirectory, isolated from previous and concurrent runs — perfect for intermediate files, working drafts, or anything you don't want bleeding into the next run.

Opt in with a single attribute:

```hcl
mission "analyze" {
  scratchpad = true
}
```

That's the whole configuration. Scratchpads are auto-deleted 7 days after the run started — long enough to inspect what an agent produced and to resume a mission with `squadron mission --resume <id>`, short enough to keep disk usage in check.

Agents reach it under the name `scratchpad`:

```json
{ "slot": "scratchpad", "path": "notes.txt", "content": "..." }
```

### When to use a scratchpad

Reach for the scratchpad when one run needs working storage that the *next* run shouldn't see:

- **Multi-step or multi-agent pipelines.** Agent A scrapes 50 pages and writes them to `scratchpad/raw/`; agent B reads, filters, and summarizes; agent C writes only the final summary to `memory/`. Each run starts clean — no stale `raw/` files leaking between runs.
- **Intermediate computation you don't want to ship.** Partial JSON, debug dumps, retry attempts, half-rendered output — anything the LLM produces while figuring out the right answer but that shouldn't accumulate forever.
- **Per-run isolation under concurrency.** Two simultaneous runs of the same mission can both write to `scratchpad` without colliding; each gets its own `<mission>/<run-id>/` directory.
- **Resume material.** If a long-running mission crashes mid-flight, its scratchpad stays on disk so `squadron mission --resume <id>` can pick up where it left off.

### Memory vs scratchpad

If you're not sure which to use, this is the rule:

| Question | Use |
|----------|-----|
| Should the *next* run of this mission see this file? | `memory { }` |
| Is this a working draft, intermediate result, or temp file? | `scratchpad = true` |
| Will multiple missions need to read this? | top-level `memory "name" { ... }` |
| Does this need to survive across runs *and* be writable by agents? | `memory { }` (every memory is writable) |

A mission can declare both — the persistent `memory { }` for things worth keeping, and `scratchpad = true` for everything else.

## Tool Reference

All six file tools take a required `slot` parameter — that's the slot name (`"memory"`, `"scratchpad"`, or a shared memory's label):

| Tool | Purpose |
|------|---------|
| `file_list` | List files and directories, with optional recursion and pagination |
| `file_read` | Read a file (optionally capped by lines or bytes) |
| `file_create` | Create, overwrite, or append to a file |
| `file_delete` | Delete a file (directories are not allowed) |
| `file_search` | Recursively search for files by filename regex |
| `file_grep` | Search file contents by regex |

Paths are always relative to the slot's root directory. Absolute paths and `..` escapes are rejected.

## Full Example

```hcl
memory "reference" {
  description = "Reference materials shared across missions"
}

mission "research" {
  commander { model = models.anthropic.claude_sonnet_4 }
  agents    = [agents.researcher]

  memories   = [memories.reference]
  memory     { description = "Finished reports, one per run" }
  scratchpad = true

  task "gather" {
    objective = "Gather sources from the reference memory and save notes to the scratchpad"
  }

  task "publish" {
    depends_on = [tasks.gather]
    objective  = "Write the final report into the mission memory"
  }
}
```