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 artifacts are stored.
| Source | Setting |
|---|
| Python | ns.set(runs_dir="./my-runs") |
| Environment | NOESIS_RUNS_DIR=./my-runs |
| TOML | runs_dir = "./my-runs" |
| Default | "./runs" |
planner_mode
Controls the level of governance and observability.
| Source | Setting |
|---|
| Python | ns.set(planner_mode="meta") |
| Environment | NOESIS_PLANNER=meta |
| TOML | planner_mode = "meta" |
| Default | "meta" |
| Value | Description |
|---|
meta | Full governance with MetaPlanner and PreActGovernor |
minimal | Skip governance, use legacy stepwise planner |
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" |
| 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" |
| 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 |
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
Control 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 |
| 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" |
Configuration file
Create a noesis.toml in your project root:
[noesis]
runs_dir = "./runs"
planner_mode = "meta"
learn_mode = "record"
learn_home = "./learn"
intuition_mode = "advisory"
direction_min_confidence = 0.7
learn_auto_apply_min_confidence = 0.85
learn_auto_apply_min_successes = 3
prompt_provenance_enabled = false
prompt_provenance_mode = "hash_only"
Environment variables
All 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 |
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 |
# Set via environment
export NOESIS_PLANNER=meta
export NOESIS_RUNS_DIR=./artifacts
export NOESIS_DIRECTION_MIN_CONFIDENCE=0.8
# 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="./runs",
planner_mode="meta",
direction_min_confidence=0.5,
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 overrides
Some options can be overridden per episode:
import noesis as ns
# Global config
ns.set(planner_mode="meta")
# Override for specific episode
episode_id = ns.run(
"quick test",
tags={"override": "true"},
seed=42, # per-call seed for reproducibility
)
CLI configuration
Configure the CLI via environment variables (the CLI does not expose --runs-dir or --planner flags):
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 = "./runs"
planner_mode = "minimal"
direction_min_confidence = 0.5
prompt_provenance_enabled = false
Staging
[noesis]
runs_dir = "./runs"
planner_mode = "meta"
learn_mode = "record"
direction_min_confidence = 0.5
prompt_provenance_enabled = false
Production
[noesis]
runs_dir = "/var/noesis/runs"
planner_mode = "meta"
learn_mode = "record"
learn_auto_apply_min_confidence = 0.95
learn_auto_apply_min_successes = 5
prompt_provenance_enabled = true
prompt_provenance_mode = "hash_only"
Next steps
