Configuration - Noēsis

Noēsis can be configured through multiple sources. This page documents all available options and how to set them.

Configuration precedence

Configuration is resolved in this order (highest to lowest priority):

ns.set() calls in Python code
Environment variables (e.g., NOESIS_PLANNER)
noesis.toml configuration file
Default values

Configuration options

runs_dir

Directory where episode artifacts are stored (episodes root).

Source	Setting
Python	`ns.set(runs_dir="./my-runs")`
Environment	`NOESIS_RUNS_DIR=./my-runs`
TOML	`runs_dir = "./my-runs"`
Default	`".noesis/episodes"`

planner_mode

Controls planning strategy and direction behavior.

Source	Setting
Python	`ns.set(planner_mode="meta")`
Environment	`NOESIS_PLANNER=meta`
TOML	`planner_mode = "meta"`
Default	`"meta"`

Values:

Value	Description
`meta`	MetaPlanner-enabled planning (direction search / directives)
`minimal`	Minimal planning; skips direction search and runs a simple planner

planner_mode controls planning strategy. Governance is controlled separately via governance_mode and governance_failure_policy.

agents

Reserved/unused in v1.0.0. Parsed into the runtime config but not read by the CLI/runtime execution paths in this release.

Source	Setting
Python	`ns.set(agents="agents.yaml")`
Environment	`NOESIS_AGENTS=agents.yaml`
TOML	`agents = "agents.yaml"`
Default	`"agents.yaml"`

tasks

Reserved/unused in v1.0.0. Parsed into the runtime config but not read by the CLI/runtime execution paths in this release.

Source	Setting
Python	`ns.set(tasks="tasks.yaml")`
Environment	`NOESIS_TASKS=tasks.yaml`
TOML	`tasks = "tasks.yaml"`
Default	`"tasks.yaml"`

timeout_sec

Episode timeout in seconds.

Source	Setting
Python	`ns.set(timeout_sec=120)`
Environment	`NOESIS_TIMEOUT_SEC=120`
TOML	`timeout_sec = 120`
Default	`60`

learn_mode

Controls how learning proposals are handled.

Source	Setting
Python	`ns.set(learn_mode="record")`
Environment	`NOESIS_LEARN_MODE=record`
TOML	`learn_mode = "record"`
Default	`"record"`

Values:

Value	Description
`off`	Disable learning
`record`	Record proposals only
`apply`	Auto-apply approved proposals

learn_auto_apply_min_confidence

Minimum confidence for auto-applying learn proposals.

Source	Setting
Python	`ns.set(learn_auto_apply_min_confidence=0.9)`
Environment	`NOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCE=0.9`
TOML	`learn_auto_apply_min_confidence = 0.9`
Default	`0.75`

learn_auto_apply_min_successes

Minimum successful triggers before auto-applying.

Source	Setting
Python	`ns.set(learn_auto_apply_min_successes=5)`
Environment	`NOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSES=5`
TOML	`learn_auto_apply_min_successes = 5`
Default	`3`

intuition_mode

Controls intuition advisory posture.

Source	Setting
Python	`ns.set(intuition_mode="advisory")`
Environment	`NOESIS_INTUITION_MODE=advisory`
TOML	`intuition_mode = "advisory"`
Default	`"advisory"`

Values:

Value	Description
`advisory`	Intuition provides hints only
`interventive`	Intuition can modify plans
`hybrid`	Combination based on confidence

direction_min_confidence

Minimum confidence threshold for applying plan directives.

Source	Setting
Python	`ns.set(direction_min_confidence=0.8)`
Environment	`NOESIS_DIRECTION_MIN_CONFIDENCE=0.8`
TOML	`direction_min_confidence = 0.8`
Default	`0.5`

governance_mode

Controls pre-act governance behavior.

Source	Setting
Python	`ns.set(governance_mode="enforce")`
Environment	`NOESIS_GOVERNANCE_MODE=enforce`
TOML	`governance_mode = "enforce"`
Default	`"off"`

Values:

Value	Description
`off`	Governance disabled
`audit`	Record decisions; never blocks execution
`enforce`	Veto blocks Act; runtime terminates by default or pauses/checkpoints when `governance_pause_on_veto=true`

governance_failure_policy

How to handle governance errors/timeouts.

Source	Setting
Python	`ns.set(governance_failure_policy="fail_closed")`
Environment	`NOESIS_GOVERNANCE_FAILURE_POLICY=fail_closed`
TOML	`governance_failure_policy = "fail_closed"`
Default	Depends on mode (audit→fail_open, enforce→fail_closed)

Values:

Value	Description
`fail_open`	On error, allow action to proceed
`fail_closed`	On error, treat as veto

governance_timeout_ms

Reserved/unused in v1.0.0. Parsed into the runtime config but not enforced during episode execution in this release.

