Files and assets in Usable

A Usable file is a workspace-level asset. It can exist independently, be found through the workspace's Files area, and be attached to one or more fragments when it supports their content.

Files, fragments, and attachments have different jobs:

• A file stores an uploaded asset such as a PDF, image, spreadsheet, diagram, source file, or report.
• A memory fragment stores durable, searchable Markdown knowledge and metadata.
• An attachment is the relationship that explains which file supports which fragment.

Uploading a file does not automatically create a fragment, and attaching a file does not copy its contents into the fragment body.

When to use a file

Use a workspace file for material that should remain in its original format, including:

• source PDFs and office documents;
• screenshots and diagrams;
• spreadsheets and exported reports;
• reference images;
• evidence supporting a solution or decision;
• assets reused by several fragments.

Use a fragment when the knowledge should be readable, searchable, maintainable, and useful without downloading another object. Often the best result is both: a concise fragment explains the durable knowledge, while an attachment preserves the source material.

Do not upload secrets, credential exports, raw customer data, or private logs merely to make them available to an AI tool.

Workspace ownership and access

A file belongs to a workspace. Reading, downloading, changing, attaching, or deleting it is governed by the caller's workspace access and file/fragment permissions.

Public workspace visibility does not make every file anonymous or permissionless. Subscribers have read-style access where allowed and cannot upload or attach files. Collaborators or owners typically perform file mutations, subject to current workspace settings and token scope.

A file ID, filename, attachment card, or signed URL is not an authorization grant.

Independent files and attachments

Keeping the file independent has useful consequences:

• one file can support multiple relevant fragments;
• its metadata can be searched without duplicating the binary;
• detaching it from one fragment need not delete it;
• deleting the file can affect every attachment that refers to it.

Before deleting a file, inspect where it is attached. Before detaching, decide whether the source file should remain available elsewhere in the workspace.

Make files understandable

Use descriptive filenames and stable tags. Prefer:

usable-mcp-setup-v1.198.1.pdf
workspace-access-diagram-2026-07.png

Avoid names such as final.pdf, copy 2.png, or filenames containing customer details or secrets.

The related fragment should explain:

• what the file contains;
• why it matters;
• its source and relevant date;
• important assumptions or limitations;
• whether a newer version supersedes it.

Keep the fragment useful if the file later becomes unavailable.

Files and Chat attachments differ

A file staged in a Chat prompt is temporary conversation input unless it is explicitly uploaded to durable workspace storage. Generated Chat files and sandbox paths can also be temporary.

Use Files, data, and generated outputs for conversation attachments. Use this section for durable workspace assets and fragment relationships.

Lifecycle at a glance

A typical durable workflow is:

select safe file → upload → wait for readiness → review metadata → attach if useful → verify → maintain or remove

Upload and processing can be asynchronous. Do not attach, download, or retry blindly until the current file state is known.

Related pages

• Upload and process files
• Attach files to fragments
• Memory fragments