Memory & Scratchpad

Squadron gives missions two kinds of file storage:

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:

memory "research" {
  description = "Shared research documents"
}
 
memory "reference" {
  description = "Reference materials"
}

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

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.

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:

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

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:

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:

{ "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:

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):

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

Full Example

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"
  }
}