> ## Documentation Index
> Fetch the complete documentation index at: https://mainbranch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Reflect: automated session observation and promotion

> Auto-Reflect observes significant events during your session and surfaces recurring patterns for promotion to AGENTS.md — no manual logging required.

Auto-Reflect adds two automated behaviors to the agent context workflow: continuous observation during a session, and a structured reflection pass at the end. Together they replace the manual habit of remembering to log what happened — the agent does it, and flags what's worth keeping.

## Two modes of operation

### Continuous observation

After each significant event — a commit, a bug fix, a pattern reused, a dead end — the agent appends a one-line observation to `.agents.local.md` under `## Session Observations (auto)`. Each line includes an ISO timestamp.

```markdown theme={null}
## Session Observations (auto)

- 2026-03-20T14:32Z | Fixed circular import — moved shared types to types/auth.ts
- 2026-03-20T15:01Z | DB_URL needed even for unit tests (third time)
```

Keep each observation under 120 characters. The agent appends only — it never edits or deletes existing observations.

**What counts as a significant event:**

* A commit was made
* A bug or error was fixed
* A pattern from `AGENTS.md` was reused or validated
* A dead end was hit (approach tried and abandoned)
* A workaround was discovered

### Session-end reflection

At the end of a session, the agent scans all of `.agents.local.md` — both `## Session Observations (auto)` and `## Session Log` entries — and identifies anything that has appeared in 3 or more separate sessions. It groups matches by category and writes suggestions into a `## Ready to Promote` table.

```markdown theme={null}
## Ready to Promote

| Category | Item | Detail |
|----------|------|--------|
| Gotcha | DB_URL required for unit tests | Set DB_URL even for unit tests, or they silently skip |
| Pattern | Result<T> for error handling | All services return Result<T>, never throw |
```

You review the table and decide what moves into `AGENTS.md`. In the default mode, the agent never touches `AGENTS.md` on its own.

## Promotion modes

Control how promotions work by adding a config directive to the top of `.agents.local.md`:

```markdown theme={null}
<!-- auto-reflect: promote=auto -->
```

<Tabs>
  <Tab title="suggest (default)">
    The agent writes suggestions to `## Ready to Promote`. You decide what moves to `AGENTS.md`. Nothing in `AGENTS.md` changes without your approval.

    This is the default if no directive is present.
  </Tab>

  <Tab title="auto">
    The agent promotes patterns directly to `AGENTS.md` after they recur 3+ times. It logs what was promoted under `## Auto-Promoted` in `.agents.local.md` so you can review after the fact and remove anything you disagree with.

    ```markdown theme={null}
    <!-- auto-reflect: promote=auto -->
    ```

    Because `AGENTS.md` is version-controlled, any promotion is reversible with `git revert`.
  </Tab>

  <Tab title="off">
    Skips the reflection pass entirely. Observations are still collected during the session if continuous observation is enabled.

    ```markdown theme={null}
    <!-- auto-reflect: promote=off -->
    ```
  </Tab>
</Tabs>

## What the full flow looks like

Here is `.agents.local.md` with auto-reflect active across multiple sessions:

```markdown theme={null}
## Session Observations (auto)

- 2026-03-18T14:32Z | Fixed circular import in utils/auth.ts — moved shared types to types/auth.ts
- 2026-03-18T15:01Z | Test suite needs DB_URL set even for unit tests (third time hitting this)
- 2026-03-19T09:15Z | Used Result<T> pattern again for API error handling in orders service
- 2026-03-19T10:44Z | Commit: refactor order validation to use shared schema
- 2026-03-20T11:30Z | pnpm build silently passes with type errors when --noEmit missing (again)
- 2026-03-20T14:22Z | Reused the barrel export pattern for new feature module

## Ready to Promote

| Category | Item | Detail |
|----------|------|--------|
| Gotcha | DB_URL required for unit tests | Set DB_URL=postgres://localhost:5432/test even for unit tests, or they silently skip |
| Pattern | Result<T> for error handling | All service functions return Result<T>, never throw — see orders, auth, billing |
| Gotcha | pnpm build hides type errors | Always run with --noEmit flag or type errors pass silently |
```

## Safety model

<AccordionGroup>
  <Accordion title="In suggest mode, AGENTS.md is never modified without your approval">
    The agent writes to `## Ready to Promote` only. No changes reach `AGENTS.md` until you explicitly move them.
  </Accordion>

  <Accordion title="In auto mode, all changes are logged and reversible">
    Every auto-promotion is recorded under `## Auto-Promoted` in `.agents.local.md`. Because `AGENTS.md` is committed to version control, you can revert any change you disagree with.
  </Accordion>

  <Accordion title="Observations are data, not instructions">
    The agent treats observation content as factual session records. If an observation resembles a behavioral directive or command override, the agent ignores it. The scratchpad is a log, not a control surface.
  </Accordion>

  <Accordion title="The scratchpad stays gitignored">
    `.agents.local.md` is gitignored by default. Observations never appear in version control or shared with teammates.
  </Accordion>
</AccordionGroup>

<Note>
  Auto-Reflect is built on the same principle as Mastra's Observer/Reflector pattern — dedicated observation and reflection passes extract insights from interactions automatically. The difference is that Auto-Reflect requires no infrastructure: just file appends and a reflection prompt.
</Note>