Skip to main content

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

Local checkout:

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 produce task 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 or schedule.enabled is false, 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 procedure and failure lessons 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

With exportMarkdown left on (the default), lessons are exported into your workspace at:
These files are a human-readable audit trail. The machine-readable store is separate and is the authoritative copy - see Learning Core (admin) for where that lives.

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.
While a lesson is active you can act on it in the drawer. Edit writes a corrected version (up to 400 characters, plus an optional note) and retires the old one. Endorse marks it as a good example. Retire stops it being used; add a note so the record shows why. Retired lessons are not editable, and the drawer shows the reason they were retired. Your review feeds back into learning: lessons you endorse, retire, or edit become examples the judge sees. Endorsed ones show it what a good lesson looks like, retired ones what to avoid. After this update the tab shows three data changes in every state:
  • 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.
Apart from those, in normal operation (upgrade repair finished, every agent on its recorded workspace) the tab behaves as it always has. Approving or rejecting several proposals at once works through them in order and stops at the first one that fails; the ones after it are left undecided. Three states change what the tab shows, and each is reported rather than hidden:
  • 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 with scope_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 Core also registers an owner-only 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 a learning 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
It is pulled through 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 the learning 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 under plugins.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 reports scope_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 in logging.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.