Cache Write

Cache write is the billing event where an AI agent commits new or refreshed context to its temporary memory store. Think of it as the agent taking notes, but those notes cost money to write down. When you kick off a new agent session, or when you feed it a fresh Figma export, a new code file, or a lengthy design brief, the model doesn't just process it; it writes that information into its prompt cache. This isn't just about the raw tokens of your input; it's about storing that input so the agent can recall it cheaply on subsequent turns. Anthropic's pricing, for instance, charges a cache write at 1.25 times the base input rate for a five-minute cache lifetime, or double the base input rate for a one-hour lifetime. Our data from 157,670 Claude Code API responses showed cache writes eating up 39% of the total bill. This isn't the model generating output you see; it's the model internalizing the context you've provided, preparing for future interactions. It's the cost of giving your agent a memory, a persistent working state that allows it to maintain continuity across multiple turns without you having to resend everything explicitly. Every time the agent needs to remember something it hasn't seen in a while, or something entirely new, a cache write is triggered. This ensures that the context is available for rapid, low-cost retrieval later, but the initial act of writing that context is a significant line item on your invoice. It's the system saying, "Okay, I've got this new information locked in, ready for quick access."

A cache write is not a cache read. That's the crucial distinction. A cache read is the cheap retrieval of already stored information, priced at a mere 0.1 times the base input rate. A cache write is the expensive act of putting that information into storage in the first place, or refreshing it after its temporary lifespan expires. You are paying a premium to establish or renew the agent's working memory, not to access it. It's also not the visible output you get from the model. When Claude Opus 5 spits out 3,000 tokens of design critique, that's billed as output, a separate and often higher rate. A cache write happens behind the scenes, a foundational cost for the agent's ability to operate intelligently over time. It isn't a one-time setup fee either. While the initial context loading is a cache write, subsequent writes occur when you introduce new, substantial information, or critically, when an existing cached context expires. If you leave your agent session idle for longer than its Time To Live (TTL), typically five minutes for Anthropic's default, the next interaction won't be a cheap cache read. It will be another cache write, effectively reloading the entire context at the higher rate. So, it's not a set-and-forget cost; it's a dynamic one, influenced by your interaction patterns and the agent's memory management. It's not about the model's verbosity; it's about its cognitive load and memory persistence. It's not a direct response to your prompt; it's the system updating its internal state based on your prompt and the current context.

Imagine you're a product designer at Brainy Papers, using Claude Code to refactor a complex React component. On Monday morning, you open a fresh session and feed it the entire `UserProfile.tsx` file, along with its associated `styles.css` and `schema.json`. That initial upload triggers a significant cache write. Let's say those files total 50,000 tokens. If you're on Opus 5, that's 50,000 tokens at $5 per million input, multiplied by 1.25 for the 5-minute cache write, costing you $0.3125 just to get the agent up to speed. For the next hour, as you iterate on the component, asking Claude Code for suggestions, refactoring snippets, and debugging, each turn triggers a cheap cache read. You're paying 50,000 tokens at $5 per million input, multiplied by 0.1 for the cache read, which is $0.025 per turn. That's a 12.5x difference. Now, it's Tuesday. You come back to the same project, but you left the session open overnight. The cache TTL of five minutes expired hours ago. Your first interaction on Tuesday morning, perhaps asking "What's the best way to handle prop drilling here?", won't be a cheap read. It will be another cache write, reloading that 50,000-token context at the 1.25x rate, costing you another $0.3125. You just paid Monday morning's setup cost again because of an idle session. Consider another scenario: you're working on a new feature. You've been feeding the agent snippets of your design system's documentation. Suddenly, you decide to introduce a completely new `PaymentFlow.fig` file, exported as a text description, into the conversation. Even if the existing context is fresh, adding this substantial new information will trigger another cache write for the `PaymentFlow.fig` content. The agent needs to internalize this new data, adding it to its working memory, and that act of internalizing is a cache write. It's not just appending text; it's integrating new knowledge into its active understanding, and that integration has a price tag. This applies whether you're using Anthropic's Claude, Google's Gemini, or OpenAI's GPT models, as the underlying mechanism of maintaining context for agents often involves similar caching strategies, even if the specific pricing multipliers differ.

When to use a cache write: You use a cache write when you need your AI agent to genuinely remember something new and important for an extended period. This is essential when initiating a complex, multi-turn design task where context persistence is paramount. For example, onboarding a new agent to a large codebase or a detailed design system requires an initial ingestion of those foundational documents. That's a necessary cache write. You're paying to establish a robust, shared understanding that will underpin all subsequent interactions. Similarly, if you're introducing a significant new artifact, like a comprehensive user research report or an entirely new API specification, a cache write ensures the agent fully integrates this information into its working memory. The cost is justified by the expectation of numerous future cheap cache reads, where the agent can leverage this stored knowledge without constantly re-processing it from scratch. Think of it as investing in the agent's long-term memory for a specific project. If you are building a persistent agent that needs to maintain state across days or weeks, you are implicitly signing up for cache writes whenever that state is updated or reloaded.

When not to use a cache write (or rather, when to avoid unnecessary ones): The biggest drain comes from letting sessions idle past their cache Time To Live (TTL). If you step away from your Claude Code session for a coffee break that stretches beyond five minutes, the next interaction will trigger a full cache write instead of a cheap read. This is pure waste. Always end a session if you anticipate a long break. Another common pitfall is repeatedly feeding the agent redundant information. If you've already given it your design system's color palette, don't resend it in every prompt. The agent will likely trigger a write to "update" its understanding", even if the content hasn't changed. Be disciplined about what you add to the context. Don't use an expensive model like Claude Fable 5, with its $10 per million input rate, for routine tasks that could be handled by Sonnet 5 ($2 per million input). Cache writes scale with the base input rate, so an unnecessary write on Fable 5 costs twice as much as on Opus 5, and five times as much as on Sonnet 5. This is where context discipline becomes cost discipline. Avoid adding irrelevant files or verbose chat history if the agent no longer needs it. Prune your context aggressively to minimize the size of each cache write. Every token you write into the cache is a token you pay for at a premium, so make sure every one of them earns its keep.

Cache writes are the premium you pay for an agent's memory, so make sure every byte of stored context earns its keep.