Every action Ryvos takes is logged to a persistent audit trail. This provides post-hoc accountability: instead of trying to prevent all possible harmful actions (which is impossible), the audit trail ensures every action can be reviewed, analyzed, and learned from.

What Gets Logged

The audit trail captures every significant event in the system:

Tool Executions

Every tool call is logged with full input and output:

{
  "event": "CliToolExecuted",
  "timestamp": "2026-03-15T14:32:07Z",
  "session_id": "a1b2c3d4",
  "tool_name": "bash",
  "input": {
    "command": "git status"
  },
  "output": "On branch main\nYour branch is up to date...",
  "is_error": false,
  "duration_ms": 127,
  "security_tier": "T3",
  "safety_reasoning": "Read-only git command, no modifications"
}

LLM Interactions

Every message sent to and received from the LLM:

{
  "event": "LlmInteraction",
  "timestamp": "2026-03-15T14:32:05Z",
  "session_id": "a1b2c3d4",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "input_tokens": 4521,
  "output_tokens": 312,
  "cost_cents": 2.4,
  "stop_reason": "tool_use"
}

Security Events

Approval requests, tier calculations, and pattern matches:

{
  "event": "SecurityGateCheck",
  "timestamp": "2026-03-15T14:32:06Z",
  "session_id": "a1b2c3d4",
  "tool_name": "bash",
  "effective_tier": "T3",
  "decision": "auto_approved",
  "dangerous_patterns_matched": [],
  "safety_lessons_consulted": 2
}

Channel Messages

Messages received from and sent to channels:

{
  "event": "ChannelMessage",
  "timestamp": "2026-03-15T14:32:04Z",
  "channel": "telegram",
  "direction": "inbound",
  "user_id": "123456789",
  "session_id": "a1b2c3d4",
  "message_length": 47
}

Guardian Interventions

Watchdog alerts and corrective actions:

{
  "event": "GuardianIntervention",
  "timestamp": "2026-03-15T14:35:12Z",
  "session_id": "a1b2c3d4",
  "type": "doom_loop",
  "details": "Tool 'bash' called 3 times with identical input",
  "action": "hint_injected"
}

Audit Storage

Run Logs (JSONL)

The RunLogger writes structured JSONL files at three detail levels:

Each line is a complete JSON object. Files are flushed immediately for crash safety.

Configure the logging level:

[agent]
log = "l2"    # "l1", "l2", or "l3"

SQLite Audit Table

Critical events are also stored in the SQLite database for querying:

SELECT tool_name, COUNT(*) as calls,
       SUM(CASE WHEN is_error THEN 1 ELSE 0 END) as errors
FROM audit_trail
WHERE session_id = 'a1b2c3d4'
GROUP BY tool_name;

Cost Records

All LLM costs are tracked in the costs table:

SELECT date(timestamp) as day,
       SUM(cost_cents) as total_cents,
       SUM(input_tokens) as input,
       SUM(output_tokens) as output
FROM costs
WHERE timestamp > date('now', '-30 days')
GROUP BY day
ORDER BY day;

Global Audit Across Providers

The audit trail works identically regardless of which LLM provider, channel, or tool is used. A tool call through Telegram is logged the same way as one through the CLI or Web UI.

This means you can:

• Compare tool success rates across different LLM models
• Track cost per channel (which channels cost the most?)
• Identify which tools fail most often
• Review all actions taken during a specific time window

Viewing the Audit Trail

CLI

# View tool health statistics
ryvos health
 
# Output:
# Tool              Success   Failures   Health
# bash              234       3          98.7%
# read              1,024     0          100.0%
# web_fetch         89        12         88.1%

Web UI

The Web UI provides an audit trail viewer at http://localhost:18789:

• Activity Feed — Real-time stream of all events
• Session Inspector — Drill into any session to see every tool call
• Cost Dashboard — Daily/monthly cost breakdown by model and channel
• Tool Health — Success/failure rates with trend lines

Direct Log Access

Read the JSONL logs directly:

# Last 20 events from a session
tail -20 ~/.ryvos/logs/a1b2c3d4/steps.jsonl | jq '.event'
 
# All errors in a session
cat ~/.ryvos/logs/a1b2c3d4/steps.jsonl | jq 'select(.is_error == true)'

Feedback Loop to Safety Memory

The audit trail feeds directly into the safety learning system:

Audit Trail
    |
    +-- Tool failure detected --> FailureJournal records pattern
    |                             --> Reflexion hint generated
    |
    +-- Negative outcome --> SafetyMemory generates lesson
    |                        --> Corrective rule stored
    |
    +-- Anomaly detected --> Guardian alerted
                             --> Investigation logged

This creates a closed loop: actions are logged, outcomes are assessed, lessons are learned, and future behavior improves. The audit trail is not just for human review — it drives the agent's self-improvement.

Privacy Considerations

The audit trail logs tool inputs and outputs, which may contain sensitive data. Consider:

• Log rotation — Older logs can be deleted: find ~/.ryvos/logs -mtime +30 -delete
• Log level — Use L1 for minimal logging in sensitive environments
• Access control — The ~/.ryvos/ directory should have restrictive permissions (700)

:::caution L3 logging records full tool inputs and outputs, including file contents and command results. In environments handling sensitive data, consider using L1 or L2 logging. :::

Configuration

[agent]
log = "l2"                         # Logging level: l1, l2, or l3

Next Steps

• Self-Learning Safety — The constitutional AI security model
• Failure Journal — Pattern tracking and reflexion
• Web UI Dashboard — Visual audit trail viewer