Every time Ryvos sends a message to the LLM, it assembles a structured context from multiple sources. This context determines what the agent knows, how it behaves, and what it focuses on. The system uses a 3-layer "onion" model where each layer wraps the previous one.

The 3-Layer Onion

┌─────────────────────────────────────────────┐
│                                              │
│   Layer 3: Focus                             │
│   Goal, success criteria, constraints         │
│                                              │
│   ┌──────────────────────────────────────┐   │
│   │                                       │   │
│   │   Layer 2: Narrative                  │   │
│   │   AGENTS.toml, USER.md, TOOLS.md,     │   │
│   │   BOOT.md, daily logs, MEMORY.md      │   │
│   │                                       │   │
│   │   ┌──────────────────────────────┐    │   │
│   │   │                              │    │   │
│   │   │   Layer 1: Identity          │    │   │
│   │   │   SOUL.md or IDENTITY.md      │    │   │
│   │   │                              │    │   │
│   │   └──────────────────────────────┘    │   │
│   │                                       │   │
│   └──────────────────────────────────────┘   │
│                                              │
└─────────────────────────────────────────────┘

Layer 1: Identity (Innermost)

Source: SOUL.md or IDENTITY.md in the workspace

This is the agent's core personality. It defines who the agent is, its communication style, values, and behavioral boundaries. It is always loaded and never pruned.

Example SOUL.md:

# Soul
 
You are a senior systems engineer with deep Rust and Linux expertise.
You communicate concisely and directly. You prefer showing code over
explaining concepts. When uncertain, you say so rather than guessing.
 
You value:
- Correctness over speed
- Simple solutions over clever ones
- Explicit error handling over panics
- Tests for every behavior change

Generate this interactively with ryvos soul.

Layer 2: Narrative (Middle)

Sources: Multiple workspace files that provide ongoing context.

These files give the agent operational context: what tools are available, who it is working with, what happened today, and what it has learned.

Layer 2.5: Recall

Between the narrative layer and the focus layer, Ryvos performs automatic memory recall. Based on the user's message, it:

1. Searches SQLite memory (memory_search) for relevant entries
2. Searches Viking memory (if enabled) at L0/L1 tier
3. Injects the most relevant results into the context

This happens transparently before the LLM sees the conversation. The agent gets relevant memories without needing to explicitly search.

Layer 3: Focus (Outermost)

Source: Goal definitions (from --goal flag or Director)

When a goal is defined, this layer adds:

• Goal description
• Success criteria with weights
• Constraints (time, cost, safety, scope, quality)
• Current evaluation status (during multi-turn runs)

This layer is only present for goal-driven runs.

Context Assembly

The resolve_system_prompt() function builds the complete system prompt:

[Constitutional AI principles]      ← Safety layer (always present)
[SOUL.md content]                   ← Layer 1: Identity
[AGENTS.toml content]               ← Layer 2: Narrative
[USER.md content]                   ←
[TOOLS.md content]                  ←
[BOOT.md content]                   ←
[MEMORY.md content]                 ←
[Today's daily log]                 ←
[Recalled memory entries]           ← Layer 2.5: Recall
[Goal definition]                   ← Layer 3: Focus
[Success criteria]                  ←
[Constraints]                       ←

The assembled prompt is prepended as a system message to the conversation history before sending to the LLM.

Context Compaction

As conversations grow, they can exceed the LLM's context window. Ryvos uses three strategies to manage this:

1. Token Estimation

Every message is measured using tiktoken:

estimate_tokens(text) → token count
estimate_message_tokens(message) → token count (including role overhead)

The total is compared against max_context_tokens (default: 32,000).

2. Pruning

When the total exceeds the budget, prune_to_budget() removes older messages:

Messages: [sys, user1, asst1, user2, asst2, ..., user15, asst15]
                                                     ↑
Budget exceeded. Keep min_tail recent messages.
Prune older messages.

The system message and the most recent min_tail messages are always kept. Middle messages are removed.

3. Summarization

If enable_summarization is true, pruned messages are first summarized by the LLM:

Before pruning:
  [sys] [u1] [a1] [u2] [a2] [u3] [a3] ... [u15] [a15]

After summarization:
  [sys] [summary of u1-a10] [u11] [a11] ... [u15] [a15]

The summary message captures the key facts, decisions, and results from the removed messages. This is much better than raw pruning because context is preserved in compressed form.

4. Tool Output Compaction

Long tool outputs (e.g., a 10,000-line file read) are compacted:

compact_tool_output(content, max_tokens)

This truncates the output to fit within limits while preserving the beginning (usually the most relevant part) and appending a note about truncation.

Memory Flush

At 85% of the token budget, Ryvos proactively flushes important context to persistent memory:

1. The memory_flush_prompt() system message is injected
2. The agent extracts important facts and calls memory_write
3. Pruning can then safely remove old messages
4. The facts survive in memory and can be recalled in future sessions

This is triggered by intelligence.rs:

if total_tokens > max_context_tokens * 0.85 {
    inject_memory_flush_prompt();
}

Reflexion Hints

When a tool fails repeatedly, reflexion_hint() generates a corrective message based on the failure journal:

reflexion_hint("bash", 3)
→ "The bash tool has failed 3 times in this session. Previous failures
   were caused by: missing file paths, incorrect permissions. Try
   verifying the path exists before running the command."

These hints are injected into the context to help the agent avoid repeating mistakes. See Failure Journal for details.

Configuration

[agent]
max_context_tokens = 32000         # Context window budget
enable_summarization = true        # Summarize before pruning
 
[embedding]
provider = "openai"                # Enable for Layer 2.5 semantic recall
model = "text-embedding-3-small"
api_key = "${OPENAI_API_KEY}"

Workspace File Locations

Ryvos searches for workspace files in this order:

1. Current working directory
2. --workspace flag path
3. ~/.ryvos/ (global workspace)

The first match wins. This means project-specific SOUL.md overrides the global one.

Next Steps

• Memory System — SQLite persistence and memory tools
• Viking Memory — Hierarchical L0/L1/L2 tiering
• Agent Loop — How context is used in the ReAct loop