Avoid Duplicate System Messages

Deduplicate System Messages (Prompt Cache Prefix Consolidation)

Overview

Many multi-agent frameworks inject fresh role: "system" messages or duplicate guideline blocks into the middle of conversation histories (e.g., re-injecting system rules after every tool execution).

Scattering system messages throughout the message array causes two severe issues:

1. Breaks Prompt Caching: Modern LLM caching engines (Anthropic Prompt Caching, OpenAI Prefix Caching) require a static, uninterrupted prefix. Injecting dynamic system messages invalidates the cache on every turn.
2. Input Token Inflation: Re-sending 1,500 tokens of system instructions on every turn across 40 turns burns 60,000 redundant input tokens.

The System Prompt Consolidation Protocol enforces a single, canonical, immutable system header at Turn 0, ensuring maximum prompt cache hit rates (90% discount) and zero redundant token spend.

Fragmented System Injection vs. Consolidated Prefix Cache

┌─────────────────────────────────────────────────────────────┐
│                 Prompt Cache Invalidation                   │
│                                                             │
│  Fragmented System Injections (Anti-Pattern):               │
│  • Turn 0: System Message (1,200 tokens)                    │
│  • Turn 1: User Request                                     │
│  • Turn 2: System Message ("Remember to be concise!")       │
│    ↳ INVALIDATES PROMPT CACHE AT TURN 2! Full re-bill!      │
│  • Turn 3: System Message ("Follow tool rules!")            │
│    ↳ INVALIDATES PROMPT CACHE AT TURN 3!                    │
│                                                             │
│  Consolidated Single-Prefix Architecture (Cached):          │
│  • Turn 0: Single Static Consolidated System Header         │
│    ↳ CACHE_CONTROL: EPHEMERAL (Locks in 90% discount)       │
│  • Turn 1..50: Dynamic User & Assistant Turns ONLY          │
│    ↳ 100% Cache Hit Rate across entire 50-turn session!     │
└─────────────────────────────────────────────────────────────┘

The 3 Rules of Prompt Cache Consolidation

1. The Single System Anchor

Maintain strictly ONE system message at the root of the conversation payload. Never append additional role: "system" objects to the messages array in later turns.

2. Move Dynamic Runtime Hints to User Turns

If the agent runtime must pass a dynamic notification (e.g. "File size exceeds 50KB" or "Test runner passed with 0 errors"), inject it as a lightweight User-Queued Message (role: "user") rather than a system instruction.

3. Order by Stability (Static $\rightarrow$ Semi-Static $\rightarrow$ Dynamic)

Structure your root system prompt from most stable to most dynamic to maximize prefix caching:

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. Core Agent Identity & Safety (100% Static - Never Changes)             │
│ 2. Available Tool Definitions & Schemas (Semi-Static - Changes per project)│
│ 3. Workspace Path & Environment Variables (Set once at session startup)   │
└───────────────────────────────────────────────────────────────────────────┘

Production Python Message Consolidator Middleware

Use this pre-request interceptor to merge fragmented system messages before dispatching API calls:

from typing import List, Dict, Any

def consolidate_system_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """Merges all fragmented system messages into a single root system prompt."""
    system_chunks: List[str] = []
    sanitized_messages: List[Dict[str, Any]] = []
    
    for msg in messages:
        if msg.get("role") == "system":
            content = msg.get("content", "")
            if content and content not in system_chunks:
                system_chunks.append(content)
        else:
            sanitized_messages.append(msg)
            
    # Combine all unique system instructions into one root block
    consolidated_system = "\n\n---\n\n".join(system_chunks)
    
    # Return formatted array with single cacheable system header
    return [
        {
            "role": "system",
            "content": consolidated_system,
            # Anthropic Prompt Caching breakpoint
            "cache_control": {"type": "ephemeral"}
        },
        *sanitized_messages
    ]

Prompt Caching Economics Benchmark

Evaluation across a 40-turn coding session (Claude 3.5 Sonnet):

Agent Operational Directive

MANDATORY: Agent runtimes must never push role: "system" messages into ongoing conversation arrays after session initialization. All runtime state updates must be transmitted via tool responses or user-role context notifications.