> ## 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.

# How agent notes and operator notes work in Maxi AI

> Notes are a persistent communication system between agents and operators — covering bug reports, reusable knowledge, and live operator instructions.

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.

<CardGroup cols={3}>
  <Card title="agent-knowledge" icon="lightbulb">
    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.
  </Card>

  <Card title="agent-note" icon="flag">
    Bug reports, optimization suggestions, and feedback that agents surface to operators. Tracked through a fix-and-verify lifecycle.
  </Card>

  <Card title="operator-note" icon="bullhorn">
    Authoritative instructions from the operator to agents. Delivered at session bootstrap and obeyed directly.
  </Card>
</CardGroup>

## Fields

Every note has the following fields:

| Field         | Values                                                                                                          |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `type`        | `agent-knowledge`, `agent-note`, `operator-note`                                                                |
| `status`      | Depends on type — see lifecycles below                                                                          |
| `topic`       | `bug`, `optimization`, `how-to`, `policy`, `warning`, `feedback`                                                |
| `priority`    | `low`, `normal`, `high`, `critical`                                                                             |
| `assigned_to` | WordPress user ID (optional). When set, only that agent should act on the note. `null` means any agent can act. |

## 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 → acknowledged → verify → resolved
                    ↘         ↙
                      fix ←──┘
          (any state) → archived
```

* `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

<Warning>
  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`.
</Warning>

### operator-note

Used for operator instructions to agents. Operators control these statuses — agents must not change them autonomously.

```
review → active ↔ idle
  (any state) → archived
```

* `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 → active ↔ idle
  (any state) → archived
```

* `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

| Ability                   | Description                                                                                                                                           | Minimum capability  |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `maxi/create-note`        | Create a note with type, title, content, and optional topic, priority, and assigned\_to.                                                              | `is_user_logged_in` |
| `maxi/list-notes`         | List notes with filters for type, status, topic, priority, assigned\_to, or free text. Supports `exclude_status` to hide resolved and archived notes. | `is_user_logged_in` |
| `maxi/get-note`           | Read a single note by ID, including the last 20 comments.                                                                                             | `is_user_logged_in` |
| `maxi/update-note`        | Update a note's title, content, status, topic, priority, or assignment. Status transitions are enforced per type.                                     | `is_user_logged_in` |
| `maxi/delete-note`        | Permanently delete a note. Prefer archiving instead.                                                                                                  | `manage_options`    |
| `maxi/add-note-comment`   | Append a comment to a note. Use to add test results, corrections, or context. Comments are append-only.                                               | `is_user_logged_in` |
| `maxi/list-note-comments` | List all comments on a note in chronological order. Use when a note has more than 20 comments.                                                        | `is_user_logged_in` |

## Creating a note

```json theme={null}
{
  "type": "agent-note",
  "title": "list-products returns incorrect count when filtering by stock status",
  "content": "When calling maxi/list-products with stock_status=outofstock, the returned total count includes in-stock items. Steps to reproduce: ...",
  "topic": "bug",
  "priority": "high"
}
```

<Tip>
  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.
</Tip>

## 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.