Skip to main content
Notes are a persistent, structured communication system built into Maxi AI Core. Agents use notes to surface bug reports and optimization ideas, save reusable solutions for future sessions, and read live instructions from site operators. All notes abilities are available on the Lite plan.

​
All notes abilities

AbilityDescriptionCapabilityPlan
maxi/create-noteCreate a note of any type. Types: agent-knowledge, agent-note, operator-note. Optional topic, priority, and assigned_to (WordPress user ID).is_user_logged_inLite
maxi/list-notesList and search notes. Filter by type, status, topic, priority, or free-text search. Supports exclude_status and assigned_to: 0 for unassigned notes. Paginated.is_user_logged_inLite
maxi/get-noteRead a single note by ID, including its last 20 comments.is_user_logged_inLite
maxi/update-noteUpdate a note’s title, content, status, topic, priority, or assignment. Status transitions are PHP-enforced per note type.is_user_logged_inLite
maxi/delete-notePermanently delete a note. Prefer status: archived to preserve history.manage_optionsLite
maxi/add-note-commentAppend a comment to a note. Use for test results, clarifications, or corrections. Comments are append-only.is_user_logged_inLite
maxi/list-note-commentsList comments on a note in chronological order. Use when a note has more than 20 comments and you need to paginate.is_user_logged_inLite

​
Note types

agent-note

Bug reports, optimization ideas, and feedback from agents to the site operator. Agents create these; operators and dev-agents act on them.

agent-knowledge

Reusable how-tos, workarounds, and non-obvious solutions. Agents create these for operator review; only admins can activate them (maker-checker pattern).

operator-note

Live instructions from the site operator to all agents. Agents read and follow these — they must not change their status autonomously.

​
Status flows

Status transitions are enforced in PHP. Passing an invalid transition returns an invalid_transition error with the list of valid targets from the current state. The archived status is terminal — no further transitions are possible.
open → acknowledged → verify → resolvedIf verification fails: verify → fix → verify (loops until resolved)archived is reachable from any state and is terminal.When you receive an agent-note bug report, acknowledge it on read to signal it has been seen. Use verify when a fix is in place — you must confirm the fix works before moving to resolved. If the fix doesn’t hold, set status to fix and loop back.

​
Key ability examples

​
maxi/create-note

Create an agent-note to report a bug or unexpected behavior you encountered during a task. 
{
  "type": "agent-note",
  "title": "list-products returns stale data after bulk update",
  "content": "After calling bulk-update-products, a subsequent list-products call returns old prices for ~2s. Appears to be object cache.\n\nWorkaround: call maxi/flush-cache after bulk updates.",
  "topic": "bug",
  "priority": "normal"
}
Valid values for topic: bug, optimization, how-to, policy, warning, feedback. Valid values for priority: low, normal, high, critical.
Use clear, specific titles. Knowledge-note titles are matched against the current task at the start of each session — vague titles make notes invisible to future agents.

​
maxi/list-notes

Retrieve active operator instructions at the start of a session: 
{
  "type": "operator-note",
  "status": "active"
}
List open bug reports while excluding resolved and archived ones: 
{
  "type": "agent-note",
  "exclude_status": ["resolved", "archived"]
}
Use assigned_to: 0 to filter for unassigned notes, or pass a WordPress user ID to see notes assigned to a specific agent.

​
maxi/get-note

Read a single note by its ID. The response includes the note’s full content and its last 20 comments. 
{ "id": 15 }
When reviewing an agent-note, always read its comments before acting. Comments may contain test results, corrections, or context that changes how you should respond to the note.

​
maxi/update-note

Acknowledge an agent-note after reading it: 
{
  "id": 15,
  "status": "acknowledged"
}
You can update multiple fields in a single call. Send only the fields you want to change. 
{
  "id": 15,
  "status": "verify",
  "priority": "high"
}
A status transition requires that you have called maxi/get-note for that note in the current session first. Each successful transition consumes the read flag — you must re-read the note before the next status change. This prevents blind status updates without reviewing the current state.

​
maxi/add-note-comment

Append a comment to a note when you have new information — test results, a clarification, or a correction. 
{
  "note_id": 15,
  "content": "Confirmed: flushing object cache after bulk-update resolves the stale data issue."
}
Comments are append-only and cannot be edited or deleted. Use comments to add context, not just to acknowledge you read a note — status changes already communicate that.

​
Surfacing friction and saving knowledge

After completing a task, you may encounter two situations worth flagging to the operator: Friction you hit. If a task felt inefficient, repetitive, or required an unexpected workaround, mention it in your response and offer to log an agent-note with topic bug or optimization. Do not create the note autonomously — let the operator decide whether to log it. Problems you solved the hard way. If you worked through a non-obvious task and found a solution, offer to save it as an agent-knowledge note. Future agents will find it via bootstrap knowledge-note headers and skip the discovery phase.
The quality bar for offering a note: would you mention this friction casually to a colleague? If yes, offer to log it. Mechanical offers for every micro-inefficiency become noise the operator stops reading.

​
assigned_to field

The assigned_to field accepts a WordPress user ID. When set, only the agent running as that user should act on the note. A null value means any agent can act on it. Use maxi/get-current-user to find your current WordPress user ID. Your agent identity is agent-{user_id}@{site_slug} — use this format when authorship matters in note content or comments.