# Lessons Keeper

> 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.

- Skill: `paladini/lessons-keeper` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add paladini/lessons-keeper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paladini/lessons-keeper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: paladini (https://skillmd.com/u/paladini)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paladini/lessons-keeper

---


# 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

1. Run: `python scripts/lessons.py list`
   (filter with `--tag <topic>`, e.g. `--tag build`).
2. 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.
3. 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.