--- title: "Buckets: scoped knowledge for AI agents | Calypso Context" canonical_url: "https://www.calypso.so/context/buckets" last_updated: "2026-09-16T00:41:14.819Z" meta: description: "A bucket is a named, durable collection of sources. Ingestion writes into buckets, agents search only the buckets they are bound to, and nothing crosses between them. Provision by slug, list, inspect members, bind to agents." keywords: "knowledge base for AI agents, scoped retrieval, multi-tenant RAG, RAG knowledge buckets, retrieval storage for AI agents" "og:description": "A bucket is a named, durable collection of sources. Ingestion writes into buckets, agents search only the buckets they are bound to, and nothing crosses between them. Provision by slug, list, inspect members, bind to agents." "og:title": "Buckets: scoped knowledge for AI agents | Calypso Context" "twitter:description": "A bucket is a named, durable collection of sources. Ingestion writes into buckets, agents search only the buckets they are bound to, and nothing crosses between them. Provision by slug, list, inspect members, bind to agents." "twitter:title": "Buckets: scoped knowledge for AI agents | Calypso Context" --- Calypso home **Calypso Context · Buckets** # Give every agent the right memory. A bucket is a named, durable collection of sources. Ingestion writes into buckets, agents search only the buckets they are bound to, and nothing crosses between them unless you bind it. The slug is the handle your scripts use; the id is the stable machine handle. [**Read the buckets docs**](https://docs.calypso.so/context/manage/buckets) [**Start 14-day free trial**](https://context.calypso.so/join) ## **Uploads arrive with intent** Every file, page, batch, and MCP upload names its bucket before indexing starts. There is no unsorted pile to clean up later. ## **Readiness is visible** Each member reports its own ready bit and the bucket reports store readiness, so you know before a test whether retrieval can succeed. ## **Agents search curated memory** An agent is bound to the buckets that match its job. Support answers from the handbook; Sales from the catalog; neither sees the other. **The example** ## Provision by slug, then inspect. PUT on the slug is the recommended way for scripts to make sure a destination exists before uploading: explicit, idempotent, and separate from the upload call. **CALYPSO_API_KEY** ``` curl -X PUT "https://api.calypso.so/v1/buckets/support-handbook" \ -H "Authorization: Bearer $CALYPSO_API_KEY" # 201 when created, 200 with "created": false when it already exists. # { "id": "bucket_abc", "slug": "support-handbook", # "status": "active", "created": true } ``` **Buckets by purpose** ## Separate what should never be mixed. One team, four kinds of knowledge, four buckets. Each agent reads the set it is supposed to trust. bucket://support-handbook ### **Support** Help center pages, troubleshooting PDFs, screenshots, and escalation notes in one cite-ready set. bucket://pricing ### **Pricing** Plan sheets as CSV, packaging docs, procurement FAQs, and discount rules kept apart from broad product knowledge. bucket://legal ### **Legal** Terms, policies, compliance PDFs, and data handling documents for a governed, legal-facing agent. bucket://onboarding ### **Onboarding** Setup guides, diagrams, checklists, and customer-specific instructions for an onboarding assistant. **How it works** ## Name it, route into it, bind it. 1. 01 ### **Name the bucket** Pick a slug that says what the set is for. Slugs are unique per team and appear in every citation attribute. 2. 02 ### **Route sources into it** The bucket is in the URL of every ingestion call: files, imports, pages, batches, and MCP uploads. 3. 03 ### **Bind it to an agent** A named agent lists the buckets it searches. bucket_ids takes precedence over every other source field in its policy. **From the docs** ## The endpoints and the rules. | **Handle** | Slug, unique per team and human-readable; id, stable for machines | | --- | --- | | **Provision** | PUT /v1/buckets/{slug} · 201 created, 200 existing | | **List** | GET /v1/buckets | | **Members** | GET /v1/buckets/{bucket}/sources | | **Detach from one bucket** | DELETE /v1/buckets/{bucket}/sources/{id} | | **Delete a source everywhere** | DELETE /v1/sources/{id} · POST /v1/knowledge/files:delete (≤ 100 ids) | | **Scope rule** | bucket_ids takes precedence over every other source field: file_mode is forced to selected and file_ids, website_ids, and qa_ids are cleared | | **Concurrency** | Two callers ensuring the same slug at once is a success case: the loser re-reads and returns the winner with created: false | **Questions and answers** ## Before you create one. **Keep reading** [

**Sources **

PDFs, images, pages, and data. What it reads and how it gets in.](https://www.calypso.so/context/sources) [

**Agents **

One default, any number of named agents with their own scope and policy.](https://www.calypso.so/context/agents) [

**Citations **

A source on every answer: annotations by offset, a structured source list, native mode.](https://www.calypso.so/context/citations) [

**Search **

Retrieval without generation: the passages an answer would cite, ranked.](https://www.calypso.so/context/search) [

**Privacy **

Yours, isolated: no training on your data, export or delete any time, keys with explicit scopes.](https://www.calypso.so/context/privacy) [

**Buckets in the docs **

The reference this page is written from, with every endpoint and field.](https://docs.calypso.so/context/manage/buckets) **Start today** ## **Create the source layer your agents can trust.** Provision a bucket, route your first sources into it, and bind it to an agent in the same hour. [**Start 14-day free trial**](https://context.calypso.so/join) [**Read the developer docs**](https://docs.calypso.so/context/manage/buckets)