state-management

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.

See also

• handoff-protocols — context transfer between agents uses the state architecture; design them together.
• observability-design — state mutations are the most useful traces. Design what's logged at the same time as what's stored.
• consent-and-agency — cross-session and cross-agent state is consent-laden by default.
• task-decomposition — task-state schema is determined by the decomposition shape; co-design.

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