The consolidation system of your development environment.
Learn is a post-session skill for Claude Code that consolidates working memory into durable long-term storage AND reconciles project documents with current reality. It runs at the end of every session, reviews what happened, extracts what's worth remembering, and ensures STATUS.md, ISSUES.md, PLAN.md, and README.md reflect the truth.
Most sessions produce zero memories. That's correct. But most sessions that touch code DO shift project state — and documents that don't reflect reality create proactive interference for the next session.
AI coding assistants forget everything between sessions. Every conversation starts from zero. Your memory system (.claude/projects/*/memory/) solves storage, but not curation — what gets stored, how it's organized, when it's retired, and when patterns should be promoted from passive memory to active infrastructure.
But memory isn't the only thing that drifts. Project documents — STATUS.md, ISSUES.md, PLAN.md, README.md — degrade too. A STATUS.md that says "In Progress: auth setup" three sessions after auth shipped is proactive interference. A PLAN.md with unchecked items that were completed last week is noise. An ISSUES.md that doesn't reflect what was just resolved creates false urgency.
Learn solves both problems by modeling how human memory actually works — not the folk model ("memory is a filing cabinet") but the neuroscience model ("memory is a living system that encodes selectively, consolidates actively, prunes ruthlessly, and promotes patterns into procedural knowledge"). The same reconsolidation principle that governs memory files applies to project documents: read them, reactivate them, update them.
The result: your development environment gets smarter with every session, and your project documents stay aligned with reality.
Learn is grounded in nine principles from cognitive neuroscience and memory research. Each maps directly to a step in the skill's workflow.
Source: Piotr Wozniak, SuperMemo (1990s–present)
Complex knowledge is built from simple, atomic pieces connected by association — not from compound entries that try to capture everything at once. Each memory item should encode exactly one piece of information.
In Learn: Every memory file contains one idea. If a session learning contains "and" connecting two distinct insights, it becomes two separate memories. This is the foundational rule — everything else builds on it.
Why it works: Atomic memories have higher retrieval accuracy. Compound memories create retrieval interference — you recall part of the bundle but not the part you actually need. Wozniak's decades of SRS research consistently show that simpler items have dramatically better retention curves.
Source: Craik & Lockhart, "Levels of Processing: A Framework for Memory Research" (1972)
Deeper processing at encoding time produces stronger, longer-lasting memories. Shallow encoding (surface features) decays fast. Deep encoding (meaning, connections, implications) persists.
In Learn: Every memory includes a Why: line (forcing intermediate-depth processing) and a How to apply: line (forcing deep processing by connecting the learning to future action). Recording what happened is shallow. Recording why it matters and when it applies is deep.
Source: Frederic Bartlett, Remembering (1932); Jean Piaget, The Construction of Reality in the Child (1954)
New information is processed through two mechanisms:
- Assimilation — absorbed into an existing mental model (schema)
- Accommodation — existing schema is restructured to incorporate genuinely new understanding
In Learn: The consolidation step defaults to assimilation: update an existing memory with new context. Accommodation — creating an entirely new memory — is reserved for genuinely novel insights that don't fit any existing schema. This prevents memory bloat while keeping the system adaptive.
Source: LaBar & Cabeza, "Cognitive Neuroscience of Emotional Memory" (2006); Cahill & McGaugh, "Mechanisms of Emotional Arousal and Lasting Declarative Memory" (1998)
The amygdala-hippocampal circuit prioritizes emotionally salient events for encoding. Strong emotional signals during an experience predict stronger memory consolidation.
In Learn: The recall step prioritizes encoding for four emotional signals mapped to development sessions:
| Emotion | Session Signal | Priority |
|---|---|---|
| Frustration | Something took longer than expected, dead ends hit | HIGH |
| Surprise | Something worked or failed unexpectedly | HIGH |
| Correction | User redirected the approach | HIGHEST |
| Relief | Long-standing issue finally resolved | MEDIUM |
Routine, expected outcomes are skipped — they carry no encoding signal.
Source: Nader, Schafe & LeDoux, "Fear Memories Require Protein Synthesis in the Amygdala for Reconsolidation after Retrieval" (2000)
When a stored memory is reactivated, it enters a labile state and must be re-stabilized (reconsolidated). During this window, the memory can be updated, strengthened, or modified. This is not a bug — it's the mechanism by which memories stay current.
In Learn: When checking for existing memories during consolidation, each existing memory that's read is reactivated. This is the reconsolidation window. Learn uses it to update the memory with new context rather than leaving it unchanged and creating a parallel entry. Every update is both a retrieval event (strengthening) and an integration event (modernizing).
This is why "update > create" is a core constraint, not just a preference. It's how biological memory works.
Source: McClelland, McNaughton & O'Reilly, "Why There Are Complementary Learning Systems in the Hippocampus and Neocortex" (1995)
The brain uses two systems with different learning speeds:
| System | Speed | Function | Biological Home |
|---|---|---|---|
| Hippocampal | Fast (one-shot) | Specific episodes, exact details | Hippocampus |
| Neocortical | Slow (gradual) | General patterns, abstractions, procedures | Neocortex |
Over time, specific episodes that recur get "replayed" and gradually extracted into general knowledge that lives in the neocortex. This is why you can recall the general rule long after forgetting the specific incident that taught it to you.
In Learn: Individual memory files are hippocampal (fast, episodic). Skills, hooks, and conventions are neocortical (slow, procedural). The elevation step detects the hippocampal-to-neocortical transition: when 3+ memory files encode variations of the same pattern, it's time to extract that pattern into a skill, hook, or convention. The specific memories become unnecessary once the abstraction exists.
Source: Ebbinghaus, Memory: A Contribution to Experimental Psychology (1885); Cepeda et al., "Distributed Practice in Verbal Recall Tasks" (2006)
Without reinforcement, memories decay along a predictable exponential curve. Memories that are retrieved at spaced intervals resist this decay. Memories that are never retrieved become noise.
In Learn: The prune step retires memories that have been superseded, contradict current state, or reference passed deadlines. If a memory is never reconsolidated across multiple sessions, it's evidence that it wasn't actually useful — a natural signal for pruning. Conversely, memories that keep getting updated are proving their relevance through the spacing effect.
Source: McGeoch, "Forgetting and the Law of Disuse" (1932); Underwood, "Interference and Forgetting" (1957)
Two types of interference degrade memory retrieval:
- Proactive interference — old, stale memories interfere with new learning
- Retroactive interference — new, similar memories interfere with recall of older ones
In Learn: Pruning stale memories reduces proactive interference. Merging near-duplicate memories reduces retroactive interference. Using specific, distinctive description fields in frontmatter improves discrimination during retrieval — the memory system can find the right memory faster when descriptions are precise.
Source: Bjork, "Memory and Metamemory Considerations in the Training of Human Beings" (1994)
Making encoding slightly harder (not impossible, just effortful) improves long-term retention. Easy encoding produces weak traces.
In Learn: Memories are written as principles — not just records of what happened. The Why: line forces elaborative processing. The How to apply: line forces prospective encoding (projecting the learning into future scenarios). This additional encoding effort produces memories that are more deeply integrated and more reliably retrieved.
Learn runs a six-step pipeline that mirrors the stages of human memory consolidation, extended to include project document reconciliation:
Session Buffer (conversation)
|
[1. RECALL] .............. sensory gating — scan for learning signals
|
[2. ENCODE] .............. atomization — one idea per memory, six gates
|
[3. CONSOLIDATE] ......... integration — update existing > create new
|
[4. PRUNE] ............... forgetting — retire stale, resolve interference
|
[5. ELEVATE] ............. abstraction — patterns become skills/hooks
|
[6. RECONCILE] ........... document sync — STATUS, ISSUES, PLAN, README
|
Long-Term Memory (files)
Scans the session conversation for high-signal moments, ranked by encoding priority:
- User corrections — "no", "don't", "not that" (highest signal)
- Errors or failures that revealed something non-obvious
- User confirmations of non-obvious choices
- Architecture/design decisions with rationale
- New external resources or tools
- User role/expertise insights
- Project constraints or stakeholder context
Every candidate learning must pass six gates to be encoded:
| Gate | Question | Principle |
|---|---|---|
| The "And" Test | Does this contain two distinct ideas? Split it. | Minimum Information |
| The 30-Day Test | Would this matter in a month? | Forgetting Curve |
| The Derivability Test | Is this in the code, git log, or docs already? | Desirable Difficulty |
| The Specificity Gradient | Actionable AND transferable? | Schema Theory |
| Type Assignment | feedback / project / user / reference? | Levels of Processing |
| Description Quality | Would a future session find this? | Interference Prevention |
For each encoded memory:
- Read the existing memory index
- Search for topical overlap with existing memories
- If overlap exists: reconsolidate — read the existing file, update it with new context (schema assimilation)
- If genuinely new: create a new memory file (schema accommodation)
- Update the index
While reading existing memories during consolidation:
- Flag memories that contradict current code/project state (proactive interference)
- Flag memories superseded by better understanding (redundancy)
- Flag project memories with passed deadlines (temporal decay)
- Merge near-duplicates (retroactive interference prevention)
Detect when episodic memories have accumulated enough to warrant procedural abstraction:
| Pattern | Elevation Target |
|---|---|
| 3+ feedback memories about the same mistake | Hook (automated prevention) |
| 3+ feedback memories about the same preference | Convention (CLAUDE.md entry) |
| 3+ reference memories about the same system | Consolidated reference doc |
| Complex multi-step process across memories | Skill |
Learn surfaces these patterns. You decide whether to act on them.
Synchronize project documents with current reality. Each document type serves a distinct retrieval purpose in a progressive disclosure hierarchy:
| Document | Question | Time Horizon |
|---|---|---|
| README.md | "What is this and how do I start?" | Permanent |
| STATUS.md | "Where are we right now?" | Session-to-session |
| ISSUES.md | "What's broken or incomplete?" | Days to weeks |
| PLAN.md | "What's the roadmap?" | Weeks to months |
For each document that exists at the project root:
- Read it — this is reactivation (Nader et al.)
- Compare against reality — what shifted this session?
- Update what changed — reconsolidate with new context
- Prune what decayed — old session entries, resolved issues, completed plan phases
- Cross-validate — issue counts in STATUS match ISSUES; plan progress aligns with STATUS
Key constraints:
- STATUS.md — always update if code was touched; keep last 10 session entries
- ISSUES.md — add discovered issues, close resolved ones, merge duplicates
- PLAN.md — check off completed tasks, collapse finished phases, flag stale items
- README.md — only update for structural changes (new deps, changed setup, restructured dirs)
- Skip documents that don't need changes — reconciliation without change is noise
- Create STATUS.md or ISSUES.md when warranted; never create PLAN.md or README.md unprompted
The same derivability test applies: don't persist in documents what's derivable from code or git. Issue context belongs in ISSUES.md; which lines of code were affected does not.
Learn is designed to get better with every session — not through code changes, but through the compounding dynamics of the systems it curates.
The memory system starts sparse. Learn encodes the highest-signal learnings: user corrections, critical project context, foundational preferences. Project documents get their initial structure — STATUS.md and ISSUES.md are created as needed, existing PLANs get their first checkmarks. The system is learning what matters.
Existing memories get reconsolidated with new context, becoming richer and more precise. Near-duplicates are merged. The prune step starts finding stale entries. The elevation step begins detecting patterns — the first suggestions to promote memories to skills, hooks, or conventions appear.
Project documents stabilize into reliable state: STATUS.md reflects reality, ISSUES.md tracks what's actually broken, PLAN.md shows real progress. The reconciliation step catches drift before it accumulates.
The memory system has been curated through dozens of consolidation cycles. The most important learnings have been reconsolidated many times and are deeply integrated. Patterns have been elevated to procedural knowledge (skills, hooks, conventions). What remains in memory is genuinely unique, non-obvious, and high-value.
Project documents have been pruned through dozens of reconciliation cycles. Completed PLAN phases are collapsed to summaries. Resolved issues live in git, not ISSUES.md. STATUS.md is a tight, accurate snapshot — not an archaeological record.
The key insight: Learn doesn't just add memories — it actively maintains the health of the entire project knowledge system. Each session is a consolidation cycle that strengthens relevant memories, prunes irrelevant ones, detects patterns, and keeps documents aligned with reality. The system converges toward an increasingly high signal-to-noise ratio over time.
Better memories + accurate documents
-> better context in future sessions
-> better decisions in future sessions
-> fewer mistakes to encode
-> fewer but higher-quality memories
-> less document drift to correct
-> better memories + accurate documents
Add to your ~/.claude/settings.json:
{
"extraKnownMarketplaces": {
"phdemotions-learn": {
"source": {
"source": "github",
"repo": "phdemotions/learn"
}
}
},
"enabledPlugins": {
"learn@phdemotions-learn": true
}
}Updates are automatic — Claude Code pulls the latest version from GitHub.
/learn
Integrate into your session-end hook chain:
/session-audit -> /learn
observe consolidate + reconcile
Learn handles both memory consolidation AND project document reconciliation (STATUS.md, ISSUES.md, PLAN.md, README.md). It is the single post-session consolidation pass.
Each memory is a standalone markdown file with YAML frontmatter:
---
name: Descriptive Title
description: One-line retrieval cue — specific enough for relevance matching
type: feedback
---
The rule or principle.
**Why:** The incident, preference, or constraint that taught this.
**How to apply:** When and where this guidance kicks in.| Type | Captures | Example |
|---|---|---|
feedback |
How to work (approach, style, preferences) | "Run full test suite, not just changed files" |
project |
Why things are this way (decisions, constraints) | "Auth rewrite driven by legal compliance" |
user |
Who we're working with (role, expertise) | "Deep Go expertise, new to React" |
reference |
Where to find things (external systems) | "Pipeline bugs tracked in Linear project INGEST" |
The following papers and books inform Learn's design:
- Bartlett, F.C. (1932). Remembering: A Study in Experimental and Social Psychology. Cambridge University Press.
- Bjork, R.A. (1994). Memory and metamemory considerations in the training of human beings. In J. Metcalfe & A.P. Shimamura (Eds.), Metacognition: Knowing about knowing (pp. 185–205). MIT Press.
- Cahill, L. & McGaugh, J.L. (1998). Mechanisms of emotional arousal and lasting declarative memory. Trends in Neurosciences, 21(7), 294–299.
- Cepeda, N.J., Pashler, H., Vul, E., Wixted, J.T., & Rohrer, D. (2006). Distributed practice in verbal recall tasks. Review of Educational Research, 76(3), 354–380.
- Craik, F.I.M. & Lockhart, R.S. (1972). Levels of processing: A framework for memory research. Journal of Verbal Learning and Verbal Behavior, 11(6), 671–684.
- Ebbinghaus, H. (1885). Memory: A Contribution to Experimental Psychology. Trans. H.A. Ruger & C.E. Bussenius (1913). Teachers College, Columbia University.
- LaBar, K.S. & Cabeza, R. (2006). Cognitive neuroscience of emotional memory. Nature Reviews Neuroscience, 7(1), 54–64.
- McClelland, J.L., McNaughton, B.L., & O'Reilly, R.C. (1995). Why there are complementary learning systems in the hippocampus and neocortex. Psychological Review, 102(3), 419–457.
- McGeoch, J.A. (1932). Forgetting and the law of disuse. Psychological Review, 39(4), 352–370.
- Nader, K., Schafe, G.E., & LeDoux, J.E. (2000). Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval. Nature, 406(6797), 722–726.
- Piaget, J. (1954). The Construction of Reality in the Child. Basic Books.
- Roediger, H.L. & Karpicke, J.D. (2006). Test-enhanced learning: Taking memory tests improves long-term retention. Psychological Science, 17(3), 249–255.
- Underwood, B.J. (1957). Interference and forgetting. Psychological Review, 64(1), 49–60.
- Wozniak, P.A. (1990). Optimization of Learning: Application of the SuperMemo Method. University of Technology in Poznan.
MIT