#Pin notes, folders and tools into a task prompt
Type @ in a task's instructions to pin a vault note, a vault folder or a tool, so the agent gets it on every run of that task without having to look for it.
#Pin something
- Open the agent, go to Tasks and open the task.
- In Instruction for this task, type
@after a space or at the start of a line. - A menu opens with two tabs: Knowledge (the notes and folders of the agent's vaults) and Tools. Switch tabs with ← and →, narrow the list by typing, choose with ↑ and ↓ and pin with Enter — or click an entry.
The pin appears as a chip in the text: a note, a folder or a tool, each with its own icon. One Backspace removes the whole chip. The instructions stay readable text around it; save the agent as usual.
The menu offers only what the task may use: vaults attached to the agent and released
for this task under the task's Vault view, and tools released under its Tools view.
An @ inside a word, such as in info@example.com, stays plain text and opens no menu.
Pins work in a task's instructions only. In the agent's own system prompt @ stays
text, because something allowed for the agent may be forbidden in one of its tasks.
#What the agent gets
The pins are resolved again at the start of every run of the task, from the vault as it is at that moment — a note you edit reaches the next run without a redeploy.
flowchart LR
P["Task instructions with pins"] --> R{"Kind of pin"}
R -- "Note, within budget" --> I["Content given in the prompt"]
R -- "Note over budget" --> Ref["Given as a reference — the agent reads it with its vault tools"]
R -- "Folder" --> F["Given as a reference — the list of its notes"]
R -- "Tool" --> T["Given as a reference — the exact tool to use"]
R -- "No longer valid" --> U["Not given — the agent is told it is unavailable"]
| Pin | What the agent receives |
|---|---|
| Note | The note's current content, placed in the prompt |
| Folder | A reference: the notes it contains. The agent reads them itself if it needs them. |
| Tool | A reference to exactly that tool, so the agent knows which one is meant |
#The size limit
Pinned note content is sent with every model call of the run, so it costs tokens every time. Two limits keep that in check:
| Limit | Value |
|---|---|
| One note | 8,000 characters |
| All pinned notes of a task together | 24,000 characters |
A note over the first limit, or one that would push the total over the second, is not dropped: it goes as a reference instead, and the agent can still read it. Notes count in the order they appear in the instructions. Below the field a counter shows how many characters the pinned notes add up to, and turns amber when the total is exceeded.
#When a pin is no longer valid
A pin points at live vault content, so it can break after you set it. The chip then turns amber with a warning sign, its tooltip names the reason, the field gets an amber frame and a line below it lists the affected pins. The same warning appears in the agent's validation.
| Reason | What happened |
|---|---|
| The vault is no longer attached to the agent | Attach it again or remove the pin |
| The vault is not allowed in this task | Release it in the task's Vault view or remove the pin |
| The note was deleted | Pin another note or remove the pin |
| The note exists twice | Two notes share the same address; rename one |
| The folder no longer exists | Pin the new folder or remove the pin |
| The tool no longer exists, or is not allowed in this task | Pin another tool or release it in the task's Tools view |
| The note is too large, or does not fit the budget | Nothing is broken — it goes as a reference |
⚠️ These warnings never block saving or deploying, and Chester never changes or removes a pin by itself — you fix it. At run time a broken pin does not fail the run either; the agent is told the item is unavailable.
⚠️ The warning texts below the field are currently shown in German, whatever language the designer is set to.
Renaming or moving a note does not break its pin. The chip shows the note's current title, and the pin keeps working after the note moves to another folder.
#See what a run was given
The thought loop of each run lists under Pinned every pin with what the agent got: content given, given as a reference, too large (reference only), unavailable, or invalid. See Follow what an agent did in a run.