Working with lessons.md

lessons.md is a short, running list of what to do differently next time. When you correct your agent, you write the correction down once, and every future session reads it, so you do not have to give the same feedback twice.

It is the difference between an agent that keeps making the same mistake and one that learns your preferences and holds them.

What goes in

Forward-looking corrections and durable preferences. Newest on top, one dated line each:

**2026-07-14** Draft investor updates in plain prose, not bullet lists.
**2026-07-09** Check the roster in accounts.md before prepping a call.
**2026-07-02** We say "customers", not "users".

Keep it to things worth remembering. A lesson earns a line when a teammate, or an agent doing this next month, would want to know.

Lessons, not history

lessons.md is what to do differently (rules, forward-looking). It is not a record of what happened, that is log.md. Keep the two apart: corrections in lessons, events in the log.

How to add one

Tell your agent, or let it offer.

• "Add a lesson: keep subject lines under six words."
• "That was wrong, note it so you don't do it again."

Most of the time the agent suggests a lesson when it learns something durable, and you approve.

Shared across your team

lives in the workspace, not in one agent's memory, so it is versioned and shared. When you share the folder, everyone's agent reads the same lessons, so a correction one person makes steers the whole team's agents. Keep team-wide rules here, and put personal preferences in your own file.