Attaching a file

When to use

When a research file — a PDF, CSV, notebook, image — should live in the vault attached to a note: importing a paper, capturing a figure, filing a dataset.

Use the tool

limestone_attach_file(collection, note_path, filename, content_base64)

• collection — the collection's id or name.
• note_path — the note's vault-relative path, as returned by limestone_create_row or limestone_get_note.
• filename — what the file should be called, with its extension.
• content_base64 — the file's bytes, base64-encoded.

Attach to a note that already exists. Create one first with limestone_create_row(collection, title) if you need to; it returns the path to pass here.

Allowed: PDFs, CSVs, notebooks and images.

Do not place the file yourself

Never write the bytes into the vault and hand-link them from frontmatter. Where an attachment lives, what its property is called, and how its name is recorded are decisions the tool makes, and they have changed — a note is promoted to its own folder and the file is stored beside its .md (ADR-0037, ADR-0072). A file placed by hand ends up somewhere Limestone does not look, and the user sees a filename where an image should be.

A file you place yourself is also invisible to the vault's activity view, which shows what an agent did by watching the operations, not the filesystem. Work that never went through a tool did not happen as far as the user can see.

If a file is already on disk and the user asked you to keep it — something they dropped into the conversation, or output from a run — read its bytes, base64 them, and attach them with the tool.

If the tool fails, stop

Say what failed and stop. Do not fall back to writing the file yourself.

A hand-written attachment looks finished and is not: it lands where Limestone does not look, the user sees a filename instead of their image, and nothing appears in the vault's activity view. Reporting "done, but I used a different method" hands the user a broken result dressed as a working one. A refusal they can act on is worth more.

Older notes may show a different layout

A vault accumulates history. You may find attachments under <collection>/assets/ with a vault_file wikilink in frontmatter — that layout is retired (ADR-0072) and Limestone no longer reads it. Do not copy a pattern because you found it in the vault; what the vault contains is a record of what happened, not a specification.

Example

row = limestone_create_row(collection="Visuals", title="Smiley")
limestone_attach_file(
    collection="Visuals",
    note_path=row["path"],
    filename="smiley.svg",
    content_base64=<the encoded bytes>,
)

The note appears as a row in Visuals, and opening it previews the attachment.

Tips

• One note per attached file. To replace the file, attach it again with the same filename on the same note.
• The tool returns the updated record; read the path from it rather than constructing one.