Calypso Calypso

Elephant · Buckets

Folders your AI remembers.

A bucket is a named folder of sources: your thesis papers, your lease and insurance, the manuals for your home. Save into one from the chat, rename it, move files between buckets. Ask every bucket at once, or only the ones you name. The slug is the handle your scripts use; the id is the stable machine handle.

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.

Ask one bucket, or all

Ask everything at once, or point a question at the buckets that should answer it. Your research never quotes your receipts unless you ask it to.

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.

Four parts of a life, four buckets. Each question reads the set it should trust.

bucket://research

Research

Papers, preprints, lecture slides and your own reading notes, ready for a literature review.

bucket://home-and-contracts

Home and contracts

Lease, insurance policy, warranties and the letters you keep, quoted clause by clause.

bucket://manuals

Manuals

User guides for the kettle, the car and the router, so every setup and fix is one question.

bucket://receipts

Receipts

Invoices and receipts as PDFs and photos, so totals and dates are one question away.

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 in your account 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.

HandleSlug, unique in your account and human-readable; id, stable for machines
ProvisionPUT /v1/buckets/{slug} · 201 created, 200 existing
ListGET /v1/buckets
MembersGET /v1/buckets/{bucket}/sources
Detach from one bucketDELETE /v1/buckets/{bucket}/sources/{id}
Delete a source everywhereDELETE /v1/sources/{id} · POST /v1/knowledge/files:delete (≤ 100 ids)
Scope rulebucket_ids takes precedence over every other source field: file_mode is forced to selected and file_ids, website_ids, and qa_ids are cleared
ConcurrencyTwo 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

Start today

Make your first bucket in the chat.

Ask ChatGPT or Claude to create a bucket and save a PDF into it, then ask it a question a minute later.