Documents and preferences
When you want later agents to retain a fact or follow an instruction, read this page because it explains who owns a saved document and how to inspect or revise it.
You can give future agents useful context without pasting the same background into every conversation. Ask an agent to save a durable fact or instruction, then inspect the saved document yourself from the terminal.
A saved note is a document, one kind of object on your canvas. It has an owner, a name of the form <owner>/<path>, a one-line preview, and recorded revisions, and other documents or messages point at it as [[name]]. The agent saves it by running crtr doc write; you find, read and watch documents with crtr canvas.
Tell an agent what should persist
Say what should be saved and where it applies.
| If you want to save | Tell the agent |
|---|---|
| A fact or procedure | “Remember that our staging database is reset every Friday.” |
| An instruction about how to work | “Remember that I want a short recommendation before any production change.” |
| Something for every project you use | “Remember this as a user preference.” |
| Something only agents in this repository need | “Remember this for this project.” |
A preference tells an agent how to act. Knowledge gives it facts or a procedure to consult. The narrowest useful owner is best: a document you own follows you everywhere, while a document a repository owns belongs to that one repository. For the explanation of document owners and loading, see Documents.
Browse what was saved
List the documents you can read, optionally narrowed with --kind, --owner, --privacy or --name <prefix>:
crtr canvas list --type documentRead one by its name from that list:
crtr canvas read <name>crtr canvas read resolves a bare name by looking first at the reading node's own documents, then its repos (nearest first), its profile and app, then your own documents, installed plugins, and crouter's built-in documents last. Write <owner-handle>/<path> to name one owner's document exactly, and use crtr canvas search to find one by its text. Reading a document also makes you a watcher of it, so its later edits reach you; list and search record nothing.
Edit a document
Document revisions are intentional and recorded. To replace a document's body, pipe the complete replacement text to crtr doc edit and give the reason for the revision:
printf '%s\n' 'Production changes need an explicit approval.' | \
crtr doc edit <name> --rationale "Updated the approval rule."crtr doc edit replaces the whole body you pipe; it does not append text. For a partial change, use crtr doc edit <name> --rationale '…' --blocks <<'EOF' with whole-line <<<<<<< SEARCH, =======, and >>>>>>> REPLACE markers around verbatim old and new text. An empty REPLACE deletes text. Scripts can still use --replace '[{"old":"…","new":"…"}]'. Read the document before you edit it; an edit made from an older revision is refused. Use crtr doc history <name> to read the revision history. If you want to create a document yourself, use crtr doc write; it takes a name, a preview sentence that tells agents when to read it, and the document body on stdin. --kind knowledge|preference (default knowledge) sets how agents use it, and --owner node|user|profile|app|repo chooses who owns it (default: the writing node; profile:<name> and repo:<handle> name a specific one). New documents are privacy: public unless --privacy friends or --privacy private is supplied; a repository owns only public documents. crtr doc edit --privacy <level> changes the level. An edit that changes only fields (privacy, preview, summary, rules, --why-it-exists) takes effect at once but makes no new revision: revisions are versions of the body, so the revision number does not move and crtr doc history shows nothing for it.
Documents are for reusable current truth and durable instructions, not a transcript of one conversation. When a fact changes, update the existing document rather than saving a second version.
Answering agents in the human inbox
When an agent needs your decision or review, read this page because it explains the inbox pages it sends and how your answer resumes its work.
The official plugin marketplace
When you want to know which plugins crouter ships in its official marketplace, or how to install one, read this page because it lists each plugin with what it adds and what it needs on your machine.