Attach files to fragments

An attachment connects a workspace file to a memory fragment. The file remains a workspace asset; the attachment tells readers and tools why that asset belongs with the fragment.

Use attachments for source documents, screenshots, evidence, diagrams, exports, or other files that directly support the fragment's maintained explanation.

Before attaching

Confirm that:

• the file and fragment belong to an appropriate accessible workspace;
• the file is ready, not still uploading or processing;
• the caller can read the file and update the fragment relationship;
• the file is safe for the fragment's audience;
• the relationship is useful and not already present.

Do not attach a file solely to make it easier to find. Improve filenames, tags, or the explaining fragment instead.

Attach from the dashboard

1. Upload or locate the file in the workspace's Files tab.
2. Open its actions or the fragment's file controls.
3. Select the target fragment.
4. Confirm the attachment.
5. Open the fragment detail page.
6. Verify that the expected file appears and can be opened by an authorized user.

If the same file supports several fragments, attach it only where the relationship is meaningful. Avoid turning every related fragment into a duplicate file index.

Attach through MCP

Use attach-file-to-fragment after the upload has completed and the client has confirmed both identifiers:

{
  "fileId": "<file-id>",
  "fragmentId": "<fragment-id>"
}

The model choosing these values is not authorization. The service must verify workspace ownership and the current user's permission.

Attach through REST

The practical REST sequence is:

upload → poll status → inspect file → attach to fragment → list fragment files

Use the current public OpenAPI document at GET /api/docs for exact request and response schemas. Deterministic services should keep the returned file and fragment IDs in their own state.

Keep the fragment useful

An attachment is supporting evidence, not a substitute for maintained knowledge. In the fragment body, explain:

• what the file is;
• which section or data matters;
• source and date;
• any caveats;
• whether it supersedes an older file.

Readers should understand the essential conclusion even if they cannot preview or download the file.

Detach versus delete

Detaching removes the relationship from a fragment. Deleting removes the underlying workspace file and can break every attachment that refers to it.

Before deleting:

1. Find the file's current attachments.
2. Confirm no fragment or workflow still relies on it.
3. Preserve needed historical evidence in an approved location.
4. Remove or update stale references.
5. Delete only with the required permission and confirmation.

Use detachment when the file is still valid elsewhere. Use deletion when the file itself should no longer exist in the workspace.

Replace a source file

Uploads create file assets; do not assume uploading a newer file updates every existing attachment automatically.

For a replacement:

1. Upload and verify the new file.
2. Update the explaining fragment with its date and scope.
3. Attach the new file.
4. Verify reader access.
5. Detach the obsolete file.
6. Delete the old asset only after checking all other relationships.

Troubleshooting

The file cannot be selected

It may belong to another workspace, still be processing, or be hidden by permissions. Resolve the exact file and workspace first.

Attachment returns 403

The user or token may read but not attach. Use the minimum suitable write permission; do not broaden workspace access unnecessarily.

The file appears in Files but not on the fragment

Upload succeeded, but the attachment relationship did not. Retry the attachment only after checking whether it already exists.

A deleted file still appears in prose

Attachments and Markdown links are separate. Update the fragment body and any generated documentation links after deletion.

Related pages

• Files and assets in Usable
• Search, download, and maintain files
• Memory fragments