Per-task Markdown memory

Per-task Markdown memory is the practice of giving every unit of agent work its own short Markdown record, holding the outcome, scope, acceptance criteria, dated findings and next step, instead of keeping one big notes file for the whole project. The record is the agent's working memory for that task. It is read at the start of every session, appended to as the work goes, and closed with evidence when the task ends. The alternative most people start with, a single NOTES.md or progress log, works for a week and then becomes a liability: it mixes unrelated tasks, contradicts itself, and grows until no agent reads it carefully. Per-task records stay small, have one clear owner and expire naturally when the work is done. This workflow covers the template, how to use it during a task and how to keep it honest. It deliberately leaves global instruction files and architecture decision records to their own pages.

Why one global notes file stops working

A global notes file starts as a good idea. You ask the agent to keep a running log so the next session knows what happened. Within a few weeks the file has problems that are hard to see from inside a single session.

It mixes concerns. Findings about the payment bug sit next to a half-finished plan for the search page. An agent working on search reads both and may act on the wrong one.

It contradicts itself. An early entry says the cache is disabled in tests; a later one says it was re-enabled. Unless the agent reads both and notices the dates, it may trust whichever it saw last, or first.

It grows without end. Nobody deletes old entries because nobody is sure they are obsolete. The file becomes long enough that it crowds the context window or gets skimmed.

It has no status. You cannot tell from the file which work is finished, which is blocked and which was abandoned.

The fix is not a better global file. It is to give each piece of work its own record, so the scope of every note is obvious from where it lives.

What goes in a per-task record

Use one file per task, named by ID and slug, for example tasks/ENG-42-webhook-retries.md. Keep the same headings in every file.

Outcome: one sentence describing the finished state. 'Failed webhook deliveries are retried up to 5 times with exponential backoff.'

Status: one word from a fixed list your team agrees on, such as todo, active, blocked, verify, done or dropped.

Scope: the files or modules the task may change, and anything explicitly out of bounds.

Acceptance criteria: checks a reviewer can run. 'tests/test_webhooks.py passes, including test_backoff_cap. No new dependencies.'

Depends on and related: IDs of other tasks and decision records, as links.

Findings: dated, append-only entries. '2026-10-30: the sender swallows timeouts; see sender.py line 88.'

Next step: one concrete action, rewritten at the end of every session.

Evidence: when the task closes, the commands run and their results, with the commit they apply to.

This is close to what tasks agents can finish recommends for the task description, extended with the parts that change during work.

Using the record during a task

Step 1: Create the record before the first session. Fill in outcome, scope, criteria and dependencies yourself. Leave findings empty.

Step 2: Start each session by pointing the agent at the record. 'Read tasks/ENG-42-webhook-retries.md and the records it links to. Work only within its scope.' The record is short, so it sits at the top of the window.

Step 3: Ask the agent to append findings as it learns things, with dates. Facts that will matter later, such as an odd behavior, a failed approach or an exact error string, belong here, not only in chat.

Step 4: End each session by updating status and next step. This doubles as a handoff; how to hand off an AI coding session covers the routine in detail.

Step 5: Close the record with evidence. Run the acceptance checks yourself, paste the results and commit, and set the status. If follow-up work appeared, create new records for it and link them rather than expanding this one.

Step 6: Archive, do not delete. Move closed records to tasks/done/. They are useful history, and keeping them out of the active folder keeps the next agent's view small.

Keeping per-task records honest

A record is only useful if its status means something. Three habits help.

Define your status words. 'Done' is the most abused word in agent work. Write down whether it means implemented, reviewed, accepted or released, and stick to it. BRAIN FLUID's own development board on October 30, 2026 shows why: it had 123 cards, 50 of them DONE and 39 in VERIFY, while a separate acceptance checklist had 70 of 139 items passed. Those are different populations, and DONE there could mean implementation closed at the owner's direction before manual acceptance. A record should say which kind of done it is.

Keep findings append-only. If a finding turns out to be wrong, add a dated correction rather than deleting it. The wrong turn is itself useful to the next session.

Keep one writer for status. Agents may append findings, but a person, or a check you trust, should change status to done. An agent marking its own work complete is a claim, not evidence.

Review the active folder weekly. Records that have not changed in a month are stale or abandoned; close them as dropped or bring them up to date. Backlog hygiene for AI projects covers the broader routine.

QUESTIONS

Should I keep one notes file or one file per task for AI agents?

One file per task for working notes, plus a short global file for rules that are always true. Per-task files keep each agent's view small and scoped, have a clear status and can be archived when the work closes. A single growing log mixes tasks and becomes contradictory.

Should task notes for AI agents be committed to git?

Usually yes, on the same branch as the work. That keeps the notes and code in step, gives you history and lets reviewers see the findings beside the diff. Keep secrets, tokens and personal data out of them, since committed notes are shared and are often pasted into prompts.

What belongs in the findings section of a task note?

Facts the next session would otherwise have to rediscover: unexpected behavior, failed approaches and why, exact error messages, file and line references, and questions for a human. Date every entry. Leave out narration of routine steps and anything that belongs in a decision record.

RELATED GUIDES

• How to create a project card in BRAIN FLUID Desk
• How to find and organize work across projects
• How to read project progress in BRAIN FLUID Build

RELATED HARNESS PAGES

• How to hand off an AI coding session How to hand off an AI coding session: a short end-of-session routine so the next agent or person can continue without guessing.
• Recording architecture decisions for AI agents Recording architecture decisions for AI agents: short decision records an agent will read, where to keep them and how to supersede one.
• How to write a task an AI coding agent can finish How to write a task an AI coding agent can finish: one outcome, a scope, dependencies, completion criteria and the check that proves them.
• Keeping an AI project backlog clean Keeping an AI project backlog clean: decline or hold work instead of deleting it, merge duplicates, avoid ID collisions and groom on a schedule.
• Keeping secrets out of AI project memory Keeping secrets out of AI project memory: what never goes into notes, cards, prompts or handoffs, and redaction habits that hold up.