Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- plans/noesis-autonomous-compounding-implementation-plan.html
- plans/noesis-first-complete-iteration.html
- plans/noesis-high-leverage-correction-plan.html
- plans/compounding-partnership-product-loop.html
- AGENTS.md
- packages/domain/test/architecture.test.ts
- packages/tui/test/architecture.test.ts
- packages/runtime/test/turn-intelligence.test.ts
Noesis is a research system designed for autonomous compounding, an integrated build process that converts ordinary software work into evidence for self-improvement. It leverages LLMs to author coupled prompt, skill, tool, and routing revisions, while maintaining a deterministic "protected kernel" for authority, persistence, and execution boundaries.
The system is structured as a TypeScript monorepo where LLMs perform high-level semantic work (hypothesis formation, revision authoring) and code provides thin, transactional rails for operational state and safety.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:152-168
Core System Modules
The architecture follows a "deep module" philosophy with earned boundaries. Packages are only created when stable boundaries or independent process ownership are required.
| Package | Responsibility | Authority |
|---|---|---|
@noesis/workspace | Persistence, SQLite transactions, migrations, and file revision metadata. | SQLite & Canonical Files |
@noesis/runtime | Adapter-neutral turn orchestration, intelligence plans, and activation decisions. | Turn Plans |
@noesis/runtime-pi | The exclusive boundary for Pi-specific imports and model role execution. | Pi Adapter |
@noesis/intelligence | Hybrid search (FTS + embeddings) over sessions and file revisions. | Rebuildable Indexes |
@noesis/capabilities | Stable capability identities, candidate revisions, and activation policies. | Capability Registry |
@noesis/evals | LLM-native evaluation, paired trials, and blinded judging. | Evaluation Evidence |
@noesis/policy | Effect enforcement, principal grants, and protected rule execution. | Protected Kernel |
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:263-315, plans/noesis-first-complete-iteration.html:1050-1070
Dependency Direction and Constraints
To maintain architectural integrity, specific dependency rules are enforced through automated tests:
- Runtime Isolation:
packages/runtimeis adapter-neutral and must not importpackages/runtime-pi. Sources: packages/domain/test/architecture.test.ts:186-192 - Pi Boundary: Only
packages/runtime-piandpackages/tuimay import@earendil-works/pi-*packages. Sources: packages/domain/test/architecture.test.ts:117-125 - TUI Port: The Terminal User Interface (TUI) sits behind a narrow runtime port and is forbidden from importing internal modules like
@noesis/workspace,@noesis/ledger, or@noesis/policy. Sources: packages/tui/test/architecture.test.ts:11-20
Data Authority and Persistence
Noesis operates under a "One authority per datum" rule to prevent dual-write conflicts and competing canonical copies.
This diagram shows the authoritative sources for data and how rebuildable indexes are derived.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:332-358, AGENTS.md:18-28
Revisions and Snapshots
Working definitions (prompts, tools) remain editable by the user. However, for every execution turn or evaluation, Noesis creates byte-stable revisions.
- Each revision includes a content digest, actor ID, and a reference to its predecessor.
- Turns pin specific revision IDs, ensuring that mutable file changes do not break active sessions or valid evaluation reports.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:343-348, AGENTS.md:21-25
The Autonomous Learning Lifecycle
The system improves itself through a continuous feedback loop triggered by "signals" (e.g., user corrections, recurring workflows, or friction).
This sequence illustrates the flow from a user correction to the activation of a new capability revision.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:435-445, plans/compounding-partnership-product-loop.html:430-440
Learning Components
- Signal Harvester: Records sessions, message outcomes, and explicit user steering in SQLite. Sources: plans/noesis-autonomous-compounding-implementation-plan.html:448-452
- Reflector: Analyzes signals to form hypotheses. It may result in
no_changeor a specific experiment brief. Sources: plans/compounding-partnership-product-loop.html:120-125 - Evaluation Lab: Conducts LLM-native preflights. It generates cases from evidence and uses a "blind judge" to compare candidate performance against a baseline. Sources: plans/noesis-autonomous-compounding-implementation-plan.html:515-535
- Atomic Activation: Activation occurs via a single SQLite transaction that updates activation pointers only after preflight bytes are materialized and verified. Sources: plans/noesis-autonomous-compounding-implementation-plan.html:410-415
Protected Control Plane and Security
Noesis employs "Protection by Construction" to ensure generated content cannot widen its own authority.
The Effect Gateway
All side effects (write, network, execute) must pass through the EffectGateway. This layer verifies AuthorityReceipts issued by the AuthorityBoundary. Ordinary components cannot mint their own receipts or install grants.
Sources: plans/noesis-high-leverage-correction-plan.html:500-520, AGENTS.md:43-48
Role Isolation
Context is separated by model role to prevent "gaming" the evaluation:
- Revision Authors: See hypotheses and source cases but cannot see judge decisions.
- Trial Agents: Execute one arm of an experiment (candidate or baseline) in isolation.
- Blind Judges: See randomized A/B outputs with the identity of the arms hidden.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:530-545
Risk-Based Autonomy
| Change Type | Policy | Authority |
|---|---|---|
| Memory/Preference | Record automatically | Quiet notification |
| Learned Prompt | Auto-activate if preflight passes | Low-risk only |
| New Effect/Scope | Explicit Approval | User-required |
| Kernel Modifications | Forbidden | System-protected |
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:600-615
Execution Substrate: Turn Intelligence Plans
Before a model execution turn, Noesis constructs a FrozenTurnPlan. This plan is an immutable manifest that ensures execution remains consistent even if the workspace changes during the turn.
interface TurnIntelligencePlan {
planId: string;
sessionId: string;
turnId: string;
activationId: string; // Pinned activation snapshot
selectedDefinitions: readonly FileRevisionRef[];
retrievalCitations: readonly ExactCitation[];
availableTools: readonly FrozenToolRef[];
routingDecisionRef: ArtifactRef;
}
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:402-412, packages/runtime/test/turn-intelligence.test.ts:135-150
Conclusion
The Noesis architecture is centered on a robust, SQLite-backed operational core that governs the lifecycle of LLM-generated enhancements. By enforcing strict dependency directions, single-authority data models, and a receipt-based effect gateway, the system allows for rapid evolution of "semantic" capabilities while maintaining hard deterministic rails for safety and reversibility.