Overview

Souveraine is a Rust runtime for a persistent personal agent. It manages per-agent identity, Git-backed memory, tool access, context pressure, background processing positions and local or HTTP/SSE execution. SouveraineOS is the separate operating-system layer around that runtime.

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, loaded or generated on first use. Node commissions remain design work.
Sensorium	Tool definitions for files, memory, scheduling, the machine and other agents. JSON schemas define calls; agent-facing descriptions use first-person prose.
Processing positions	Primary, subconscious, reflection and archivist positions with separate rhythms and memory trees.
Compaction	Five implemented strategies and advisory pressure warnings. Critical pressure narrows the output budget without choosing a strategy for the agent.
Backends	Local in-process and Remote HTTP/SSE, with optional fallback to local execution. Inference locality still depends on the configured provider.

Current design decisions

• Filesystem tools and memory operations use separate paths with an explicit override boundary.
• The runtime warns about context pressure; the agent selects a compaction strategy.
• Primary and subconscious positions share an agent identity while retaining separate memory trees.
• The local backend removes the server dependency. It does not imply that the configured inference provider is local.

Where the source is today

The substrate, nervous system and daily Pixel path contain running software. The dedicated agent-principal boundary, node commissioning and a complete clean-machine reproduction path remain open. The dated implementation notes keep those moving seams in one compact place.

Runtime entry points

The checked public projection contains the early-alpha substrate source and these runtime entry points. That does not make it a complete clean-machine SouveraineOS installation path.

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