Skip to main content
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. 
## 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. 
## 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: 
<!-- auto-reflect: promote=auto -->
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.

​
What the full flow looks like

Here is .agents.local.md with auto-reflect active across multiple sessions: 
## 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

The agent writes to ## Ready to Promote only. No changes reach AGENTS.md until you explicitly move them.
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.
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.
.agents.local.md is gitignored by default. Observations never appear in version control or shared with teammates.
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.