lessons

Documentation

Overview

Package lessons is the distilled-failure memory: strategy-level lessons ("when X breaks, do Y") extracted from the agent's own failure-and-repair episodes, accumulated as lesson_signal events, and promoted to standing plaintext files once they recur — the preference_signal promotion rigor applied to failures (≥3 signals, ≥2 sessions, weighted score ≥ 2.0).

Memory is a COST lever here, not a quality lever: a promoted lesson saves the re-derivation turns, so the gate errs toward silence. Lessons surface as DATA (background evidence in the prompt), never as instructions — the documented poisoning path is a hostile input becoming a standing rule, and the recurrence gate plus data-framing is the defense.

Files are canonical: signals live in each session's events.jsonl (the SQLite events table is a rebuildable index; see the runtime's backfill), and a promoted lesson is a user-editable .memcode/lessons/<id>-<slug>.md — delete the file to revoke the lesson.

Index

• func Demote(root string, c Candidate) error
• func Inline(root string) string
• func InlineTop(root string) (string, []string)
• func WriteLesson(root string, c Candidate) (string, error)
• type Candidate
  • func PendingDemotions(root string, cands []Candidate) []Candidate
  • func PendingPromotions(root string, cands []Candidate) []Candidate
  • func Reduce(ctx context.Context, st store.Store) ([]Candidate, error)
• type Promoted
  • func List(root string) []Promoted
• type Signal

Functions

func Demote

func Demote(root string, c Candidate) error

Demote removes a lesson's file(s) and drops a demotion marker so the same cluster can't silently re-promote next startup on the same old evidence. It re-earns only when a NEW signal lands after the marker (see demotedAndNotReearned).

func Inline

func Inline(root string) string

Inline renders the top lessons as a compact context block — DATA, not instructions (the poisoning boundary), ranked by weight, hard-capped.

func InlineTop

func InlineTop(root string) (string, []string)

InlineTop is Inline plus the ids of the lessons actually surfaced — the caller records them (context_inlined) so the adherence judge only scores rules the model really saw.

func WriteLesson

func WriteLesson(root string, c Candidate) (string, error)

WriteLesson persists a promoted lesson as a user-editable markdown file and returns its path. Evidence lines carry provenance: which session AND which commit (repo HEAD at the episode) each contributing episode came from. Promotion clears any demotion marker — the cluster re-earned its place.

Types

type Candidate

type Candidate struct {
	ID           string // content-derived, stable across rebuilds
	Trigger      string // representative (highest-strength signal)
	Strategy     string
	Weight       float64
	SignalCount  int
	SessionCount int
	Evidence     []Signal

	// Adherence tallies (from KindAdherence events referencing this ID).
	Violations     int // violated verdicts on corrected/rejected sessions
	Reinforcements int // followed verdicts on accepted sessions
}

Candidate is a cluster of similar signals with its evidence tally.

func PendingDemotions

func PendingDemotions(root string, cands []Candidate) []Candidate

PendingDemotions returns candidates whose lesson file exists but whose adherence violations have crossed the threshold — the agent kept breaking the rule (or the rule kept being wrong) on sessions the human then corrected or rejected. Mirror of prefs.PendingDemotions, keyed on git-outcome evidence instead of user pushback.

func PendingPromotions

func PendingPromotions(root string, cands []Candidate) []Candidate

PendingPromotions returns candidates past the evidence bar whose lesson file doesn't exist yet. File existence IS the status — no candidate table. A candidate carrying enough violations, or demoted and not re-earned since (no signal newer than its demotion marker), stays out.

func Reduce

func Reduce(ctx context.Context, st store.Store) ([]Candidate, error)

Reduce scans lesson_signal events and clusters them into candidates. Deterministic, bounded, no model calls.

type Promoted

type Promoted struct {
	ID       string // stable content-addressed id (the filename prefix)
	Trigger  string
	Strategy string
	Weight   float64
}

Promoted is one promoted lesson file, parsed.

func List

func List(root string) []Promoted

List returns every promoted lesson, strongest first.

type Signal

type Signal struct {
	Trigger   string
	Strategy  string
	Strength  float64
	SessionID string
	HeadSHA   string // repo HEAD when the episode happened — provenance
	TS        time.Time
}

Signal is one distilled lesson observation.