souveraine/saf/config.md

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"