Learning Core (plugin)
Lesson-first learning loop with queued skill proposals. This page is for people who use the agent and review what it learned. Operators who run the Gateway should also read Learning Core (admin); plugin authors, Learning Core (developer). Run costs and lesson health are in the Dreams view. Learning Core watches finished chats, notes a short candidate when a chat ends, and later turns repeated corrections and failures into lessons. When a lesson has recurred enough times it queues a skill proposal. It never writes a skill by itself: applying a proposal is an explicit approval step you make.Install
Turning it on
The plugin is disabled by default. Enable the plugin entry, then set the mode:mode accepts off, observe, and assist. off stops capture entirely. observe is the
default: it records candidates and can promote them into lessons, but does not change what the
agent says next. assist does the same capture work and feeds a few active lessons into the
next reply so the agent can use them.
What it does
- Notes a candidate when a chat ends. The plugin claims that finished chat and stores a redacted window of up to 12 messages (4,000 characters) around the message it anchors on - usually your last correction. Heartbeat, cron and subagent turns are dropped before capture, so a chat with nothing you said produces no candidate. It does not write a lesson at that moment.
- Promotes candidates into lessons. A background
producetask turns pending candidates into lessons shortly after the chat ends, using LLM consolidation when it is configured and able to run, and the deterministic promote step otherwise. Promote runs right when the chat is claimed instead when background tasks are off orschedule.enabledisfalse, so you still see a lesson without waiting for a night-time job. Dream Cycle being on or off makes no difference. - Consolidates with a judge model (optional). With consolidation turned on and a model set, a judge model reads each new candidate - the stored message window plus up to five of the agent’s lessons (most similar first, filled out with the newest, so it can correct an existing lesson that contradicts the new one even when they share no words) and up to six examples you endorsed or retired - and decides to add a lesson, update or replace one, retire one, or do nothing. Every lesson it adds must cite the messages that taught it and name its kind: a correction, a preference, a procedure, or a failure. Lessons that state facts about you or other people are rejected; facts belong to the agent’s memory, not lessons. It runs within a daily call cap per agent; once the daily cap is spent, consolidation waits until the next day without calling the model. It needs a SQLite or Postgres store. Promote, by contrast, makes no model call: it merges repeats of the same lesson text using the thresholds below.
- Counts recurrence. A lesson seen once is recorded but not acted on. Repeats increment an occurrence count and record which chats they came from.
- Queues skill proposals. Once a lesson passes the promotion thresholds, or a distill pass
picks an eligible lesson, a proposal sits in a queue waiting for you. Distill is selective: it
only considers
procedureandfailurelessons that have recurred at least twice, or that you endorsed or edited. - Exports a readable trail. Lessons are written as Markdown into your workspace so you can read what the agent thinks it learned without touching a database.
Where lessons appear
WithexportMarkdown left on (the default), lessons are exported into your workspace at:
Reviewing what was learned
Open the Learning tab in the control panel. You can search lessons, preview a proposal before you decide, and approve or reject several proposals at once. Clicking a lesson row opens the lesson drawer, which shows:- What the lesson says, its kind and whether it is active or retired.
- Why it was written: the judge’s one-sentence rationale, or a note saying none was recorded for lessons created before this tracking existed.
- Where it came from: who produced it (the judge, a promotion, or you), the model and the judge prompt version, and when.
- The evidence it learned from: the quoted messages with the speaker, each with an Open session button that jumps back to that chat.
- Its history: earlier versions of the lesson and when each was valid.
- The skill proposals built from it.
- Legacy-only proposals are listed. Proposals that existed only in an older fs-jsonl log are copied into the database by the one-time upgrade repair, then appear in the queue and can be decided like any other.
- Upgrade counts can be lower bounds. Before the upgrade repair finishes, SQL reads include
only the newest 8 MiB of a legacy learning log. An incomplete legacy window marks counts
truncated; after repair, counts come from SQL aggregates. - Records are grouped by canonical workspace. Lessons and proposals are grouped and filtered under each agent’s canonical workspace (its configured workspace path), so records written under an older workspace key appear with that agent once the repair has moved them.
- Decisions wait for the upgrade repair. Until the one-time
upgrade fence finishes its repair, approve and
reject fail with
repair_pending. A proposal of an agent whose workspace does not match the recorded one fails withscope_mismatch. Internal skill-name claims are never decidable. - Mismatched agents are hidden. When this Gateway resolves a different workspace for an agent
than the one recorded in the shared database, that agent’s lessons and proposals are left out
of the tab, and opening one of its proposals fails with
scope_mismatch. See Learning workspace. - Older lessons may be cut before the repair. On SQLite or Postgres, before the repair
finishes, lessons that still live only in the old fs-jsonl log come from a bounded window of
its newest part. When that window does not reach the start of the log, the lesson list reports
truncated.
learning tool. Ask your agent to use it, or call it
directly. The actions are:
Every action is refused unless the caller is the workspace owner.
On glasses
Learning Core registers alearning glance widget for display-glass clients (ADR 0107). Titled
Learning, it refreshes every 5 minutes
and renders three lines from the same aggregates the overview RPC uses:
<N> proposals pending<N> lessons<N> applied
glance.widgets.list on the operator scope; it makes no decisions and writes
nothing.
Applying a proposal is gated
apply_proposal runs the proposal body through a security scanner before anything is written. A
proposal that trips a scanner rule is stored as quarantined. Apply accepts only pending
proposals; there is no transition from quarantined back to pending. Re-create the proposal
after review if you still want it applied. An approved skill is written as
~/.openclaw/skills/<name>/SKILL.md (or $OPENCLAW_STATE_DIR/skills/<name>/SKILL.md). This is the
point of the lesson-first design: a bad lesson is cheap to ignore, a bad skill changes behaviour
in every future session.
Correcting a lesson
Lessons are never deleted. In the lesson drawer, Edit writes a corrected version and links it to the lesson it replaces; the same supersede is available through thelearning tool
(supersede_lesson) if you prefer to ask the agent. The chain of what the agent believed and
when stays intact and auditable. The superseded lesson stops being active but remains readable.
Tuning when a lesson gets promoted
These live underplugins.entries.learning-core.config:
Correction lessons use
minOccurrencesWithCorrection and do not also have to clear
minOccurrences - being told directly that something is wrong is stronger evidence than a pattern
inferred from a failure.
maxLessonsForPrompt is read only when mode is assist. Consolidation and distill stay off
unless you set their enabled flags. Distill queues a proposal written by the configured model; it
does not write a skill file, and without a model it writes nothing.
If lessons stop appearing
After an update, new lessons can stop if Learning Core failed to start with the Gateway (the assistant that talks to you). You still see older lessons, but corrections from new chats never become lessons. What you should see after a healthy restart: the Gateway comes back. The next finished chat produces a new candidate (and later a lesson) only when learning is turned on and that chat includes something you said. If learning is off, or the chat has no human turn (heartbeat, cron and subagent turns are dropped before capture), no candidate is expected. If that does not happen, ask whoever runs the Gateway to restart it and confirm Learning Core loaded without a register error. Right after an update, Learning Core also finishes a one-time repair of its database before it learns anything new; chats that end during it are learned from once it completes. If the Gateway log reportsscope_mismatch, two Gateways that
share the learning database resolve different workspaces for the same agent; see
Learning workspace. Scheduled reminders that also stopped after the same
update are a separate cron-store issue; see Cron or heartbeat did not fire.
Privacy
Lesson text passes through a redaction layer before it is stored, covering credentials and API-key-shaped secrets, email addresses and phone numbers, plus any patterns you have configured inlogging.redactPatterns. So a key pasted into a correction does not reach the stored lesson text,
its evidence quotes, or the exported Markdown. Exported Markdown files and the state directory
are created private to your user.
Related
- Learning Core (admin) - storage backends, placement, verification
- Learning Core (developer) - store contract and extension seams
- Dream Cycle - produces repeated-work candidates; stops short of proposals
- Plugins
- Skills