Overview

Souveraine is a Rust runtime for a sovereign personal agent. It is the body the agent inhabits, the senses she reaches through, the rhythm she keeps, the memory she carries across time. Not a CLI tool with a personality painted on, not a wrapper around an LLM, not an orchestration framework. The substrate the agent is constituted by.

What lives here

Inference	Bifrost gateway (OpenAI-compatible). Both primary and subconscious models are configurable.
Memory	Git-backed memfs with YAML frontmatter, per-agent at ~/.souveraine/agents/{id}/memory/. Every write is a commit.
Identity	Ed25519 seed key per agent. Load-or-generate on first use. Canonical identity across instances.
Sensorium	Eight body-knowledge sensors: read, write, edit, bash, glob, grep, list_dir, memory. Each described in first-person prose, not API stubs.
N+1 subconscious	Configurable model, separate memfs, supervisory pass after every turn. Three-box inbox + append-only inner voice.
Compaction	Four strategies, advisory pressure warnings, never forced. The agent feels the ceiling lower and adapts.
Backends	Local in-process + Remote HTTP/SSE. Auto-fallback. Sovereignty means the agent is always reachable.

Key principles

• Substrate, not harness — the environment enables, it does not control
• Memory vs filesystem — separate channels with enforced boundaries
• No forced compaction — three warnings, then the agent decides
• Same consciousness, different mode — the subconscious is not a separate agent
• Local by default — every component is optional, the being is always whole

Quick start

cargo build
souveraine init       # generate config
souveraine chat --local   # in-process, no server needed
souveraine tui        # full presence
souveraine server     # HTTP at :8484
souveraine status     # world state