Skip to content

Memory ​

The learning layer. A correction or a discovery gets captured once as a structured lesson – when it trips, what to do, and why – filed into a per-domain store, and the next session in that domain reads it back before it repeats the mistake. The store is sharded by domain so recall loads one slice, not the world, and every lesson carries a type, a source, and hit and miss counts that decide how long it lives and whether it earns promotion. It replaces only the flat lessons.md scratchpad; the project (rules.md) and global (~/.claude/RULES.md) rule tiers stay manual and confirmed, always – the tooling flags candidates, it never moves anything.

The install is two parts now, not one flat accordion. memory itself bundles four – store is the base (the engine, the routing table, the readme, the rendered slices) and it is inert on its own, lesson drops the /lesson command, recall drops the lesson-recall skill, and debrief ships the SessionEnd hook plus its /debrief twin. The per-prompt injector used to be a fifth option inside that same accordion, with the settings fragment that wires it sitting beside it as a second, separately-tickable option – which meant a project could tick the hook and skip the fragment, leaving it shipped and dead. It has been promoted out into its own part, lesson-injector (drawn as injector in the picker; the display-only label keeps it from sitting one letter off the context module's injectors part). It draws under: "memory" and needs: ["memory"] – it scores a store it does not itself ship – and it now carries both hooks/inject-lessons.nu and settings-fragment.json together, so it is wired or it is not installed at all. It remains the one piece here that costs a turn, and now it installs and removes on its own rather than as a checkbox inside the bundle.

In Practice ​

Capture a fix the moment it lands. You hit a gotcha, solve it, then run /lesson (or the tool directly). It pulls the when, dont, do, and why from the conversation, tags a type and source, and files it – leaving --domain off so the text routes itself:

nu lessons.nu add \
  --when "LNK2019 unresolved external symbol at link time" \
  --do "add the missing .lib to the linker input or define the symbol" \
  --why "LNK2019 is always a symbol the linker cant find, the fix is supplying it" \
  --type gotcha --source corrected

The keywords unresolved and linker score the compile-errors domain, the entry lands, and that domain's md slice is rerendered on the spot:

added compile-errors/add-the-missing-lib
  when LNK2019 unresolved external symbol at link time
  do   add the missing .lib to the linker input or define the symbol
  bc   LNK2019 is always a symbol the linker cant find, the fix is supplying it

Recall arrives on its own, tagged as binding. With the lesson-injector part installed (drawn as injector in the picker), every prompt is scored against the whole store before the agent ever sees it. inject-lessons.nu runs on UserPromptSubmit, splits the prompt into words, and scores each stored lesson's when-plus-do-plus-why text against them. Anything scoring two or more word overlaps makes the cut, best five first, and the whole block goes out wrapped in a <lessons> tag rather than sat loose as background prose – an agent follows a tagged block as binding, and the tag gives a transcript reader a hard boundary to attribute it to:

<lessons>
lessons matching this prompt, from .claude/memory, apply what fits, confirm a real use with lessons.nu hit, miss one that surfaced wrong:
- [nu/use-plain-complete-it] when capturing an externals stderr through the nushell mcp or a pipeline, do use plain | complete, bc o+e> redirects stderr into stdout before complete sees it
</lessons>

An example outcome, verified live. A real run this session returned a tagged block round five scored hits, and the telemetry scanner over that transcript attributed both a pre-wrap and a post-wrap injection correctly – the tag change doesn't break anything already reading these hooks' output.

Recall by hand, before you touch a domain. Without the injector, or as a second check, read the rendered slice directly – lessons/nu.md, lessons/compile-errors.md, and so on. It is sorted highest-hits first, most-recently-useful breaking ties, so the proven lessons sit on top:

- when capturing an externals stderr through the nushell mcp or a pipeline, do use plain |
  complete, it keeps stdout and stderr as separate columns, o+e> merges them into stdout
  first, bc o+e> redirects stderr into stdout before complete sees it, so the record has no
  stderr column and access errors (gotcha, observed, 2026-07-08, hits 0)

For a targeted lookup across every domain, find matches all query words against a lesson's full text and returns the hits with their counts:

nu lessons.nu find "stderr complete"
domain  id                     when                                       do                        hits  misses
nu      use-plain-complete-it  capturing an externals stderr through …    use plain | complete, …   0     0

If you are unsure where a note belongs, nu lessons.nu route "the nushell pipeline closure captured a mut" prints nu and nothing else – the same scoring add uses to place it. One thing outranks that scoring outright: an MSVC or linker diagnostic code, an upper-case C2365 or LNK2019, routes straight to compile-errors whatever else the text says. It exists because the ordinary count weighs every word the same – a lesson about a C2365 redefinition once routed to style off the single word "naming" while compile-errors's own keywords (compile, compiler, diagnostic) matched none of it, and had to be moved by hand.

A shell eating your text gets caught before it lands. A backtick or a $ inside a double-quoted shell string runs as command substitution before nu ever sees the line – that is exactly what happened on 2026-09-06, when it silently rewrote a lesson's text into "especially a sentinel on an enum" with a trailing ", , ," and add banked it without a word. add now checks the when, do, why, and dont fields first, for an empty field, punctuation with no real words left, a , , gap, a trailing comma, or a doubled space, and refuses outright when it finds one:

add refused, the text looks mangled, do has a doubled space, something between the words substituted to nothing. check for backticks or $ in a double quoted shell string, they run before nu sees them, then re-run with the text you meant

--force does not bypass this. Force is the dedup escape below and reaching for it out of habit is exactly the case this check exists to survive – there is no legitimate add carrying a , ,, the fix is always to re-run with the text you actually meant.

The store pushes back on duplicates. Reinforcing an existing lesson beats bloating the store toward its cap with another copy, so add checks the routed domain for near duplicates first and refuses rather than append. A match needs both halves of the bar: at least four shared significant words, and those shared words making up at least 40% of the shorter of the two lessons. The ratio is what stops a long, wordy lesson resembling everything simply by having enough words to collide with:

not added, claude-code already has 1 near dup(s) of this
  claude-code/read-the-tail-of, 16 shared words, 0.84 of the shorter, when a fan-out subagent has written a file for you, a wiki page writer, any agent whose deliverable is the file itself
confirm one instead, nu lessons.nu hit claude-code <id>, or rerun add with --force

The counts are printed so a match can be judged rather than taken on trust – one sitting right on the bar reads very differently from the near-total overlap above.

That bar was raised on 2026-09-02. It had been two shared words and nothing else, which fired on 898 of the store's pairs – very nearly every pair in it – so genuinely new lessons were refused as duplicates and --force became the habit rather than the exception, which is the state where a duplicate check is worse than no check at all. Measured against the same store, a real paraphrase of a stored lesson shares sixteen words where the false positives topped out at three, so the signal was always there and only the threshold was wrong. The current bar takes those 898 firing pairs down to six. Note it is deliberately stricter than the bar distill clusters on: deduplication asks whether this is the same lesson, clustering asks whether several are related enough to look at together, and the two should not be unified.

The clustering bar had the same disease until 2026-09-04, but from the other direction – clusters-of ran on a bare shared >= 2 word count and never called overlap-of at all, so it had no ratio floor to stop a long, wordy lesson matching everything it brushed past. Measured over the real 246-row store, that put 166 rows – 67% of it – into 56 clusters, recommending a merge of two thirds of everything, and pairing unrelated lessons like "only list what descriptive names carry" with "set an env guard". It now runs through overlap-of, the same function dedup uses, at a looser bar: cluster_min_ratio of 0.3 with cluster_min_shared of 2 as a floor against a single shared word ever clustering anything on its own. Over that same store the fix takes it to 18 clusters across 37 rows. The ratio is the whole signal here and the count is close to noise – 2, 3, or 4 shared words give identical results once a ratio is in play.

The distill output changed to match. Each cluster row now carries tie – the weakest pair in that cluster, ie how well its loosest member actually holds on – and clusters print strongest-tie-first, so reading down the table is reading a confidence ranking rather than parsing a fixed cutoff: you stop at the point the members stop looking like one lesson. do was dropped as a column entirely – it is the longest field a lesson has, and a boxed table wrapping every one of them took a 44-row domain to 5,600 lines of unreadable output – so the table now carries only cluster, tie, id, and when, and find <id> is where the actual do and why still live.

Undo a bad add. A lesson banked wrong is not stuck once it is in the store. remove takes one row back out by domain and id, prints it first so you can check it is the right one, and asks before it touches anything – there is no --all and no filter here on purpose, the moment it took a predicate it would be distill --drop wearing another name:

nu lessons.nu remove compile-errors add-the-missing-lib
remove compile-errors/add-the-missing-lib
  when LNK2019 unresolved external symbol at link time
  do   add the missing .lib to the linker input or define the symbol, check a declared-but-not-defined function or a missing source in the project
  bc   LNK2019 is always a symbol the linker cant find, the fix is supplying it
  (gotcha, corrected, 2026-07-10, hits 0)
remove it, this cannot be undone, type yes to confirm,

A lesson with hits gets an extra NOTE line first, since that is the row most likely to be removed by mistake and the one there is no getting back. --yes skips the confirm for a caller that has already shown the row. The removal rewrites the whole jsonl through the same save-domain path every other mutation uses rather than a line-level edit – the obvious shell one-liner, grep -v <id> f > tmp && mv tmp f, is wrong in a way that looks right: grep exits 1 when it selects no lines, so on the one file where that matters, every line matching, the && never fires and the removal silently does not happen while reporting success.

Confirm what pays off, and it climbs on its own. When a stored lesson actually applies, mark the hit. A corrected lesson – the strongest source – flags for promotion at two hits instead of three:

nu lessons.nu hit compile-errors add-the-missing-lib
compile-errors/add-the-missing-lib now at 2 hits
promotion candidate, ask finn before moving it up a tier, the tool only flags, never moves

Confirming a hit now also stamps last_hit to the day it fired, so a current run's line reads now at N hits, last hit YYYY-MM-DD. That stamp, not the hit count on its own, is what keeps a lesson off the drop list below – a lesson that keeps saving an agent but never gets a hit reads as dead, and lesson-recall's own procedure now says do not skip the hit step for exactly that reason.

Promotion deliberately stays keyed on hits alone, never on the injector's surface count, and the source carries a comment saying why: a surface means the injector's word overlap fired and the lesson was reachable, a hit means someone confirmed it actually applied, and only the second is evidence a rule should bind every future session. The gap between the two is wide enough to matter – 6,330 surfaces against 43 hits over the same store – so promoting on surfaces would flag half the store in a week.

Bank the session's takeaways without asking. With the debrief sub-part wired to SessionEnd, debrief.nu rereads the ending transcript, seeds itself from any queries logged to lessons/gaps.log during the session, and asks a cheap model to extract at most three reusable lessons in a strict DOMAIN|TYPE|WHEN|DO|WHY line format. Each parsed line banks through lessons.nu add --source extracted; malformed lines are dropped, not fixed. /debrief does the same sweep by hand, from inside the conversation, without spawning a second model.

An example outcome. The compile-errors lesson is now a flagged candidate for a rule tier, but nothing moved – the tool only ever flags. Promotion into rules.md or ~/.claude/RULES.md is a human call, made once, after which the jsonl line is deleted so no lesson lives in two places.

Key Files ​

lessons.nu ​

The engine – every operation is a subcommand: add, remove, render, route, find, hit, miss, stats, distill, expire, garden, and efficacy. It queries the jsonl and, on every mutation, rerenders the touched domain's md so the rendered slice never drifts from the backend.

An add (and a rejected near-dup) also emits a line through an internal meta-emit, appended to harness-meta.jsonl. The destination is not hardcoded to ~/.claude – it resolves through the same three-step lookup every harness tracker uses (T5.2): an HARNESS_TELEMETRY_DIR env override, then the telemetry pointer harness local stamps at ~/.claude/harness-store.nuon (overridable with HARNESS_STORE), then ~/.claude as the fallback. That is what lets a copy of this module, sat inside whichever project installed it, write back to the one store the harness itself reads, without knowing where the harness lives. The whole call sits inside a try, so a missing or unreachable tracker never blocks a lesson from being captured – worst case is a gap in a metric, never a lost lesson.

efficacy is the newest subcommand and sits outside that mutation pattern entirely – it is a pure read, no jsonl write and no rerender. Per domain it sums hits and misses, computes a ratio, counts rows carrying the review and reverify flags, and reads the mix as learning (hits at or above misses), stagnant (misses ahead), unused (neither has fired yet), or empty (no rows at all). It is not mentioned in USAGE.md, the store's own README.md, or even the script's own no-args usage print – real and runnable in the source, just not written up anywhere else yet.

domains.nuon ​

The routing table – maps single lowercase keywords to domains. It ships ten: sfml, ue5, ahk, ts, nu, claude-code, harness, installer, compile-errors, and style. A lesson's when-plus-do text is scored against every domain's keyword list, most hits wins, and anything scoring zero lands in general. One signal outranks that keyword count entirely: a diagnostic code in the text, an uppercase C#### or LNK####, routes straight to compile-errors before the keyword table is even consulted – it is a statement about what the lesson is, and no number of generic words should be able to outvote one.

commands/lesson.md ​

The /lesson capture command – installed to a project's .claude/commands/ by the lesson sub-part. It shapes a correction into the when, dont, do, and why fields, tags the type and source (a correction is always corrected), calls lessons.nu add, then echoes the captured lesson back in one line so it can be vetoed or re-routed.

README.md ​

The data model and lifecycle – the entry shape, the type and source semantics, and the tier-system rules the rest of the module implements. The reference to read before extending any of it. Note its own hooks section still describes the injector as a branch of the memory bundle's accordion, "tick store alone and nothing runs per turn" – that predates the split covered above, lesson-injector is its own part in module.json now, under: "memory" rather than a checkbox inside it, so that section of the readme reads stale against the actual install shape.

The Store ​

lessons/<domain>.jsonl ​

The backend – one JSON object per line, one file per domain, and the source of truth the scripts read and write. It is never edited by hand; mutations go through lessons.nu.

lessons/<domain>.md ​

The render – the slice agents actually read, generated from the jsonl highest-hits first, most-recently-useful breaking ties, so proven lessons sit on top. Its header says not to hand edit it – any change belongs in the jsonl, and the next mutation would overwrite it anyway.

The Injector ​

Its own module.json part now, lesson-injector (under: "memory", needs: ["memory"], displayed as injector), rather than a checkbox inside the memory bundle. Both files below ship together as that one part, so the hook can never land wired to nothing. Projects that installed memory before the split have these two files recorded under memory; the registry's part-split migration re-keys them onto lesson-injector on the next read, so nothing orphans and no file moves.

hooks/inject-lessons.nu ​

The UserPromptSubmit hook – scores the whole store's when-plus-do-plus-why text against the incoming prompt's words, keeps hits scoring two or more overlaps, takes the top five, and prints the result as a <lessons> ... </lessons> block. The lines are built in full before the first print, so the open tag can never make it out without its close even if something downstream throws. A HARNESS_HOOKS_OFF env check guards against re-firing when a harness hook has already spawned Claude further up the chain.

Before scoring, it strips filler from the prompt's own words: a fixed stoplist of generic English plus a second one built fresh from the store itself, any word carried by more than 5% of the store's lessons once the store holds at least 40 rows. Measured 2026-09-05 over 251 lessons, harness sat in 76 of them and one in 86 – common enough on their own to clear the two-word overlap threshold and surface a lesson that had nothing to do with the prompt. The store-derived half is never hand-maintained; a fixed list naming things like harness would rot the moment the store moved on.

settings-fragment.json ​

Wires the injector – registers hooks/inject-lessons.nu on UserPromptSubmit. It used to ship as a second, independently-tickable option beside the hook, which let a project install the hook and skip the fragment, shipping it dead. It now travels inside the lesson-injector part together with the hook it wires, so a project either has both or neither.

The Debrief ​

hooks/debrief.nu ​

The SessionEnd hook, opt in – rereads the ending transcript (tail-biased, capped near 60,000 characters), seeds itself from lessons/gaps.log, and hands both to a haiku call constrained to a strict lesson-line format. Up to three parsed lessons bank via lessons.nu add --source extracted. It is deliberately left out of any settings fragment because it spawns a model on every session end; wiring it is a hand edit to the target project's settings.json, following the snippet in store/README.md. It resolves its own claude binary via which claude.exe claude claude.cmd rather than a hardcoded path, so it keeps working across whichever hash-named build the desktop app happens to have bundled that week.

commands/debrief.md ​

The /debrief command – the manual twin of the hook, run from inside the conversation instead of against a saved transcript. Same sweep, same three-lesson cap, same gaps.log consumption, but no second model spawned.

Lifecycle ​

A lesson's type sets how fast it goes stale, aged off whichever day it was last proven useful – its last_hit when the row has one, its creation date as the fallback when it doesn't. expire flags anything past its type's reverify age – graded down the ladder below – but expire itself never deletes anything; a reverified lesson gets its date refreshed by hand. Deletion, where it exists in this store at all, lives one section down, in the drop pass.

typewhat it capturesreverify age
env-factversions, paths, toolchain quirks90 days
gotchaa trap and the way around it180 days
processhow work should flow365 days
styleformatting and voicenever

The source field weights a lesson by its origin – corrected (finn corrected the agent) outranks stated, observed, inferred, and extracted. Two biases hang off it: a corrected lesson flags for promotion at two hits rather than three, and it rots one tier slower than its type, so an env-fact ages like a gotcha and a style still never rots.

Two counts drive the flags. A confirmed use is a hit; at three hits – two for a corrected source – the lesson flags promote. A lesson that surfaced but did not apply is a miss; at three misses, and only when misses beat hits, it flags review. Neither flag ever acts on its own – promotion up a tier is confirmed by hand, and a review lesson waits for a distill pass or a human call.

date is the creation date and never moves, so on its own it can only say a lesson is old, not whether it is dead. A hit closes that gap: it stamps last_hit to the day it fired – a de facto reverification, since the lesson just surfaced and applied against the real world. Everything that reads staleness (expire, render's sort, and the drop pass below) now goes through a single last-seen helper that prefers last_hit, then falls back to last_surfaced – the day the recall hook last put the lesson in front of an agent, written by the telemetry module's scan-lessons.nu sync – and only then to date. last_hit is absent on every row written before it landed and nothing was backfilled – there is no honest source for a retroactive date, and a guessed one would be worse than none, so absent reads correctly as never hit. last_surfaced is absent the same way until a project has run a sync at least once. Confirming a lesson is what keeps it alive now, not a nicety layered on top of the count; a lesson that keeps saving an agent but never gets a hit reads as dead – though one the injector keeps surfacing is no longer read as dead either, only as unconfirmed.

That staleness reading feeds the one real deletion in this store. distill <domain> lists the lessons in that domain that have never been hit and never surfaced and have sat past 30 days (drop_age) since they were last seen useful. The surfaced half is new: a lesson the recall hook has actually shown an agent is reachable and alive whatever its hit count says, where a zero hit count is often just a fact about nobody having run hit yet – on 2026-09-04 the hits-only version of this test offered to delete 20 of 44 harness lessons, including a gate that had surfaced 34 times that same week. surfaces is written by the telemetry module's scan-lessons.nu sync and is absent until a domain has been synced at least once, so distill checks whether any row in the domain carries the field and, if none do, falls back to the old hits-only test and prints the list as a WEAK LIST – naming it as weak, since a hits-only list still names lessons that are alive and merely unconfirmed. A bare distill only names the candidates and prints the follow-up command; distill <domain> --drop is the one thing here that actually removes anything, in the whole store – everything else, expire, miss's review flag, a cap breach, is flags-only. It is deliberately two calls – the list goes to finn, and an agent never passes --drop off its own judgement. The cluster pass that follows in the same command runs on the survivors after a drop, not on the rows that were just removed. remove <domain> <id> is the other, unrelated way a row leaves the store – one lesson named by hand, with a confirm, for undoing a bad add; it takes no filter and is never a drop pass wearing another name.

A standing rule in the harness's own CLAUDE.md holds --drop unrun entirely until 2026-10-01, whatever a domain's drop list shows: the hit and surface counters landed long after most of the store did, so an early lesson reads as never-hit-and-never-surfaced simply because nobody was counting yet, and dropping on that signal would delete live rules for having been early rather than for being wrong. The date is the amnesty window, long enough for the older rows to accumulate real hits or surfaces and be judged on those instead. A merge through the cluster pass is not a drop and stays fine throughout.

Caps keep a slice readable: 60 rendered entries per domain right now, 25 for project rules, 15 for global. That domain cap is a temporary raise from its usual 40 – landed 2026-09-05 alongside the drop amnesty above, and due back down to 40 the same day the amnesty lifts, 2026-10-01. With drops frozen till then, the only way under a cap is a merge, and distill had run out of clusters to merge: harness sat at 49 rows against one weak cluster, so a cap nothing could meet was just training everyone to ignore the warning. render warns loud on a domain breach and stats shows every tier, and a breach is the cue to run distill, which clusters overlapping lessons for a merge – the merge itself is agent work, not script work. garden runs the whole cycle in one pass: expire, then stats, then the distill clusters, then a count of the never-hit lessons past the drop age – flagging only. Garden itself still never merges and never drops; it is distill --drop, run by hand, that does the one deletion in the cycle. efficacy sits beside garden as a second, read-only report – domain by domain hit/miss health rather than domain by domain staleness – and neither call mutates anything.

Connects to ​

  • Its own hooks: store/hooks/inject-lessons.nu (UserPromptSubmit) ships inside the lesson-injector part, a part of its own that draws under memory in the picker (needs: ["memory"]) rather than a bundled option inside it, and store/hooks/debrief.nu (SessionEnd, the debrief sub-part of memory, opt in) banks new lessons back through lessons.nu add --source extracted.
  • Read before drafting by skill-smith – lessons.nu find "<topic>" turns stored lessons into anti-patterns a new skill must dodge, and a distill cluster of several lessons on one topic can propose a whole new skill.
  • Placed by the installer – each part copies to its own destination inside a target project's .claude/: the store to .claude/memory/, /lesson to .claude/commands/, the lesson-recall skill to .claude/skills/, and lesson-injector's hook and settings fragment into .claude/memory/hooks/ and alongside the store.
  • Writes its own add, reject, and remove events into the shared harness-meta.jsonl telemetry stream, addressed through the same store-pointer resolve every telemetry tracker uses, so a copy of this store installed in any project can still write back to the one place the harness reads from. The relationship runs the other way too now – scan-lessons.nu sync, part of the telemetry module, reads back over transcripts and writes surfaces and last_surfaced onto this store's own rows, which is what lets drop-candidates and last-seen tell a reachable lesson from a merely unconfirmed one.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/memory/USAGE.md – that one is the thin command, config and gotcha reference, this page is the deeper read on how the pieces are built.