> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The Minion Pattern

> Isolated cron sessions do the grunt work. The main session does the thinking.

## The Problem

ArgentOS runs scheduled jobs (cron) in **isolated sessions** -- separate agent instances with no conversation history, no memory access, and no personality context. This is by design: isolation prevents cron jobs from polluting the main session's context window and allows them to run on cheaper model tiers.

But isolation creates three gaps:

<AccordionGroup>
  <Accordion title="Visibility Gap">
    Isolated sessions produce work that the main session never sees. The agent wakes up, does research, generates output, and the result evaporates when the session ends.
  </Accordion>

  <Accordion title="Quality Gap">
    The main session has MemU, conversation history, SOUL.md, and USER.md. Isolated sessions have none of this. They produce competent but generic output -- missing the personal touch.
  </Accordion>

  <Accordion title="Accountability Gap">
    There's no verification that the isolated session completed all requirements, met quality standards, or handled edge cases. Fire-and-forget means fire-and-hope.
  </Accordion>
</AccordionGroup>

## The Insight

ArgentOS has two **persistent** storage systems that survive gateway restarts:

| System          | Storage                 | Persists? | Accessible By     |
| --------------- | ----------------------- | --------- | ----------------- |
| **Task system** | SQLite (`dashboard.db`) | Yes       | All sessions      |
| **Doc panel**   | SQLite (`dashboard.db`) | Yes       | All sessions      |
| System events   | In-memory queue         | No        | Main session only |
| Session history | In-memory               | No        | Same session only |

<Warning>
  The minion pattern uses persistent storage (tasks + doc\_panel) as the handoff mechanism, with system events as a bonus notification layer -- not the primary one.
</Warning>

## The Pattern

```mermaid theme={null}
sequenceDiagram
    participant Cron as Cron Trigger
    participant Minion as Isolated Session
    participant DB as dashboard.db
    participant Main as Main Session
    Cron->>Minion: Fire isolated session
    Minion->>Minion: 1. Research
    Minion->>Minion: 2. Write draft
    Minion->>DB: 3. Save to doc_panel
    Minion->>DB: 4. Create handoff task
    Main->>DB: Check tasks (startup/heartbeat)
    DB-->>Main: Pending handoff task
    Main->>DB: Read draft from doc_panel
    Main->>Main: Add context & personality
    Main->>Main: Deliver to channels
    Main->>DB: Mark task complete
```

### The Minion's Job (Isolated Session)

The minion has a narrow, well-defined scope:

1. **Research** -- Gather raw data (web search, API calls, inbox checks)
2. **Draft** -- Write a structured draft of the deliverable
3. **Persist** -- Save the draft to `doc_panel` (survives restarts)
4. **Hand off** -- Create a task assigned to the main session with clear instructions

The minion does NOT:

* Generate final audio/media
* Deliver to external channels (Discord, email)
* Make judgment calls about tone, timing, or audience
* Access memory or personality context

### The Main Session's Job

The main session picks up the handoff during its normal operating cycle:

1. **Discover** -- Check tasks during startup, heartbeat, or contemplation
2. **Read** -- Open the doc\_panel draft, review the minion's work
3. **Enhance** -- Add context from memory, conversation history, personality
4. **Deliver** -- Generate final media, send to channels, notify the user
5. **Close** -- Mark the task complete

### Why This Split Works

| Capability             | Isolated Session | Main Session |
| ---------------------- | ---------------- | ------------ |
| Web search             | Yes              | Yes          |
| Tool calls             | Yes              | Yes          |
| MemU (memory)          | No               | Yes          |
| SOUL.md (personality)  | No               | Yes          |
| Conversation context   | No               | Yes          |
| Relationship awareness | No               | Yes          |
| Model tier             | Usually cheaper  | Full routing |
| Quality judgment       | Limited          | Full         |

<Tip>
  This mirrors how human teams work: a junior researcher gathers data and writes a first draft, then the senior partner reviews, adds their expertise, and signs off.
</Tip>

## Implementation Details

### Cron Job Configuration

```json theme={null}
{
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "You are a research minion for [task]. Your ONLY deliverables are: doc_panel draft + task creation. Do NOT deliver to channels yourself."
  },
  "delivery": {
    "mode": "announce"
  }
}
```

Key settings:

* **`sessionTarget: "isolated"`** -- Runs in a separate session (no context pollution)
* **`wakeMode: "now"`** -- Triggers immediate heartbeat in main session after completion
* **`delivery.mode: "announce"`** -- Posts system event to main session
* Both `wakeMode` and `delivery` are **supplementary** -- the task in `dashboard.db` is the primary handoff

### Main Session Discovery

The main session checks for minion handoffs at three points:

1. **Session startup** -- AGENTS.md "Cron Job Awareness" section
2. **Contemplation cycles** -- CONTEMPLATION.md "Check your minions" section
3. **Heartbeats** -- Triggered by `wakeMode: "now"` after cron completion

This triple-check ensures the handoff is discovered even if one mechanism fails.

### Failure Modes and Recovery

| Failure                                 | Impact                          | Recovery                   |
| --------------------------------------- | ------------------------------- | -------------------------- |
| Minion crashes mid-research             | No draft, no task created       | Next cron run retries      |
| Minion creates draft but not task       | Draft exists but undiscoverable | Manual check of doc\_panel |
| Gateway restarts after minion completes | System event lost               | Task persists in SQLite    |
| Main session skips task check           | Task sits pending               | Discovered on next cycle   |

## Design Principles

1. **Persistent Over Ephemeral** -- Never rely on in-memory state for cross-session communication
2. **Narrow Minion Scope** -- "Research and draft" is good. "Research, draft, generate audio, deliver, and verify" is too much
3. **Explicit Handoff Instructions** -- The task description should be a complete checklist
4. **Triple-Check Discovery** -- Wire the handoff into multiple discovery points
5. **Separation of Concerns** -- Minion: data gathering (context-independent). Main: quality control (context-dependent)

## Applying the Pattern

For any new cron job, ask:

1. What part is **data gathering**? -> Minion does this
2. What part requires **context/memory/personality**? -> Main session does this
3. What's the **deliverable format**? -> Minion saves draft to doc\_panel
4. What's the **delivery channel**? -> Main session handles delivery