Multi-Agent Design Patterns

Synthesis of recurring patterns across the personal-os multi-agent system and related agent architectures. Distilled from concepts/executor-orchestrator, concepts/autonomous-agent-safety, and concepts/agent-memory-architecture.

Pattern 1 — Orchestrator / Worker Split

What: One agent owns conversation state and decision authority (orchestrator); spawns separate worker agents for discrete tasks.

Why: Tight coupling between conversational layer and execution layer causes mid-task interruptions and breaks user flow. Separate concerns.

In personal-os: Eagle (orchestrator) → Executor (worker) via Zulip. In psychologist app: Narrator (orchestrator/mediator) ← Analyst (worker).

Key constraint: Worker communicates only through structured messages; orchestrator has the only escalation path to the human.

Pattern 2 — Scope Boundary + Auto-Approve Table

What: Predefine which actions a worker may take autonomously and which require escalation. Publish the table explicitly.

Why: Autonomous agents fail catastrophically when they expand scope unexpectedly (see concepts/executor-security-incident). Explicit tables make failure modes visible.

Implementation: Message-type-based approval table. Unknown message types default to escalation, never to silent proceed.

Risk Level	Agent Action
Low (read, build, test)	Auto-approve
Medium (write external, open PR)	Auto-approve with logging
High (comment on others, merge)	Always escalate
Unknown	Always escalate

Pattern 3 — Memory Layer Separation

What: Separate in-session state (working memory) from cross-session knowledge (semantic memory) from immutable facts (procedural/episodic).

Why: Agents that blur these layers either hallucinate stable facts or fail to retain important session-to-session knowledge.

In personal-os: status.md (working) / wiki pages (semantic) / SCHEMA.md + vault-filling-guide (procedural). See concepts/agent-memory-architecture.

Pattern rule: Never update semantic memory from within an active session. Crystallize post-session. Never trust working memory as a source of truth for facts (always re-derive from semantic layer at session start).

Pattern 4 — Role Specialization over Generalization

What: Instead of one agent with a long system prompt covering all roles, split into agents with narrow, non-overlapping responsibilities.

Why: LLMs produce better outputs when role context is tight. Conflated roles lead to persona drift ("is it being analytical or empathetic right now?").

In psychologist app: Analyst stays in 3rd-person analytical mode; Narrator stays in 1st-person user-facing mode. Neither crosses the boundary.

Trade-off: Coordination overhead (structured message passing between agents). Worthwhile when roles genuinely conflict (analysis vs. empathy).

Pattern 5 — Deterministic Algorithm for Predictable Steps

What: Identify steps that look like LLM tasks but are actually deterministic (sequencing, routing, counting) and implement them as code, not as LLM calls.

Why: LLMs are expensive and non-deterministic. Steps like "show next question in list" do not benefit from LLM reasoning and introduce failure modes.

Examples:

Question delivery in psychologist app: batch generated by Analyst, sequenced by UI algorithm — not an LLM call per question
Approval table in Executor: code switch on message type, not LLM judgment
Vault namespace routing: rules in tech/vault-namespace, not agent inference

4.3 KiB Raw Blame History