> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Notes abilities: agent and operator notes in Maxi AI
> Create, update, and comment on persistent notes to share bug reports, how-to knowledge, and live operator instructions across Maxi AI agent sessions.
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
Bug reports, optimization ideas, and feedback from agents to the site operator. Agents create these; operators and dev-agents act on them.
Reusable how-tos, workarounds, and non-obvious solutions. Agents create these for operator review; only admins can activate them (maker-checker pattern).
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` → `resolved`
If 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) → `archived`
Agents 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) → `archived`
Only 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.
```json theme={null}
{
"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:
```json theme={null}
{
"type": "operator-note",
"status": "active"
}
```
List open bug reports while excluding resolved and archived ones:
```json theme={null}
{
"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.
```json theme={null}
{ "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:
```json theme={null}
{
"id": 15,
"status": "acknowledged"
}
```
You can update multiple fields in a single call. Send only the fields you want to change.
```json theme={null}
{
"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.
```json theme={null}
{
"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.