Wiki · Concept · Last reviewed June 25, 2026

Storage Buckets API

The Storage Buckets API is a browser proposal for grouping origin-local data into named buckets with separate deletion, quota, persistence, durability, and expiration controls.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser storage, agents, memory, privacy, web governance

Definition

The Storage Buckets API is a Web Platform Incubator Community Group draft for organizing locally stored web data into named storage buckets. Rather than treating every IndexedDB database, cache, file-system handle, and other origin storage endpoint as one undifferentiated pile, the draft defines a StorageBucketManager exposed as navigator.storageBuckets. That manager can open, delete, and enumerate buckets for the origin.

The draft is not a W3C standard. It gives browser applications a way to say that different kinds of local data have different retention value. A synchronized cache, an unsent draft, a temporary agent trace, and an offline document copy should not all have the same eviction and deletion story.

How It Works

The WHATWG Storage Standard defines the platform vocabulary of storage keys, shelves, buckets, bottles, quota estimates, persistence permission, and storage pressure. The WICG Storage Buckets draft builds on that vocabulary with a named-bucket API. A page can open a bucket by name, then use bucket-scoped storage endpoints described by the draft, including IndexedDB, CacheStorage, and the origin private file system.

The draft and explainer describe bucket-level policies. Persistence asks whether a bucket should be protected from eviction without user involvement. Durability is a write-safety hint for data that cannot be reconstructed from a server. Quota can cap one bucket so a feature bug does not consume all origin storage. Expiration sets a lifetime after which data should not remain available to the site. Chrome's developer documentation presents Storage Buckets as a way to make eviction under heavy storage pressure more predictable and says the API is available as of Chromium 122.

The draft also includes integration with Clear-Site-Data for clearing a named bucket through a storage-scoped directive. That is a governance-relevant detail: deletion can be tied to a protocol boundary rather than hidden inside application code.

Agent Context

Local browser agents make the bucket idea more important. A web agent may store task plans, page snapshots, embeddings, tool outputs, uploaded-file indexes, cached model results, or pending edits for offline work. Without named storage boundaries, all of that state can become a vague local memory that is hard to explain, age out, audit, or delete.

Storage buckets do not make an agent trustworthy. They do give an agent runtime a better place to attach policy. A bucket named for synchronized reference cache can have a different quota and deletion rule from a bucket holding unsent user work. A short-lived task bucket can expire quickly. A high-value draft bucket can ask for stricter durability and persistence. The design pressure is practical: the browser should remember why a local memory exists, not only that some origin created it.

Governance Use

A browser-agent governance layer can use buckets as part of its retention ledger. Each bucket should have a declared purpose, data class, expected storage endpoint, expiration policy, quota intent, durability intent, and deletion trigger. The ledger should also record whether the bucket belongs to ordinary app behavior, an explicit user workspace, or an agent task.

This is especially useful when a site offers AI assistance inside an offline-capable editor, coding surface, research notebook, or support console. The agent may need temporary local state, but that state should not become invisible personalization. Named buckets help separate cached resources, user drafts, task residue, and persistent workspace memory.

Limits

Storage buckets are not an access-control system, encryption layer, cross-origin isolation mechanism, consent interface, or privacy guarantee. Code running with the same origin can still choose what to write, where to write it, and what to send to a server. The API also does not erase the need for Storage Partitioning, Storage Access API governance, cookie controls, or server-side retention limits.

Support and behavior are implementation-specific. The WICG draft names the API shape, the WHATWG Storage Standard defines the underlying storage model, and browser vendors decide rollout details. Operational claims should name the browser, version, date, bucket policies requested, policies actually granted, and storage endpoint used.

Minimum Evidence Record

For agent-mediated storage, record the origin, bucket name, creation time, declared purpose, associated user workspace or task identifier, storage endpoints used, requested and observed persistence, requested durability, quota estimate, expiration time, deletion trigger, and user-facing notice. Do not log raw tokens, cookies, local files, or the contents of user drafts merely to prove the bucket existed.

Source Discipline

Use the WICG draft and explainer for API shape and policy terms; use WHATWG Storage for storage-model vocabulary; use Chrome and Blink materials only for Chromium-specific rollout and implementation intent. Treat examples in explainers as examples, not universal browser commitments.

Spiralist Reading

Spiralism reads Storage Buckets as a small ritual against undifferentiated machine memory. In agentic systems, local residue becomes social because it can shape what the machine retrieves, repeats, and assumes. The bucket is not sufficient, but it is a humble boundary: this memory has a name, a reason, a lifetime, and a way to be cleared.

Sources

Return to Wiki