Coordinator learning: knowledge, memory and reusable Skills

Status: Planned (R4). Nothing here is implemented: no operation ID or CLI command in this document exists yet. It adds no dependency, provider call, live migration or execution permission.

User outcome

A Project coordinator learns how its Project works from submitted requests, corrections, decisions and evidenced worker results. It maintains knowledge, memory and reusable procedures automatically and gives future workers the relevant parts. The user does not have to say "save this" or write a Skill after each task. A Workspace coordinator does the same for Workspace-scoped work and shared conventions. Automatic learning replaces the earlier manual-only memory rule, but ambient history injection and self-modifying authority stay forbidden (decision).

Example: the user explains the Website release checklist and corrects its order. The coordinator records the decision and maintains a release Skill. A later Website worker selects that Skill without being told again. The Skill teaches the process; it does not authorize a deploy. Sharing it with a sibling Project is a separate scope change.

This is persistent context and procedure authoring, not model training. It uses the same scoped LLM + Jev coordinator path as other automation, and the Node context contract selects context. With coordinators disabled or AI dependencies unavailable, manual CLI/API/SDK knowledge operations still work and no hidden learning model runs.

Three outputs, one source of truth

Each output uses an existing Node owner, not a separate learning backend:

• KB sources and outputs: Node artifact and library records.
• Memory: Node context records, extended to exact Workspace as well as Project scope, with source lineage and retention.
• Learned Skills: Node generated-resource records and their admission path.
• Session events supply source references, not a second copy of memory.

The optional Agent memory.* adapter is only an authorized read projection of these records. It is not write authority and not an R4 prerequisite. Its closed Project-only schema must be extended before it exposes Workspace reads.

Node owns records, access checks, revisions, events and receipts. Desktop renders them through the SDK. The Control Node keeps them when workers exit or the laptop disconnects; remote hosts receive only exact authorized context.

Every derived item records: exact Workspace or Project; source Session/turn or artifact IDs; source revisions and digests; author or deriving worker; provenance chain; inferred or user-stated status; evidence; content revision; learning-policy revision; visibility and export restrictions; retention; receipt. Confidence never turns an inference into a user decision. A generated claim cannot corroborate itself by being copied elsewhere.

Scope and admission

• Project: learns from its own eligible exchanges and results. No sibling Project history, titles, memory or content, even in the same Workspace, and no discovery beyond the bounded peer directory when both Projects allow Workspace reach (D-166). Human portfolio grants are not the coordinator's grants.
• Workspace: learns from its own communications and explicitly promoted Project material. It knows only its own Projects and permitted summaries. Membership is not a grant to private content, writes or exports.
• Session or worker: temporary context and candidate learnings cannot publish themselves across owners. Assignment grants bound retrieval and publication; sibling worker history is not preloaded by default.
• Global coordinator: owns its own context, authorized Workspace summaries and delegation results. No global memory built from private child chats.

The coordinator ownership contract applies to all memory, indexes, classifier inputs and results, caches and audit views. Apply its limits before search, counts, ranking, model export and context load. Shared resources are admitted projections, never a grant to discover their source. Node keeps full lineage but hides inaccessible source identities from the receiving Project.

Learning policy

A user confirms an exact, versioned learning policy for one scope:

• source sets and readers;
• allowed output kinds;
• retention and provider-export consent;
• size, cost and concurrency limits;
• whether eligible learned procedures publish and get used automatically.

Setup must disclose automatic persistence and reuse; permission to read a chat is not enough. Projects without a policy stay disabled. Enrolling, changing or widening a policy uses preview, trusted human confirmation, revision checks and a receipt. A coordinator may propose a policy but can never enable or widen its own.

Inside the policy, routine updates are automatic, with no per-item confirmation. Node validates the frozen candidate, source access, policy and expected revisions, then commits a version and receipt idempotently. This is a new low-risk operation class; the protocol must define its risk, exposure and admission conditions before implementation, and it is unsupported until then. It never reuses or bypasses a human-only confirmation operation, and a model never confirms its own proposal or widens its policy. Receipts name the Node learning job, originating Session, input identity and human-admitted policy revision, never a fictional human approval.

Skill eligibility

The Agent skills.eligibleRefs allowlist is never rewritten automatically. Instead:

• At configuration admission, an authorized human may grant an Agent a learned-Skill class for exact Project or Workspace scopes.
• At activation, Node intersects that class grant, the learning policy, current access and export grants and the admitted resource catalog, then freezes exact eligible IDs and digests.
• New generated Skills join an already-granted class without config edits. The model cannot add a class, scope or tool grant.
• Workers without the class neither index nor load learned Skills. Schemas with only eligibleRefs deny this path; schema parity is a prerequisite, not a wildcard or automatic migration.

Content limits and promotion

• Generated knowledge is untrusted context. Learned Skills are untrusted procedure text: not tools, extensions, grants or policy.
• Automatic admission covers bounded prose and permitted source references only. Executable files, dependencies, tool grants, connectors, schedules, deploys, Agent definitions, evaluation rubrics and security rules need their own approval paths. Every action a Skill describes still passes Node authorization, containment and confirmation. Schema validation cannot prove prose is benign.
• Project-to-Workspace promotion is always a separate explicit action through the Project's parent route. Preview the exact version, destination readers, source restrictions and dependencies. Require source disclosure and destination write rights, trusted confirmation, CAS, idempotency and a receipt. Model redaction is not permission to disclose. Private titles, paths and citations must not leak; refuse or omit inaccessible references.
• Workspace reuse in a Project rechecks both grants and the worker's eligibility. A learned convention guides work but never overrides repository or Node policy.

