Operations

Everything an agent can ask Limestone to do, whether it is the agent in the app or one connected over MCP. Each is exposed as limestone_<name>.

Generated from contract/operations.py, which is the same registry the MCP server builds its tools from — so this page cannot describe an operation that does not exist, or miss one that does.

limestone_attach_file

writes · needs an unlocked vault

Attach a base64-encoded file to a note, linked via a vault_file property. FOR CONTENT THAT IS NOT IN THE VAULT YET.

To link a file the vault already holds — anything limestone_create_notebook or limestone_write_note_file returned a path for — use limestone_set_property with that path instead. Sending the bytes back through here re-writes a file that is already there, and puts its whole contents through your context on the way.

parameter	meaning
collection	A collection id or name.
note_path	The note's vault-relative path.
filename	The attachment's file name (allowed: .pdf, .csv, .ipynb, images).
content_base64	The file's contents, base64-encoded.

limestone_capture_environment

writes · needs an unlocked vault

Write down what an environment contains, so another machine can rebuild it.

Writes requirements.txt + requirements.lock.txt into the vault's Environments collection. Pass interpreter to record an environment Limestone did NOT build (a conda env the user already had): its packages are read and written down, and nothing is installed into it.

parameter	meaning
name	The environment to record.
interpreter	Optional absolute path, to capture an environment we did not build.

limestone_create_collection

writes · needs an unlocked vault

Create a collection (a vault sub-folder) with an optional property schema.

parameter	meaning
name	The collection name.
properties	Optional list of {"name": …, "kind": …} property definitions.

limestone_create_environment

writes

Create a new, empty Python environment for this vault.

Use this when the user's work needs packages that no existing environment has — build one for the task rather than installing into theirs. Then add packages with limestone_install_packages and select it with limestone_set_environment.

parameter	meaning
name	A short name of your choosing, e.g. "rna-seq" — letters, digits, dashes and underscores only. This is a new name, not one from limestone_list_environments: to use an environment that already exists, pass its environment value to limestone_set_environment instead.

limestone_create_notebook

writes · needs an unlocked vault

Create a notebook (.ipynb) in a note's folder. Returns the notebook's path, the note's note_path — which MOVES if this is the first file in a flat note's folder — and the cell count.

To make the app open it in the notebook editor, link it with limestone_set_property: pass the returned path as the value of the collection's vault_file property (often "Attachment"). No bytes, no re-upload — the file is already in the vault. Then run it with limestone_run_notebook.

