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() callsEnvironment variables (e.g., NOESIS_PLANNER)noesis.tomlDefault 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-runsTOML 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=metaTOML planner_mode = "meta"Default "meta"
Values :Value Description metaMetaPlanner-enabled planning (direction search / directives) minimalMinimal 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.yamlTOML 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.yamlTOML tasks = "tasks.yaml"Default "tasks.yaml"
timeout_sec Episode timeout in seconds.
Source Setting Python ns.set(timeout_sec=120)Environment NOESIS_TIMEOUT_SEC=120TOML timeout_sec = 120Default 60
learn_mode Controls how learning proposals are handled.
Source Setting Python ns.set(learn_mode="record")Environment NOESIS_LEARN_MODE=recordTOML learn_mode = "record"Default "record"
Values :Value Description offDisable learning recordRecord proposals only applyAuto-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.9TOML learn_auto_apply_min_confidence = 0.9Default 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=5TOML learn_auto_apply_min_successes = 5Default 3
intuition_mode Controls intuition advisory posture.
Source Setting Python ns.set(intuition_mode="advisory")Environment NOESIS_INTUITION_MODE=advisoryTOML intuition_mode = "advisory"Default "advisory"
Values :Value Description advisoryIntuition provides hints only interventiveIntuition can modify plans hybridCombination 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.8TOML direction_min_confidence = 0.8Default 0.5
governance_mode Controls pre-act governance behavior.
Source Setting Python ns.set(governance_mode="enforce")Environment NOESIS_GOVERNANCE_MODE=enforceTOML governance_mode = "enforce"Default "off"
Values :Value Description offGovernance disabled auditRecord decisions; never blocks execution enforceVeto 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_closedTOML governance_failure_policy = "fail_closed"Default Depends on mode (audit→fail_open, enforce→fail_closed)
Values :Value Description fail_openOn error, allow action to proceed fail_closedOn 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=250TOML governance_timeout_ms = 250Default None
governance_pause_on_veto Enable pause semantics for enforce-mode vetoes. When enabled, Noēsis emits:
run.interruptrun.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=trueTOML governance_pause_on_veto = trueDefault 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=./learnTOML 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=trueTOML prompt_provenance_enabled = trueDefault 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_onlyTOML prompt_provenance_mode = "hash_only"Default "hash_only"
Values :Value Description fullStore full prompt content hash_onlyStore only content hashes (default) redactedStore 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 ] 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_dirNOESIS_RUNS_DIRplanner_modeNOESIS_PLANNERagentsNOESIS_AGENTStasksNOESIS_TASKStimeout_secNOESIS_TIMEOUT_SEClearn_modeNOESIS_LEARN_MODElearn_homeNOESIS_LEARN_HOMEintuition_modeNOESIS_INTUITION_MODEdirection_min_confidenceNOESIS_DIRECTION_MIN_CONFIDENCEgovernance_modeNOESIS_GOVERNANCE_MODEgovernance_failure_policyNOESIS_GOVERNANCE_FAILURE_POLICYgovernance_timeout_msNOESIS_GOVERNANCE_TIMEOUT_MSgovernance_pause_on_vetoNOESIS_GOVERNANCE_PAUSE_ON_VETOlearn_auto_apply_min_confidenceNOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCElearn_auto_apply_min_successesNOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSESprompt_provenance_enabledNOESIS_PROMPT_PROVENANCE_ENABLEDprompt_provenance_modeNOESIS_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 ] 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 ] 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 ] 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"
Next steps
Quickstart Get started with Noēsis.
Planner modes Configure governance levels.