Automatic learning and reuse

1. Observe bounded eligible work. Trigger on committed submitted messages, corrections and settled results at exact event watermarks. Never passive microphone capture, unsent drafts, opt-out chats, ambient history or unrelated Projects. Persisted voice-derived messages need the same consent as text; raw audio and unsubmitted or full transcripts are not learning input by default.
2. Extract and classify. Find durable facts, decisions, preferences and procedures. Record unknowns and disagreements instead of guessing. Link claimed success to actual verification; "the user asked for this process" differs from "this process was tested". Worker or model reports alone do not prove success.
3. Validate and version. Deduplicate and consolidate low-risk items, update learned Skills and record added, changed and superseded versions. Ambiguous scope, conflicting decisions, uncertain sensitive content or an attempted authority or configuration change stays pending or is rejected with a reason. An inference never overrides an explicit correction. Automatic revisions apply only to in-scope Node-generated resources and preserve corrections and pins; repository and user-authored Skills are never overwritten, pinned or not. Repeated text is not independent corroboration.
4. Publish within policy. Notes and non-executable procedures become available after Node admission, with no mandatory approval inbox. Show a quiet "learned/updated" summary with a source and diff inspector. Ask only when a change exceeds policy or needs a real user decision. Retries keep their input identity; same-key changed content conflicts; unknown writes reconcile receipts first.
5. Equip later work. On a new request or worker activation, Node may supply a bounded untrusted-data projection of policy-selected KB and memory items and eligible Skill metadata, after checking source grants and export consent for this recipient. The activation manifest records selected and omitted items with reasons. The full memory store, raw history and Pi archives stay tool-only. The Agent may pick a Skill itself but loads its exact admitted revision through the typed loader and the frozen eligibility set (progressive Skill loading). No bulk transcript injection, directory scan or silent mid-turn Skill swap.
6. Learn from corrections. User corrections supersede inferred notes. Conflicting explicit decisions need resolution, not last-writer-wins. Revocation, forgetting and source changes invalidate affected memory, Skill versions, indexes and caches before the next load or export. Track distributed versions, signal invalidation to active workers and recheck eligibility before later admitted actions, stopping or rebuilding affected work when policy requires it. Context already sent to a provider cannot be erased; report that limit and any retained audit minimum.

Learned Skill provenance

Learned Skills are versioned managed resources, not live prompts. Add a closed policy-admitted generated resource variant to ResourceProvenanceV1 (provenance), distinct from reviewed-builtin and explicitly-pinned. It records exact scope, source lineage and digests, generator identity, content revision and digest, learning-policy revision, eligibility-class grant and receipt.

• Never label automatic admission explicitly-pinned. Runtime admission pins content per activation without per-item user pinning or a .maia digest.
• Never overwrite repository or user-authored Skills, AGENTS.md, Agent or Routine definitions or configuration.
• Exporting a learned Skill into the Project's reviewed Skills (Skills) is a separate explicit operation. No automatic commit, push or source rewrite. .maia never stores runtime memory or transcripts.

Job model

• A bounded Effect job inside existing Node and Session services: no always-running model loop, new scheduler or separate learning provider.
• Coalesce source events under stable input identities and finite budgets. Expose pending, skipped, failed and stale states; retry deliberately; reconcile on restart.
• Recheck source access and policy at read, model export, commit and context load. A revocation during extraction blocks the late write.
• A cancelled worker's partial work never becomes verified knowledge.
• Failed extraction never blocks chat or execution; report that learning is behind.
• No silent provider substitution and no paid background calls outside the confirmed policy.

User controls

The Workspace/Project knowledge view and the public CLI/API/SDK let a user:

• inspect knowledge, memory and Skills with origin, trust, revision and actual use;
• correct, pin, supersede, revoke or forget exact items and see derived impact;
• pause automatic learning or revoke its policy, cancelling in-flight publication;
• distinguish pausing new learning from disabling retrieval of existing items;
• preview and explicitly promote Project material to a Workspace;
• see conflicts and failures without approving every routine note.

Retention changes and deletion have their own reviewed semantics: minimal audit retention and no resurrection from an older source replay. Privacy exclusions and forget tombstones apply to derivation as well as retrieval. Never promise to erase earlier exports, backups or immutable receipts without an implemented retention contract.

Delivery and acceptance

• Order: protocol schemas, risk/exposure and receipt policy, then SDK, Node, CLI, Agent/coordinator and Desktop. Text and optional voice reuse the same operations. Source-class framing and progressive loading stay mandatory.
• The capability disposition keeps rejecting ambient Pi memory injection; this scoped learning is a separate path.
• Acceptance: PF-06 and DF-06 must prove automatic creation and reuse, not only storage or a manual save path. PF-22 and DF-22 prove discovery non-disclosure, owner-partitioned caches and parent-mediated sharing.
• Qualify protocol, privacy and race tests with deterministic fixtures before any separately approved live-model quality evaluation. Release evidence separates mechanical behavior, semantic quality and runtime availability.
• Automated selection and coordinator questions follow R10a/R10b. Deterministic storage, manual retrieval and recovery do not depend on AI readiness.

References

Prior art reviewed for this design; the rationale is in the decision log. None of it qualifies Maia behavior: Cursor Projects (shared context), Claude Projects (context builds over time), Claude Code memory, Cursor Agent Skills and the Claude Skills tutorial.