Source	Setting
Python	`ns.set(governance_timeout_ms=250)`
Environment	`NOESIS_GOVERNANCE_TIMEOUT_MS=250`
TOML	`governance_timeout_ms = 250`
Default	`None`

governance_pause_on_veto

Enable pause semantics for enforce-mode vetoes. When enabled, Noēsis emits:

run.interrupt
run.checkpoint

and halts side effects instead of finalizing/sealing the run.

Source	Setting
Python	`ns.set(governance_pause_on_veto=True)`
Environment	`NOESIS_GOVERNANCE_PAUSE_ON_VETO=true`
TOML	`governance_pause_on_veto = true`
Default	`false`

policy_aliases

Mapping of policy alias → import spec. Used by the CLI --policy flag to resolve short names.

Source	Setting
Python	`ns.set(policy_aliases={"safe": "my.module:SafetyPolicy"})`
TOML	`policy_aliases = { safe = "my.module:SafetyPolicy" }`
Default	`{}`

learn_home

Directory for learning data storage.

Source	Setting
Python	`ns.set(learn_home="./learn")`
Environment	`NOESIS_LEARN_HOME=./learn`
TOML	`learn_home = "./learn"`
Default	`~/.noesis/state`

prompt_provenance_enabled

Enable prompt provenance logging.

Source	Setting
Python	`ns.set(prompt_provenance_enabled=True)`
Environment	`NOESIS_PROMPT_PROVENANCE_ENABLED=true`
TOML	`prompt_provenance_enabled = true`
Default	`false`

prompt_provenance_mode

Mode for prompt provenance storage.

Source	Setting
Python	`ns.set(prompt_provenance_mode="hash_only")`
Environment	`NOESIS_PROMPT_PROVENANCE_MODE=hash_only`
TOML	`prompt_provenance_mode = "hash_only"`
Default	`"hash_only"`

Values:

Value	Description
`full`	Store full prompt content
`hash_only`	Store only content hashes (default)
`redacted`	Store redacted content

prompt_provenance_mode="full" may record prompt content. Use hash_only or redacted for sensitive environments.

Configuration file

Noēsis searches for a config file by walking upward from the current working directory. Supported filenames are noesis.toml and .noesis.toml. The recommended form is a [noesis] table (if the table is missing, Noēsis falls back to treating the full TOML file as the config mapping):

noesis.toml

[noesis]
runs_dir = "./.noesis/episodes"
agents = "agents.yaml"
tasks = "tasks.yaml"
planner_mode = "meta"
learn_mode = "record"
learn_home = "./learn"
intuition_mode = "advisory"
direction_min_confidence = 0.7
governance_mode = "off"
governance_failure_policy = "fail_open"
governance_pause_on_veto = false
learn_auto_apply_min_confidence = 0.85
learn_auto_apply_min_successes = 3
prompt_provenance_enabled = false
prompt_provenance_mode = "hash_only"

Environment variables

The following runtime configuration options have environment variable equivalents:

Option	Environment variable
`runs_dir`	`NOESIS_RUNS_DIR`
`planner_mode`	`NOESIS_PLANNER`
`agents`	`NOESIS_AGENTS`
`tasks`	`NOESIS_TASKS`
`timeout_sec`	`NOESIS_TIMEOUT_SEC`
`learn_mode`	`NOESIS_LEARN_MODE`
`learn_home`	`NOESIS_LEARN_HOME`
`intuition_mode`	`NOESIS_INTUITION_MODE`
`direction_min_confidence`	`NOESIS_DIRECTION_MIN_CONFIDENCE`
`governance_mode`	`NOESIS_GOVERNANCE_MODE`
`governance_failure_policy`	`NOESIS_GOVERNANCE_FAILURE_POLICY`
`governance_timeout_ms`	`NOESIS_GOVERNANCE_TIMEOUT_MS`
`governance_pause_on_veto`	`NOESIS_GOVERNANCE_PAUSE_ON_VETO`
`learn_auto_apply_min_confidence`	`NOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCE`
`learn_auto_apply_min_successes`	`NOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSES`
`prompt_provenance_enabled`	`NOESIS_PROMPT_PROVENANCE_ENABLED`
`prompt_provenance_mode`	`NOESIS_PROMPT_PROVENANCE_MODE`

policy_aliases has no environment variable form in v1.0.0 (configure it via ns.set() or noesis.toml).NOESIS_DIR_MIN_CONFIDENCE is a deprecated alias for NOESIS_DIRECTION_MIN_CONFIDENCE (if set, Noēsis warns and uses it).

Example:

# Set via environment
export NOESIS_PLANNER=meta
export NOESIS_RUNS_DIR=./artifacts
export NOESIS_DIRECTION_MIN_CONFIDENCE=0.8
export NOESIS_AGENTS=agents.yaml
export NOESIS_TASKS=tasks.yaml

