> ## Documentation Index
> Fetch the complete documentation index at: https://noesis-32c1d602-cursor-technical-documentation-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete reference for Noēsis configuration options.

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):

1. **`ns.set()` calls** in Python code
2. **Environment variables** (e.g., `NOESIS_PLANNER`)
3. **`noesis.toml`** configuration file
4. **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 |

<Info>
  `planner_mode` controls planning strategy. Governance is controlled separately via `governance_mode` and `governance_failure_policy`.
</Info>

### 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              |

<Warning>
  `prompt_provenance_mode="full"` may record prompt content. Use `hash_only` or `redacted` for sensitive environments.
</Warning>

## 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):

```toml noesis.toml theme={null}
[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`          |

<Note>
  `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).
</Note>

**Example**:

```bash theme={null}
# 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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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
)
```

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

## CLI configuration

Most CLI configuration is done via environment variables:

```bash theme={null}
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:

```python theme={null}
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

<Tip>
  **Use environment variables for deployment.** Set `NOESIS_RUNS_DIR`, `NOESIS_PLANNER`, and related knobs per environment.
</Tip>

<Warning>
  **Don't commit secrets.** If using `noesis.toml`, ensure it doesn't contain sensitive values and is in `.gitignore` if needed.
</Warning>

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

## Example configurations

### Development

```toml noesis.toml theme={null}
[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

```toml noesis.toml theme={null}
[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

```toml noesis.toml theme={null}
[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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started with Noēsis.
  </Card>

  <Card title="Planner modes" icon="shield" href="/guides/configure-planner-modes">
    Configure governance levels.
  </Card>
</CardGroup>