Skip to main content
Version: Next

Cross-project lessons

A correction learned in one project should not be relearned in the next. Orion keeps a lesson memory shared across every project on the machine, and injects it into the agent's CLAUDE.md at the start of each session.

Commands​

orion lessons add "Money is BigDecimal, never double"
orion lessons list           # what is recorded, and whether anything is observing
orion lessons pending        # proposals waiting for your yes or no
orion lessons approve <sig>  # record one
orion lessons reject <sig>   # discard one, and never propose it again
orion lessons retire "<t>"   # stop injecting a lesson

How a lesson is learned​

Most lessons arrive without you typing anything. When a branch whose CI went red is fixed and merged, orion collect files an observation: a mistake with its own correction attached, both seen by the system.

  • The same observation seen twice becomes a proposal.
  • A proposal becomes a lesson only when you approve it.
  • A single sighting cannot be approved, even deliberately, since one occurrence may be circumstance.

You approve each lesson because the block is read at the start of every session, so a wrong lesson misdirects every future run.

Scope and size​

A lesson starts local to its project and reaches others only after it recurs somewhere else.

The injected block is capped at 25 entries, because the agent reads CLAUDE.md in full every session. Entries are ranked by recurrence weighted toward recency, and expire after 90 days. Hand-written content outside Orion's managed markers in CLAUDE.md is preserved.

An empty list or a broken observer​

orion lessons list tells apart "nothing has been recorded" from "nothing is writing here". From the outside the two look identical, and only the second means something is broken.

Not documented yet​

  • Where lessons are stored on disk.