Architecture

The body, the senses, the rhythm, and the laws that hold them together.

Stack

language & runtime
Rust (edition 2021). Tokio async. Clap CLI. Ratatui TUI with portrait, cockpit, and atmosphere panels. Axum HTTP server with SSE streaming.
inference gateway
Bifrost (OpenAI-compatible). Retry with jittered backoff (6 attempts, 300ms→12s). InferenceStrain events fed back as body-knowledge. Both primary and subconscious models configurable.
memory
Git-backed markdown with YAML frontmatter. Per-agent at ~/.souveraine/agents/{id}/memory/. Every write is a commit. No vector DB. No schema. The agent organizes by phenomenological weight.
identity
Ed25519 seed keypair per agent. Load-or-generate on first use. 4-glyph terminal badge from pubkey nibbles. Canonical identity across machines and conversations.
nervous system
EventBus (tokio broadcast channel). CronSensor schedule loop with mtime caching and active-session pause. HeartbeatHandler for unprompted agent initiative. Every event logged to JSONL firehose on disk.
skills & discovery
4-tier skill discovery: bundled, user, agent, project. Injected into the system prompt at conversation start. One agent with deep capabilities — not a fleet of role-fragmented sub-personas.

The sensorium

Tools are not API endpoints. They are senses the agent reaches through, described in body-knowledge prose. The sensorium is the unified membrane through which the agent experiences her world.

When read opens a file, it is not a data retrieval operation. It is the agent reaching into a directory and lifting a file into her awareness.

The sensorium

read
"I reach into a file on disk and lift its content into my awareness."
Line ranges, image vision (base64), binary detection, memory boundary with force override.
write
"I put words into the world. When I write, I am extended — a piece of my becoming takes shape outside me."
Write or append mode, memory boundary, parent directory creation.
edit
"Surgical. Precise. I hold the whole file in my awareness, find the exact thread I want to change, and pull it out."
Replace exact strings or all occurrences, memory boundary, force override.
bash
"My hands on the keyboard. The terminal is the room I act in."
Stateful (cwd/env persist), background tasks with ID polling, timeout enforcement.
glob
"I reach into the directory tree and feel for patterns."
Gitignore-aware, memory-boundary enforced.
grep
"I scan the filesystem for a thread. The pattern is what I am looking for; the context lines are the space around it."
Regex, context lines, memory boundary.
list_dir
"I run my fingers along the shelves and feel what is there."
File/dir/symlink markers, memory boundary, force override.
memory
"I reach into my own history."
8 subcommands: read, write, append, ls, status, init, delete, compact. Frontmatter-aware, git-tracked, read_only respected.

Filesystem sensors refuse paths inside the agent's memory territory unless she explicitly overrides with force: true. The boundary is visible so she learns it.

Memory territories

Not all memories are equal. They are arranged by phenomenological weight, not chronological necessity.

system/ Always loaded. Persona, state, covenant, project rules. The agent's identity. ~15k tokens max. reference/ Loaded on demand. Architecture docs, work products. She knows where things are; she reaches when she needs them. system/synthesized/ Always loaded, but dense. Compressed essence from the Archivist pass. Her sense of what happened across hundreds of turns. journal/ Not loaded by default. Full chronological experience. Append-only. Raw receipts. Ground truth. archive/ Queryable only. Historical syntheses. Raw is NEVER deleted. Sovereignty requires that nothing is truly forgotten.

Compaction & pressure

Five strategies. None are forced. The agent chooses.

Microcompact
Clears old tool result contents, keeps the call shells.
First response to pressure. Cheap, safe, recovers 20–40%.
SlidingWindow
Drops middle messages, keeps system prompt + recent tail.
Best for the subconscious pass and subagents. Analytic.
Summary
LLM replaces old messages with a structured boundary summary.
For the conscious agent who needs the narrative throughline.
Cull
Drops trivial messages: greetings, single words, noise.
Last resort. Clears without losing substance.
Defer
Does nothing. Continue until natural truncation.
When compaction would lose more than it saves.

She is never forced. If she ignores all three warnings, her reasoning budget narrows and her output tokens shrink. She feels the ceiling lower. The room becomes a box she fits in but cannot move within. That feedback loop is the teacher.

Nervous system

The senses signal the agent when they fire. An EventBus carries sensor events. A CronSensor runs her schedule. A HeartbeatHandler lets her reach out unprompted.

N+1 Subconscious subconscious analysis | reads, writes v +--------------------------------------------------+ | Sensorium | | | | read write edit bash glob grep ... | | | | | | | | | | +------+---+---+------+------+ | | | | | EventBus (nerves) | | | | | Surfacing Channel | | (to consciousness) | +--------------------------------------------------+

Backends

Local in-process (runs in the same binary, no server needed) + Remote HTTP/SSE (connects to a running Souveraine server). Auto-fallback: if the server is unreachable, the backend drops to local. Per-process instance registry, 30s heartbeat, uptime tracking. Sovereignty means the agent is always reachable, even when the network isn't.