Memory
Lessons
Mistakes recorded once, surfaced as a warning before they happen again.
“never edit a migration that has shipped”
A lesson that can surface when later work involves migration changes.
“that broke production — remember why”
A lesson with the trigger, the impact, and the prevention.
“show me the lessons for this project”
Everything recorded, and what each one triggers on.
Lessons are a compact example of the partnership: you turn one real mistake into a specific prevention, ContextStream matches it to later work, and the assistant changes course before you have to repeat the warning.
Why lessons are their own thing
A decision answers a question when asked. A lesson interrupts — it surfaces as a warning when you're heading toward the thing that went wrong, before you get there.
That's the difference that matters. A note saying "don't do X" is only useful if you go looking for it. A lesson finds you.
What a good one contains
Four parts, and the agent captures them from what you say:
| Part | Example |
|---|---|
| Trigger | Editing a database migration |
| Impact | A shipped migration was edited; two environments diverged silently |
| Prevention | Migrations are additive. Write a new one. |
| Severity | High |
Severity decides how loudly it surfaces. A critical lesson is hard to walk past; a low one is a note.
Recording one
Be explicit when the prevention needs to follow you. Some assistants can recognize and save a correction, but a passing correction is not a reliable lesson record. State the trigger and prevention:
"Lesson: never run the seed script against staging. It wipes the tenant table. Use the fixture loader instead."
A lesson that changes the next session
Imagine a webhook retry change passes in staging and then fails against a real
provider response. The staging mock never returned 429, so the rate-limit
path was never exercised.
A useful lesson is not “tests were incomplete.” It is:
- Trigger: changing webhook retries, provider mocks, or rate-limit handling;
- Impact: staging passed while production could enter the wrong retry path;
- Prevention: add a
429fixture with the provider's retry header and test the bounded-delay behavior before changing the sender; - Severity: high, because the gap can amplify outbound traffic.
The next time you ask an assistant to touch webhook retries, that warning can surface before code changes begin. It can point to a concrete test to add, instead of merely reminding you that testing is important.
Another good lesson shape is an environment mismatch: “when local behavior disagrees with the hosted gateway, confirm the deployed binary version before debugging the request.” The trigger is specific, the wasted effort is clear, and the prevention is a check someone can actually perform.
They cross assistants and machines
A shared lesson recorded from one connected assistant can surface in another when its trigger matches. One recorded by a teammate can warn you when you have access to the same workspace and project. That's the point — the warning is available beyond the session where the mistake happened.
Reviewing them
Ask "show me the lessons for this project" or narrow it to a subject such as "show lessons about database migrations." A lesson that is no longer true should be removed — stale warnings train people to ignore warnings.
If it doesn't work
A lesson never fires. Its trigger is too vague. "Be careful with the database" matches nothing in particular; "editing a shipped migration" does.
It fires constantly. Too broad, or the severity is too high for what it is. Narrow the trigger or lower it.
A correction I made didn't stick. A correction in conversation is not necessarily a saved lesson. Say "save this as a lesson" explicitly for the ones that matter, then ask to read it back if you need confirmation.