parameter	meaning
note_path	The vault-relative path of the note whose folder to create it in.
filename	A bare file name ending in .ipynb, e.g. 'analysis.ipynb'.
cells	Ordered list of {"cell_type": "code"

limestone_create_row

writes · needs an unlocked vault

Add a row (a note) to a collection with an optional Markdown body.

Use body for prose deliverables (protocols, write-ups) — the content lives in the note itself, not a notebook.

parameter	meaning
collection	A collection id or name.
title	The row's title.
body	Optional Markdown body (the note's prose content).
values	Optional {property_name: value} map of typed properties.

limestone_delete_account

REFUSED — deleting an account cannot be undone, so no agent does it. Calling this returns the place the user goes instead: Settings ▸ Danger Zone ▸ Delete account, which asks them to type the name first.

It exists so that asking has an answer (ADR-0227 §3). A capability that is merely absent invites a way round it.

limestone_delete_environment

writes · needs an unlocked vault

Delete an environment Limestone built, reclaiming its disk.

Managed environments only — never one found on the machine, which belongs to the user. The spec stays in the vault, so it can be rebuilt with limestone_recreate_environment. Reports which notebooks are now bound to something absent.

parameter	meaning
name	The managed environment's name.

limestone_delete_organization

REFUSED — deleting an organization cannot be undone, so no agent does it. Calling this returns the place the user goes instead: Settings ▸ Danger Zone ▸ Delete organization, which asks them to type the name first.

It exists so that asking has an answer (ADR-0227 §3). A capability that is merely absent invites a way round it.

limestone_delete_row

writes · needs an unlocked vault

Delete a note (row) by moving it to Limestone's Trash — a reversible soft-delete, NOT a permanent removal. The note keeps its identity and the user can restore it from the Trash in the app (a 30-day window). Use this when the user asks to delete or remove an entry; never tell the user to delete files by hand or through another app — the vault is worked through Limestone. Refuses a locked note and a note already in Trash.

parameter	meaning
path	The note's vault-relative path.

limestone_delete_vault

REFUSED — deleting a vault cannot be undone, so no agent does it. Calling this returns the place the user goes instead: Settings ▸ Danger Zone ▸ Delete vault, which asks them to type the name first.

It exists so that asking has an answer (ADR-0227 §3). A capability that is merely absent invites a way round it.

limestone_edit_note_file

writes · needs an unlocked vault

Replace an exact snippet in a file in a note's folder.

find must appear EXACTLY ONCE. If it is missing or appears more than once, the file is left untouched and the error says which — a refusal is recoverable and a wrong edit in a synced folder is not.

Read the file first (limestone_read_file) so find matches its text exactly, including indentation.

parameter	meaning
note_path	The vault-relative path of the note.
filename	The file in that note's folder.
find	The exact text to replace. Must occur once.
replace	What to put in its place.

limestone_edit_notebook_cell

writes · needs an unlocked vault

Replace one cell's source in a notebook, leaving every other cell alone.

This is how a notebook is edited. Do NOT rewrite one with limestone_create_notebook — it refuses a path that exists, and serializing .ipynb JSON by hand loses cells, outputs and ids.

Cells are numbered from 0. The write carries the revision just read, so it cannot overwrite an edit made in the app in between.

parameter	meaning
notebook_path	The vault-relative path of the .ipynb.
cell_index	Which cell to replace, numbered from 0.
source	The cell's new source.

limestone_file_attachment

writes · needs an unlocked vault

Documented with its handler rather than here: this operation is declared for classification and its surfaces are hand-written.

limestone_get_note

needs an unlocked vault

Read a note's frontmatter facts and body.

parameter	meaning
path	The note's vault-relative path.

limestone_get_notebook_environment

needs an unlocked vault

Where a notebook will run, and why there.

Ask this before concluding anything about why a notebook failed. A notebook runs in the environment it is bound to; one bound to nothing runs in the vault default, which is a different environment and a common surprise. source says which: notebook / vault / fallback. unowned means no note owns the file, so it cannot hold a binding at all.

parameter	meaning
notebook_path	The vault-relative path of the notebook.

limestone_import_notebook

writes · needs an unlocked vault

Import a notebook-app export into a new collection, returning a summary to finalize. Accepts a file (Evernote .enex), a folder (an Obsidian vault), or an archive (a Notion .zip). Does the whole bulk conversion in one call — never import notes one at a time. Load the importing-from-<app> skill first, then finalize the unconverted items.

parameter	meaning
collection_name	Name for the new collection (defaults to the source name).
path	Absolute path to the export file or folder on this machine.

limestone_install_packages

writes

Install Python packages into an environment you created.

Only environments Limestone manages can be installed into — not the system Python, not a conda environment, and not the app's own runtime. That is deliberate: those belong to the user or are replaced on update. Create one with limestone_create_environment first.

parameter	meaning
environment	The managed environment's name.
packages	Package specs, e.g. ["pandas", "scipy==1.14.1"].

limestone_list_agents

Which agent runs in Limestone's dock, and which others this machine has. Each says whether it is installed and runnable right now; one that is not installed is still a legal choice.

limestone_list_collections

List every Limestone collection with its property schema.

limestone_list_environments

List the Python environments available on this machine for running notebooks.

Use this before running a notebook, to see whether the current environment can actually run it.

Two separate facts, and you need both. can_run_notebooks is whether the environment has a kernel (ipykernel) — an environment without one runs nothing at all, so never select it. has_data_science is whether numpy and pandas import, the usual proxy for a real analysis environment. An environment can have a kernel and no analysis packages, which is fine and is what a fresh Limestone environment looks like; install into it.

is_current marks the one this vault is configured to use.

limestone_list_note_folder

needs an unlocked vault

The files in a note's own folder, by name.

A note's folder is where its files live — attachments, images it embeds, and anything a run saved. Read this before changing anything in it. A note with no folder returns an empty list rather than an error.

parameter	meaning
note_path	The vault-relative path of the note.

limestone_list_settings

List Limestone's user-level settings, their values and choices.

limestone_load_skill

needs an unlocked vault

Load one skill's full instructions on demand (progressive disclosure).

The agent's brief advertises each skill's name + description; when a task matches one, call this to read its full SKILL.md procedure before acting. Returns the skill's instructions plus the paths of its bundled files (scripts/references), which you can reference by path.

parameter	meaning
name	The skill's advertised name (or its folder name).

limestone_lock_note

writes · needs an unlocked vault

Lock a note so it can no longer be edited through Limestone — protect data once it's recorded, so a later mistake (yours included) can't change it. A locked note rejects all further edits. You can lock but CANNOT unlock; unlocking is a deliberate user action.

parameter	meaning
path	The note's vault-relative path.

limestone_move_note

writes · needs an unlocked vault

Move a note into another collection. A note belongs to the collection whose folder holds its file, so this is the ONLY correct way to change it — never move a note's file with a shell command or another app. A bare mv looks like it worked and is not the same thing: a note holding attachments lives in its own folder and moving only the .md strands that folder, its attachment references keep naming where they used to be, and the checks below are skipped.

Properties the destination has no column for do not disappear. By default they are written into the top of the note's body as plain Name: value lines; with create_missing_properties they become hidden columns on the destination instead. Ask the user which they want when it matters.

Refuses a locked note, a move into or out of the Trash (delete and restore own those), a read-only collection, and the collection the note is already in.

parameter	meaning
path	The note's vault-relative path.
collection	The destination collection's name or id.
create_missing_properties	Add the note's unmatched properties to the destination as hidden columns, instead of writing them into the note's body. Default false.

limestone_query_records

needs an unlocked vault

Query a collection's rows (title, path, properties, tags, links).

parameter	meaning
collection	A collection id or name (e.g. "Experiments").
filter	Optional {"property": name, "op": "equals"

limestone_read_file

needs an unlocked vault

Read a vault file's contents by its vault-relative path.

parameter	meaning
path	The file's vault-relative path.

limestone_recreate_environment

writes · needs an unlocked vault

Build an environment on this machine from what the vault recorded.

For a vault opened somewhere new: the spec travels with the folder and the venv does not. Reports which file it built from — the lock reproduces exact versions, the requirements file does not.

parameter	meaning
name	The environment to rebuild.

limestone_remember

writes · needs an unlocked vault

Keep a durable fact about the user or their work in the vault's Memory, so you still have it in a later session.

For things that stay true — how they like to work, what their project is, a decision they have made. Not for the contents of this conversation, and not for anything you can read from the vault when you need it.

A title already in Memory is REPLACED, so reuse one to revise a fact.

parameter	meaning
title	A short, stable name for the fact — the memory's identity.
fact	The fact itself, in a sentence or two.

limestone_run_notebook

writes · needs an unlocked vault

Run a vault .ipynb locally; returns status + summary. Inline outputs stay in the notebook; files the script saves become attachments on the notebook's note.

parameter	meaning
notebook_path	The vault-relative path of the notebook to run.

limestone_search

needs an unlocked vault

Search note titles and bodies, best matches first, each hit with a snippet.

parameter	meaning
query	Text to match.
scope	Where to match: "all" (titles and bodies) or "title".
limit	Maximum number of hits to return.

limestone_set_agent

writes

Hand Limestone's dock to another agent — including this one's own replacement. Undone by choosing again, which is what makes it something an agent may do (ADR-0227).

parameter	meaning
agent_id	An id from limestone_list_agents, e.g. "limestone" or "claude-code". Anything else is refused with the list.

limestone_set_environment

writes

Set the vault-wide DEFAULT environment, used by notebooks that are not bound to one of their own. To give a single notebook its own environment — usually what is wanted — use limestone_set_notebook_environment.

parameter	meaning
name	A managed environment's name (one you created with limestone_create_environment), or an absolute path to a Python interpreter from limestone_list_environments. The choice is written to the vault, so it travels with the folder.

limestone_set_note_body

writes · needs an unlocked vault

Overwrite a note's Markdown body; frontmatter is preserved.

parameter	meaning
path	The note's vault-relative path.
body	The new Markdown body (the note's prose content).

limestone_set_notebook_environment

writes · needs an unlocked vault

Bind ONE notebook to an environment, leaving every other notebook alone.

Not limestone_set_environment, which sets the vault-wide default. Use this when a particular notebook needs particular packages.

parameter	meaning
notebook_path	The vault-relative .ipynb.
environment	A managed environment's name, or an absolute interpreter path for one already on the machine. Empty clears the binding.

limestone_set_property

writes · needs an unlocked vault

Set one typed property value on a note.

parameter	meaning
collection	A collection id or name.
path	The note's vault-relative path.
name	The property name.
value	The new value.

limestone_set_setting

writes

Change one of Limestone's user-level settings, e.g. the display theme.

parameter	meaning
name	The setting, exactly as limestone_list_settings names it (e.g. "theme").
value	Its new value — one of that setting's choices, or true/false.

limestone_show_note

opens it in your window · needs an unlocked vault

Open a note in the person's window. Changes nothing.

Use this when they ask to see something — limestone_get_note reads a note to you, this one shows it to them. Before this existed the only way to make a note open was to write to it, which is a destructive way to answer 'show me that'.

It does nothing visible unless they have turned on Follow agent activity, which is theirs to decide and not worth asking about: the call is harmless either way.

parameter	meaning
note_path	The note's vault-relative path.

limestone_speak

writes

Read something aloud on this machine, in the voice the user chose. Only while the user has Read aloud switched on.

parameter	meaning
text	What to say. Plain words — it is spoken, not displayed.

limestone_write_note_file

writes · needs an unlocked vault

Write a text file into a note's folder, creating or replacing it.

Use this for a NEW file. To change part of one that exists, use limestone_edit_note_file — rewriting a whole file from memory is how content gets dropped.

The file is NOT attached to the note. The attachment property is a claim about which file matters, not an inventory of the folder: a project has many files and one of them is the point. Attach that one deliberately with limestone_attach_file.

parameter	meaning
note_path	The vault-relative path of the note whose folder to write in.
filename	A bare file name, e.g. 'helper.py' — one level, no directories.
content	The file's full text.