Learning Core (admin)
Operational reference for Learning Core: where lesson state is placed, how to move it, and how to prove a deployed gateway is capturing lessons. For what the plugin does and how to review proposals, see Learning Core.Storage placement
Learning Core stores lessons in SQL, separately from the conversation tables. The shared domain-storage resolver follows the system session store backend by default: SQLite on an unconfigured host, Postgres when sessions use Postgres. No configuration is needed for the common case. File-backed serving and failure fallback have been removed. Resolved defaults, with<state> being the state directory (~/.openclaw unless
OPENCLAW_STATE_DIR says otherwise):
This placement follows the plugin table rule (ADR 0099,
dev-docs/adr/0099-plugins-own-their-tables.md): a plugin owns its tables in its own
namespace (Postgres schema plugin_<id>, SQLite prefix plugin_<id>_) and never reads,
writes, or alters core session tables. Conversation data reaches plugins through the
plugin-sdk, and pnpm lint:extensions:no-core-tables (part of pnpm check) fails on any
core table reference under extensions/.
Overriding placement
Setplugins.entries.learning-core.config.storage to pin a backend independently of the system
store:
- An explicit
backendwins outright. - With no
backend, adatabaseUrlimpliespostgresand asqlitePathimpliessqlite. - With neither, the system session store backend is used.
schema applies to Postgres only and must match ^[a-z_][a-z0-9_]{0,62}$. It is validated before
it reaches the database, because Postgres cannot parameterise an identifier. An unsafe value is
rejected at resolution, not interpolated.
Guards you should know about
- Backend name. An unrecognised
backendthrows at resolution rather than silently degrading. - Postgres without a URL. Resolving to
postgreswith nodatabaseUrlon either the override or the system store throws, naming the domain. - Collision with the session database. A
sqlitePaththat resolves to the same file as core’s own session database is refused. Learning state gets its own file so that a learning schema change can never affect session storage.
The table
Both SQL dialects use one table,learning_records, keyed
(workspace_id, agent_id, record_type, record_id). Payloads are JSONB on Postgres and TEXT on
SQLite. Two indexes are created: one on (workspace_id, agent_id, record_kind) for scope-filtered
reads, one on invalid_at for active-lesson filtering.
The DDL is CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS and runs on first use, so
there is no separate migration step to schedule. On Postgres the schema is created if absent.
record_type is the discriminator. Lessons stay record_type='lesson'. Finished-chat excerpts
land as record_type='candidate' in the same table. Do not add a record_kind='candidate'
column value or a second extraction_candidates table.
Optional search DDL (ALTER TABLE for a Postgres search_tsv generated column + GIN, or SQLite
FTS5) is skipped when the backend rejects it. searchLessons then scans listLessons(). A
capability downgrade is not implied by that skip.
Capture, promote, and apply
Asession.end claim admits one redacted candidate when the transcript has a human user turn
(heartbeat, cron and subagent turns are dropped before capture). The
capture is insert-if-absent: a redelivered claim never resets a candidate a producer already
finalized. No human user turn means no candidate row. What happens next depends on the route:
The claim is acknowledged only after the enqueue or the inline promote finished. A claim that
cannot proceed yet (a store outage after the claim, an enqueue that recovery admission refuses,
a bucket consolidation owns) is deferred without spending an attempt, so it never drifts toward
dlq. With mode: "off" nothing is captured or enqueued.
The passes are learning-core.produce, learning-core.promote, learning-core.consolidation,
learning-core.distill, learning-core.reconcile-skills, and learning-core.maintenance. Those
are the effective (namespaced) ids in task_runs and logs; registerTaskPass takes the bare
id and the backbone prefixes learning-core..
The produce pass
learning-core.produce chooses the lesson producer each run: consolidation (budgeted LLM) or
promote (deterministic). Consolidation is chosen only while it is runnable:
consolidation.enabled is true, consolidation.provider and consolidation.model are both set,
schedule.enabled is not false, the task pipeline is running, both
consolidation.maxCallsPerAgentPerDay and consolidation.maxCallsPerRun are above zero, the
lesson store is SQLite or Postgres, and the upgrade fence is active (below). Otherwise promote
runs. Dream Cycle’s state plays no part.
Each agent’s UTC day is one bucket with one producer. The first finalization or budget
reservation of the day records the owner, and every later finalization in that bucket must come
from the same producer (producer_conflict otherwise, which changes nothing). A bucket that
consolidation owns stays consolidation’s for the day, even if consolidation stops being runnable:
produce then records notRunnable and the candidates wait for the next day. Only a bucket with
no applied effect and no unrefunded consolidation spend can switch producer.
Every produce run records a pass.metrics row whose items.producer is consolidation,
promote, or null when the run took no ownership (nothing finalized and nothing spent), and
items.producerReason says why (disabled, unconfigured, notScheduled, upgrade_day,
notRunnable, frozen_conflict, cap_exhausted when the agent’s daily consolidation cap was
already spent so the run made no model call, no_effect, and so on; items.capExhausted: true
appears on every run that stood down for the cap). Standalone learning-core.promote runs record
the same fields.
When a produce run applied a lesson effect (in this attempt or an earlier one of the same work
item), it queues learning-core.reconcile-skills, and with distill.enabled, the reconcile run
queues learning-core.distill. These follow-ups are written in the same transaction that
completes the run. A consolidation run stopped by maxCallsPerRun or its time budget, with
candidates and daily capacity left, queues an immediate continuation; any other run that leaves
claimable candidates behind (including a spent daily cap, which writes no reservation rows) queues
a next-day carry, available at the next UTC midnight. Pending candidates are therefore processed
without a new session.
While consolidation is runnable, a standalone promote changes nothing: it neither writes lessons
nor skips untagged candidates. Promote also leaves alone any agent whose current UTC day’s bucket
consolidation already owns. A consolidation run that is not runnable records why in its
pass.metrics row: skipped is disabled, unconfigured, notScheduled, budget_disabled,
or store_unsupported, and items.scheduleActive shows the schedule state. tasks.runDryRun
reports the same reason with no model call.
This change takes effect after a gateway restart (Linux:
systemctl --user restart openclaw-gateway;
macOS: wednesdayai gateway restart --deep).
Consolidation needs a SQLite or Postgres lesson store. Each candidate is claimed before any
budget use or model call, so two overlapping runs never judge or apply the same candidate twice.
A run that finds a candidate claimed by another live run finishes the rest, then fails with the
retryable learning-core: candidates busy error. The daily budget lives in a learning_budget
table in the lesson store’s own database, so gateways that share the database share one cap.
Untagged candidates that the explore sample passes over stay pending. Once one is older than
7 days and has no recorded judge or no-output failure, a consolidation run finalizes it as
skipped with skipReason: "not_sampled_expired" (at most 200 per run). A candidate with
failures follows the quarantine rules instead.
The consolidation pass timeout is effectiveCalls x timeoutMs + 30 s (at most 5 minutes). A run
starts a judge call only if that call’s full timeoutMs still ends at least 10 seconds before the
pass timeout. All waiting counts toward this check, including waiting for another learning-core
run’s analysis call. When the next call no longer fits, the run stops with
stoppedEarly: "time_budget" and is not charged for that call. With maxCallsPerRun: 1, the one
call still fits unless the run has already waited more than about 20 seconds. Every call that
starts can therefore finish, and a verdict that returns within its call timeout is always
applied. A run that is aborted, for example at shutdown, never starts another paid call. The
distill pass follows the same rules.
The task cost class is fixed when the plugin registers. Consolidation registers as llm only
when it is enabled with a model, both caps are above zero, schedule.enabled is not false, and
the store is SQL. Otherwise it registers as deterministic. Distill uses its own test, with no
schedule or consolidation term. Only llm passes are held back by the restart-loop guard.
The previous consolidation-budget.jsonl ledger is imported once for the current UTC day, then
it is no longer written. You can delete it after the upgrade.
How the consolidation judge decides
For each selected candidate the pass sends its capture window to the configured judge model through the analysis runtime. The window holds up to 12 redacted user and assistant messages (4,000 characters at most). Heartbeat, cron and subagent turns are dropped at capture, and a session with no human turn yields no candidate. The pass also sends the anchor message, the tags, up to five of the agent’s active lessons (most similar first, filling remaining slots with the newest lessons even when they share no words, so a contradiction can be caught), and up to six operator-reviewed examples. The judge answers with one JSON verdict (action, lessonId, text,
kind, sourceIndexes, rejectCategory, reason, confidence from 0 to 1), and the plugin
validates it.
A lesson is a reusable rule for how the agent behaves. Facts about the user, other people,
events, health, money or legal matters belong to memory, and the judge rejects them. add and
update need text (at most 400 characters), a kind (correction, preference,
procedure, failure), and sourceIndexes that cite at least one user message in the window. A
noop needs a rejectCategory (fact, one_off, automated, transient_failure,
already_known, no_signal). The written lesson records its origin: the model, the judge
prompt version (judge-v2:<sha>), the rationale, and the analysis job id. It also keeps the cited
messages as evidence quotes with the speaker and the message timestamp.
update and delete must name one of the lessons shown to the judge; any other id is invalid
output. Every supersede uses a successor id derived from the old lesson and the candidate’s
session, so a retried run never writes a second successor.
The pass treats the model as having answered only when reply text came back. Token counts do not
count as an answer.
- Bad answer (not JSON, fails validation, or the store refuses it): the candidate records a failure and stays pending.
- No answer (timeout, empty reply, refusal, provider error): if another call in the run
answered, the candidate records a failure. Otherwise the run fails with the retryable
learning-core: analysis unavailableerror and records no failures. Two no-answer calls in a row also end the run that way. - Quarantine: after three recorded failures, or three UTC days of no-answer runs, the candidate is skipped for 7 days. It stays pending and is never deleted.
maxCallsPerAgentPerDay, whatever happened.
Only calls that never left the gateway are refunded: analysis concurrency limit exceeded
rejections and failures before dispatch, such as a missing API key. A long outage can therefore
use up the day’s calls; pending candidates then wait for the next UTC day. The pass retries up to
14 times with backoff from 1 minute to 1 hour, about 8 hours in total.
Each run records a pass.metrics row whose items hold the run summary (judged, added,
updated, superseded, invalidated, noop, the failure counters, and meanConfidence).
qualityScore is the mean verdict confidence, omitted when no verdict succeeded; the
Dreams view plots it as the consolidation quality trend. costSource follows the
Gateway pricing rule: a judge model declared under
models.providers reports priced, with costUsd: 0 when its entry has no cost block; a
model with no config entry reports unpriced with costUsd: null; and a run with a call that
returned no usage reports usage_unavailable.
How skill distillation works
Distillation turns a lesson into a skill proposal using the SQL lesson store. Withdistill.enabled but no provider/model, a run records unconfigured and writes no proposal.
There is no template fallback.
A lesson is eligible when it is active, has no proposal yet, is not deferred, and at least one
session merged into it ended completed (its successEvidence). Sessions with an unknown or
aborted outcome never count. Selection runs as one SQL query, oldest eligible lessons first,
with lessons that failed before sorted after untried ones.
- Name: the skill name is derived from the lesson text and id. The model never picks it,
and the name is the dedup key: a lesson that already has a proposal (from distill or from the
learningtool, under any name) is never authored again. - Skill-name claim: before any budget use the pass takes a global claim on the name, so two workspaces that learn the same lesson make one model call and get one proposal. The claim is a hidden record. It never shows in proposal lists, counts, or decisions.
- Authoring: the model returns a
descriptionand a Markdownbody. The description must containUse when:andNOT for:, be at most 1024 characters, and contain no<or>. The pass redacts both fields, writes the proposal body as aSKILL.mdwith YAML frontmatter (name,description), and rejects any result over 16 KiB. - Failures follow the consolidation rules: a bad answer counts a failure against the lesson,
and so does a no-answer call when another call in the run answered. Two no-answer calls in a row,
or a run where no call answered, fail with
learning-core: analysis unavailableand count no failure. After three counted failures (or three UTC days of no-answer runs) the lesson is deferred for 7 days. Calls that reached the provider count againstdistill.maxCallsPerAgentPerDay. - Continuation: when eligible lessons remain after a run, the pass enqueues one follow-up
distillrun for that agent and workspace. It is available at once while the day’s cap has room, otherwise at the next UTC midnight. Repeated runs reuse the same follow-up, so each scope has at most one pending follow-up.
pass.metrics row with authoring: "llm" and items such as considered,
proposed, alreadyProposed, budgetSkipped, the failure counters, and continuation.
Approved proposals write atomically to the managed skills root:
OPENCLAW_STATE_DIR is unset, that is ~/.openclaw/skills/<name>/SKILL.md. The write is
tmp-file + fsync + rename. learning-core.reconcile-skills restores a deleted or mutated file
from the proposal’s stored desiredState hash.
Capability levels
learning.overview reports a capability alongside the resolved backend:
Upgrade fence
On its first start, the new version installs a one-time upgrade fence in the lesson database (alearning_budget row with key meta:upgrade-fence) and repairs the database in bounded
batches before any learning writer runs:
- It finalizes candidates that an older promote had already merged but never marked (a crash residue), so no lesson is applied twice.
- It copies lessons that exist only in the legacy fs-jsonl log into SQL.
- It copies legacy-only proposals into their scopes and records their skill names, so distill never re-authors them. Lessons named by any proposal are flagged as proposed.
- It moves every agent’s older learning rows onto the agent’s canonical workspace (below).
repair_pending): no session claim is
taken, produce, promote, consolidation, distill, and reconcile runs fail and retry, and the
owner’s learning tool and learning.decideProposal return UNAVAILABLE. The repair runs from a
background service at gateway start, even with the task pipeline disabled, and resumes after a
crash or a SQL outage. Several gateways sharing one database run one repair between them.
Steps 2 and 3 read one legacy log: the one of the gateway that installed the fence. At install
the fence records that log’s files by their path relative to the plugin log directory, with each
file’s size and content hash (meta:legacy-source). Another gateway continues those steps only
when its own legacy log is the same (same relative files, same content). A gateway with a
different legacy log leaves them to the installing gateway: it logs fence_source_mismatch, its
writers stay repair_pending, and learning.overview reports
fence: { state: "repair_pending", reason: "fence_source_mismatch" }. Its own legacy-only lessons
and proposals are not copied. repaired_at is set only after every lesson and proposal in the
recorded log has been copied, and the repair position only moves forward.
The fence also fixes an activation time: the next UTC midnight after install. Until then
(upgrade_day) promote is the producer; from then on consolidation can own a bucket.
Stop every older gateway that shares the learning database before the first new-version gateway
starts, because older versions ignore candidate claims. A downgrade after the upgrade is not
supported.
Learning workspace
Every learning record is scoped to one canonical workspace per agent: the agent’s configured workspace (agents.list[].workspace, else agents.defaults.workspace for the default agent),
as an absolute path. A sandbox directory is never used. The id is recorded in the database
(canonical:<agentId>) and never rewritten. It is recorded only by a gateway that configures the
agent (in agents.list, or the default agent), in one of two ways:
- when that gateway installs or repairs the upgrade fence;
- on that gateway’s first learning write for the agent.
agent_unconfigured.
Gateways that share a learning database must resolve identical absolute workspaces for each
agent (the same HOME, OPENCLAW_HOME, OPENCLAW_PROFILE, and state directory). A gateway
that resolves a different workspace logs scope_mismatch for agent <id> and fails closed for
that agent: it captures nothing, moves nothing, and its session claims wait. Changing an agent’s
workspace after the upgrade is not supported either; to recover, restore the recorded workspace
path.
The same rule covers every learning entry point on that gateway, not only capture:
- The standalone
promote,consolidation,distill, andreconcile-skillspasses fail withscope_mismatch, whether their payload names the agent and workspace, only the agent, or nothing (then the default agent). They make no model call and write nothing. producealso fails closed when its payload workspace is not the agent’s recorded one.- The
learningtool,learning.decideProposal, and the workspace-resolution sidecar refuse. - The maintenance pass and the startup sweep never queue work for a mismatched scope, and the
maintenance retention never deletes a
learning_budgetrow of a mismatched agent (the gateway whose workspace matches trims them). - Operator reads: a read with
agentIdfor a mismatched agent fails withlearning unavailable: scope_mismatch. For an agent that this gateway does not configure and that has no recorded workspace, it fails withlearning unavailable: agent_unconfigured. A read withoutagentIdexcludes the rows of every mismatched agent and names them inmismatchedAgents.
scope_unavailable, retried daily) and is
never captured into a guessed workspace. A session claim for an agent that this gateway does not
configure and that has no recorded workspace (for example, an agent removed from agents.list
with claims still pending) waits too (agent_unconfigured, retried daily). It never holds up the
session claims of the configured agents.
Recovery and retention
Aproduce, distill, or reconcile-skills item that exhausts its 14 attempts goes to the
dead-letter queue, and there is no operator replay for task work. Its candidates stay pending
and are picked up again by:
- the agent’s next session end or idle event;
- the next-day carry;
- the startup sweep: once the task pipeline runs, each gateway start queues one recovery
produceitem per (agent, workspace) with pending candidates; - the daily
learning-core.maintenancepass, which queues one recovery item per scope per day for pending candidates, eligible distill lessons, and applied proposals.
learning-core.maintenance runs at startup and then daily through its own next-day follow-up,
even when the lesson store is unreachable. It also trims the learning_budget table by row kind:
denied, refunded, and imported reservations after 35 days; spent reservations and per-item effect
rows only once their work item is finished (and effect rows after the 30-day task-run
retention); a bucket’s owner row once nothing retained supports it. Rows of a work item that can
still be retried are kept however old they are, and the fence rows are never deleted.
Migrating from a JSONL deployment
No migration command is required. Retired file-backend configuration is removed on config load. The upgrade fence copies legacy lessons and proposals into SQL in bounded batches. Until it setsrepaired_at, reads also show the newest part of the old log, so
lessons captured before the move stay visible.
The read-through is deliberately conservative and worth understanding before you plan a cutover:
- It only reads. It never locks the log, never creates the directory or a lock file beside it, and never rewrites, compacts, or deletes it.
- It is bounded. Before
repaired_atit reads at most the newest 8 MiB or 2,000 lessons of the log, never the whole file. When that window does not reach the start of the log,learning.overviewcounts are lower bounds andtruncatedistrue,learning.listLessonsreportstruncated: true(older legacy-only lessons are missing), and similar-lesson ranking recordsselectionTruncated: truein itspass.metricsrow. - After
repaired_at, every read is SQL only and the old log is never opened again. Lessons of an agent this gateway does not configure stay under their legacy scope key in SQL until that agent is configured and re-keyed; SQL reads include them. - Where a lesson id exists in both places, the SQL row wins - it is the newer state.
- It covers lessons only. A proposal that exists solely in a legacy log is not folded in and will not appear in the queue until the fence copies it.
learning.overview reports the
lesson counts you expect from the SQL backend and its fence.state is no longer
repair_pending, you can archive the JSONL directory at your leisure.
Backend failure behaviour
A SQL outage never switches reads or writes to files.- SQLite that cannot be opened (unwritable path, corrupt file) logs a warning. Every data
operation reports retryable
store_unavailable. A missing parent directory is created automatically; an invalid or unwritable path still needs repair. - Postgres connects lazily. Connection failures surface on the operation; the store remains Postgres and subsequent operations can retry against SQL when service is restored.
store_unavailable.
Check the gateway log and database connectivity rather than looking for a reduced-capability
backend. The retained legacy read-through is for upgrade data, not outage recovery.
Verifying a deployment
Do not infer capture from a green test suite. Observe the live system. None of these scripts callwednesdayai gateway start (that would restart the live unit).
Candidate / pass / apply (current loop):
OPENCLAW_VERIFY_SESSION_ID is fail-closed (exit 2). A skipped consolidation or reconcile
leg is not a pass. The script also runs the isolated placement check.
Placement only (never touches live config):
~/.openclaw/openclaw.json.
C0 tracer-bullet (lesson-on-claim): scripts/verify-learning-core-c0.sh still exists and
expects a record_type='lesson' row for the claimed session. After the candidate swap that is
only true when promote ran inline (consolidation not runnable). Prefer the full script
on current builds.
Observability
Ten gateway methods (reads first; decide, revise and rate methods mutate):inspectLesson needs the read scope. reviseLesson and rateLesson need the approvals scope and
write a lesson.revised, lesson.endorsed or lesson.retired audit row. The actor is the
client name plus the paired device id. Endorsed, retired and operator-edited lessons become the
judge’s good and bad examples. SKILL.md proposals are distilled only from procedure and
failure lessons that have at least two occurrences, an endorsement, or an operator edit.
learning.decideProposals decides the ids in order. When every id succeeds it returns
{ proposals }. At the first failure it stops and fails with UNAVAILABLE failed to decide;
the ids before it stay decided and the ids after it are not attempted. The error details are
{ proposalId, reason, message, decided, notAttempted }: the failing id, its cause (reason is
scope_mismatch, repair_pending, agent_unconfigured, and so on, when the item failed at a
gate), the item’s own error message, the ids already decided, and the ids not attempted.
learning.listLessons adds truncated: true when, before repaired_at on SQLite or Postgres,
the legacy log window it read did not reach the start of the log (older legacy-only lessons are
then missing). learning.searchLessons returns up to k hits after it drops the rows of
mismatched agents: it widens the store query until k visible hits are found or the store runs
out, up to 1,000 candidates, and adds truncated: true if that ceiling stopped it first.
The four list and overview reads take an optional agentId, which narrows them to that agent’s
recorded workspace. Without it they span every agent except the mismatched ones (see
Learning workspace), which the response lists in mismatchedAgents.
On SQLite and Postgres, learning.overview counts are database aggregates and truncated is
false. Before the upgrade fence sets repaired_at, the legacy read-through can add lessons
from the newest 8 MiB of the old log. When that window is incomplete, the counts are lower bounds
and truncated is true.
On SQLite and Postgres, learning.overview also reports fence: { state, reason? }, where
state is repair_pending, upgrade_day, or active and reason is fence_source_mismatch
when this gateway stands by for another gateway’s repair. The field is left out when the SQL
store is unreachable.
These status codes show up in the gateway log, in pass errors, in learning.overview, and in
learning.decideProposals error details.reason:
Learning Core is a session consumer with
effectKind: session.end over all lanes. Its claims are
in session_consumer_claims under a namespaced consumer id of the form
<agentId>:learning-core:session.end - not the bare plugin id. Query with a prefix match, or you
will find nothing while the claim is sitting there processed. See
Session consumer claims.
The active JSONL log has its own rotation profile, extensions.learningCore. It is path-indexed,
so maxFileBytes, maxBackups, compress, and maxQueuedBytes apply and file is ignored. See
the configuration reference.
Troubleshooting
Claims are processed but no lessons appear. That is expected on the claim path. Confirm arecord_type='candidate' row exists for the session (verify-learning-core-full.sh). A lesson
appears only after promote (inline whenever consolidation is not runnable) or after a
consolidation pass. If even the candidate is missing, the transcript had no human user turn.
learning.overview reports a backend you did not configure. Either the system session store
resolved differently than you expected, or a fallback fired. Check the gateway log for
lesson store backend failed.
Lessons from before a backend change are missing. Check that the legacy directory is still at
<state>/learning/learning-core/. The read-through resolves it relative to the state directory, so
a changed OPENCLAW_STATE_DIR hides the old log without deleting it.
Postgres permission errors on first use. The role needs CREATE on the database to create the
schema, or you can pre-create plugin_learning_core and grant table-creation rights inside it.
PLUGIN_REGISTER_ERROR: Plugin task pass id must not contain ”.” The plugin failed to load
because a pass was registered with a dotted id such as learning-core.promote. Pass ids must be
bare; the backbone namespaces them. After upgrade you should see 22 loaded (or your usual count)
and 0 register errors. Restart the Gateway after deploying the fix (Linux:
systemctl --user restart openclaw-gateway; macOS: wednesdayai gateway restart --deep).
Related
- Learning Core - what it does and how to review proposals
- Learning Core (developer) - store contract and extension seams
- Session consumer claims
- Configuration reference