Architecture
Layer 1: Episodes — core/learnings/episodes.jsonl (append-only)
Layer 2: Learnings — core/LEARNINGS.md (scored, max 30)
Layer 3: Rules — rules.md / CLAUDE.md (promoted, owner only)
CLI
Engine: ~/.claude/scripts/learnings-engine.mjs
ENGINE="node ~/.claude/scripts/learnings-engine.mjs"
# Record new episode
echo '{"context":"...","error":"...","rule":"...","impact":"high","tags":["workflow"]}' | $ENGINE capture
View scored learnings
$ENGINE score
Lint: find HOT (freq 3+), STALE (score < 0.15), PROMOTE (score > 0.8)$ENGINE lint
Promote learning to rules$ENGINE promote EP-20260411-007
Archive stale learning$ENGINE archive EP-20260411-009
Bump frequency (repeat violation)$ENGINE bump EP-20260411-001
Generate markdown report$ENGINE report
## Scoring
Composite score: `Recency (40%) + Frequency (30%) + Impact (30%)`
- Recency: `max(0, 1 - ageDays / 30)` — decay to 0 over 30 days
- Frequency: `min(1, freq / 3)` — 3+ violations = max score
- Impact: critical=1.0, high=0.7, medium=0.4, low=0.1
## Thresholds
| Condition | Action |
|---|---|
| Score > 0.8 | Propose promotion to rules (via owner) |
| Score < 0.15 | Propose archival |
| Freq 3+ in 30 days | ALERT: rule not working, change system |
## When to record
Record ONLY when:
- Owner explicitly corrected ("no, do it this way", "wrong")
- Expensive error (access, security, infrastructure, data)
- Repeated pattern (same mistake twice)
- Owner sets new standard/rule
Do NOT record:
- Normal clarifications
- Choice between options
- Minor style tweaks without pattern
## Episode format
```json
{
"id": "EP-YYYYMMDD-NNN",
"ts": "ISO8601",
"type": "correction|insight|knowledge_gap",
"agent": "{{AGENT_ID}}",
"source": "owner|experience|review",
"context": "situation",
"error": "what went wrong",
"rule": "rule for the future",
"impact": "critical|high|medium|low",
"tags": ["tag1"],
"freq": 1,
"status": "active|promoted|archived"
}
Access zones for auto-fix
| Zone | Files | Who edits |
|---|---|---|
| GREEN | SKILL.md, TOOLS.md, LEARNINGS.md | Agent autonomously |
| YELLOW | AGENTS.md, decisions.md | Agent with justification |
| RED | rules.md, CLAUDE.md | Owner only |
What to do at freq 3+
| Error type | Action |
|---|---|
| Forgot a step | Add hook (PreToolUse/PostToolUse) |
| Wrong response style | Update CLAUDE.md or rules.md (via owner) |
| Used wrong tool | Update TOOLS.md |
| Asked unnecessary question | Add rule to CLAUDE.md (via owner) |
| Code error | Add test or lint rule |
Hooks integration
- SessionStart: inject scored top-5 from
$ENGINE score - Stop: analyze session corrections, auto-capture episodes
- Weekly cron:
$ENGINE lint+ report to owner