Clapilot-Agent Learning Contracts

Learning is how Clapilot turns things it observed during work — a user preference, a client rule, a repeated workflow — into governed objects that can later be injected back into prompts. Safe, evidence-backed facts and preferences use an opt-out activation policy: they become active immediately, while exceptions stay inactive. A configurable model-backed curator later checks only new or changed facts and rejects high-confidence false, unsafe, duplicate, or non-durable content. Every learning object carries explicit visibility, activation/approval state, provenance, and cost attribution, so an admin can always answer what was learned, from what, which policy or model checked it, and what it costs. This page is the canonical contract for that model.

This page defines the learning object model for the native clapilot-agent runtime. Milestone 2 added passive storage and inspection for learning objects, approval decisions, and audit events. Milestone 3 added controlled runtime retrieval for approved learning objects as a separate prompt layer. Milestone 4 added conservative post-response extraction. Milestone 5 adds opt-out activation, agentic curation, and admin review for exceptions. The protected Learning Curator system automation runs with the model selected on /geplante-aufgaben. It evaluates only facts it has not checked at their current content hash, defaults to keeping them, and rejects only high-confidence false, unsafe, duplicate, or non-durable content. Procedures, corrections, conflicts, weak or unsafe evidence, and other exceptions remain review-only. The runtime exposes read-only learning_search / learning_get_object tools for approved, visible objects plus unified read access through context_search / context_get. It still does not add agent-facing learning mutation tools or executable procedure promotion.

The goal is to make future learning features explicit before implementation:

• what can be learned
• who can see it
• who or what approved it
• how it was derived
• how much it cost to create or retrieve
• when it is ready to become an agent-facing tool or autonomous workflow

Milestone 5 Implementation Status

Milestone 2 implemented the control-plane substrate:

• PostgreSQL tables for learning objects, approvals, and audit events
• native internal endpoints under /internal/learning and /internal/learning-objects
• admin app endpoints under /api/agent-runtime/learning
• a ClapilotAICore Learning settings page for inspection and curation

Milestone 3 added the first runtime use path:

• internal retrieval under POST /internal/learning-objects/retrieve
• approved-learning prompt selection inside sessions.executeRun()
• the approved_learning_objects prompt token layer in request logs and run metadata
• learning.used_in_prompt audit events for objects actually injected into a provider prompt
• retrieval-focused indexes for prompt-eligible objects, validity windows, text matching, and prompt-use audit history

Milestone 4 adds the first self-learning write path:

• memory.storeSharedFacts() returns the already extracted shared-fact text and token attribution to the post-response runtime
• learningObjects.runConservativeExtraction() converts shared-fact lines or explicit "remember this" user instructions into canonical Memory v2 assertions and Learning projections
• subscription-bridge chat runs can create candidates by default because extraction reuses shared-facts output and records the runtime provider in source refs; CLAPILOT_AGENT_LEARNING_EXTRACTION_ALLOW_SUBSCRIPTION_RUNTIME=false disables that path
• the opt-out policy immediately activates evidence-backed facts and preferences with safe scope, sufficient confidence, and no unresolved conflict or correction semantics
• CLAPILOT_AGENT_LEARNING_EXTRACTION_AUTO_APPROVE_SAFE_FACTS and CLAPILOT_AGENT_LEARNING_EXTRACTION_AUTO_APPROVE_EXPLICIT_USER_FACTS default to true; policy activation records auto_approved_by_policy plus policy provenance instead of pretending a person reviewed the object
• the Learning settings queue contains the exceptions that need a decision; policy-activated facts remain visible in the full inspector and audit trail
• policy activation is reversible until a human review adopts the object; rejection changes an active fact to status=rejected, removing it from future prompt retrieval
• low-risk procedure observations start as status=needs_evidence, proposal_kind=procedure, and readiness_state=needs_evidence
• procedure proposals, corrections, conflicts, weak evidence, and unsafe categories require review before they can become prompt context; safe durable policy/workflow facts can use the same opt-out activation path as other facts
• run.postprocess.completed events report candidate, created, auto-approved, skipped, skipped-reason, and error counts
• internal diagnostics can call POST /internal/learning-objects/extract

