[Feature Request] Context slots for ephemeral state management

[coreykarnei]

Summary

Add support for "context slots" - designated pieces of context that can be updated between conversation turns without accumulating in the conversation history. This would allow agents to maintain current state information (like game state, session data, or dynamic configuration) that Claude needs to see, but without the token waste and context pollution of repeatedly including historical versions of that state.

Motivation

I'm building an RPG game using the Claude Agent SDK where I need Claude to always know the current game state (player stats, inventory, location, etc.). Currently, my options are:

1. Include full state in every user message - This causes the conversation history to balloon with redundant state snapshots
2. Use tool calls to retrieve state - This is wasteful (extra API call every turn) and still pollutes the history with tool call/result pairs
3. Rely on Claude's memory - Unreliable for structured data that changes frequently

None of these patterns are ideal for applications with frequently-updating structured state.

Proposed Solution

Introduce a context_slots parameter (or similar) in the SDK that allows specifying named pieces of context that:

• Are visible to Claude in the current turn
• Get replaced (not appended) when updated in subsequent turns
• Don't appear in the conversation history as separate messages
• Are sent to the API separately from the conversation messages array

Example API (conceptual):

options = ClaudeAgentOptions(
    mcp_servers={"game-tools": server},
    allowed_tools=[f"mcp__game-tools__{t.name}" for t in ALL_TOOLS],
    model="claude-opus-4-5",
    system_prompt="You are a dungeon master.",
    context_slots={
        "game_state": {
            "player": {"hp": 100, "inventory": ["sword"]},
            "location": "forest",
            "nearby_enemies": ["goblin"]
        }
    }
)

async with ClaudeSDKClient(options=options) as client:
    await client.connect()

    await client.query("I enter the cave")
    # ... process response

    # Update slot between turns — replaces in-place, no history pollution
    client.update_context_slot("game_state", {
        "player": {"hp": 85, "inventory": ["sword", "potion"]},
        "location": "cave",
        "nearby_enemies": ["dragon"]
    })

    await client.query("I attack the dragon")

Use Cases

This pattern would benefit any application with ephemeral state:

• Games & simulations - Current game state without history pollution
• Dashboards & monitoring - Latest metrics without accumulating old snapshots
• Multi-user sessions - Current user context that changes frequently
• Configuration-driven agents - Dynamic settings that override defaults
• Real-time data applications - Current sensor readings, stock prices, etc.

Benefits

1. Reduced token usage - No redundant state in conversation history
2. Cleaner conversation context - History contains actual dialogue, not state dumps
3. Better separation of concerns - State management separated from conversation flow
4. More predictable context windows - State doesn't push important conversation out of context
5. Simpler application code - No need for workarounds with tool calls or system prompts

Alternative Approaches Considered

• System prompt updates - Could work but feels like overloading system prompt's purpose
• Dedicated state management tool - Still adds tool call overhead and history pollution

Implementation Notes

This might be implementable at the API level by having context slots appear as a special message type that the API handles differently, or as metadata that gets appended to system prompts in a way that doesn't accumulate in history.

Would be happy to discuss implementation approaches or contribute a proof-of-concept if helpful!

[coreykarnei]

@ashwin-ant Thoughts?

[EdanStarfire]

Brute force way that works right now

This is a fun ask, and I'm not sure exactly how to solve it myself, but have been trying to address a similar "out of date memory" issue. What I've played with so far is to capture as close to context as I can from the SDK message stream, and then just create a new session, and feed all that context in with the modified information I want to include.

Hacky way using forked message history

