Configuration Management

Relevant source files

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

• packages/config/src/index.ts
• packages/config/test/config.test.ts
• AGENTS.md
• plans/noesis-autonomous-compounding-implementation-plan.html
• biome.json

Configuration Management in Noesis provides a robust, schema-validated system for governing agent behavior, autonomous learning parameters, and risk-based autonomy levels. It ensures that the system operates within predictable bounds while allowing for user-defined overrides via CLI, environment variables, or local configuration files.

The system is built around a single authoritative JSON configuration file (config.json) located in the workspace home directory, managed through strict Zod schemas and atomic file operations to prevent data corruption during concurrent writes.

Sources: packages/config/src/index.ts:1-50, AGENTS.md:21-23

Configuration Schema and Defaults

Noesis utilizes a versioned schema (currently schemaVersion: 1) to define the structure of the system configuration. The configuration is divided into four primary segments: Agent, Learning, Autonomy, and Experiments.

Core Configuration Segments

Segment	Description	Key Options
Agent	LLM provider and model settings.	provider, model, thinkingLevel
Learning	Controls for ambient reflection and background work.	enabled, notifications, backgroundBudget
Autonomy	Risk thresholds and permission policies.	riskLevel, approval, pins, vetoes
Experiments	Limits for candidate evaluation trials.	maxCases, maxAttemptsPerArm, maxCost

Sources: packages/config/src/index.ts:11-54

Default Values

The system provides built-in defaults to ensure a functional baseline even in the absence of a user-provided config.json.

export const BUILT_IN_AGENT_DEFAULTS: ResolvedAgentConfig = {
  provider: "openai-codex",
  model: "gpt-5.5",
  thinkingLevel: "medium",
};

export const BUILT_IN_AUTONOMY_DEFAULTS: Required<AutonomyConfig> = {
  riskLevel: "low",
  approval: "authority_expansion",
  pins: "respect",
  vetoes: "respect",
};

Sources: packages/config/src/index.ts:111-131

Configuration Resolution and Precedence

Noesis follows a strict hierarchy of precedence when resolving configuration values. This allows developers and users to quickly override persistent settings for single sessions or specific environments.

Resolution Hierarchy

1. CLI Arguments: Highest priority. Overrides all other sources.
2. Environment Variables: Overrides config file and defaults (e.g., NOESIS_MODEL).
3. Config File: Persistent user settings defined in config.json.
4. Defaults: Hardcoded system fallbacks.

The following flowchart illustrates the resolution logic for an individual configuration key:

The system also tracks the source of each resolved value (e.g., whether the model came from "cli" or "config").

Sources: packages/config/src/index.ts:167-203, packages/config/test/config.test.ts:32-52

Atomic Updates and Concurrency Control

To prevent race conditions when multiple processes attempt to update config.json (such as a TUI session and a background learning worker), Noesis implements a file-based locking mechanism.

Writer Lock Mechanism

Before any write operation, the system attempts to acquire an exclusive lock file (config.json.writer.lock). This lock contains the Process ID (PID) and a unique token. If a lock is held by a stale process (verified via process.kill(pid, 0)), the system automatically reclaims it.

Architectural Invariants

The Configuration Management system enforces several architectural constraints to maintain system integrity and security boundaries:

• One Authority per Datum: Configuration must only be stored in the designated config.json or environment variables; it is never reconstructed from activity logs.
• No Credentials in Config: The NoesisConfigSchema strictly forbids the inclusion of API keys or secrets. Credentials must remain in the protected credential store or process environment.
• Immutable Pins/Vetoes: The autonomy configuration includes pins: "respect" and vetoes: "respect" as literal constraints, ensuring the system cannot be configured to ignore user-defined blocks on behavior.
• Validation at Boundary: All configuration data is validated using Zod at the point of ingestion (file read or CLI parse).

Sources: AGENTS.md:21-30, packages/config/src/index.ts:35-50

Implementation Details

Validation Functions

The system uses the decodeConfig function to ensure that any loaded JSON matches the schemaVersion: 1 structure. It also handles legacy field cleanup, such as removing the deprecated agent.runtime selector.

function decodeConfig(path: string, value: unknown): Result<NoesisConfig, NoesisConfigError> {
  if (value !== null && typeof value === "object" && "schemaVersion" in value &&
    value.schemaVersion !== NOESIS_CONFIG_SCHEMA_VERSION) {
    return err(new NoesisConfigError(path, `unsupported schemaVersion; accepts only 1`));
  }
  // ... (validation logic)
}

Sources: packages/config/src/index.ts:303-332

User Control Updates

The updateUserControlConfig function allows for atomic updates to the Learning, Autonomy, and Experiment segments while preserving the current Agent settings.

Sources: packages/config/src/index.ts:430-454, packages/config/test/config.test.ts:117-131

Conclusion

Configuration Management in Noesis is a centralized service that balances flexible execution with strict safety rails. By combining Zod-driven validation, a clear precedence hierarchy, and atomic concurrency controls, it provides a stable foundation for the agent's autonomous operations. This structure ensures that users maintain ultimate control through "respect" policies for pins and vetoes while enabling ambient self-improvement.