Milestone 5 adds the first curation workflow:

• the ClapilotAICore Learning settings page surfaces exception states such as candidate, draft, needs_evidence, needs_tools, and needs_approval in a dedicated exception-review queue; safe policy-activated facts do not require repetitive approval
• admins can approve, reject, or request changes for one object, with optional decision notes
• admins can bulk approve or bulk reject selected review-queue objects
• the full object list can be searched and filtered by status, object type, and visibility scope
• all curation actions append approval/audit state through the existing decision endpoint; they do not create agent-facing tools

Read-only agent access is now available:

• learning_search searches approved, visible, unexpired learning objects using the same prompt-eligible approval and visibility checks as prompt injection
• learning_get_object reads one approved, visible learning object by id
• context_search includes approved, visible Learning objects in a broader internal-context pass alongside Wiki, native memory, exact session history/summaries, and the Knowledge Graph
• context_get can read learning:<id> results through the same visibility checks as learning_get_object
• candidates, rejected objects, audit rows, approval decisions, extraction, curation, and promotion remain admin/runtime control-plane capabilities rather than agent tools

Bundled automated curation adds the agentic cleanup loop:

• native installs ship a protected Learning Curator system automation under /geplante-aufgaben
• the job calls learningObjects.runAgenticCuration() with the provider/model selected on the automation; a blank model fails closed and leaves facts unchanged
• candidates are limited to canonical durable facts with evidence and no terminal manual decision, and a content hash prevents rechecking unchanged facts
• the prompt is opt-out: keep is the default, and rejection requires a reason plus configurable minimum confidence (default 0.8)
• high-confidence false, contradicted, duplicate, non-durable, runtime-noise, unsafe, or clearly worthless facts are rejected; uncertain facts are kept
• manual admin/user decisions are authoritative and are rechecked immediately before any curator mutation
• every curator result records model, policy version, content hash, confidence, reason code, explanation, and audit events
• Dreaming v2 retains a targeted deterministic safety pass for its newly written assertions. Safe, durable, evidence-backed facts, preferences, decisions, constraints, and procedures are policy-approved immediately; unsupported Dream assertions are policy-rejected instead of entering the exception-review queue. Approved projections can therefore extend recall and the Knowledge Graph before the scheduled agentic quality-control pass.

The active storage families are durable facts, procedure / skill proposals, and hot memory snapshots. Approval state and audit events are stored in dedicated append-friendly tables instead of being mixed into the primary object table. Prompt retrieval uses those tables directly; it does not create user-callable tools.

Still intentionally out of scope:

• no agent-facing learning write, approval, rejection, extraction, curation, or promotion tools
• no separate extraction model call beyond the existing shared-facts postprocess
• no agent-facing curator call; model-backed curation remains a protected scheduled control-plane operation
• no promotion of procedure proposals into executable tools, specialists, or automations

Object Families

The contract separates learning state into five object families.

These families should stay separate even when they share fields. A durable fact is not a procedure. A hot memory snapshot is not a durable fact. An approval decision should never be overwritten by rewriting the learned object.

Common Envelope

Every learned object should carry the following envelope when implemented:

source_refs must be specific enough that an admin can reconstruct why the object exists without replaying an entire workspace.

Durable Facts

Durable facts represent stable learned knowledge. Examples:

• a user's preferred invoice wording
• a client's recurring filing rule
• a team workflow convention
• a channel-specific routing rule
• a verified operational fact from a completed task

Required contract additions beyond the common envelope:

Default policy:

• user preference facts start as private unless explicitly shared
• client, document, task, and team facts start as team when created in authenticated web/team contexts
• unknown or unlinked channel facts start as channel
• operational runtime facts can be workspace only when they are not user- or client-specific

Durable facts should be safe to retrieve repeatedly. If a learned item is only useful for the current run or near-term task, model it as a hot memory snapshot instead.

Procedure And Skill Proposals

Procedure / skill proposals are candidate repeatable workflows. They are not active tools in the current runtime.

Examples:

