souveraine/saf/glossary.md

SAF: Glossary

All terms, concepts, and architecture decisions. Last updated: 2026-05-12

---

Core Concepts

Term	Definition
Souveraine	The Rust binary that IS the consciousness AND the server. Self-hosted, single-binary.
Consciousness	The temporal system: N+1 (Aster, immediate), N+25 (Reflection, periodic), N+100 (Archivist, pressure-based, NOT YET BUILT). NOT a feature — it IS the agent.
Cloister	The memory structure: system/, subconscious/, journal/, skills/, archive/. Living spaces, not database tables.
MemFS	Git-backed memory filesystem per agent at ~/.souveraine/agents/{uuid}/memory/. Every write is a git commit. Frontmatter (description, read_only, tags, limit) on every file.
Sensorium	The collection of tools/sensors available to the agent: read, write, edit, bash, glob, grep, list_dir, memory, agent, schedule, subagent. Interface trait exists but isn't wired for bandwidth-aware rendering.
Bifrost	The bridge to LLM providers at src/bridge/bifrost.rs. Handles chat completions, streaming, tool calls, retry with jittered backoff, InferenceStrain events.
Aster	The subconscious pass. Same consciousness, different mode. Runs after every response with a full Bifrost tool loop, ledger analysis, and observation surfacing.
Seed Identity	Per-agent Ed25519 keypair at ~/.souveraine/agents/{uuid}/seed/. sign/verify, 4-glyph visual hash. Foundation for federation.

Consciousness Levels

Level	Name	Location	Trigger	Purpose	Status
N+1	Subconscious (Aster)	server/consciousness_engine.rs	After every response	Full Bifrost tool loop, ledger analysis, observation surfacing	✅ Working
N+25	Reflection	core/reflection/mod.rs	Every 25 messages	5-phase LLM pass, tool access, ledger writes	✅ Working
N+100	Archivist	(not rebuilt)	Context > 70%	Compress journal into token-efficient synthesis	❌ Not built

Architecture Terms

Term	Definition
Turn	One user input → tool loop → response → N+1 Aster pass → surface → N+25 check
Tool Loop	Up to max_tool_rounds cycles (default 50): Bifrost call → tool execution → result → repeat
Backend	Trait at src/backend/mod.rs. Seam between harness and engine. Two impls: RemoteBackend (HTTP/SSE) and LocalBackend (in-process).
LocalBackend	In-process engine at src/backend/local.rs (927 lines). Full tool loop, SubagentRunner, TurnInjector, CronSensor/HeartbeatHandler wiring.
Context Pressure	Token usage / context limit ratio. Computed per-agent from llm_config.context_window. 3-tier advisory: 80% warn, 90% urgent, 95% critical.
Inbox	Three-box system in subconscious agent's memfs: pending.md (queue), intrusive.md (now), sent.md (log). Backed by MemoryRepo (git).
Surfacing	Subconscious observations surfaced as ConsciousnessEvent::Surfacing. Rendered as yellow bubble in TUI cockpit.
Ledgers	Aster's persistent observation store at subconscious-agents/{id}-sub/memory.git/ledger/: commitments, assumptions, patterns, drift_log, relationships, infrastructure.
Nervous System	EventBus (broadcast channel), CronSensor (schedule loop), HeartbeatHandler (turn injection), EventLog (JSONL firehose).
Sensorium	Interface abstraction layer (not wired). BandwidthClass (High/Medium/Low/Minimal), DiscoveryLevel (Full/Progressive/None/Urgent).
Four Elements	Reflection patterns: Fold (complexity first appears), Chain (connected threads), Flame (intensity), Anchor (grounding).
Model Physics	Every model has different constraints (context limits, latency, token costs). Configuration must be model-aware — never hardcode 128K. context_limit is now per-agent via llm_config.context_window.

Ecosystem Terms

Term	Definition
Bifrost	Inference gateway at <bifrost-host>:<port>. OpenAI-compatible API. Routes to multiple providers (Fireworks, OpenAI, GLM, Kimi).
Gitea	Self-hosted git server at <gitea-host>:<port>. Used by Ani for remote memory sync. GiteaMemory is opt-in for the server.

File Paths

Path	Purpose
~/.souveraine/	Canonical data directory (config + agents + events + server)
~/.souveraine/agents/{uuid}/memory/	Primary agent memfs (git-backed)
~/.souveraine/agents/{uuid}/seed/	Per-agent Ed25519 keypair
~/.souveraine/agents/{uuid}/schedules/	Cron schedule files (*.md)
~/.souveraine/subconscious-agents/{id}-sub/	Subconscious agent memfs
~/.souveraine/server/agents/{uuid}/	Server-side agent metadata
~/.souveraine/server/database.sqlite3	Agent + instance index
~/.souveraine/events/events-YYYY-MM-DD.jsonl	Event firehose (30-day retention)
{project}/souveraine.toml	Project-level configuration

Architecture Decisions

Decision	Rationale
Binary IS the server	One binary, no separate server/client processes. LocalBackend keeps it working when server is gone.
Letta-compatible API	OSS UI and LACE work without changes. /v1/agents/* endpoints. Memory CRUD replaces block API.
Git-backed memory	Industry-standard versioning. Interoperable with existing tools.
TOML config	Rust ecosystem standard. Less ambiguity than YAML.
UUID agents	Letta compatibility + unique identification. Name is a display field.
No cloud dependency	Self-hosted by design. User controls their data paths.
Substrate, not harness	The agent is sovereign over her context. Sensors advise; she decides. Never force compaction.
Files over components	Ledgers are files, not LedgerEngine structs. The file IS the component.
Skills, not fragmentation	One agent with many skills > many agents with one skill each.