# Learnings > Capture, browse, query, supersede, and selectively admit evidence-backed execution learnings through the passive Learnings protocol definition. Trigger for `$learnings`, browse/recent/search learnings, lessons learned, takeaways, wrap up, handoff, validation transitions, strategy pivots, footguns, retry loops, or memory admission of a durable learning. - Skill: `tkersey/learnings` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add tkersey/learnings` - Raw SKILL.md: https://api.skillmd.com/api/skills/tkersey/learnings/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tkersey (https://skillmd.com/u/tkersey) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tkersey/learnings --- # Learnings ## Mission Maintain a repo-local, evidence-backed execution-learning store and selectively admit only high-value learning snapshots to the global Codex memory compiler. Authority split: ```text definitions/ledger/learnings-protocol.json canonical passive protocol; learning records live under event.record /.ledger/learnings/events.jsonl canonical repo-local store ~/.codex/memories/extensions/learnings/notes/*.md immutable admission snapshots for Phase 2 memory_summary.md / MEMORY.md / skills/* compiled memory written only by Phase 2 ``` Do not duplicate every learning into memory notes. For an accepted admission, load `$memory-source-notes` before invoking `run_memory_note_tool`. ## Trigger Cues - `$learnings`; - browse, recent, search, rank, or summarize learnings; - "what do we already know about X"; - lessons learned, takeaways, wrap up, or handoff; - fail-to-pass, pass-to-fail, timeout-to-stable; - strategy pivot, footgun, gotcha, retry loop, or acceleration pattern; - before a Codex-made commit/PR/handoff after material implementation; - explicit request to promote/admit a learning to memory. ## Canonical Store Before the first native Ledger command in this workflow, load `$ledger` and complete `$ledger ensure`. Require Ledger 1.0.3 or newer within major version 1 and `ledger-artifact-abi/v1`. Set: ```bash learnings_definition="$(realpath "${CODEX_HOME:-$HOME/.codex}/skills/learnings/definitions/ledger/learnings-protocol.json")" ``` Use `ledger transact --operation capture` for writes; use definition-bound `record`, `recent`, `recall`, `search`, `reconciliation-index`, and `memory-note` projections for reads. Treat the returned `lrn-*` identity as canonical. Do not open or hand-edit the store. An unbound current-format store requires the explicit one-shot `bind-existing` transaction. When an authoritative external transport such as Git advances the valid store while a local binding remains stale, use the separate `rebind-existing` transaction. Both routes validate the complete current store and otherwise fail closed; there is no alternate-path reader. Rows should preserve `id`, `captured_at`, `status`, `learning`, `evidence`, `application`, `source`, `fingerprint`, `context`, `tags`, `related_ids`, and `supersedes_id`. Standalone recall, browse, and source-local capture remain Learnings operations. No aggregate coordinator or sibling fan-out is required. At a material execution boundary, evaluate the capture gate directly and retain the source-owned disposition. ## Capture Gate Capture only when at least one decision-shaping event occurred: 1. validation transition; 2. strategy pivot; 3. hidden footgun or brittle assumption; 4. repeated acceleration pattern; 5. useful or failed recalled learning; 6. delivery boundary after real implementation work. Require decision delta, transferability, and counterfactual cost. Prefer one essential learning; append at most three per turn. Evaluate this gate from available task evidence before bootstrap or store inspection when no recall or canonical operation is needed. If it does not pass, retain `no-op` internally and continue the task. ## Disposition Invariant At each material Learnings activation, retain exactly one internal outcome: ```text learning-disposition: appended id=lrn-... learning-disposition: duplicate-skip reason= learning-disposition: no-op reason= learning-disposition: blocked reason= ``` Evaluation is mandatory once the source is materially activated; append is conditional. Do not claim Learnings closeout without a disposition. Keep `no-op` and `duplicate-skip` internal unless the user asks, while `blocked` is user-visible when it affects delivery. ## Write Workflow 1. Verify the git root: ```bash git rev-parse --show-toplevel ``` 2. Fail closed when either retired Learnings path exists without the canonical store. Do not create a parallel store or read the retired path: ```bash if [ ! -f .ledger/learnings/events.jsonl ] && { [ -e .ledger/learnings/learnings.jsonl ] || [ -e .learnings.jsonl ]; }; then printf '%s\n' 'blocked: retired Learnings store requires explicit owner-authorized recovery' >&2 exit 1 fi ``` 3. Run the definition-bound doctor: ```bash ledger doctor \ --definition "$learnings_definition" \ --repo "" \ --format json ``` Append only when the store is `current` or absent. For an unbound current-format store, run the explicit `bind-existing` operation once after full validation. For `StoreBindingRevisionMismatch` or `StoreBindingRecordCountMismatch` after authoritative external transport, run `rebind-existing`; it must validate the complete current store, replace only stale Ledger binding metadata, and leave event bytes unchanged. Stop on every invalid row; do not skip or reinterpret it. 4. Gather exact evidence and changed paths. 5. Distill objective, inflection, proof, and transferable rule. 6. Author `learning.json` as one `submission.record` packet, then append from the verified repo root: ```bash ledger transact \ --definition "$learnings_definition" \ --operation capture \ --repo "" \ --input submission=learning.json \ --format json ``` 7. Retain the appended learning ID, rerun definition-bound doctor, and use a focused `record` or `recall` projection to verify readability. 8. Before any Codex-made commit, inspect the current learning through the `record` projection. Do not read the store directly. 9. Retain exactly one canonical learning proof line in working evidence. Include source-memory proof in the final user-facing reply only when it changed repo-visible state, needs user action, explains a blocker/error, or the user explicitly asks. Use the disposition invariant above as the internal proof line. ## Recall Workflow ```bash ledger project \ --definition "$learnings_definition" \ --projection recall \ --repo "" \ --param "query=" \ --param "now=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ --param search_limit=5 \ --param drop_superseded=true \ --format json ``` Do not use `recall` as a substitute for current artifact inspection. ## Memory Admission Gate A learning becomes a custom memory-source note only when all four checks pass: 1. the canonical row exists and its ID is known; 2. evidence is inspectable and embedded in a bounded snapshot; 3. scope and future behavior are clear; 4. Phase 2 consideration would plausibly reduce future steering, retries, or search. At least one must also hold: - status is `codify_now`; - the same theme appears at least three times; - the user explicitly asks to remember/promote it; - it captures a stable cross-task preference or operating default; - it is an unusually high-impact failure shield, repo map, verification path, or stop rule; - it proves a repeatable procedure suitable for a memory-root skill. Do not admit every `do_more` row, raw chronology, weak `review_later` candidates, failed-hypothesis exclusions better owned by `negative-ledger`, operating-correction events better handled as standing policy, or synesthetic mappings. ## Definition projection and admission After the source owner accepts admission, load `$memory-source-notes` and pass the deterministic definition projection to the general writer: ```bash ledger project \ --definition "$learnings_definition" \ --projection memory-note \ --repo "" \ --param id=lrn-... \ --payload-only \ --format json | run_memory_note_tool append \ --extension learnings \ --kind learning-admission \ --json - ``` Do not reconstruct the payload from prose, `recent`, or query output. The projection validates the canonical store and fails closed for a missing or incomplete row; it does not decide admission eligibility. ## Admission Proof When admission is user-visible or actionable, report canonical and admission outcomes separately: ```text appended: id=lrn-... memory-note: id=MSN-... extension=learnings kind=learning-admission status=created ``` If the CLI is unavailable: ```text appended: id=lrn-... memory-note: not-attempted: cli unavailable ``` A failed memory admission must never roll back or invalidate the canonical learning append. ## Supersession and Withdrawal When a canonical learning is superseded or withdrawn from memory relevance, append the new canonical row, create a `learning-supersession` or `learning-withdrawal` note, reference the previous memory-source note ID when known, and let Phase 2 update compiled memory surgically. Never edit or delete prior admission notes. ## Memory Digest `$memory-source-notes` owns generated Learnings digests and their timestamped resources. Ledger supplies only the deterministic source projection. ## Relationship to Negative Ledger A learning can seed negative evidence, but the learning source is not the operational route-exclusion store. Promote witnessed failed hypotheses through the Negative Evidence definition's `capture` transaction, then use its `memory-note` projection for admission. ## Guardrails - Ground every row in observed evidence. - Write rules, not changelog bullets. - Do not append from an unverified non-repo cwd. - Do not force-add local-only source stores. - Do not bypass the Ledger API or edit persistent-adapter records directly. - Do not admit every learning to memory. - Do not write compiled memory directly. - Do not use source notes to bypass the canonical store. - Do not invoke a sibling source merely because Learnings activated.