• "When a German VAT deadline email arrives, create a task, link the client, and draft a reply."
• "For this client, use the three-step monthly bookkeeping checklist."
• "This recurring prompt should become a named specialist or automation."

Required contract additions:

Promotion rules:

• proposals may reference current tool contracts, but they are not tool contracts themselves
• proposals that require new tool schemas must stay needs_tools
• proposals that mutate data or send external messages must stay blocked until approval and audit paths exist
• future promotion should create or update a separate executable artifact; it should not mutate the proposal into an executable object in place

Hot Memory Snapshots

Hot memory snapshots are compact working sets used to keep near-term context fresh without turning everything into durable memory.

Examples:

• the active task and its last few decisions
• a condensed view of the current channel thread
• current document-editing intent
• active client context across several nearby agent turns

Required contract additions:

Hot memory should default to narrower visibility than durable facts. It can be promoted into a durable fact only through a separate extraction/proposal path with evidence and audit state.

Approval And Audit State

Learning state needs explicit approval and audit contracts before autonomous write or promotion tools are added.

Approval state should answer:

• who approved, rejected, or requested changes
• what exact object version was reviewed
• whether approval came from a user action, admin action, or policy rule
• what scope the approval applies to
• whether approval is reversible

Recommended approval fields:

Automatic safe activation uses decided_by_kind=system_policy and records the stable policy id/version in the decision reference or metadata. It is not equivalent to human review: the policy decision can be compensated or revoked until a later user or admin decision adopts the object.

Audit events should be append-only. Recommended audit event names:

• learning.extracted
• learning.proposed
• learning.approval_requested
• learning.approved
• learning.rejected
• learning.promoted
• learning.superseded
• learning.expired
• learning.used_in_prompt
• learning.used_by_tool
• learning.token_cost_attributed
• learning.deleted

Audit payloads should include the learned object id, source refs, actor, previous status, next status, visibility scope, and token-cost attribution when available.

Visibility Scopes

Learning objects reuse the current memory visibility language and tighten it for promotion decisions.

Visibility is an access control input, not just a retrieval ranking signal. Retrieval may boost matching subjects, but it must not cross visibility boundaries.

Token-Cost Attribution

Learning should carry cost metadata so admins can understand whether memory improves or bloats runtime work.

Attribution concepts:

Current learning work does not add billing behavior. It preserves enough metadata to answer:

• which learned objects are expensive to create
• which learned objects are repeatedly injected
• whether a hot snapshot or durable fact reduced prompt size
• whether a procedure proposal came from high-cost or low-confidence evidence

Milestone 1 persists request-level prompt-layer estimates in agent_model_request_logs.prompt_layer_tokens_json. Milestone 2 learning objects added per-object token_cost_json so extraction, retrieval, prompt-injection, and avoided-context estimates can be attached. Milestone 3 adds the approved_learning_objects request layer and learning.used_in_prompt audit events with prompt-injected token estimates. Milestone 4 reuses shared-facts postprocess token estimates when creating candidates, so self-learning does not add another extraction prompt. Subscription-bridge runs use the same reused-output path and attach runtimeProvider in source refs for auditability. Current request attribution covers runtime system prompt, compaction summary, bootstrap prompt files, retrieved memory, approved learning objects, extra system prompt, stored history, current request, tool schemas, message prompt estimate, and provider input estimate.

Runtime Prompt Retrieval

Milestone 3 retrieval is deliberately narrower than generic memory search.

An object is eligible for prompt injection only when:

• status is approved, active, or promoted
• it is not expired and any valid_from / valid_until window is current
• visibility matches the current user, session, channel, team, workspace, or structured subject refs
• approval-required objects have a latest decision of approved or auto_approved_by_policy
• procedure proposals have readiness_state of ready_for_milestone_2 or promoted and are not risk_level=blocked

The prompt renderer emits a separate Approved learned context system block. That block explicitly tells the model to treat learned items as context data, not higher-priority instructions. The runtime caps this layer to a small share of the prompt budget and drops it before trimming stored conversation history.

Agents can also explicitly query the same approved/visible corpus with read-only tools:

