| name | lessons-keeper |
| description | Record and recall durable project lessons across agent sessions using a versioned lessons file. Use when finishing a task that revealed a surprise, workaround, or user correction worth remembering, when starting non-trivial work to recall relevant lessons, or when the user says "remember this", "keep note of", or asks what we learned before. |
| license | MIT |
| metadata | {"author":"paladini","version":"1.0.0"} |
Lessons Keeper
Give sessions a memory: durable lessons live in a plain markdown file,
versioned with the project, written and parsed by
scripts/lessons.py so the format is enforced mechanically.
Recall — before starting non-trivial work
- Run:
python scripts/lessons.py list
(filter with --tag <topic>, e.g. --tag build).
- Read every returned lesson. Lessons cite evidence — a file path,
command, or error. If the evidence no longer exists in the code, the
lesson may be stale: verify against the code before obeying, and prune
it (see below) if outdated.
- Memory is advisory. Code, tests, and CI win any disagreement with a
lesson.
Record — after finishing a task
Record a lesson when you learned something durable that a future session
would otherwise rediscover the hard way: surprising behavior, a workaround,
a user correction, a decision with its rationale.
Run: python scripts/lessons.py add "<lesson>" --tag <topic>
and include the evidence inside the lesson text: (evidence: path/file.py)
or (evidence: command that reproduces).
What qualifies
| Record | Don't record |
|---|
"Staging API requires X-Org-Id even on GETs (evidence: api/auth.py)" | "Added a function to auth.py today" |
| "Docker build needs HTTPS_PROXY build-arg behind the VPN" | "Tests are red right now" |
| "Chose Postgres over Mongo for multi-region reads (decision + date)" | Anything transient about the current conversation |
Rules
- One idea per lesson, one line. Merge related findings.
- Never record secrets, tokens, credentials, or personal data.
- Never record transient context ("what I'm doing now") — that's
conversation, not memory.
- Prefer pruning over accumulating:
python scripts/lessons.py prune --keep 100
when count grows large, and whenever a lesson's evidence has vanished
from the codebase.
.lessons/lessons.md is committed and reviewed in pull requests like any
other file — expect humans to read it.
Script reference
add "<text>" [--tag t] [--scope project|user] [--date YYYY-MM-DD] —
append a lesson; exact duplicates are refused with exit 0 (idempotent).
Scope project writes .lessons/lessons.md in the repo (default);
user writes ~/.lessons/lessons.md.list [--tag t] [--scope …] — print lessons (newest last).prune --keep N — keep the N most recent lessons.count — number of lessons.- Exit codes:
0 ok · 1 storage error · 2 bad arguments. The entry
date defaults to today; pass --date to reproduce runs exactly.
