Learning Engine & Candidates

Relevant source files

The following files were used as context for generating this wiki page:

• packages/learning/src/organ.ts
• packages/learning/src/schemas.ts
• plans/noesis-autonomous-compounding-implementation-plan.html
• plans/noesis-first-complete-iteration.html
• plans/noesis-high-leverage-correction-plan.html
• packages/learning/test/automatic-learning.test.ts

The Learning Engine is the core module responsible for the self-improvement lifecycle of Noesis. It transforms ordinary work, user corrections, and session outcomes into actionable evidence through a process of reflection, hypothesis formation, and candidate authoring. Its primary goal is to ensure that "later work is better because earlier work happened" by creating versioned capability revisions grounded in recorded evidence.

The engine operates ambiently, triggering reflection based on signals like explicit corrections or recurring failures. It produces CapabilityRevisions—coupled sets of prompts, skills, and tools—which are treated as candidates until they pass preflight evaluations. This architecture ensures a clear separation between the "Learned" layer and the "Protected" kernel, allowing the system to evolve its behaviors without compromising core authority rules.

Sources: plans/noesis-high-leverage-correction-plan.html:120-123, plans/noesis-autonomous-compounding-implementation-plan.html:437-449

Learning Lifecycle & Architecture

The learning engine follows a structured pipeline that transitions from raw signals to activated system capabilities. This flow is governed by the AutomaticLearningOrgan, which coordinates reflection and revision authorship.

The Learning Pipeline

1. Signal Detection: The engine monitors sessions for LearningSignalKind events, such as explicit_correction, repeated_failure, or surprising_success.
2. Reflection: An LLM-based "Reflector" role analyzes signals and evidence citations to decide between a no_change outcome or the creation of an experiment_hypothesis.
3. Candidate Authoring: If a hypothesis is formed, the "Revision Author" role generates a CapabilityRevision containing prompt modules, skills, tool code, and routing rules.
4. Preflight & Evaluation: Candidates are tested against a baseline using historical and generated cases to ensure no regressions occur.
5. Activation: Convincing, low-risk revisions are staged and then atomically activated via a SQLite transaction, updating the system's active definition pointers.

Sources: packages/learning/src/schemas.ts:46-56, plans/noesis-autonomous-compounding-implementation-plan.html:565-575, packages/learning/src/organ.ts:154-190

Data Flow Diagram

The following diagram illustrates how signals are processed through the learning organ to produce candidate revisions.

The diagram shows the transition from raw interaction signals to the serving of a learned capability in future turns.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:565-575, packages/learning/src/organ.ts:316-350

Core Data Structures

The learning engine relies on strongly typed schemas to maintain the integrity of evidence and candidates.

Learning Signals & Evidence

Evidence is captured via EvidenceObservation and FeedbackSignal objects, which contain exact citations to database rows or file revisions.

Field	Type	Description
kind	LearningSignalKind	Type of signal (e.g., explicit_correction, capability_gap).
evidenceRefs	EvidenceRef[]	Pointers to authoritative data sources.
citations	ExactCitation[]	Precise offsets and digests for the signal in source messages/files.
strength	number	Numeric weight indicating the significance of the signal.

Sources: packages/learning/src/schemas.ts:46-56, plans/noesis-autonomous-compounding-implementation-plan.html:437-449

Capability Candidates

A CapabilityRevision is the primary artifact of the learning engine. It is an immutable, versioned bundle of behavioral definitions.

interface CapabilityRevision {
  capabilityRevisionId: string;
  capabilityId: string;
  promptModules: readonly FileRevisionRef[];
  skills: readonly FileRevisionRef[];
  tools: readonly FileRevisionRef[];
  toolset: ToolsetAndRouter;
  activationPolicy: ActivationPolicy;
  permissionManifest: PermissionManifest;
  sourceEvaluationDefinitions: readonly FileRevisionRef[];
}

Sources: packages/learning/src/schemas.ts:121-145, plans/noesis-autonomous-compounding-implementation-plan.html:463-479

Intelligent Reflection & Authoring

The system utilizes specialized LLM roles to perform semantic analysis and code generation. These roles are isolated from the protected control plane to prevent privilege escalation.

Reflector Role

The Reflector performs cross-session analysis. It can abstaining from changing the system (no_change) if the evidence is insufficient or specific to a single turn. When successful, it produces a hypothesis and source cases for evaluation.
Sources: packages/learning/src/schemas.ts:89-112, packages/learning/src/organ.ts:154-190

Revision Author Role

The Revision Author transforms a hypothesis into executable code and prompts. It outputs a RevisionAuthorOutput containing:

• Prompt Modules: Layered instructions for the model.
• Skills: Declarative procedure definitions.
• Tools: Executable code for side effects (e.g., .mjs files).
• Router: Strategy for when to activate this capability.
• Permission Delta: Requested changes to the capability's authority.

Sources: packages/learning/src/schemas.ts:121-145, packages/learning/test/automatic-learning.test.ts:358-375

Operational Controls & Autonomy

Noesis implements risk-based autonomy, where the level of human intervention depends on the nature of the proposed change.

Change Type	Autonomy Level	Default Policy
Explicit Memory	Automatic	Record automatically; quiet notification.
Narrow Read-only Skill	Automatic	Preflight and activate if low risk.
Broader Effect/Scope	Approval Required	Explicit user approval through TUI.
Credential Access	Prohibited	Never self-activatable; requires user action.
Protected Kernel	Hard Gate	Never modifiable by the learning engine.

Sources: plans/noesis-autonomous-compounding-implementation-plan.html:692-705, plans/noesis-high-leverage-correction-plan.html:565-580

The Experiment Spindle

Every learning episode is tracked as an Experiment. This durable record connects the initial hypothesis to preflight reports, activation decisions, and real-world feedback (keep, revise, or revert).

Summary

The Learning Engine & Candidates module provides a falsifiable mechanism for system evolution. By grounding all self-modification in immutable CapabilityRevisions and paired-replay metrics (like win rate and scope leakage), Noesis ensures that behavioral improvements are both measurable and reversible. This structure allows the system to quietly become better during normal use while maintaining strict boundaries on authority and permissions.

Sources: plans/noesis-high-leverage-correction-plan.html:150-175, plans/noesis-autonomous-compounding-implementation-plan.html:840-855