Skip to content

Working with collections

When to use

When you need to add a row to a Limestone collection, set a note's typed properties, or find notes across the vault. Read limestone-vault-conventions first.

How notes map to rows

A collection is a top-level vault folder. Every .md note inside it is one row of the collection's table — including a note that has been promoted to its own folder to hold an attachment, which is still one row. A note's typed property values are frontmatter keys whose names match the collection's columns; the value must fit the column's type (text, number, boolean, date, select, etc.).

Create a note in a collection

Write a Markdown file into the collection's folder. Give it frontmatter with the title and any property values. Example — a new row in the Experiments collection with a text Status:

---
title: Assay 05
limestone_type: note
Status: Reading
tags: [pichia]
---

Body notes.

Save it as Experiments/assay-05.md. It appears as a row immediately (files-as-truth). You do not need to invent a limestone_id — one is assigned.

Set or change a property

Edit the note's frontmatter and re-save. Add the key if it's missing; change the value to update the cell. Use native YAML (Done: true, Count: 42, Due: 2026-08-01). Removing the key clears the cell.

Move a note to another collection

Use limestone_move_note. Do not move the file yourself.

A note belongs to the collection whose folder holds it, so a shell mv of the .md looks like it worked and is not the same thing:

  • a note that holds attachments lives in its own folder (<collection>/<slug>/<slug>.md), and moving only the .md strands that folder and everything in it;
  • its attachment references keep naming where the folder used to be;
  • and none of the refusals apply — into or out of the Trash, a read-only collection, a locked note.

Properties the destination has no column for are not lost either way. By default they are written into the top of the note's body as plain Name: value lines; pass create_missing_properties to add them to the destination as hidden columns instead. Ask the user which they want when it matters.

Query with the Limestone MCP tools

The Limestone MCP server exposes read/query tools (namespaced by your harness, e.g. mcp_limestone_*). Prefer them over guessing at files:

  • list_collections — every collection and its property schema. Start here to learn the exact column names and types before writing values.
  • query_records — a collection's rows (title, path, properties, tags, links, backlinks). Optional filter {property, op: equals|contains, value}.
  • get_note — one note's frontmatter facts + body, by vault path.
  • search — title search across the vault's filed notes.

Typical loop: list_collections to learn the schema → write or edit the .md → query_records to confirm the row and its values.