# SAF: Config Reference

> Every config option, its default, where it's read, and what it controls.
> **Last updated:** 2026-05-12 (Full audit — 16 sections, many new since May 6)

---

## File: `souveraine.toml` (or `souveraine.yaml`)

Loaded by `ConsciousnessConfig::load()` in `src/core/config.rs`.

### `[bifrost]` — LLM Provider Connection

| Key | Type | Default | Read In | Description |
|-----|------|---------|---------|-------------|
| `base_url` | String | `http://<bifrost-host>:<port>` | bifrost.rs | Bifrost API endpoint |
| `api_key` | String | (OS keyring or env) | bifrost.rs | Bearer token for auth. Falls back to `credentials::get_bifrost_key()` which checks env `BIFROST_KEY` then OS keyring |
| `primary_model` | String | `fireworks/.../kimi-k2p5-turbo` | local.rs, server.rs | Default model for conversations |
| `virtual_key` | String | (env `BIFROST_VIRTUAL_KEY`) | bifrost.rs | x-bf-vk header |

**Note:** The `api_key` may also include a Bifrost bearer token embedded in the example config. In-memory fallbacks read from env vars before the keyring.

### `[models.<name>]` — Per-Model Overrides

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `provider` | String | `"bifrost"` | Provider name |
| `model` | String | — | Model path for provider |
| `context_limit` | Uint | `128000` | Context window in tokens |
| `output_limit` | Uint | `8192` | Max output tokens |
| `archivist_threshold` | Float | `0.7` | Per-model archivist threshold |
| `archivist_interval` | Uint | `100` | Per-model archivist interval |

**Note:** Model names with dots (like `kimi-k2.5-turbo`) must use quoted table headers: `[models."kimi-k2.5-turbo"]`. Built-in defaults for `kimi-k2p5-turbo` and `deepseek-v4-pro`.

### `[subconscious]` — N+1 / Aster Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `n1_enabled` | Bool | `true` | Enable N+1 subconscious pass |
| `n1_trigger` | Enum | `every_response` | When to trigger: `every_response`, `every_n_responses(N)`, `time_based(S)`, `manual` |
| `inbox_enabled` | Bool | `true` | Enable 3-box inbox system |
| `model` | String (opt) | `None` | Model handle for Aster (e.g. `"openai/glm-5.1"`). None = use primary's model |
| `max_tokens` | Uint (opt) | `None` | Max tokens for Aster's response. None = model default |

### `[reflection]` — N+25 Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `true` | Enable N+25 reflection |
| `message_interval` | Uint | `25` | Messages between reflections |
| `trigger` | Enum | `step_count` | `off`, `step_count`, `compaction_event` |

### `[archivist]` — N+100 Configuration (NOT WIRED)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `true` | Enable N+100 compression |
| `interval` | Uint | `100` | Messages between syntheses |
| `threshold` | Float | `0.7` | Context pressure threshold (0.0-1.0) |
| `compression_model` | String | `"auto"` | Model for synthesis (NOT used — archivist not rebuilt post-cleanup) |
| `synthesis_elements` | Vec | `[Themes, Emotions, Tensions, Anchors, Evolution]` | Elements to include in synthesis |

**Critical:** N+100 archivist is **not implemented**. Config fields exist but nothing reads them. See gaps.md.

### `[compaction]` — In-Session Message Compaction

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `true` | Enable compaction engine |
| `strategy` | Enum | `cull` | Default strategy: `microcompact`, `sliding_window`, `summary`, `cull` |
| `warn_pressure` | Float | `0.80` | Tier-1 (warn) advisory threshold |
| `urgent_pressure` | Float | `0.90` | Tier-2 (urgent) advisory threshold |
| `critical_pressure` | Float | `0.95` | Tier-3 (critical) advisory threshold |

Per-agent-type overrides under `[compaction.per_type.<type>]` where type is `primary`, `subconscious`, or `subagent`. Each override has the same fields as above plus `max_summary_length`, `kv_target`, `min_messages`.

### `[subagent]` — Forked Agent Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `true` | Enable subagent spawning |
| `max_concurrent` | Uint | `3` | Max concurrent forks |
| `timeout` | Uint | `300` | Per-fork timeout in seconds |
| `max_depth` | Uint | `3` | Max nesting depth |
| `max_tool_rounds` | Uint | `50` | Max tool rounds per turn |
| `warning_1_threshold` | Float | `0.80` | First "attention narrowing" warning |
| `warning_2_threshold` | Float | `0.95` | Second "last chance" warning |
| `inter_round_delay_ms` | Uint | `300` | Delay between subagent tool rounds |

### `[memory]` — Git-Backed Memory

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `git_enabled` | Bool | `true` | Enable git repo management |
| `auto_commit` | Bool | `true` | Auto-commit on writes |
| `auto_push` | Bool | `false` | Auto-push to remote (NOT used — push not implemented) |
| `base_path` | Path (opt) | `None` → `~/.souveraine/` | Base path for memory & agents |

### `[server]` — HTTP Server Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `bind` | String | `127.0.0.1` | Server bind address |
| `port` | Uint | `8484` | TCP port |
| `url` | String | `http://127.0.0.1:8484` | Client-facing URL (env `SOUVERAINE_SERVER_URL` overrides) |

#### `[server.auth]`

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `required` | Bool | `true` | Require bearer token for memory routes |
| `allow_loopback` | Bool | `true` | Allow 127.0.0.1/::1 to bypass auth |

### `[schedules]` — Cron Schedules

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `true` | Enable schedule system |
| `schedules_dir` | Path (opt) | `None` | Custom schedules directory |

### `[events]` — Event Persistence (Firehose)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `true` | Enable JSONL event log |
| `events_dir` | Path (opt) | `None` | Custom events directory |
| `retain_days` | Uint | `30` | Days to retain event logs |

### `[federation]` — Cross-Instance Sync

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `false` | Enable federation |
| `instance_label` | String (opt) | `None` | Human-readable instance label |

### `[websocket]` — WebSocket Server

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | Bool | `false` | Enable WebSocket listener |
| `port` | Uint | `7373` | WebSocket port |

### `[sensorium]` — Interface Configuration (NOT WIRED)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `primary_bandwidth` | Enum | `high` | Bandwidth class: `high`, `medium`, `low`, `minimal` |

---

## Environment Variables

| Variable | Overrides | Default |
|----------|-----------|---------|
| `SOUVERAINE_CONFIG_DIR` | Config search path | `~/.config/souveraine/` |
| `SOUVERAINE_SERVER_URL` | Server client URL | `http://127.0.0.1:8484` |
| `SOUVERAINE_SERVER_BIND` | Server bind address | Config value or `127.0.0.1:8484` |
| `SOUVERAINE_API_KEY` | API bearer token | `""` |
| `BIFROST_KEY` | Bifrost bearer token | (OS keyring) |
| `BIFROST_VIRTUAL_KEY` | x-bf-vk header | `""` |
| `SOUVERAINE_GITEA_URL` | Gitea API URL | (none) |
| `SOUVERAINE_AGENT` | Default agent ID for memory tool | `"default"` |
| `AGENT_ID` | Alternative agent ID env var | `"default"` |