Write Operator Notes That Change Behaviour

Operator notes are how you tell your agent how to work on your site — your standing instructions, in your own words. This guide covers writing one, putting it into effect, and changing or retiring it later. You do all of this by talking to your agent.

An operator note is a standing instruction the agent reads at the start of every session and follows. It’s the main lever you have for shaping behaviour: how the agent should act (“always save new posts as drafts for me to review”), the tone it should use, and the specifics of how your site works (“our products use a custom field called vintage_year — always set it”). If you haven’t yet, The Notes System explains how notes fit together; this guide is the practical how-to.

Everything here is done by asking your agent in plain language — operator notes are managed through conversation, the same way you do everything else with Maxi.

Draft first, then active

This is the one mechanic worth understanding up front. An operator note has a status, and only one — active — actually reaches the agent. A note starts life as a draft, meaning you’ve written it but the agent isn’t following it yet. It takes effect only once it’s set to active.

So putting a note in place is two steps: write it, then activate it. That separation is deliberate — it lets you draft and refine an instruction before it goes live, instead of every half-formed thought immediately steering the agent.

Writing a note

Just ask. For example:

“Create an operator note: always confirm with me before changing any product price.”

The agent writes the note for you. It’s especially natural to do this right after you’ve worked something out together — you’ve just figured out how a task should go, so you capture it as a standing rule on the spot (see working it out together). The note is saved as a draft.

Activating it

A freshly written note is a draft — the agent won’t put it into force on its own. Instead, once it’s written, the agent will ask you whether to activate it. You confirm, and the note goes live. That confirmation is the whole point: an instruction only takes effect when you’ve explicitly agreed to it, right there in the conversation.

A newly activated operator note takes effect immediately on the next prompt — even in a conversation that’s already running. Every ability response includes an operator_notes_revision counter, and if it has incremented since bootstrap, the agent automatically refreshes its operator notes before the next tool call. You don’t need to start a new conversation.

Tip: if the agent doesn’t seem to be following a note you wrote, it’s almost always because the note is still a draft/review. Confirm it’s active, then repeat your request.

Writing notes that work well

• Be specific and concrete. “Use a friendly tone” is weaker than “Write product descriptions in a warm, conversational tone; avoid technical jargon.”
• One instruction per note. Separate notes are easier to edit, pause, or retire individually than one long combined note.
• Say what to do, not just what to avoid. “Save new posts as drafts for review” is clearer than “don’t publish things.”
• Describe your site’s specifics. Notes are where the agent learns your custom fields, your categories, your conventions — the things a general-purpose agent can’t know on its own.

Changing, pausing, or retiring a note

All by asking the agent:

• Edit it any time — ask the agent to change what it says. An updated active note takes effect in your next conversation.
• Pause it — ask the agent to set it to idle, and confirm. The agent stops following it, but it’s kept so you can switch it back on later. Good for temporary rules.
• Retire it — ask the agent to archive it, and confirm. Permanently put away, but preserved for the record. Prefer archiving over deleting, so your history stays intact.

As with activation, turning a note on or off is something you confirm — the agent won’t change whether a note is in force without your say-so.

In summary: an operator note is a standing instruction the agent follows. You manage notes by talking to your agent: ask it to write one, and it’ll ask you to confirm before making it active — your confirmation is what puts it in force. Once active, it takes effect in your next conversation. Keep notes specific and single-purpose, and use idle to pause or archived to retire them.