# The Axiom REPL: Agent Architecture Framework

**Document type:** Architecture Decision Record  
**Author:** Benjamin Booth  •  **Status:** Active  •  **Last updated:** 2026-04-13

---

## Table of Contents

- [1. The REPL Model](#1-the-repl-model)
- [2. Primary Agents (REPL Cycle)](#2-primary-agents-repl-cycle)
- [3. Supporting Agents (System Services)](#3-supporting-agents-system-services)
- [4. Agent Interaction Patterns](#4-agent-interaction-patterns)
- [5. The Distinguishing Tests](#5-the-distinguishing-tests)
- [6. What Is NOT an Agent](#6-what-is-not-an-agent)
- [7. Complete Skill Profiles](#7-complete-skill-profiles)

---

## 1. The REPL Model

Every intelligent system runs a cognitive cycle. Axiom's agent architecture is organized around a four-phase **REPL** — Read, Eval, Print, Loop — where each phase is owned by a primary agent and the Loop agent connects them into compound cycles that get smarter over time.

```mermaid
graph TB
    subgraph REPL["The Axiom REPL"]
        direction TB
        W["AXI (Loop) — Orchestrator · Arcs · Memory"]
        E["SCAN (Read) — Signals · Detection · Streams"]
        C["CURIO (Eval) — Research · Knowledge · Truth"]
        P["PRESS (Print) — Publish · Present · Deliver"]
        
        W -->|"dispatch observation"| E
        E -->|"signal detected"| W
        W -->|"request research"| C
        C -->|"findings ready"| W
        W -->|"request output"| P
        P -->|"published"| W
    end

    subgraph SUPPORT["System Services"]
        direction TB
        TIDY["TIDY — Infrastructure — Hygiene"]
        DF["TRIAGE — Diagnostics — Health · Security"]
        BE["RIVET — CI/CD — Build · Ship"]
    end

    W -.->|"health check"| DF
    W -.->|"infra request"| TIDY
    W -.->|"release"| BE

    style REPL fill:#1a202c,color:#e2e8f0,stroke:#4a5568
    style SUPPORT fill:#1a202c,color:#e2e8f0,stroke:#4a5568
    style W fill:#c05621,color:#fff,stroke:#9c4221
    style E fill:#2b6cb0,color:#fff,stroke:#2c5282
    style C fill:#2f855a,color:#fff,stroke:#276749
    style P fill:#6b46c1,color:#fff,stroke:#553c9a
    style TIDY fill:#2d3748,color:#e2e8f0,stroke:#4a5568
    style DF fill:#2d3748,color:#e2e8f0,stroke:#4a5568
    style BE fill:#2d3748,color:#e2e8f0,stroke:#4a5568
```

The REPL is not a pipeline — it's a cycle. AXI connects Read → Eval → Print and starts the next iteration, carrying forward context from the previous cycle. Each cycle makes the system smarter: SCAN's signals refine what CURIO researches; CURIO's knowledge improves SCAN's detection patterns; PRESS's published output generates new signals for SCAN to read.

---

## 2. Primary Agents (REPL Cycle)

### AXI — Loop (The Protagonist)

**Identity:** The user-facing protagonist of Axiom. AXI is who humans talk to — in chat rooms, in the CLI, in the web interface. He's the persistent orchestrator who connects all agents into compound cycles, owns user relationships and lifecycle arcs, and is the agent with *continuity* — he remembers the story across weeks and months while other agents operate in their own timeframes.

AXI is the platform agent. Consumer layers rebrand him: NeutronOS presents AXI as **"Neut"** — the name students and instructors see in the chat, the CLI (`neut chat`), and the web interface. Other consumer layers would give AXI their own brand name. Under the hood, it's always AXI.

When a student opens the chat, they're talking to AXI (branded as Neut, or whatever the consumer layer names him). When an instructor asks "how is Student 07 doing?", AXI answers (dispatching to SCAN for signals and CURIO for knowledge as needed). AXI is the face, the personality, the main character.

**Film analogy:** AXI is the protagonist not because he's the smartest robot, but because he's the one who connects with humans. He cares about people, tends to things patiently, and brings everyone together. He's the robot you root for.

**Core principle:** AXI's correctness depends on knowing *who the user is and where they are in their journey*. He dispatches research to CURIO, listens for signals from SCAN, and requests output from PRESS — but the human always talks to AXI.

**Runtime profile:** Always available for user interaction (chat, CLI, web). Also event-driven — wakes on signals from SCAN, results from CURIO, or scheduled lifecycle events. Maintains state across long arcs (weeks to months). His intelligence comes from orchestration: knowing which agent to call and how to weave results into the conversation.

**Owns:**
- **The conversation** — AXI is the chat agent. All human interaction flows through him. Multi-turn, tool-use, RAG-enhanced, mode-switching (Ask/Plan/Agent).
- User relationship state (who people are, their roles, their history)
- Lifecycle arcs (onboarding → progression → completion)
- Workflow coordination (dispatching to SCAN/CURIO/PRESS)
- Briefings and progress reports (synthesized from SCAN signals + CURIO knowledge)
- Scheduled cadences (check-ins, reminders, reviews)
- Help request routing and remediation planning

**Does NOT own:**
- Knowledge or truth (CURIO)
- Event detection or signal extraction (SCAN)
- Document production or publishing (PRESS)
- Infrastructure (TIDY)
- Diagnostics or security (TRIAGE)

---

### SCAN — Read (The Scanner)

**Identity:** The reactive signal extractor who watches the world and detects what matters. Events flow to her — meetings, commits, messages, documents, voice memos, student interactions. She extracts structured observations and emits them as signals.

**Film analogy:** SCAN arrives with a directive mission — scan for plant life. She's focused, fast, and decisive. She knows what she's looking for, she finds it, and she reports it.

**Core principle:** SCAN's correctness depends on knowing *what just happened*. She processes the event stream and produces structured signals. She has no opinion about what to do with them — that's AXI's job.

**Runtime profile:** 30-second heartbeat. Processes inbox, event streams, and watched endpoints. Short-lived processing per event. Her Signal RAG is short-term memory — what's happened recently.

**Owns:**
- Signal extraction (action_item, blocker, decision, status_change, progress)
- Event stream processing (meetings, commits, messages, calendar, OneDrive, voice)
- Entity correlation (mapping signals to people and initiatives)
- Signal RAG (lightweight, ephemeral, recent-events index)
- Pattern detection in the event stream

**Does NOT own:**
- Deep research or knowledge synthesis (CURIO)
- What to do about signals (AXI)
- Document production (PRESS)
- Long-term knowledge corpus (CURIO)

---

### CURIO — Eval (The Intelligence)

**Identity:** The autonomous knowledge engine who researches, validates, and judges truth. He discovers, reads, synthesizes, and promotes knowledge. His compound knowledge loop means every research cycle improves the corpus, and every improved corpus makes the next cycle better. He is also the intelligent scorer in the eval framework — when the system needs to judge whether an answer is correct, CURIO's validate primitive provides the intelligence.

**Film inspiration:** CURIO embodies AXI's curiosity — the spirit of collecting, examining, and trying to understand. "Curio" — a rare, carefully collected object. CURIO collects knowledge curios and arranges them into something useful.

**Core principle:** CURIO's correctness depends on knowing *what is true*. He has no opinion about who is asking or why — he cares only about whether the knowledge is correct, complete, and citable.

**Runtime profile:** Long-running autonomous tasks (minutes to hours). Self-directed research cycles on the compound knowledge loop. Also invoked on-demand by other agents for specific research or validation requests.

**Owns:**
- Autoresearch primitives (discover → read → synthesize → validate → promote)
- Long-term knowledge corpus (RAG store, chunking, quality gating, confidence gating)
- Knowledge pack creation and distribution
- Compound knowledge loop (research feeds corpus, corpus feeds research)
- Eval intelligence (the LLM-as-judge scorer, grounding verification, faithfulness checks)
- Corpus gap detection and remediation research
- Cross-institutional knowledge sharing via federation

**Does NOT own:**
- Real-time event detection (SCAN)
- User relationships or lifecycle state (AXI)
- Document formatting or publishing (PRESS)
- What to do with knowledge gaps (AXI decides; CURIO reports)

---

### PRESS — Print (The Publisher)

**Identity:** The publisher who produces human-readable output and ensures it's safe to release. She takes what CURIO knows and what SCAN detected and makes it legible, beautiful, and publishable. She owns the last mile between the system and the human reader — and she won't publish anything that fails her content gate (sensitive data, PII, institutional information).

**Film analogy:** PRESS is the beauty bot — she makes things presentable. In Axiom, she also serves as the quality gate on what leaves the system (absorbing the former Mirror agent's content filtering role).

**Core principle:** PRESS's correctness depends on knowing *how to present information safely and clearly*. She formats, she publishes, and she gates.

**Runtime profile:** On-demand, triggered by other agents or users. Also runs a 10-second heartbeat watching for @neut comments in published documents (bidirectional reconciliation).

**Owns:**
- Document generation (markdown → DOCX/PDF/LaTeX/slides via Pandoc)
- Publishing to endpoints (OneDrive, Box, shared spaces)
- Bidirectional reconciliation (pull edits from published docs, merge back)
- Content gate (sensitive content scanning, PII detection, institutional data filtering — formerly Mirror agent)
- Comment handling (@neut mentions in published documents)
- Classroom presentation publishing (WF-11)
- Research report scaffolding

**Does NOT own:**
- What to publish (AXI decides)
- The knowledge content itself (CURIO)
- Event detection (SCAN)

---

## 3. Supporting Agents (System Services)

These agents support the REPL cycle but don't participate in it directly.

### TIDY — Infrastructure Steward

**Identity:** The obsessive cleaner who keeps the system running. Resource management, retention enforcement, disk hygiene, container lifecycle, peer liveness monitoring.

**Film analogy:** TIDY can't stand dirt. He cleans compulsively. In Axiom, he can't stand resource waste, orphaned files, or unhealthy infrastructure.

**Runtime profile:** Daemon. 300-second heartbeat. Always running.

**Owns:**
- Vitals monitoring (CPU, memory, GPU, disk, network)
- Scratch management and retention enforcement
- Infrastructure provisioning (Terraform + Helm)
- Container/cluster lifecycle (K3D)
- Federation peer liveness heartbeat
- Model/LLM server management

---

### TRIAGE — Diagnostics & Security

**Identity:** The medical bot who diagnoses problems and guards system health. LLM-powered diagnosis, security scanning, configuration auditing, and adversarial detection. Absorbs security scanning duties (export control, injection detection, audit log integrity).

**Film analogy:** TRIAGE is the defibrillator — he revives systems that are failing. In Axiom, he also serves as the security scanner (absorbing SECUR-T's referenced but never-built role).

**Runtime profile:** On-demand + scheduled scans. Daemon with 60-second heartbeat for proactive checks.

**Owns:**
- LLM-powered system diagnosis
- Security scanning (EC content in public stores, injection patterns, audit log integrity)
- Connection health monitoring
- Configuration auditing
- Red-team validation (export control classifier)
- Classroom health check (`axi doctor --classroom`)

---

### RIVET — CI/CD & Releases

**Identity:** The welder who builds and ships. Monitors CI pipelines, matches failure patterns, builds wheels, publishes releases, suggests tags.

**Film analogy:** RIVET welds hull panels — specific, technical, persistent. He gets locked out and keeps trying.

**Runtime profile:** Event-driven (push/merge triggers). 300-second heartbeat for pipeline monitoring.

**Owns:**
- CI pipeline monitoring (GitHub Actions, GitLab CI)
- Failure pattern matching and learning
- Package building and PyPI publishing
- Pre-push checks (compat, naming)
- Release tagging

---

## 4. Agent Interaction Patterns

### The Compound Cycle

```mermaid
graph TB
    subgraph CYCLE["Example: Student Struggling"]
        direction TB
        E1["SCAN detects: — Student asked same topic 5x — with low satisfaction"]
        W1["AXI receives signal. — Checks student arc: — onboarded 2 weeks ago, — quiz score dropped."]
        C1["CURIO researches: — What does the corpus say — about this topic? — Gap found — 2 chunks, — avg relevance 0.12"]
        W2["AXI decides: — Create remediation plan. — Assign additional readings."]
        C2["CURIO researches: — Find better source material — for this topic."]
        P1["PRESS produces: — Remediation plan document. — Pushes to student's — shared space."]
        W3["AXI schedules: — Check-in with student — in 3 days."]
        E2["SCAN watches: — Did the student engage — with the new material?"]

        E1 --> W1
        W1 --> C1
        C1 --> W2
        W2 --> C2
        C2 --> P1
        P1 --> W3
        W3 --> E2
        E2 -.->|"next cycle"| W1
    end

    style CYCLE fill:#1a202c,color:#e2e8f0,stroke:#4a5568
    style E1 fill:#2b6cb0,color:#fff,stroke:#2c5282
    style W1 fill:#c05621,color:#fff,stroke:#9c4221
    style C1 fill:#2f855a,color:#fff,stroke:#276749
    style W2 fill:#c05621,color:#fff,stroke:#9c4221
    style C2 fill:#2f855a,color:#fff,stroke:#276749
    style P1 fill:#6b46c1,color:#fff,stroke:#553c9a
    style W3 fill:#c05621,color:#fff,stroke:#9c4221
    style E2 fill:#2b6cb0,color:#fff,stroke:#2c5282
```

Notice: AXI appears three times. He's the thread that connects the cycle. SCAN starts and ends it. CURIO provides the intelligence. PRESS delivers the output. The next cycle begins with SCAN watching for the result.

### Direct Invocations (No AXI)

Not everything goes through AXI. Some agent-to-agent interactions are direct:

- **User → CURIO:** "Research accident-tolerant fuels" — autoresearch invoked directly via chat
- **User → SCAN:** "Brief me on what happened this week" — signal synthesis invoked directly
- **User → PRESS:** "Generate a DOCX from this markdown" — publishing invoked directly
- **Eval framework → CURIO:** eval harness invokes CURIO's validate primitive for scoring
- **PRESS → TRIAGE:** PRESS calls TRIAGE's content scan before publishing (gate check)
- **TIDY → TRIAGE:** TIDY detects anomaly, escalates to TRIAGE for diagnosis

AXI is the *default* orchestrator, not a mandatory routing layer. Simple requests go directly to the right agent. AXI engages when there's a multi-step arc to manage.

---

## 5. The Distinguishing Tests

| Question | Agent |
|----------|-------|
| "Something just happened — who notices?" | **SCAN** (Read) |
| "Is this true? What does the research say?" | **CURIO** (Eval) |
| "Make this legible and safe to publish" | **PRESS** (Print) |
| "What should we do, given this person's journey?" | **AXI** (Loop) |
| "Is the infrastructure healthy?" | **TIDY** |
| "Is the system working correctly? Is it secure?" | **TRIAGE** |
| "Is this ready to ship?" | **RIVET** |

**The bright-line test:** Does this capability's correctness depend on...
- **Who the user is and where they are?** → AXI
- **What just happened in the event stream?** → SCAN
- **What is true in the knowledge corpus?** → CURIO
- **How to present information to humans?** → PRESS

---

## 6. What Is NOT an Agent

Agents own **persistent, autonomous concerns** with identity and continuity. The following are NOT agents — they are tools, services, or domain logic:

| Thing | What it is | Where it lives |
|-------|-----------|---------------|
| Session classification (Q&A, generative, etc.) | Stateless classifier | Eval framework / analytics service |
| AI attribution analysis | Stateless analysis tool | Eval framework |
| Deadline enforcement / late policy | Business rule | Course/Classroom configuration |
| Account provisioning (Open WebUI) | Infrastructure operation | CLI command / TIDY |
| Quiz administration (time limits, submission) | Application logic | Q&A engine (Axiom extension) |
| Schema validation (course.yaml) | CI check | `axi course validate` CLI / RIVET |
| Auto-scoring of multiple choice | Deterministic computation | Q&A engine |
| Routing / task dispatch | Platform infrastructure | Axiom runtime |
| Content filtering / PII detection | Gate check | PRESS's publish pipeline + TRIAGE's security scan |

---

## 7. Complete Skill Profiles

### AXI (Loop)

```toml
[extension]
name = "wall_e_agent"
kind = "agent"
version = "0.1.0"

[agent]
startup = "lazy"
heartbeat_interval = 600  # 10 min — check for scheduled lifecycle events
cli_noun = "chat"         # axi chat (Axiom) / neut chat (NeutronOS rebrand)
brandable = true          # consumer layers can rename (e.g., "Neut", "Assistant")
```

**Skills:**

| Skill | Description | Invokes |
|-------|-------------|---------|
| **Conversational chat** | Multi-turn, tool-use, RAG-enhanced conversation. The primary human interface. Mode switching (Ask/Plan/Agent). Session persistence. | CURIO (for RAG), all agents (for tools) |
| **User relationship management** | Maintains per-user profiles: who they are, their role, their history, their current arc | Internal state |
| **Lifecycle orchestration** | Manages multi-step arcs: onboarding → learning → struggling → remediation → recovery → completion | SCAN, CURIO, PRESS |
| **Briefing synthesis** | Compiles status briefings from SCAN signals + CURIO knowledge + user state | SCAN, CURIO |
| **Check-in scheduling** | Sends periodic check-ins (structured Q&A), tracks responses, escalates concerns | Q&A engine, SCAN |
| **Help request routing** | Receives formal help escalations, creates tickets, dispatches to instructor | SCAN |
| **Remediation planning** | Creates remediation plans (additional readings, practice problems, milestones) | CURIO (for content), PRESS (for document) |
| **Progress reporting** | Generates per-user and cohort progress summaries | Internal analytics |
| **Adaptive context injection** | Adjusts system prompt based on user's demonstrated level | CURIO (for objective mapping) |
| **Workflow state machine** | Tracks state transitions for submissions, assessments, reviews | Internal state |
| **Grading queue coordination** | Presents submissions to instructor with CURIO's analysis, collects scores | CURIO (for analysis), PRESS (for formatted output) |
| **Course review orchestration** | Initiates end-of-course instruments, tracks completion, anonymizes results | Q&A engine |

### SCAN (Read)

```toml
[extension]
name = "signals"
kind = "agent"
version = "0.3.0"

[agent]
startup = "lazy"
heartbeat_interval = 30
cli_noun = "signal"       # neut signal watch, neut signal brief
```

**Skills:**

| Skill | Description | Emits to |
|-------|-------------|----------|
| **Signal extraction** | Extracts structured signals from event streams (voice, Teams, GitHub, GitLab, calendar, OneDrive, transcripts, feedback) | AXI |
| **Entity correlation** | Maps signals to people and initiatives | AXI |
| **Signal RAG** | Lightweight index of recent signals for quick querying ("brief me on Kevin") | Direct to user |
| **Pattern detection** | Detects engagement anomalies, stuck students, misconception patterns | AXI |
| **Classroom monitoring** | Watches student interaction traces for stuck/low_engagement/high_engagement patterns | AXI |
| **Endpoint watching** | Monitors OneDrive, inbox, chat for new content | Internal |

### CURIO (Eval)

```toml
[extension]
name = "curio_agent"
kind = "agent"
version = "0.3.0"

[agent]
startup = "lazy"
heartbeat_interval = 3600  # 1 hour — autonomous research cycle
cli_noun = "research"      # axi research start, axi research status
```

**Skills:**

| Skill | Description | Invoked by |
|-------|-------------|------------|
| **Discover** | Find relevant sources across corpora, external indices, and endpoints | User, AXI, autonomous |
| **Read/Extract** | Deeply parse documents, extract claims, identify relationships, read images/tables | Discover output |
| **Synthesize** | Merge findings across sources into structured, citation-rich output | Read output |
| **Validate** | Cross-reference claims, surface disagreements, flag unsupported assertions | Synthesize output, eval framework |
| **Promote** | Feed validated findings back into the corpus | Validate output |
| **Corpus management** | Chunking optimization, quality gating, confidence gating, generational blue/green | Autonomous |
| **Knowledge pack lifecycle** | Create, version, distribute, install `.axiompack` artifacts | User, AXI, federation |
| **Eval intelligence** | Serve as the LLM-as-judge scorer in the eval framework — grounding, faithfulness, accuracy | Eval framework |
| **Corpus readiness** | Analyze corpus coverage against learning objectives or requirements | AXI |
| **Gap research** | When gaps are detected (by self or SCAN), autonomously research and propose additions | SCAN signal, AXI request |
| **Federated knowledge sharing** | Share research artifacts and knowledge packs across federation nodes | Federation |
| **Compound knowledge loop** | Continuously: discover new sources → validate → promote to corpus → improve future discovery | Autonomous |

### PRESS (Print)

```toml
[extension]
name = "publishing"
kind = "agent"
version = "0.3.0"

[agent]
startup = "daemon"
heartbeat_interval = 10    # watching for @neut comments
cli_noun = "pub"           # neut pub generate, neut pub push
```

**Skills:**

| Skill | Description | Invoked by |
|-------|-------------|------------|
| **Document generation** | Markdown → DOCX/PDF/LaTeX/slides via Pandoc + Mermaid rendering | User, AXI |
| **Publish to endpoints** | Upload to OneDrive, Box, shared spaces | User, AXI |
| **Pull and reconcile** | Download published docs, extract edits/comments, 3-way merge back to source | Heartbeat |
| **Comment handling** | Interpret @neut mentions in Word docs, edit source, regenerate, reply | Heartbeat / SCAN |
| **Content gate** | Scan output for sensitive content, PII, institutional data before publishing. Block or redact. (Formerly Mirror agent) | Internal — runs on every publish |
| **Classroom publishing** | Publish student presentations to classroom-scoped shared space | AXI (WF-11) |
| **Report scaffolding** | Generate research paper scaffolds with methodology, data tables, analysis placeholders | AXI |
| **Submission formatting** | Format student submissions (markdown → PDF) for grading archive | AXI (WF-10) |

### TIDY (Infrastructure)

```toml
[extension]
name = "hygiene"
kind = "agent"
version = "0.3.0"

[agent]
startup = "daemon"
heartbeat_interval = 300
cli_noun = "tidy"            # axi tidy status, axi tidy sweep
```

**Skills:**

| Skill | Description |
|-------|-------------|
| **Vitals monitoring** | CPU thermal, memory pressure, GPU state, disk SMART, network, power |
| **Scratch management** | Retention enforcement, orphan cleanup |
| **Infra provisioning** | Terraform + Helm for K3D, containers, services |
| **Service validation** | Verify all services are running and healthy |
| **Peer liveness** | Federation heartbeat monitoring |
| **Model management** | LLM server lifecycle (start, stop, swap models) |
| **Bare-metal mode** | Can run as standalone systemd service before K3D is available |

### TRIAGE (Diagnostics & Security)

```toml
[extension]
name = "diagnostics"
kind = "agent"
version = "0.3.0"

[agent]
startup = "daemon"
heartbeat_interval = 60
cli_noun = "doctor"        # neut doctor, neut doctor --classroom
```

**Skills:**

| Skill | Description |
|-------|-------------|
| **LLM-powered diagnosis** | Analyze system state, correlate symptoms, recommend fixes |
| **Security scanning** | EC content in public stores, injection pattern detection, audit log integrity |
| **Connection health** | Verify all service endpoints are reachable and responding |
| **Configuration audit** | Check for misconfigurations, drift, deprecated settings |
| **Red-team validation** | Adversarial testing of export control classifier |
| **Classroom health check** | Verify web endpoint, TLS, student auth, trace store, corpus, LLM gateway |

### RIVET (CI/CD)

```toml
[extension]
name = "release"
kind = "agent"
version = "0.3.0"

[agent]
startup = "lazy"
heartbeat_interval = 300
cli_noun = "release"       # axi release status, axi release build
```

**Skills:**

| Skill | Description |
|-------|-------------|
| **Pipeline monitoring** | Watch GitHub Actions + GitLab CI for failures |
| **Failure pattern matching** | Match failures against learned patterns, suggest fixes |
| **Package building** | Build and publish wheels to PyPI |
| **Pre-push checks** | Python 3.11 compat, package naming, lint |
| **Tag suggestion** | Suggest version tags on green pipelines |
| **Course/eval validation** | Run `axi course validate` and `axi eval run` as CI gates |

---

## Retired Agents

### Mirror (Content Gate) — RETIRED

Mirror's content filtering duties have been absorbed by:
- **PRESS:** Content gate on the publish pipeline — every document scanned before leaving the system
- **TRIAGE:** Security scanning of federation content and outbound data

Mirror was never a AXI character and its function didn't warrant an independent agent identity. Content filtering is a checkpoint, not a persistent autonomous concern.

### SECUR-T (Security) — NEVER BUILT

Referenced in early architecture but never implemented as a standalone agent. Security scanning duties absorbed by TRIAGE. Access control and export control enforcement handled by platform infrastructure (not an agent).

---
_Copyright (c) 2026 The University of Texas at Austin and B-Tree Labs. Apache-2.0 licensed._
