npm package: @openclawbrain/learner
Description: Learning-first candidate-pack and learned route_fn assembly for promoted OpenClawBrain artifacts.
Author: Jonathan Gu
Latest version: 0.3.4

# `@openclawbrain/learner`

Candidate-pack and learned `route_fn` assembly helpers for always-on OpenClawBrain learning.

This package stays on the artifact side of the boundary: it ingests normalized event exports, emits deterministic candidate pack payloads, and materializes pack directories for downstream validation and activation.

## Install

```bash
pnpm add @openclawbrain/learner
```

## Includes

- deterministic fast-boot candidate packs with live-first/background-backfill defaults
- init-graph payloads that classify OpenClaw markdown files by explicit role and carry ontology-backed node metadata
- pointer-aware working-set init that parses `MEMORY.md` plus linked notes into anchor, working-set, and passive-expansion layers
- seeded init-route priors over offline artifact roles with explicit heuristic-only handoff before PG route updates
- learned routing artifacts with stable `routerIdentity` values such as `pack-id:route_fn`
- explicit collected-label PG supervision from human feedback, self-memory labels, scanner-harvested labels, and canonical teacher artifacts
- human/self label-harvest surfaces embedded into graph blocks, vectors, and manifest summaries
- structural graph learning metadata spanning Hebbian reinforcement, decay, and split/merge/prune/connect ops inside emitted candidate-pack artifacts
- always-on runtime structural plasticity defaults to a low-churn guardrail plan: connect can turn on after at least two interactions, split/merge/prune wait for at least one feedback event, and every structural op is hard-capped to one application per runtime materialization cycle unless a caller disables it explicitly
- merge materialization is deterministic and narrow: when two non-synthetic blocks share enough signal (keyword overlap plus relation/source-stream evidence), the learner emits one synthetic topology node with `compactedFrom` lineage and reciprocal `merge`/`connect` edges; `packages/learner/test/learner.test.ts` locks that behavior down
- embedded workspace snapshot provenance inside emitted manifests
- on-disk materialization for coherent downstream activation and evaluation steps
- bridge-slice and bridge-bundle materialization helpers for continuous learner refreshes
- runtime-plan summaries that make fast-init, live-first priority, and passive-backfill backlog state explicit via `describeAlwaysOnLearningRuntimeState()`
- canonical teacher-supervision artifact builders with dedup and freshness metadata
- teacher-supervision-aware candidate packs that carry fresh operator guidance into future graph/vector payloads

Learned routing refresh now uses only explicit collected-label targets carried in router traces. This package does not preserve a heuristic learned-label fallback or spread supervision onto unrelated blocks by keyword overlap. Init-time heuristics remain limited to boot priors and structural topology.

Those structural-op fields describe candidate-pack materialization metadata. They are not a claim of live active-pack mutation during serving.

Pointer-aware init keeps fast boot first: `active-tasks.md`, today's `memory/*.md`, and anchor files such as `MEMORY.md` / `AGENTS.md` become top-priority boot inputs, while additional pointer-reachable docs stay in the working set or passive-expansion queue. Use `buildPointerAwareWorkingSet()` to inspect that layered selection directly.