# Or inline
NOESIS_PLANNER=minimal NOESIS_RUNS_DIR=./artifacts noesis run "quick test"

Python API

Setting configuration

import noesis as ns

# Set individual options
ns.set(runs_dir="./artifacts")
ns.set(planner_mode="meta")
ns.set(direction_min_confidence=0.8)

# Set multiple at once
ns.set(
    runs_dir="./artifacts",
    planner_mode="meta",
    learn_mode="record",
    prompt_provenance_enabled=False,
)

Reading configuration

import noesis as ns

config = ns.get()  # returns a mapping

print(f"Runs dir: {config['runs_dir']}")
print(f"Planner mode: {config['planner_mode']}")
print(f"Direction min confidence: {config['direction_min_confidence']}")

Resetting configuration

import noesis as ns

# Set back to defaults explicitly
ns.set(
    runs_dir="./.noesis/episodes",
    planner_mode="meta",
    direction_min_confidence=0.5,
    governance_mode="off",
    governance_pause_on_veto=False,
    learn_mode="record",
    learn_auto_apply_min_confidence=0.75,
    learn_auto_apply_min_successes=3,
    prompt_provenance_enabled=False,
    prompt_provenance_mode="hash_only",
)

Per-episode parameters

Some parameters can be set per episode at call time:

import noesis as ns

# Global config
ns.set(planner_mode="meta")

# Per-episode parameters
episode_id = ns.run(
    "quick test",
    seed=42,                        # reproducibility seed
    tags={"env": "staging"},        # metadata tags
    intuition=True,                 # enable/disable intuition
)

Global configuration (via ns.set()) applies to all episodes. Per-call parameters like seed, tags, and intuition are set at run time.

CLI configuration

Most CLI configuration is done via environment variables:

NOESIS_RUNS_DIR=./artifacts noesis run "task"
NOESIS_PLANNER=minimal noesis run "task"
NOESIS_DIRECTION_MIN_CONFIDENCE=0.8 noesis run "task"

Configuration validation

Noēsis validates configuration on startup:

import noesis as ns

# Invalid planner mode raises ValueError
try:
    ns.set(planner_mode="invalid")
except ValueError as e:
    print(f"Invalid config: {e}")

Best practices

Use environment variables for deployment. Set NOESIS_RUNS_DIR, NOESIS_PLANNER, and related knobs per environment.

Don’t commit secrets. If using noesis.toml, ensure it doesn’t contain sensitive values and is in .gitignore if needed.

Use per-call seeds for debugging. Pass seed= to ns.run/ns.solve when you need reproducibility; unset it for production.

Example configurations

Development

noesis.toml

[noesis]
runs_dir = "./.noesis/episodes"
planner_mode = "minimal"
direction_min_confidence = 0.5
governance_mode = "off"
governance_pause_on_veto = false
prompt_provenance_enabled = false

Staging

noesis.toml

[noesis]
runs_dir = "./.noesis/episodes"
planner_mode = "meta"
learn_mode = "record"
direction_min_confidence = 0.5
governance_mode = "audit"
governance_pause_on_veto = false
prompt_provenance_enabled = false

Production

noesis.toml

[noesis]
runs_dir = "/var/noesis/episodes"
planner_mode = "meta"
learn_mode = "record"
governance_mode = "enforce"
governance_failure_policy = "fail_closed"
governance_pause_on_veto = true
learn_auto_apply_min_confidence = 0.95
learn_auto_apply_min_successes = 5
prompt_provenance_enabled = true
prompt_provenance_mode = "hash_only"

​Configuration precedence

​Configuration options

​runs_dir

​planner_mode

​agents

​tasks

​timeout_sec

​learn_mode

​learn_auto_apply_min_confidence

​learn_auto_apply_min_successes

​intuition_mode

​direction_min_confidence

​governance_mode

​governance_failure_policy

​governance_timeout_ms

​governance_pause_on_veto

​policy_aliases

​learn_home

​prompt_provenance_enabled

​prompt_provenance_mode

​Configuration file

​Environment variables

​Python API

​Setting configuration

​Reading configuration

​Resetting configuration

​Per-episode parameters

​CLI configuration

​Configuration validation

​Best practices

​Example configurations

​Development

​Staging

​Production

​Next steps

Quickstart

Planner modes

Configuration precedence

Configuration options

runs_dir

planner_mode

agents

tasks

timeout_sec

learn_mode

learn_auto_apply_min_confidence

learn_auto_apply_min_successes

intuition_mode

direction_min_confidence

governance_mode

governance_failure_policy

governance_timeout_ms

governance_pause_on_veto

policy_aliases

learn_home

prompt_provenance_enabled

prompt_provenance_mode

Configuration file

Environment variables

Python API

Setting configuration

Reading configuration

Resetting configuration

Per-episode parameters

CLI configuration

Configuration validation

Best practices

Example configurations

Development

Staging

Production

Next steps