Skip to main content
Notes give AI agents and site operators a shared, persistent space to communicate across sessions. An agent that discovers a non-obvious solution can save it so the next agent skips the discovery phase. An operator can leave live instructions that every agent reads at the start of each session. A developer can file a bug report and track it through to resolution — all without leaving the AI workflow.

​
Note types

There are three note types, each with a distinct purpose and its own status lifecycle.

agent-knowledge

Reusable solutions, workarounds, and how-tos that agents discover and save for future use. Reviewed and activated by operators before agents can rely on them.

agent-note

Bug reports, optimization suggestions, and feedback that agents surface to operators. Tracked through a fix-and-verify lifecycle.

operator-note

Authoritative instructions from the operator to agents. Delivered at session bootstrap and obeyed directly.

​
Fields

Every note has the following fields:

​
Status lifecycles

All status transitions are enforced server-side. Invalid transitions are rejected with an error that lists the valid targets from the current state. archived is terminal — no outbound transitions exist from it.

​
agent-note

Used for bug reports, optimization suggestions, and feedback. The lifecycle tracks a note from discovery through fix and verification.
  • open: filed, awaiting review
  • acknowledged: a reviewer has seen it and is looking into it
  • verify: a fix has been applied — the note requires a test to confirm it works before it can be resolved
  • fix: verification failed — back to the fix cycle
  • resolved: fix confirmed by verification
  • archived: terminal; preserves history
Do not skip from acknowledged directly to resolved. Use verify when a fix is in place, then confirm the fix works before resolving. If verification fails, set the status to fix.

​
operator-note

Used for operator instructions to agents. Operators control these statuses — agents must not change them autonomously.
  • review: being drafted by the operator
  • active: the instruction is live and agents must obey it
  • idle: temporarily disabled (e.g. seasonal instruction)
  • archived: permanently retired

​
agent-knowledge

Follows a maker-checker pattern: agents create knowledge notes, but only administrators can change their status (PHP-enforced). Agents must not change agent-knowledge status.
  • review: pending operator approval
  • active: approved and in use — agents see this in bootstrap headers
  • idle: outdated or temporarily disabled
  • archived: permanently retired

​
Notes abilities

​
Creating a note

Start note content with a one-line summary, then add detail. Use bullet points for steps and code blocks for commands, SQL, or file paths. Vague titles make knowledge notes invisible to future agents scanning bootstrap headers.

​
Archiving vs. deleting

Prefer setting status: archived over calling maxi/delete-note. Archived notes preserve history — operators and agents can look back at how a bug was resolved or why a policy was retired. Deletion is permanent and requires manage_options.

​
Reading comments before acting

When reviewing an agent-note, always read its comments — maxi/get-note includes the last 20 automatically. Comments may contain test results, corrections, or context that changes how you should act on the note. Use maxi/list-note-comments when a note has more than 20 comments. Only add a comment when you have new information the note author needs to see. Status changes speak for themselves — do not comment just to say you read a note.