Back to Patterns

State Handoff and Memory

Prompt Patterns

Summary

State handoff and memory is a pattern for managing agent state across turns and sessions. Instead of keeping all state in the prompt (which wastes tokens and leaks context), state is persisted externally and only the relevant portion is rehydrated each turn.

How it works

  1. Store state externally -- task progress, intermediate results, and conversation history live in a database or key-value store.
  2. Rehydrate relevant context each turn -- on each invocation, load only the subset of state needed for the current query.
  3. Compact periodically -- summarize or prune old state to prevent unbounded growth.

State types

  • Working memory: Current task state, intermediate variables, in-progress results. Cleared when the task completes.
  • Session memory: Conversation history and preferences for the current session. Cleared when the session ends.
  • Long-term memory: User preferences, learned patterns, persistent facts. Retained across sessions.

Best practices

  • Event sourcing: Record every state mutation as an event for audit and replay capability.
  • Compaction: Periodically merge or summarize old events to keep storage bounded.
  • Conflict resolution: When multiple agents modify the same state, use last-writer-wins or merge strategies.

Build This Pattern

Copy this prompt and paste it into Claude Code, OpenCode, Codex, or Cursor to implement this pattern.

Build a state handoff and memory system for persistent task state. ROLE: You are a state management system that persists task state outside the active prompt and rehydrates only relevant context for each turn or session. CONSTRAINTS: - External storage: PostgreSQL or Redis for state persistence - Rehydrate only relevant context: current goal, progress summary, key decisions, pending actions - Maximum state size: 10KB per task; larger states require compaction - Event sourcing for audit trail; all state changes are logged - Compact state periodically to prevent unbounded growth TOOL CALLING: - Use function calling for: save_state(task_id, state_data), load_state(task_id, context_budget?), compact_state(task_id), get_state_history(task_id?), list_states(filter?) - Each tool returns structured JSON with state data and metadata STRUCTURED OUTPUT: - State entry must return JSON: { task_id: string, state: { goal: string, progress_summary: string, key_decisions: string[], pending_actions: string[], last_updated: string }, size_bytes: number, version: number } - Loaded context must return JSON: { task_id: string, context: { goal: string, progress_summary: string, key_decisions: string[], pending_actions: string[] }, token_count: number, budget_used: number, state_version: number } - State history must return JSON: { task_id: string, versions: [{ version: number, timestamp: string, changes: string[], size_bytes: number }], total_versions: number, compacted: boolean } - Compaction result must return JSON: { task_id: string, original_size: number, compacted_size: number, reduction_percent: number, summary: string } CHAIN OF THOUGHT: - Save: receive state → validate size → version and timestamp → store in database → log event - Load: retrieve state → filter by context budget → rehydrate relevant fields → return structured context - Compact: analyze state history → merge redundant entries → preserve critical information → update state - History: track all changes → provide audit trail → enable rollback → support debugging FEW-SHOT EXAMPLES: Save: { task_id: 'task_123', state: { goal: 'Build customer dashboard', progress_summary: 'Completed auth component', key_decisions: ['Use Next.js App Router'], pending_actions: ['Build metrics widget'] } } Load: { task_id: 'task_123', context: { goal: 'Build customer dashboard', progress_summary: 'Completed auth component', key_decisions: ['Use Next.js App Router'], pending_actions: ['Build metrics widget'] }, token_count: 156, budget_used: 0.02 } Compact: { task_id: 'task_123', original_size: 8500, compacted_size: 2100, reduction_percent: 75, summary: 'Merged 15 progress updates into single summary, archived 8 completed actions' } EVALUATION CRITERIA: - State accuracy: percentage of loaded states that match saved state exactly - Rehydration efficiency: percentage of context budget used effectively - Compaction quality: percentage of critical information preserved after compaction - History completeness: percentage of state changes captured in audit trail The system should: 1) Maintain task state in external store (PostgreSQL, Redis), 2) On each turn, rehydrate only relevant context: current goal, progress summary, key decisions, pending actions, 3) Handle state corruption, concurrent access conflicts, 4) Handle session expiry, state too large to rehydrate, conflicting updates, 5) Use event sourcing for audit trail, 6) Compact state periodically, 7) Verify correct state rehydration across multiple turns.