What is structured note-taking for AI agents?
Structured note-taking is a context-engineering technique in which an AI agent writes notes, such as to-do lists, progress logs or decision records, to storage outside its context window and reads them back later.
Anthropic's "Effective context engineering for AI agents" (2025-09-29) lists structured note-taking, also called agentic memory, as one of three techniques for long tasks, alongside compaction and subagents. The agent writes notes as it works and pulls them back into context when needed, so critical facts survive compaction or a full context reset.
The word structured carries the weight. Anthropic's examples are to-do lists and a NOTES.md file with a known layout, not free-form journaling, and experience since shows that unstructured notes lose the details that matter.
Examples from the labs
Claude playing Pokémon
Anthropic's post describes the agent keeping precise tallies over long stretches of play, for example noting that it has been training on Route 1 for the last 1,234 steps, along with maps of explored regions and notes on which attacks work. After a context reset it reads its notes and carries on.
Progress files for coding agents
Anthropic's "Effective harnesses for long-running agents" (2025-11-26) has the agent update a progress file and commit to git after each feature, and read both at the start of the next session.
JSON over Markdown
The same post kept the feature list in JSON because the model is less likely to inappropriately change or overwrite JSON than Markdown. Agents may only flip a pass field, not edit the tests.
Memory notes with rules
OpenAI's personalization cookbook gives its agent a save-note tool whose instructions require notes to be durable, actionable and explicit, one to two sentences each, never speculative.
Why structure matters
Cognition's post on rebuilding Devin for Claude Sonnet 4.5 (2025-09-29) found the model wrote its own summary files unprompted, but they were not comprehensive enough to rely on: it sometimes paraphrased the task and dropped important details. Notes the agent invents its own format for tend to read well and recall poorly.
Fixed headings, a fixed file per purpose, and rules on what each session may change turn notes into state a later session can trust.
What it is confused with
Compaction
A summary of the history written when the window fills. Notes are written deliberately while working and survive any number of compactions.
Memory tool
Anthropic's memory tool is one way to give an agent a place to write notes. The technique works with any file or database the agent can reach.
Durable project memory
A specific set of planning and status files for long coding runs. It is structured note-taking applied to a whole project.
How Motiontic's engineers apply it
Motiontic's engineers define the note files before the agent runs: what each holds, its format, and which fields the agent may change. Evals then start fresh sessions from saved notes alone and check the agent continues correctly, which is the only test of whether the notes are good enough.
Free-form notes compared with structured notes
| Free-form notes | Structured notes | |
|---|---|---|
| Format | Whatever the model chooses | Fixed files, headings or JSON fields |
| Edit rules | Anything can be rewritten | Only named fields change, such as a status |
| Recall in a new session | Uneven; details paraphrased away | Predictable; the next session knows where to look |
| Testable | Hard to check | Can be validated like any data |
Common questions
What is structured note-taking in AI agents?
It is a technique where the agent writes progress, to-dos and decisions to files or a store outside its context window, in a fixed format, and reads them back after compaction or in a new session.
Why not just rely on compaction?
Compaction summarises whatever is in the window when it fills, and a summary can drop a detail a later step needs. Notes are written on purpose and keep exact facts such as IDs and constraints.
What format should agent notes use?
A fixed one. Anthropic used JSON for its feature list because the model was less likely to overwrite it than Markdown, plus a plain progress log and git commits.
Related
Memory tool
A file directory Claude can read and write across sessions, stored where the developer chooses.
Durable project memory
The spec, plan and status files a long agent run is anchored to.
Compaction
Summarise the old turns, keep working: the standard move for long agent runs.
Agent memory
Session state for the task at hand, plus stored knowledge the agent recalls later.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Sources
- Anthropic, Effective context engineering for AI agents (2025-09-29)
- Anthropic, Effective harnesses for long-running agents (2025-11-26)
- Cognition, Rebuilding Devin for Claude Sonnet 4.5: lessons and challenges (2025-09-29)
- OpenAI cookbook, Context engineering for personalization: state management with long-term memory notes
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.