​

Learning Core

​

Enable the plugin

{
  plugins: {
    entries: {
      "learning-core": {
        enabled: true,
        config: {
          mode: "observe",
        },
      },
    },
  },
}

• off stops capture entirely.
• observe records candidates and promotes lessons but never changes replies.
• assist does the same capture work and injects up to maxLessonsForPrompt (default 5) active lessons into the next reply’s context.

​

Configuration reference

{
  plugins: {
    entries: {
      "learning-core": {
        enabled: true,
        config: {
          mode: "assist",
          minOccurrences: 3,
          minOccurrencesWithCorrection: 2,
          consolidation: {
            enabled: true,
            maxCallsPerAgentPerDay: 8,
          },
          distill: { enabled: true },
        },
      },
    },
  },
}

​

Storage placement

​

Overriding placement

{
  plugins: {
    entries: {
      "learning-core": {
        config: {
          storage: {
            backend: "sqlite", // "fs-jsonl" | "sqlite" | "postgres"
            sqlitePath: "/var/lib/wednesdayai/learning.db",
            databaseUrl: "postgres://user:password@db.internal:5432/wednesdayai",
            schema: "plugin_learning_core",
          },
        },
      },
    },
  },
}

1. An explicit backend wins outright.
2. With no backend, a databaseUrl implies postgres and a sqlitePath implies sqlite.
3. With neither, the system session store backend is used.

​

Guards

• An unrecognised backend throws at resolution rather than silently degrading.
• Resolving to postgres with no databaseUrl on either the override or the system store throws, naming the domain.
• A sqlitePath that resolves to the same file as core’s own session database is refused, so a learning schema change can never affect session storage.

​

Capture, promote, and apply

1. Capture. A session.end claim admits one redacted candidate when the transcript has a user excerpt, then acknowledges processed. No excerpt means no candidate row; the claim is still acknowledged. The claim path never writes a lesson.
2. Promote. The learning-core.promote task pass (deterministic) turns pending candidates into lessons. The budgeted LLM pass learning-core.consolidation does the same under its daily call ceiling. When Dream Cycle is off and consolidation.enabled is false, promote runs inline right after the claim ack, so observe-mode hosts still get lessons without a night-time job.
3. Apply. learning-core.distill and promotion thresholds queue skill proposals. Approval writes atomically (tmp file + fsync + rename) to $OPENCLAW_STATE_DIR/skills/<name>/SKILL.md (or ~/.openclaw/skills/<name>/SKILL.md). learning-core.reconcile-skills restores a deleted or mutated skill file from the proposal’s stored desiredState hash.

​

Capability levels

​

Backend failure behaviour

• SQLite that cannot be opened (unwritable path, corrupt file) falls back at construction with a warning logged. The parent directory is created if missing.
• Postgres does not connect at construction, so a refusing server surfaces on first operation. The first rejection logs a warning, swaps to the fs-jsonl store, and retries that one operation there, so the caller still succeeds. After the swap, further errors are the fallback’s own and propagate normally.

​

Migrating from a JSONL deployment

• The read-through only reads - it never locks, rewrites, compacts, or deletes the old log.
• 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 the legacy log does not appear in the queue.

​

Verifying a deployment

OPENCLAW_VERIFY_SESSION_ID=<a session that ended on this gateway> \
  bash scripts/verify-learning-core-full.sh

​

Observability

​

Troubleshooting

​

Related

• Learning - what your users see
• Learning Core internals - store contract and extension seams
• Dream Cycle - idle-time reflection that feeds learning candidates
• Configuration - top-level config file basics