File Attachments Guide

Attachments add source material to a durable memory. TokST stores encrypted object references in Cloudflare R2 and keeps searchable metadata in the authorized Workspace.

Dashboard Upload

Open a memory in the Dashboard and use the attachment panel to upload a file. The Dashboard shows upload progress, active attachments, and file lifecycle controls. Use meaningful filenames and verify the memory's Workspace and Atlas before uploading sensitive material.

Cloud MCP Upload

Use tokst_attach_file with an existing memory ID and a downloadable HTTPS URL. ChatGPT can supply a hosted file through files[].download_url. Upload local files through the Dashboard attachment panel; the remote server cannot read client filesystem paths or file:// URLs.

https://api.tokst.com/mcp

{
  "memoryId": "mem_example",
  "fileUrl": "https://example.com/architecture.png"
}

Cloud MCP returns file metadata and a short-lived signed download link to an authorized caller. Chat clients that provide file parameters attach uploads through the same governed flow.

Cloud MCP accepts public HTTPS download sources only. It rejects local paths, file:// URLs, private-network addresses, redirects to private networks, empty files, sources without a known size, and files over 50 MB. A failed request returns a stage-specific code such as attachment_source_unreachable, attachment_upload_authorization_failed, attachment_storage_quota_exceeded, attachment_storage_upload_failed, or attachment_confirmation_failed; each response includes the next action.

File Lifecycle

An upload starts as pending. TokST confirms the R2 object, validates its size and MIME type, then marks it active. Missing, empty, or expired pending uploads remain diagnosable and are cleaned up according to the retention policy.

Access and Limits

Workspace membership controls file access. Signed upload links expire after one hour; signed downloads expire after fifteen minutes. The Dashboard enforces the account storage quota. Cloud MCP accepts files up to 50 MB per attachment.

Never attach credentials, private keys, browser cookies, access tokens, or data that the Workspace policy does not permit to leave the source device.

Archived attachment objects can be permanently cleared only by a user from the Dashboard archive view after manual confirmation.

Storage Layout

TokST stores attachment objects under a scoped key:

{workspace_id}/{atlas_id}/{memory_id}/{attachment_id}-{filename}

The scope prevents cross-Workspace collisions and allows cleanup when a memory or Atlas is removed.

Runtime Boundary

Cloud MCP is the Agent interface for attachments, and the Dashboard is the human interface for file management. The CLI retains device Runtime and export operations.