# 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. |
