# Expel Lesson Extractor

> Fires as a post-task hook after a non-trivial completed task (3+ tool calls, observable terminal outcome) to distil 0-N generalisable IF/THEN lessons from the trajectory and store them in RuVector so they surface at the start of similar future tasks; also invocable manually to record a lesson after a complex or failed task. NOT for trivial (<3 tool calls) or interrupted tasks, and NOT a general memory-write tool — it writes only ex:DistilledLesson records to the code-harness-lessons namespace. Schema, gates, prompt, and contradiction/archive policy live in references/.

- Skill: `dreamlab-ai/expel-lesson-extractor` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add dreamlab-ai/expel-lesson-extractor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dreamlab-ai/expel-lesson-extractor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dreamlab-ai (https://skillmd.com/u/dreamlab-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dreamlab-ai/expel-lesson-extractor

---


# ExpeL Lesson Extractor

**Status: Phase 1 — active (ExpeL, build cost S, no kernel dependency for lesson
storage; kernel improves evidence quality but is not required).**

See: ADR-019 §Mechanism 1, PRD-008 §3.4 / §7 Track B, DDD-005 §DistilledLesson.
Multi-tier memory table: `docs/developer/code-harness-multi-tier-memory.md`.

---

## When to Use

Invoke automatically via `claude-flow hooks post-task` when
`[features.expel_lesson_extraction].enabled = true`. Do not invoke manually
for trivial one-liner tasks. The minimum threshold is tasks with **3 or more
tool calls** — below this the trajectory contains too little signal for
generalisation (PRD-008 §7 C4).

May also be invoked manually after a complex or failed task where the agent
wishes to record a specific lesson explicitly, bypassing the automatic
invocation threshold.

## When NOT to Use

- Tasks with fewer than 3 tool calls (trivial-task filter; no lesson stored).
- Tasks that were interrupted mid-trajectory (ExpeL distillation only runs
  on tasks with an observable terminal outcome — success or explicit failure).
- Contexts where `[features.expel_lesson_extraction].enabled = false`.
- When the privacy filter (PrivacyFilterPort, ADR-008) is unreachable — the
  lesson is **dropped**, not written without redaction. Fail-closed is the
  contract. Emit `LessonRedactionFailed` event and return.

---

## Mechanism at a glance

Post-task, the runtime calls the `expel-distil` binary with the trajectory. It
privacy-filters the evidence, runs a templated extraction prompt to emit 0-N
IF/THEN rules, validates them against a write gate, and writes surviving
lessons to the `code-harness-lessons` RuVector namespace as
`ex:DistilledLesson` records. At the start of similar future tasks the lessons
are retrieved semantically and injected as a "Prior experience:" block.
Contradictions decay confidence over time and demote stale lessons to an
archive namespace.

All RuVector access is via `mcp__claude-flow__memory_*` only — never raw SQL,
never the `claude-flow memory *` CLI (both bypass the bge-small-en-v1.5
(384-dim, via Xinference) embedding pipeline and are invisible to HNSW search,
ADR-015).

---

## Reference index (load on demand)

| Topic | File |
|---|---|
| OWL2 classification, record schema, field definitions, write call pattern | [references/record-schema.md](references/record-schema.md) |
| Extraction prompt template and inputs | [references/extraction-prompt.md](references/extraction-prompt.md) |
| Write-gate steps and task-start retrieval/injection | [references/write-gate-and-retrieval.md](references/write-gate-and-retrieval.md) |
| Contradiction detection, conflict ranking, archive policy | [references/contradiction-and-archive.md](references/contradiction-and-archive.md) |
| Manifest gates, validator rules, hook registration, implementation notes | [references/manifest-and-hooks.md](references/manifest-and-hooks.md) |

---

## Related Files

- `expel-distil` (crate `services/agentbox-ops`) — post-task handler implementation.
- `skills/voyager-skill-library/SKILL.md` — Phase 2 verified skill library.
- `skills/agentdb-memory-patterns/SKILL.md` — memory_type discriminator details.
- `ontology/code-harness.ttl` — OWL2 class declarations.
- `docs/developer/code-harness-multi-tier-memory.md` — namespace / class table.
- `docs/archive/adr/ADR-019-experiential-skill-learning.md` — canonical decision.
- `docs/archive/prd/PRD-008-code-as-harness-integration.md` §3.4 / §7 Track B.
- `docs/archive/ddd/DDD-005-code-execution-domain.md` §DistilledLesson aggregate.
- `tests/code-harness/lesson-retrieval-queries.json` — C3 acceptance test fixture.