Setup & Installation Guide

Relevant source files

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

• package.json
• AGENTS.md
• plans/noesis-autonomous-compounding-implementation-plan.html
• plans/compounding-partnership-product-loop.html
• packages/config/test/config.test.ts
• plans/noesis-high-leverage-correction-plan.html
• biome.json

This guide provides the necessary steps to set up, configure, and verify the Noesis environment. Noesis is a research-preview system for autonomous compounding that requires a specific technical baseline to ensure transactional integrity and architectural boundaries.

The setup process involves preparing a Node.js environment, installing dependencies via pnpm, and initializing a workspace that manages both SQLite operational state and human-editable configuration files.

Technical Prerequisites

Noesis requires a modern JavaScript runtime and specific tooling to maintain strict ESM compliance and package isolation.

Requirement	Value
Node.js	>= 22.19.0
Package Manager	pnpm @ 10.29.3
TypeScript	5.9.3 (Strict ESM)
OS	Linux/macOS (Implicit from POSIX paths)

Sources: package.json:1-10, AGENTS.md:73-74

Installation Steps

Noesis uses a monorepo structure managed by pnpm workspaces.

1. Clone and Install:
   Execute the standard installation to link internal packages and fetch external dependencies.

   pnpm install
   

2. Build the Project:
   The build process uses tsc for type-checking without emitting files, as the system runs directly via tsx or within test environments.

   pnpm build
   

Sources: package.json:11-20, AGENTS.md:73-82

Initialization Flow

The following diagram illustrates the sequence from installation to a ready state.

This flow ensures that the system is verified before any state is initialized in the local environment. Sources: package.json:13, plans/compounding-partnership-product-loop.html:704-710

Configuration

Noesis configuration follows a strict precedence model: CLI arguments override environment variables, which override file-based config, which finally override system defaults.

Config Initialization

To initialize a fresh configuration in a specific home directory, the system uses initializeNoesisConfig. This prevents overwriting existing settings.

import { initializeNoesisConfig } from "@noesis/config";
await initializeNoesisConfig(homePath);

Sources: packages/config/test/config.test.ts:114-118

Precedence and Resolution

The configuration is resolved using resolveNoesisConfig, merging inputs from multiple sources into a single schemaVersion: 1 object.

The resolver identifies the source of each setting (e.g., sources.provider = 'cli'). Sources: packages/config/test/config.test.ts:32-55

Core Configuration Options

Noesis uses schemaVersion: 1. Key parameters include:

Option	Type	Default	Description
agent.provider	string	openai-codex	The LLM provider for the turn executor.
agent.thinkingLevel	enum	medium	Reasoning depth (off, low, medium).
learning.enabled	boolean	true	Enables ambient background reflection.
autonomy.riskLevel	enum	low	Tolerance for automatic capability activation.

Sources: packages/config/test/config.test.ts:80-95, packages/config/test/config.test.ts:120-134

Workspace Setup

The WorkspaceStore is the central authority for persistence. It divides data between a SQLite database and the file system.

Authority Matrix

Noesis enforces a "one authority per datum" rule to prevent synchronization conflicts.

• SQLite: Authoritative for operational state (sessions, turns, messages, activation pointers, and background jobs).
• Filesystem: Authoritative for declarative definitions (prompts, skills, tool source code, and user criteria).
• Artifacts: Stored as content-addressed files with SQLite metadata.

Sources: plans/noesis-autonomous-compounding-implementation-plan.html:265-285, AGENTS.md:27-38

Bootstrapping

A fresh workspace must be bootstrapped with a genesis baseline to enable the first learning loop. This publishes an immutable general-collaboration baseline.

Development & Verification

Verification is performed using a "clean-room" approach that does not require paid model calls or network access during CI.

Verification Commands

Command	Description
pnpm check	Runs format, lint, typecheck, and tests in sequence.
pnpm format	Formats code using Biome.
pnpm test	Executes the Vitest suite.
tsx apps/noesis/src/cli.ts	Runs the Noesis CLI/TUI directly.

Sources: package.json:11-20, biome.json:1-10

Security and Boundaries

Architectural tests enforce boundaries to ensure that the TUI and learning organs do not access protected internals directly.

• Import Scanning: Architecture tests (e.g., packages/tui/test/architecture.test.ts) forbid direct imports from @noesis/policy or @noesis/workspace within the TUI.
• Harnessing: Integration work must use AgentHarness with a credential-free controlled provider.

Sources: packages/tui/test/architecture.test.ts:10-35, AGENTS.md:78-82

Summary

Successful setup of Noesis requires Node.js >= 22.19.0 and pnpm. The system must be initialized with initializeNoesisConfig and bootstrapped via the WorkspaceStore to establish the genesis baseline. All mutations to the environment are governed by a protected control plane, and verification is strictly enforced through pnpm check using local, credential-free providers.