Package Organization
Relevant source files
The following files were used as context for generating this wiki page:
Noesis is structured as a monorepo utilizing pnpm workspaces. The architecture emphasizes strict boundary enforcement between adapter-neutral logic and external execution substrates (specifically the Pi ecosystem). The organization is designed to isolate the "self-modification" loop of the agent from protected authority and persistent storage, ensuring that generated content can propose changes but cannot unilaterally promote them.
The system follows a specific dependency direction where core domain types and neutral runtime logic reside at the base, while specific adapters and user interfaces sit at the periphery. This structure is enforced through automated architecture tests that scan imports and member access to prevent boundary violations.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:362-371, AGENTS.md:21-43, packages/domain/test/architecture.test.ts:133-149
Core Dependency Graph
Noesis enforces a strict top-down dependency flow to maintain architectural integrity. Core packages like domain and agent-types provide the foundation, while runtime orchestrates the system using adapter-neutral ports. External dependencies on the Pi ecosystem are strictly limited to the runtime-pi and tui packages.
The diagram above illustrates the intended flow of dependencies where higher-level orchestration packages depend on foundation packages, but never vice versa.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:362-371, AGENTS.md:25-30, packages/domain/test/architecture.test.ts:153-176
Internal Packages and Responsibilities
The monorepo is divided into logical units, each represented by a package under the packages/ directory.
Foundation & Domain
@noesis/domain: Contains versioned Zod schemas, IDs, and core types for events, trails, and artifacts. It serves as the primary contract spine.@noesis/agent-types: Provides adapter-neutral types for models, tools, and experiment results, specifically designed to avoid importing execution-specific types.@noesis/workspace: Owns theWorkspaceStoreand all persistence boundaries. It manages SQLite transactions, migrations, and canonical file locations.
Orchestration & Execution
@noesis/runtime: Handles adapter-neutral turn orchestration, trail lifecycles, and coordination of background jobs. It is prohibited from importingruntime-pi.@noesis/runtime-pi: The exclusive boundary for Pi-specific imports. It implements foreground runners and session tool registrations.@noesis/policy: Manages the protected control plane, includingEffectGatewayandAuthorityBoundary. It enforces grants and verifies receipts for side effects.
Intelligence & Learning
@noesis/learning: Contains the logic for reflection, signal harvesting, and capability-revision authoring.@noesis/evals: Houses the "Evaluation Laboratory" for paired trials, blind judging, and regression testing.@noesis/capabilities: Manages the registry of tools, skills, and their associated versions and permission manifests.
Sources: plans/noesis-first-complete-iteration.html:565-585, plans/noesis-autonomous-compounding-implementation-plan.html:324-358, AGENTS.md:25-33
Architectural Constraints
To ensure the integrity of the protected control plane and the modularity of the system, several strict rules are enforced via architecture tests (architecture.test.ts files).
Boundary Rules
| Package | Forbidden Imports / Access | Rationale |
|---|---|---|
packages/runtime | @noesis/runtime-pi | The runtime must remain adapter-neutral. |
packages/tui | ledger, workspace, policy, scheduler | The UI should only consume read models and use a narrow runtime port. |
| Research Packages | policy, runtime | agent-types, learning, and evals should not have direct mutation access to protected state. |
| General | @sinclair/typebox | The project uses Zod for validation; TypeBox is forbidden in first-party code. |
Sources: packages/domain/test/architecture.test.ts:153-176, packages/domain/test/architecture.test.ts:208-232, packages/tui/test/architecture.test.ts:8-25
Implementation Invariants
- One Authority per Datum: Every piece of data has exactly one canonical source (e.g., SQLite for operational state, editable files for definitions). Dual-writing is strictly forbidden.
- Immutable Revisions: Recorded definition revisions and evaluation pins must resolve to immutable, byte-stable snapshots.
- God-File Threshold: Extracted source modules are kept below an 800-line threshold to prevent the emergence of "god files."
- Protected Promotion: Generated content may propose changes (via
learning), but only the protected control plane (policy) can activate or promote them.
Sources: AGENTS.md:31-35, packages/tui/test/architecture.test.ts:46-52, plans/noesis-high-leverage-correction-plan.html:712-725
Workspace Data Authority Matrix
The following table summarizes the authoritative storage locations for various data types within the workspace, as managed by the WorkspaceStore.
| Datum | Primary Authority | Derived / Projection |
|---|---|---|
| Sessions, Messages, Jobs | SQLite | FTS / Embedding Indexes |
| Capability Definitions | Editable Workspace Files | Rebuildable Search Indexes |
| Recorded Revisions | Byte Snapshots (Revisions area) | Inspection / Revert Views |
| Large Outputs / Traces | Ordinary Artifact Files | SQLite Metadata Rows |
| Provider Credentials | Protected Credential Store | N/A |
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:376-392, AGENTS.md:31-43
Summary
The package organization of Noesis is a tiered monorepo structure that prioritizes safety and modularity. By isolating execution substrates like Pi and protecting the mutation of system doctrine through a deep adapter layer, Noesis ensures that the agent's self-improvement cycle remains governed by stable, human-inspectable rails. The monorepo structure, combined with rigorous architectural tests, prevents the leakage of execution-specific types into the core reasoning and orchestration modules.
Sources: AGENTS.md:21-43, plans/noesis-autonomous-compounding-implementation-plan.html:362-371