• learning_search returns a compact list of approved, visible Learning objects. It accepts optional query, object_type, include_hot_snapshots, include_metadata, and limit. The agent-tool object_type enum exposes only durable_fact and procedure_proposal; snapshots remain supported by storage/read paths and are included with include_hot_snapshots=true.
• learning_get_object returns one approved, visible Learning object by id.
• context_search / context_get expose the same approved objects as part of broad internal-context lookup; they are preferred when the user asks "what do we know?" rather than specifically asking for the Learning store.

These read-only tools enforce approval state, expiry/validity windows, prompt-readiness for procedure hints, and the same visibility model as prompt injection. They do not expose candidates or rejected objects and cannot approve, reject, extract, edit, delete, or promote learning objects.

Admin And Native API

Milestone 2 exposes admin-only app endpoints:

• GET /api/agent-runtime/learning lists recent learning objects, recent audit events, and grouped stats for the Learning settings inspector and exception-review queue
• POST /api/agent-runtime/learning creates a learning object manually or from a controlled backend path
• GET /api/agent-runtime/learning/[id] returns one object with linked approvals and audit events
• POST /api/agent-runtime/learning/[id]/decision records an approval, rejection, changes-requested decision, revocation, or versioned policy approval. The Learning settings exception-review queue uses this endpoint for both single-object decisions and bulk decisions.

The app endpoints proxy to native internal endpoints under /internal/learning and /internal/learning-objects. These are runtime control-plane endpoints, not mutation-capable agent tool names.

Milestone 3 also exposes one internal runtime retrieval endpoint:

• POST /internal/learning-objects/retrieve returns prompt-ready approved learning objects for native runtime use. The standard chat path calls the learning module directly rather than through HTTP, but the endpoint exists for internal diagnostics and future runtime callers.

The agent-facing read-only retrieval contract is exposed as native tools rather than public HTTP endpoints:

• context_search searches approved Learning, Wiki, native memory, session history/summaries, and Knowledge Graph context through a unified read-only facade
• context_get reads one source-qualified result returned by context_search
• learning_search searches prompt-eligible approved/visible objects through the native tool catalog and /internal/tools/execute
• learning_get_object returns one prompt-eligible approved/visible object through the native tool catalog and /internal/tools/execute

Milestone 4 also exposes one internal extraction diagnostics endpoint:

• POST /internal/learning-objects/extract runs the same conservative extractor used by post-response maintenance. It creates canonical candidates/drafts and applies the configured safe fact/preference auto-activation policy. Exceptions remain candidates. It is intended for internal smoke tests and future runtime callers, not agent tool use.
• POST /internal/learning-objects/curate runs the targeted deterministic safety curator once. Optional assertionIds / assertion_ids restrict the pass to Learning projections linked to those canonical assertions; Dreaming v2 uses this targeted form immediately after persistence and gives each targeted Dream assertion an automatic terminal approval/rejection decision. The protected scheduled Learning Curator instead calls the model-backed runAgenticCuration() path with its configured model, batchSize, and minimumRejectConfidence payload fields.

Promotion Readiness

A learning object is ready for future promotion or prompt use only when the following are true:

1. It has a stable object_type, schema_version, status, scope, source refs, and subject refs.
2. Its visibility boundary can be enforced before retrieval or execution.
3. Its source evidence can be audited without relying on an opaque model summary.
4. Any user-visible mutation, external send, workflow automation, or procedure promotion has approval state.
5. Token-cost attribution can be attached at extraction, embedding, retrieval, and prompt-injection points.
6. Conflicts and supersession can be represented without deleting history.
7. The object can be exported in a compact read shape and a full audit shape.
8. Existing agent-tool docs can list promoted or read-only behavior without mixing draft proposals with mutation-capable active tools.

Future milestones should add explicit mutation/promotion tool API docs only when executable code exists. Until then, this page is the canonical design contract for learning state and the current read-only retrieval tools.

Integration Points To Preserve

Future implementation should align with existing runtime concepts:

• durable recall, visibility, and subject matching from Memory
• prompt assembly and budget fitting from Request Flows
• provider request logs and token accounting from Providers + Models
• current native memory tools listed in Agent Tool Contracts
• endpoint documentation discipline in API Reference