​

Learning Core internals

​

Placement resolution lives in core

import { resolveDomainStorage, type DomainStoragePlacement } from "openclaw/plugin-sdk";

const placement = resolveDomainStorage({ domain: "learning-core", config });

type DomainStoragePlacement =
  | { backend: "postgres"; databaseUrl: string; schema: string }
  | { backend: "sqlite"; path: string }
  | { backend: "fs-jsonl"; dir: string };

​

The LessonStore contract

listLessons        getLesson        upsertLesson       mergeLesson
listProposals      getProposal      findProposalWithScope   listProposalsWithScope
insertProposalIfAbsent             upsertProposal     recordProposalDecision
appendAudit        listAudit
supersedeLesson    listActiveLessons                  getLessonChain
describeBackend
upsertCandidate    getCandidate     listPendingCandidates   markCandidateProcessed
searchLessons

// Do not invent a second table or overload record_kind.
await store.upsertLesson({ recordKind: "candidate", ...lesson });

await store.upsertCandidate(candidate); // record_type='candidate' in the same table

​

Record lifecycle

export const LESSON_RECORD_KINDS = ["lesson", "skill"] as const;
export const LESSON_DURABILITIES = ["durable", "decaying", "ephemeral"] as const;
export const LESSON_SCHEMA_VERSION = 1;

• withLessonDefaults stamps a new record with current defaults.
• applyLegacyLessonDefaults forward-migrates a pre-C0 record.
• isLessonActive evaluates valid_from / invalid_at against a supplied now - callers pass the clock in; the function never reads it.

​

Backend selection and fallback

• SQLite fails at open, so it is wrapped in a try and falls back immediately to the FileLearningStore.
• Postgres does not connect at construction. It is wrapped in FirstFailureFallbackLessonStore: the first rejection swaps the delegate and retries that one operation on the fallback so the caller sees success. After the swap, an error is the fallback’s own and propagates.

​

Task passes

​

Capture path

• When mode is off, the handler acknowledges without persisting.
• Otherwise it writes an ExtractionCandidate (only when a transcript excerpt exists) and acks processed. It must not call upsertLesson / mergeLesson.
• On a processing failure, the catch block logs api.logger.warn (message, error code, claim and session ids) before acking the claim as failed/retryable - a throwing ackSessionWork must never mask the real error.

​

Reading transcript text

1. Fixtures must use the real StoredConversationEntry shape. A { role, content } fixture is a shape that never occurs in production and will pass while the code is dead.
2. Text from storage carries a [<from> <host> <timestamp>] prefix, trailing space included. Correction patterns must account for it; a bare ^-anchored regex can never match.

​

Gateway and tool seams

​

Blocking the agent loop

export default function register(api: OpenClawPluginApi): void {
  const raw = fs.readFileSync("./lessons.json", "utf8"); // synchronous blocking I/O at startup
  api.registerTaskPass({ id: "promote", run: () => JSON.parse(raw) });
}

export default function register(api: OpenClawPluginApi): void {
  api.registerTaskPass({
    id: "promote",
    stage: "light",
    priority: 50,
    scope: "agent",
    costClass: "deterministic",
    run: async () => {
      await runPromotePass({ store, cfg, now: new Date().toISOString() });
    },
  });
}

​

Testing

​

Adding a backend

1. Implement LessonStore.
2. Add the dialect DDL to learning-schema.ts, keeping identifier validation in that module (the schema name is checked at both SQL interpolation boundaries, and again in the PostgresLessonStore constructor, because a caller can construct the store directly and bypass the DDL path).
3. Add the backend to the union in core’s domain-storage resolver and to SessionStorageBackendKind, so selection stays in one place.
4. Add it to BACKENDS in the conformance suite and make the suite pass unmodified.
5. Decide the failure surface - open-time or first-operation - and wire the matching fallback shape in the factory.

​

What’s next

• Learning Core admin - operation, placement, verification
• Analysis runtime - the LLM lane consolidation runs through
• Plugin manifest