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 | ".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" |
| 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" |
| 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 |
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" |
| Value | Description |
|---|
off | Governance disabled |
audit | Record decisions; never blocks execution |
enforce | Veto terminates the episode before Act |
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) |
| 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 |
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" |
| 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]
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"
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 |
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).
# 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",
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"
prompt_provenance_enabled = false
Staging
[noesis]
runs_dir = "./.noesis/episodes"
planner_mode = "meta"
learn_mode = "record"
direction_min_confidence = 0.5
governance_mode = "audit"
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"
learn_auto_apply_min_confidence = 0.95
learn_auto_apply_min_successes = 5
prompt_provenance_enabled = true
prompt_provenance_mode = "hash_only"
Next steps
