name	state-management
description	Managing shared context, memory, and state across multiple agents.

State Management

In a multi-agent system, state is the shared truth about what's happened, what's in progress, and what's been decided. Without state management, agents work with stale or conflicting information — and the user pays the cost in repeated questions, contradictory answers, and lost progress.

State management is the plumbing skill of multi-agent design. Get it wrong and every other skill in this plugin gets harder.

Types of state

Task state: where the overall task is in its lifecycle. Which subtasks are complete, in progress, or pending.
Context state: what each agent knows. What has been shared, summarised, or dropped.
User state: preferences, history, and current emotional state.
Decision state: decisions made, options considered, options rejected (and why).
Error state: what has failed, been retried, been escalated.

State architecture patterns

Centralised state: one shared store all agents read from and write to. Simple, debuggable. Bottleneck risk at scale.
Distributed state: each agent maintains its own state and syncs with others. Flexible. Consistency risk.
Event-sourced state: state is built from a log of events. Every change is recorded. Auditable. Complex.
Blackboard pattern: shared workspace where agents post results and read others' contributions. Good for collaborative problem-solving.

Designing state for users

Users have expectations about what the system remembers:

Within-session state: everything said in this conversation should persist consistently
Cross-session state: preferences, decisions, and context from past sessions should carry forward
Cross-agent state: if one agent learned something, other agents should know
User-controlled state: users should be able to see, edit, and clear what the system remembers

Decision rules

Default to centralised state. Reach for distributed only when measured cross-agent latency is genuinely the bottleneck. Most teams choose distributed prematurely and pay in consistency bugs forever.
If a piece of state lives in a single agent's working memory, treat it as lost. Memory across model invocations is unreliable; promote anything that needs to persist to the shared store.
Cross-session state requires explicit consent per category. "Remember preferences" ≠ "remember what we discussed". Granularity is the design constraint, not a nice-to-have.
For state conflicts, prefer detection over silent merging. A surfaced conflict the user resolves is recoverable; a silently merged inconsistency is invisible damage.
State a user can't see, they can't trust. Any state used to personalise behaviour must be visible somewhere the user can find within ~30 s of UI navigation.

Anti-patterns

The stale-context bug: an agent acts on state that's been superseded by another agent. Hard to detect because the agent looks correct in isolation. Mitigated by versioning every read.
The one-source-of-truth fight: two agents both claim authority over the same state slice. Resolution rules are vague. Last write wins, intermittently.
Implicit state: state lives in an agent's prompt context rather than the shared store. Lost on restart, untransferable, undebuggable.
State sprawl: schema grows unbounded as features accrete. After six months nobody knows what's used, what's dead, or what's load-bearing.
Sync deferral: writes are batched for efficiency, then dropped on failure. The user sees "saved" but the state never made it.
Invisible personalisation: state shapes behaviour the user can't see or override — drift toward manipulation.

When not to use this

Single-agent products — the model's context window is the state. Reach for context-window-design instead.
Stateless transactional features (one-shot completions, image generation calls) — explicit state architecture adds overhead without benefit.
Prototype phase — premature state architecture freezes choices that should still be loose. Use the simplest possible store, document decisions in decision-state only.

Design Artefacts

State architecture diagrams (centralised / distributed / event-sourced / blackboard)
State schema definitions (what's stored, where, by whom, with what TTL)
State lifecycle specifications (creation, update, archival, deletion)
Conflict resolution rules per state slice
User-facing state visibility and control designs

Worked example — task state for a multi-agent customer support flow:

{
  "task_id": "tk_8b2",
  "owner_agent": "router",                  // who currently holds the task
  "status": "in_progress | escalated | done",
  "subtasks": [
    {"id": "verify_account", "status": "done", "result_ref": "ctx_a91"},
    {"id": "check_refund_eligibility", "status": "in_progress", "owner": "billing_agent"}
  ],
  "user_state_ref": "us_482",               // pointer, not embedded copy
  "decisions": [
    {"at": "...", "by": "router", "choice": "billing_agent", "rejected": ["faq_agent"], "why": "intent: refund"}
  ],
  "errors": [],
  "version": 7                              // increments on every write; readers check before acting
}

The version field is the simplest defence against the stale-context bug. The decisions log with rejected makes the routing legible to humans during incident review.

Adapted from work on shared mental models in multi-agent systems and distributed-systems consistency literature (Lamport on logical clocks; the actor model on isolated state).

name	state-management
description	Managing shared context, memory, and state across multiple agents.