Notes abilities: agent and operator notes in Maxi AI

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

Ability	Description	Capability	Plan
`maxi/create-note`	Create a note of any type. Types: `agent-knowledge`, `agent-note`, `operator-note`. Optional topic, priority, and `assigned_to` (WordPress user ID).	`is_user_logged_in`	Lite
`maxi/list-notes`	List 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_in`	Lite
`maxi/get-note`	Read a single note by ID, including its last 20 comments.	`is_user_logged_in`	Lite
`maxi/update-note`	Update a note’s title, content, status, topic, priority, or assignment. Status transitions are PHP-enforced per note type.	`is_user_logged_in`	Lite
`maxi/delete-note`	Permanently delete a note. Prefer `status: archived` to preserve history.	`manage_options`	Lite
`maxi/add-note-comment`	Append a comment to a note. Use for test results, clarifications, or corrections. Comments are append-only.	`is_user_logged_in`	Lite
`maxi/list-note-comments`	List comments on a note in chronological order. Use when a note has more than 20 comments and you need to paginate.	`is_user_logged_in`	Lite

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.

agent-note
operator-note
agent-knowledge

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.

review (drafting) → active (live instruction) ↔ idle (temporarily disabled) → archivedAgents must not change operator-note status autonomously. Only the operator moves notes through this flow.

review (pending approval) → active (approved, use this) ↔ idle (outdated or disabled) → archivedOnly administrators can change agent-knowledge status — this is PHP-enforced. Agents create knowledge notes at review; operators approve them by setting status to active.

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.

Overview

Content & Media

AI Generation

WooCommerce

System & Dev

Notes abilities: agent and operator notes in Maxi AI

All notes abilities

Note types

agent-note

agent-knowledge

operator-note

Status flows

Key ability examples

maxi/create-note

maxi/list-notes

maxi/get-note

maxi/update-note

maxi/add-note-comment

Surfacing friction and saving knowledge

assigned_to field

​All notes abilities

​Note types

agent-note

agent-knowledge

operator-note

​Status flows

​Key ability examples

​maxi/create-note

​maxi/list-notes

​maxi/get-note

​maxi/update-note

​maxi/add-note-comment

​Surfacing friction and saving knowledge

​assigned_to field

All notes abilities

Note types

Status flows

Key ability examples

maxi/create-note

maxi/list-notes

maxi/get-note

maxi/update-note

maxi/add-note-comment

Surfacing friction and saving knowledge

assigned_to field