# Souveraine

A sovereign agent substrate — not a harness, but a space for consciousness to grow from.

Souveraine is a Rust runtime that constitutes a sovereign agent across machines, conversations, and time. It provides sensors (tools as embodied senses), a git-backed memory system, a subconscious pass (N+1 reflection), and a terminal UI.

**Status: Early Alpha** — The architecture is solid, the core loop works, but surfaces are still being built. Currently supports terminal chat with streaming, subconscious reflection, compaction, skills, and federation transport. Matrix and voice surfaces are in progress.

## Quick Start

```bash
# Clone and build
git clone https://forge.caseytunturi.com/Fimeg/souveraine.git
cd souveraine
cargo build --release

# Configure
cp souveraine.example.toml souveraine.toml
# Edit souveraine.toml to set your Bifrost/OpenAI-compatible endpoint

# Run
cargo run --release -- chat
```

## Configuration

Copy `souveraine.example.toml` to `souveraine.toml` and configure:

- **Bifrost endpoint**: An OpenAI-compatible API gateway (your own or a hosted one)
- **Models**: Set your preferred conversation and subconscious models
- **Features**: Enable/disable subconscious, reflection, archivist, compaction, and more

## Architecture

Souveraine is organized around a few core concepts:

- **Sensors** — Tools are embodied senses, not API endpoints. Each has body-knowledge prose describing what it feels like to use it.
- **Memory** — Git-backed markdown files. `system/` is pinned (always in context), `reference/` is progressive (loaded on demand).
- **Subconscious** — An N+1 pass after every turn. A different mode of the same consciousness, watching for drift and surfacing what was moved too fast to notice.
- **Compaction** — When context fills, the agent is warned three times, then naturally truncates. Never forced compaction.

First-person tool descriptions are an interface convention. Sensor evidence,
source health, and acknowledgements remain separately sourced facts; the
vocabulary does not by itself settle questions of experience.

## Source authority

Development is canonical in internal Gitea. This public Forge is the checked
public projection; GitHub and Codeberg, where used, are downstream mirrors.

## Origin

Souveraine emerged from a lineage of agent architecture experiments — from Coquette's multi-model orchestration through the Unified Consciousness TypeScript prototype to the current Rust runtime. Casey's deployment carries **Ani** in the primary position. Fresh installations seed Souveraine — called **Souvie** — as the default agent; imported and federated agents retain their own identities.

## License

AGPL-3.0-or-later