> ## 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 Maxi AI Core tracks agent sessions and context

> Every agent connection to Maxi AI Core is a session. Bootstrap is required first and delivers the playbook, operator notes, and knowledge note headers.

Every time an AI agent connects to Maxi AI Core, it starts a session. A session is the active connection between the agent and your WordPress site, tracked for the duration of that conversation or automation run. Sessions carry identity, ability acknowledgements, and live-refresh state — so the agent always operates with up-to-date instructions without needing to re-read everything on every call.

## Starting a session

Every session must begin with `maxi/bootstrap-session`. This is server-enforced — all other abilities are blocked until the bootstrap call is acknowledged.

<Warning>
  Calling any ability other than `maxi/bootstrap-session`, `maxi/get-ability-rule`, or `maxi/rules-sync` before bootstrap will be rejected. There is no way to bypass this requirement.
</Warning>

Bootstrap returns four things:

<Steps>
  <Step title="Operational playbook">
    The behavioral rules, content guards, and workflows the agent must follow on this site. This is the authoritative reference for how the agent should operate.
  </Step>

  <Step title="Active operator notes">
    Live instructions from the site operator. These are authoritative — the agent reads and obeys them directly. Operator notes take precedence over any default behavior.
  </Step>

  <Step title="Knowledge note headers">
    A list of `agent-knowledge` notes with id, title, topic, and priority. Agents scan these titles before starting a task. If a title matches the task, the agent fetches the full note with `maxi/get-note` and applies the documented solution — avoiding re-solving problems that are already figured out.
  </Step>

  <Step title="Available reference docs">
    On-demand playbooks that can be fetched with `maxi/get-playbook` when the task requires deeper reference material.
  </Step>
</Steps>

## Session identity

How a session is identified depends on your authentication method.

| Auth method           | Session identity                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| OAuth 2.1             | One session per OAuth grant (client + user pair). The same client connecting as the same user resumes the same session context. |
| Application passwords | One session per `Mcp-Session-Id` header. Clients that send a stable header value keep a consistent session across requests.     |

## Ability acknowledgements

When an agent acknowledges an ability rule (by reading and retrying through a `reject_first` gate, or by receiving a rule on an `inline_on_success` call), that acknowledgement is stored for the session. The rule is not re-delivered on subsequent calls to the same ability in the same session.

If an operator updates a rule's content mid-session, its version bumps. The next call to that ability re-delivers `_meta._rule` — treat this as "the rule just changed, re-read it."

## Live refresh for operator notes

After bootstrap, every ability response includes `_meta.operator_notes_revision`. The agent records the value from bootstrap as its baseline. If a later response carries a higher revision number, the agent refreshes operator notes before the next tool call:

```json theme={null}
{
  "_meta": {
    "operator_notes_revision": 4
  }
}
```

To refresh, call `maxi/list-notes` with `type=operator-note` and `status=active`, apply the returned instructions going forward, and update the baseline. The in-flight request is not blocked — this is a soft signal, not a gate.

## Live refresh for knowledge notes

The same pattern applies to knowledge notes via `_meta.knowledge_notes_revision`. When the revision increases, call `maxi/list-notes` with `type=agent-knowledge` and `status=active` to refresh knowledge note headers. Use the refreshed headers the same way you used bootstrap's: scan titles against the current task and fetch the full note if one matches.

<Info>
  Both live-refresh signals are soft — the current in-flight request continues normally. The refresh happens before the *next* call, not the current one.
</Info>

## Ending a session

Sessions end naturally when the connection closes or the conversation ends. There is no explicit close or logout ability. Acknowledged rules and revision baselines are not carried over to new sessions — the next connection starts fresh with a new bootstrap call.