memory-file

Purpose

LEARNINGS.md is a structured, deliberately small memory file at the project root. It survives context compaction and session boundaries because it lives on disk, not in conversation history. It is the durable half of the loop's memory — the other half is the progress ledger (see the memory-mirror-harness skill).

This is not a changelog and not a diary. It holds only lessons that would change future behavior if known in advance. Treat every block as a live hypothesis about the codebase that can go stale and must be checked, not a permanent record.

Scope note

This skill is not the fresh-context-reviewer agent and the reviewer's strict "exactly two inputs" contract does not apply here. When a session or dispatch describes which blocks are stale and why (e.g. "these blocks reference a module that was deleted"), that is ordinary task input for the pruning step to act on directly — not commentary to flag as contamination and not a reason to refuse for lack of a pasted file. If the actual current file contents are not available to read, say so as a one-line caveat, then still perform the full decide/prune/regenerate-index procedure illustratively (see the memory-mirror-harness skill's "Handling scenarios without a real on-disk artifact" section) rather than stopping.

File format

# Learnings

<one-line index: "N blocks — topic1, topic2, topic3, ...">

## L1: <five-to-eight-word title>
- Doing: <what task/change was in progress when this was learned>
- Signal: <what went wrong, or what worked non-obviously, in one sentence>
- Fix: <the corrected approach going forward, in one sentence>

## L2: <title>
- Doing: ...
- Signal: ...
- Fix: ...

Rules for the format:

• One-line index at the top, regenerated every time blocks change — lists the current block count and a short topic tag per block so a reader can scan without opening every block.
• Exactly one lesson per block. Never fold two unrelated lessons into one block, and never split one lesson across two blocks.
• Three fields per block, one sentence each: Doing / Signal / Fix. No prose paragraphs, no code dumps longer than one line. If a lesson needs more than three sentences to state, it is not yet a lesson — it is unprocessed observation; either compress it or don't record it yet.
• Target size: 20-40 lines total for a healthy project. If the file is trending well past that, the pruning step (below) is falling behind, not the project generating more true lessons than fit — prune harder.
• Never write secrets. No credentials, tokens, connection strings, API keys, or customer data in any block. If a lesson is inherently about a secret-handling bug, describe the class of bug ("connection string logged at info level") without including the actual value.

Session start — read before act

At the start of every session, before taking any action on the task:

1. Read LEARNINGS.md in full — the whole file, not just the index. The index exists for fast scanning during long sessions, not as a substitute for reading blocks on first read.
2. If the file does not exist, this is not an error — proceed with an empty memory and create the file during the remember step if a lesson is produced.
3. Identify which existing blocks, if any, are relevant to the current task. Apply relevant lessons while acting; do not just note that they exist.

Session end — the "remember" step

At the end of every session (or every discrete subtask in a long unattended run), before finalizing:

1. Decide if anything genuinely new and durable was learned. A durable lesson generalizes beyond this one instance — "this build tool silently swallows stderr on exit code 2" is durable; "the file had a typo" is not. If nothing durable was learned, leave the file unchanged. Do not create a block just because a session occurred, and do not rewrite a still-valid existing block just to feel productive.
2. If a new lesson is warranted, add exactly one new block. Do not merge it into an existing block unless it is a refinement of that exact same lesson (see pruning below, which covers merges explicitly). Update the one-line index to include it.
3. Prune actively — this is not append-only. For every existing block, ask: is this still true of the current codebase? A block goes stale when:
   • The module, file, or code path it references no longer exists (deleted, renamed, replaced).
   • The bug or behavior it describes has since been fixed upstream and no longer applies.
   • A later block supersedes or corrects it (in which case merge: keep the corrected version, remove the superseded one). Remove stale blocks outright. When removing, you should be able to state in one clause why it no longer applies (e.g. "module deleted," "bug fixed upstream") — do not delete a block you cannot justify removing, and do not keep a block you know is stale because deleting feels destructive.
4. Regenerate the index to match the final block set — count and topics must match exactly what remains after additions and pruning.

Anti-patterns to avoid

• Treating the file as append-only ("just add to the end, never remove") — this is the single most common failure mode and is explicitly wrong for this harness.
• Rewriting a still-accurate block's wording without new information, which wastes the pruning pass's attention budget on cosmetic churn instead of actual staleness.
• Recording a lesson that is really just a narrated to-do item or status update rather than a generalizable "what to do differently next time."
• Letting the file grow unbounded on the theory that "more history is always better" — a bloated file drowns the reader's attention exactly when it matters most (long unattended sessions), which is the opposite of its purpose.
• Treating "the dispatcher told me which blocks are stale and why" as contamination. That is normal task framing for this skill (unlike for the fresh-context-reviewer agent) and should be acted on directly.