Caute

Your library as a folder for coding agents

Claude Code, Cursor, Codex and any other agent that works from files can use a Caute library with no connection to Caute at all. caute sync keeps the library in a folder, in the card format: notes as Markdown, and everything else as an item.json beside its original. An agent reads it the way it reads code.

Set it up

npm install -g @caute/cli
caute login --sync
caute sync ~/"Caute Library" --agents --watch

--sync asks for permission to edit notes, which keeping a folder in step needs, and to apply tags, so a hashtag in a note written in the folder becomes a tag as it would in the app. (A folder signed in before @caute/cli 0.3.1 can't tag; caute sync says so, and caute login --sync again fixes it.) --agents adds a section to the folder's README.md that tells an agent how to use it, in the words an agent reads, so an agent that lists the folder learns the rules before it touches anything. It is remembered: later syncs keep it. --watch keeps going, so a note written in the folder reaches Caute within seconds, and changes in Caute arrive within a minute.

What is in the folder

  • items/<id>/item.json: one per saved thing that isn't a note: its title, url, summary, text (what was read from the original), properties (facts the person confirmed, such as a DOI or a due date) and capture (when and how it was caught, with a fingerprint of the original), and its tags. Beside it, original.<ext>, the file itself.
  • notes/: the person's notes, as Markdown. Links to cards are paths into items/.
  • highlights.md and highlights.json: every passage the person marked, with its card.
  • tags.json: every tag with the ids of its cards and notes, so an agent can gather everything under projects/atlas without asking Caute.
  • links.json, saved_searches.json and manifest.json: how things are connected.

Everything in items/ is read-only (mode 0444).

Point your agent at it

Put this in the CLAUDE.md (Claude Code) or AGENTS.md (Codex, Cursor and others) of the project the agent works in, with the folder's real path:

## My Caute library

My saved reading is kept in step at ~/Caute Library by `caute sync`. When a question touches what I've read or
saved, search ~/Caute Library/items/*/item.json (its `text`, `title`, `summary` and `properties`) and
~/Caute Library/notes/, and name the file you used. Read that folder's README.md first. Never change anything in
items/. To leave me a note, write a new .md file in notes/ with #agent/claude-code in it.

The one rule

An agent may write notes: a new .md file in notes/ becomes a note in Caute on the next sync. It is saved as the person, through their own sync sign-in, so ask the agent to put #agent/<its name> in every note it writes (#agent/claude-code, #agent/cursor). The hashtag becomes a tag in Caute, so the person can tell the agent's notes from their own and find them all on that tag. An agent shouldn't edit the person's existing notes unless they ask: an edit is saved as theirs.

An agent must never edit a card's files. They are what was caught, which is why they are read-only. A change forced into one changes nothing in Caute (the original there never changes), and the next caute sync --refresh names the file and puts it back:

Put back items/0190f3a2-…/original.pdf: it had been changed here. A card's files are what was caught, so nothing changed in Caute.

caute verify ~/"Caute Library" checks every original against the record of its catch at any time.

The folder or MCP

For agents that take an MCP server, Caute is one too: see MCP. In Claude Code:

claude mcp add --transport http caute https://mcp.getcaute.com/mcp

or, for an app that can only start a local program, @caute/mcp with a personal token.

Use the folder when Use MCP when
The agent should read widely: grep across everything, open whole documents, compare many cards. The agent needs Caute's search by meaning, gather (the best passages for a task, within a token budget) or recall (what assistants remember).
It has to work offline, or without giving the agent any Caute credential. It should save things to the library: pages, files, conversations, memories.
You want the agent to see exactly what is on disk, and nothing it can't. You want each read and write recorded in Caute against the agent's own name, and limited to the spaces you chose for it.

Both can be used together: the folder for reading, MCP for saving and for gather.