Another thing I've theorized but haven't exactly tackled in the SDK yet (haven't explored forking in SDK) is something along this line:

1. System Prompt + Tool Madness as default
2. Send Message 1 + Trailing instruction to wait to do anything until after receiving some specific memory.
3. Send Memory 1 + Trailing instruction to continue initial request now.

Then, I can manually (in CC):
4. Resume session
5. Use history to step back to where I enter Memory 1.
6. Delete that Memory 1 and replace it with Message 2 + Trailing instruction to wait.
7. Send Memory iteration 2 + Trailing continue.

The challenge is with this second method, you lose the tool usages, responses, etc. of the activity from after Memory 1, so while it retains YOUR history, it doesn't retain the AGENT's history. So it's only useful for certain use cases in that pattern.

Redacting messages option (not available, but I would love this too)

I think what would serve your purpose is instead of enabling some fixed, swappable context data, if there could be a feature where you were able to just redact a message by message ID. Then, you'd have:

1. System Prompt + Tool Madness as default
2. State 1
3. Message 1
4. Agent responses...

Send a command to redact #2

Then you'd be able to:

1. System Prompt + Tool Madness as default
2. Redacted
3. Message 1
4. Agent responses...
5. State 2
6. Message 2
   ...
   and continue on.

[pkuntik]

+1 — hit the exact same wall building a production multi-user bot with a per-user long-lived ClaudeSDKClient and a recall-driven memory system.

Setup

Each user has their own ClaudeSDKClient wrapping a CLI subprocess. Between turns we run retrieval and rebuild a fresh <memory>…</memory> block that we want in the system prompt, because the model reasons about memory most reliably when it's system-framed (and we get prompt-cache benefits).

Concrete observation

Pseudocode of what I wanted to happen:

async def ask(self, prompt: str):
    full_sp = build_system_prompt_with_fresh_memory()
    self._options = replace(self._base_options, system_prompt=full_sp)
    client = await self._ensure()
    await client.query(prompt)
    ...

async def _ensure(self):
    if self._client is None:
        self._client = ClaudeSDKClient(options=self._options)
        await self._client.connect()
    return self._client

What actually happens: the first turn locks in a system prompt. Every subsequent turn on the same connection silently ignores self._options changes — the CLI subprocess still runs with the first system prompt forever. Memory updates, taboo corrections, freshly learned facts — none of it reaches the model until we reconnect.

This is easy to miss because client.query() succeeds, logs look normal, and responses feel plausible. Only when a user says "I told you 8 times not to use markdown" do you realize the SDK has been quietly throwing away your context updates.

Workarounds, all painful

1. await self._reset() before every turn — correct but eats 5–7 s of subprocess cold start per message
2. Move <memory> from system prompt into a leading user message each turn — works but kills prompt caching on the dynamic portion and muddies the role boundary
3. Expose memory via MCP and let the model pull — more indirection, requires prompt engineering to make the model reliably query

What would fix this cleanly

• client.update_system_prompt(new_prompt) that patches the running subprocess's system preamble (or equivalently, re-reads options.system_prompt on the next query() without requiring reconnect)
• Even better: a design where the static prefix (identity, skills, rules) stays cached while a small dynamic slot (context_slot per this issue's proposal) can be swapped each turn without invalidating the cache on the prefix

Either shape solves the memory-injection use case, and both seem close to what's already being discussed here and in #848. Happy to help test a prototype.

— referenced repo: production Telegram bot for an AI personal assistant, ~50 concurrent users, 10–100 turns/user/day

[Nik-Reddy]

Came at this from a different angle in #823/PR #824, just read-only access to existing conversation history from inside a tool handler. No new storage, no write side. Doesn't really overlap with the slots/redaction/mid-session prompt stuff being discussed here, could probably land separately if it ends up useful.

[ThariqS]

This is a great idea but it does break cache. The caching API might be a bit confusing, but the high level here is that if Claude's output depends on something previous in the context, that context needs to be included for prompt caching to work.

So for example:
User: Hi I want to sacrifice 10 HP to summon a spirit.
The user's health is 5/50 HP.M
Claude: You don't have enough Health, you only have 5HP.

You can't remove that in between tags, otherwise Claude's output will no longer make sense. This is unfortunately a limitation with current LLMs and our APIs dont allow us to modify context in this way.