# asi-rishi/boros architecture

> Architecture diagram of the GitHub repository asi-rishi/boros, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asi-rishi/boros
- Repository: https://github.com/asi-rishi/boros

## Overview

1. **Repository purpose**
   - This is a self-modifying agent framework called **Boros/ARES**.
   - The core idea is a tiny Python kernel that boots a set of modular “skills,” then repeatedly runs an **evolution loop** to improve its own code, tools, and policies.

2. **Top-level runtime boundary**
   - The main execution entry points are `kernel.py`, `agent_loop.py`, and supporting orchestration code.
   - The kernel is intentionally thin: it loads the manifest, initializes skills, and routes tool/function calls. Most behavior lives in skills, not in the kernel.

3. **Boot configuration and system contract**
   - `manifest.json`, `config.json`, and `world_model.json` define the runtime mode, LLM setup, boot order, and scoring targets.
   - `world_model.json` is the externalized definition of “better,” while `config.json` controls operational limits like cycle duration and snapshot retention.
   - These files act as the system’s policy/config layer and are treated as high-value, mostly read-only inputs.

4. **Skill architecture**
   - The `skills/` directory is the main evolvable surface.
   - Each skill is a self-contained module with:
     - a `skill.json` manifest,
     - a `SKILL.md` description,
     - Python `functions/`,
     - optional `state/` and `metrics/`.
   - Skills are grouped by responsibility: boot-time infrastructure, demand-loaded capabilities, and meta-control.

5. **Core boot-time skills**
   - The boot set includes identity, mode control, temporal awareness, memory, skill routing, context orchestration, reflection, meta-evolution, meta-evaluation, and loop orchestration.
   - These form the control plane: they decide what mode Boros is in, what context to load, how to track time and state, and how to initiate improvement cycles.

6. **Demand-loaded operational skills**
   - Additional skills provide actual work capability: tool use, communication, reasoning, web research, mission control, scratchpad, eval bridge, and skill forge.
   - These are the execution plane: terminal/file operations, structured reasoning, remote research, task queueing, and code mutation.
   - The architecture separates “control” from “capability,” which is important for understanding boundaries in a diagram.

7. **State and memory subsystem**
   - Persistent runtime state is spread across `memory/`, `session/`, `logs/`, and some skill-local `state/` directories.
   - `memory/` holds evolution records, experiences, score history, and session scratchpad data.
   - `session/` tracks the current cycle, loop state, hypotheses, and proposals.
   - The memory system is explicitly file-backed and acts as the system’s long-term learning store.

8. **Evolution loop and feedback path**
   - Boros runs a recurring **REFLECT → EVOLVE → EVAL** loop.
   - Reflection consumes memory and recent failures to generate a hypothesis or target.
   - Evolution uses the skill forge to modify code and skill definitions.
   - Evaluation pushes the current build into an external eval pipeline, then feeds scores back into memory and high-water-mark tracking.
   - This is the core closed loop to show in any architecture diagram.

9. **Skill Forge and rollback boundary**
   - The skill forge is the mutation boundary for self-editing.
   - It snapshots code, applies diffs, validates changes, and can roll back on failure or regression.
   - The `snapshots/` directory contains preserved states of prior skill implementations, showing that the system treats its own codebase as versioned, reversible infrastructure.

10. **Meta-evaluation and scoring**
   - Meta-evaluation is an independent review layer that judges proposed changes before they are merged.
   - Scores are tracked per category, with regression protection and high-water marks.
   - The scoring artifacts live in `eval-generator/scoring/`, `memory/score_history.jsonl`, and related state files.
   - This creates a separate quality-control boundary from the main agent loop.

11. **External eval generator and sandboxes**
   - `eval-generator/` is a distinct subsystem that creates executable evaluation tasks, runs them in isolated sandboxes, and stores generated tests, logs, and results.
   - The `eval-generator/sandboxes/` tree shows many task-specific workspaces with scripts, input/output files, and logs.
   - This is the external capability-testing harness; it is not just prompt scoring, but execution-based verification.

12. **Provider adapters**
   - `adapters/` contains model/provider integration code for Anthropic, OpenAI, Gemini, Ollama, and OpenAI-compatible endpoints.
   - These adapters are the boundary between Boros and its LLM substrates.
   - The readme indicates Claude is typically the primary agent model, while GPT-family models are used for meta-evaluation and eval generation.

13. **Commands, missions, and human interaction**
   - `commands/`, `session/proposals/`, and `mission-control` support queued directives and operator interaction.
   - The system distinguishes between live autonomous cycles and queued work instructions such as task submission, pause/resume, rollback, and mode switching.
   - This is the human/control interface boundary rather than the intelligence core.

14. **Where to draw the diagram boundaries**
   - A clear diagram should show:
     - **Kernel/orchestrator** in the center,
     - **skills** as modular capability nodes,
     - **memory/session/logs** as persistent state stores,
     - **LLM/provider adapters** as external model dependencies,
     - **eval-generator** as an isolated external validation system,
     - **snapshots/rollbacks** as the safety/recovery layer.
   - The dominant data flow is: configuration and memory into reflection, proposed code changes into forge, executed evals into scored results, and scores back into memory and session state.

Main entry points: [`skills/skill-router`](https://github.com/asi-rishi/boros/tree/master/skills/skill-router) (Skill router), [`skills/eval-bridge`](https://github.com/asi-rishi/boros/tree/master/skills/eval-bridge) (Eval bridge), [`agent_loop.py`](https://github.com/asi-rishi/boros/blob/master/agent_loop.py) (Agent loop), [`session`](https://github.com/asi-rishi/boros/tree/master/session) (Session store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_kernel["Kernel<br/>[kernel.py]"]
  node_agent_loop["Agent loop<br/>orchestrator loop<br/>[agent_loop.py]"]
  node_manifest["Manifest<br/>boot contract<br/>[manifest.json]"]
  node_config["Config<br/>[config.json]"]
  node_world_model["World model<br/>scoring policy<br/>[world_model.json]"]
  node_tool_schemas["Tool schemas<br/>tool contract<br/>[tool_schemas.py]"]
end

subgraph group_skills["Skills"]
  node_skill_router["Skill router<br/>control skill"]
  node_context_orch["Context load<br/>control skill"]
  node_mode_controller["Mode control<br/>control skill"]
  node_temporal["Time sense<br/>control skill"]
  node_memory_skill["Memory<br/>control skill"]
  node_reflection["Reflection<br/>control skill"]
  node_meta_eval["Meta-eval<br/>review skill"]
  node_meta_evolve["Meta-evolve<br/>mutation skill"]
  node_skill_forge["Forge<br/>mutation boundary"]
  node_tool_use["Tool use<br/>execution skill"]
  node_web_research["Web research<br/>execution skill"]
  node_reasoning["Reasoning<br/>execution skill"]
  node_comms["Communication<br/>execution skill"]
  node_mission_control["Mission control<br/>execution skill"]
  node_scratchpad["Scratchpad<br/>working memory"]
  node_eval_bridge["Eval bridge<br/>eval skill"]
  node_identity["Identity<br/>control skill"]
end

subgraph group_state["State"]
  node_memory_store[("Memory store<br/>persistent state")]
  node_session_store[("Session store<br/>cycle state")]
  node_logs[("Logs")]
  node_commands["Commands<br/>operator queue"]
end

subgraph group_eval["Evaluation"]
  node_eval_gen["Eval generator<br/>external eval system<br/>[eval_generator.py]"]
  node_scoring[("Scoring<br/>eval outputs")]
  node_sandboxes[("Sandboxes<br/>task workspaces")]
end

subgraph group_safety["Recovery"]
  node_snapshots[("Snapshots<br/>recovery store")]
end

subgraph group_providers["Providers"]
  node_adapters["Adapters"]
end

node_kernel -->|"boot"| node_manifest
node_kernel -->|"init"| node_context_orch
node_kernel -->|"route tools"| node_skill_router
node_agent_loop -->|"reflect"| node_reflection
node_agent_loop -->|"evolve"| node_meta_evolve
node_agent_loop -->|"evaluate"| node_eval_bridge
node_manifest -->|"policy"| node_mode_controller
node_config -->|"limits"| node_agent_loop
node_world_model -->|"target"| node_reflection
node_tool_schemas -->|"contracts"| node_skill_router
node_skill_router -->|"expose"| node_tool_use
node_skill_router -->|"expose"| node_comms
node_skill_router -->|"expose"| node_reasoning
node_skill_router -->|"expose"| node_web_research
node_skill_router -->|"expose"| node_mission_control
node_context_orch -->|"load"| node_memory_store
node_context_orch -->|"hydrate"| node_session_store
node_reflection -->|"read/write"| node_memory_store
node_reflection -->|"update"| node_session_store
node_meta_eval -->|"review"| node_session_store
node_meta_evolve -->|"mutate"| node_skill_forge
node_skill_forge -->|"snapshot"| node_snapshots
node_skill_forge -->|"record"| node_logs
node_eval_bridge -->|"request"| node_eval_gen
node_eval_gen -->|"run"| node_sandboxes
node_eval_gen -->|"write"| node_scoring
node_eval_bridge -->|"read scores"| node_scoring
node_eval_bridge -->|"persist"| node_memory_store
node_eval_bridge -->|"high water"| node_session_store
node_mode_controller -->|"control"| node_commands
node_mission_control -->|"queue"| node_commands
node_identity -->|"state"| node_session_store
node_adapters -->|"models"| node_agent_loop

click node_kernel "https://github.com/asi-rishi/boros/blob/master/kernel.py"
click node_agent_loop "https://github.com/asi-rishi/boros/blob/master/agent_loop.py"
click node_manifest "https://github.com/asi-rishi/boros/blob/master/manifest.json"
click node_config "https://github.com/asi-rishi/boros/blob/master/config.json"
click node_world_model "https://github.com/asi-rishi/boros/blob/master/world_model.json"
click node_tool_schemas "https://github.com/asi-rishi/boros/blob/master/tool_schemas.py"
click node_skill_router "https://github.com/asi-rishi/boros/tree/master/skills/skill-router"
click node_context_orch "https://github.com/asi-rishi/boros/tree/master/skills/context-orchestration"
click node_mode_controller "https://github.com/asi-rishi/boros/tree/master/skills/mode-controller"
click node_temporal "https://github.com/asi-rishi/boros/tree/master/skills/temporal-consciousness"
click node_memory_skill "https://github.com/asi-rishi/boros/tree/master/skills/memory"
click node_reflection "https://github.com/asi-rishi/boros/tree/master/skills/reflection"
click node_meta_eval "https://github.com/asi-rishi/boros/tree/master/skills/meta-evaluation"
click node_meta_evolve "https://github.com/asi-rishi/boros/tree/master/skills/meta-evolution"
click node_skill_forge "https://github.com/asi-rishi/boros/tree/master/skills/skill-forge"
click node_tool_use "https://github.com/asi-rishi/boros/tree/master/skills/tool-use"
click node_web_research "https://github.com/asi-rishi/boros/tree/master/skills/web-research"
click node_reasoning "https://github.com/asi-rishi/boros/tree/master/skills/reasoning"
click node_comms "https://github.com/asi-rishi/boros/tree/master/skills/communication"
click node_mission_control "https://github.com/asi-rishi/boros/tree/master/skills/mission-control"
click node_scratchpad "https://github.com/asi-rishi/boros/tree/master/skills/scratchpad"
click node_eval_bridge "https://github.com/asi-rishi/boros/tree/master/skills/eval-bridge"
click node_identity "https://github.com/asi-rishi/boros/tree/master/skills/identity"
click node_eval_gen "https://github.com/asi-rishi/boros/blob/master/eval-generator/eval_generator.py"
click node_scoring "https://github.com/asi-rishi/boros/tree/master/eval-generator/scoring"
click node_sandboxes "https://github.com/asi-rishi/boros/tree/master/eval-generator/sandboxes"
click node_memory_store "https://github.com/asi-rishi/boros/tree/master/memory"
click node_session_store "https://github.com/asi-rishi/boros/tree/master/session"
click node_logs "https://github.com/asi-rishi/boros/tree/master/logs"
click node_commands "https://github.com/asi-rishi/boros/tree/master/commands"
click node_snapshots "https://github.com/asi-rishi/boros/tree/master/snapshots"
click node_adapters "https://github.com/asi-rishi/boros/tree/master/adapters"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_kernel,node_agent_loop,node_manifest,node_config,node_world_model,node_tool_schemas toneBlue
class node_skill_router,node_context_orch,node_mode_controller,node_temporal,node_memory_skill,node_reflection,node_meta_eval,node_meta_evolve,node_skill_forge,node_tool_use,node_web_research,node_reasoning,node_comms,node_mission_control,node_scratchpad,node_eval_bridge,node_identity toneAmber
class node_memory_store,node_session_store,node_logs,node_commands toneMint
class node_eval_gen,node_scoring,node_sandboxes toneRose
class node_snapshots toneIndigo
class node_adapters toneTeal
```

## Components

### Runtime

Kernel, loop, and boot-time orchestration.

- [Kernel](https://github.com/asi-rishi/boros/blob/master/kernel.py): entry kernel · Thin runtime bootstrapping and tool-call router. · `kernel.py`
- [Agent loop](https://github.com/asi-rishi/boros/blob/master/agent_loop.py): orchestrator loop · Main autonomous cycle driver. · `agent_loop.py`
- [Manifest](https://github.com/asi-rishi/boros/blob/master/manifest.json): boot contract · Runtime mode and boot-order contract. · `manifest.json`
- [Config](https://github.com/asi-rishi/boros/blob/master/config.json): ops config · Operational limits and runtime tuning. · `config.json`
- [World model](https://github.com/asi-rishi/boros/blob/master/world_model.json): scoring policy · Externalized definition of desired progress. · `world_model.json`
- [Tool schemas](https://github.com/asi-rishi/boros/blob/master/tool_schemas.py): tool contract · Schema definitions for callable tools and function routing. · `tool_schemas.py`

### Skills

Modular capability surface split into control and execution skills.

- [Skill router](https://github.com/asi-rishi/boros/tree/master/skills/skill-router): control skill · Resolves available tools and routing budget. · `skills/skill-router`
- [Context load](https://github.com/asi-rishi/boros/tree/master/skills/context-orchestration): control skill · Loads context and manifest for the active cycle. · `skills/context-orchestration`
- [Mode control](https://github.com/asi-rishi/boros/tree/master/skills/mode-controller): control skill · Reads and switches runtime mode. · `skills/mode-controller`
- [Time sense](https://github.com/asi-rishi/boros/tree/master/skills/temporal-consciousness): control skill · Tracks cycle timing and remaining budget. · `skills/temporal-consciousness`
- [Memory](https://github.com/asi-rishi/boros/tree/master/skills/memory): control skill · Pages archival memory in and out and searches stored experience. · `skills/memory`
- [Reflection](https://github.com/asi-rishi/boros/tree/master/skills/reflection): control skill · Analyzes traces and writes hypotheses for the next improvement step. · `skills/reflection`
- [Meta-eval](https://github.com/asi-rishi/boros/tree/master/skills/meta-evaluation): review skill · Reviews proposals and maintains criteria and verdicts. · `skills/meta-evaluation`
- [Meta-evolve](https://github.com/asi-rishi/boros/tree/master/skills/meta-evolution): mutation skill · Proposes, applies, validates, and rolls back self-edits. · `skills/meta-evolution`
- [Forge](https://github.com/asi-rishi/boros/tree/master/skills/skill-forge): mutation boundary · Snapshots, applies diffs, tests, validates, and rolls back skill code. · `skills/skill-forge`
- [Tool use](https://github.com/asi-rishi/boros/tree/master/skills/tool-use): execution skill · Terminal, patching, editing, and process control. · `skills/tool-use`
- [Web research](https://github.com/asi-rishi/boros/tree/master/skills/web-research): execution skill · Search, browse, and archive external sources. · `skills/web-research`
- [Reasoning](https://github.com/asi-rishi/boros/tree/master/skills/reasoning): execution skill · Plan decomposition, option evaluation, and logic checks. · `skills/reasoning`
- [Communication](https://github.com/asi-rishi/boros/tree/master/skills/communication): execution skill · Broadcast and listen for structured communication. · `skills/communication`
- [Mission control](https://github.com/asi-rishi/boros/tree/master/skills/mission-control): execution skill · Queues tasks and tracks mission status. · `skills/mission-control`
- [Scratchpad](https://github.com/asi-rishi/boros/tree/master/skills/scratchpad): working memory · Ephemeral note-taking and temporary working state. · `skills/scratchpad`
- [Eval bridge](https://github.com/asi-rishi/boros/tree/master/skills/eval-bridge): eval skill · Requests evals, reads scores, checks regressions, updates high-water marks. · `skills/eval-bridge`
- [Identity](https://github.com/asi-rishi/boros/tree/master/skills/identity): control skill · Reads and updates system identity. · `skills/identity`

### State

File-backed memory, session, logs, and proposal state.

- [Memory store](https://github.com/asi-rishi/boros/tree/master/memory): persistent state · Evolution records, experiences, score history, and session scratchpad. · `memory`
- [Session store](https://github.com/asi-rishi/boros/tree/master/session): cycle state · Current cycle, loop state, hypotheses, and proposals. · `session`
- [Logs](https://github.com/asi-rishi/boros/tree/master/logs): runtime logs · Cycle and eval logging output. · `logs`
- [Commands](https://github.com/asi-rishi/boros/tree/master/commands): operator queue · Pending commands and queued directives. · `commands`

### Evaluation

External eval generator, scoring, and sandboxed tasks.

- [Eval generator](https://github.com/asi-rishi/boros/blob/master/eval-generator/eval_generator.py): external eval system · Generates executable tests, runs sandboxed tasks, and stores results. · `eval-generator/eval_generator.py`
- [Scoring](https://github.com/asi-rishi/boros/tree/master/eval-generator/scoring): eval outputs · Stored category scores and evaluation artifacts. · `eval-generator/scoring`
- [Sandboxes](https://github.com/asi-rishi/boros/tree/master/eval-generator/sandboxes): task workspaces · Isolated per-eval execution environments and logs. · `eval-generator/sandboxes`

### Recovery

Snapshots and rollback-oriented preservation of prior code.

- [Snapshots](https://github.com/asi-rishi/boros/tree/master/snapshots): recovery store · Versioned snapshots of prior skill implementations. · `snapshots`

### Providers

LLM adapter boundary to external model backends.

- [Adapters](https://github.com/asi-rishi/boros/tree/master/adapters): model adapters · Provider boundary for Anthropic, OpenAI, Gemini, Ollama, and compatible endpoints. · `adapters`

## Connections

- Kernel → Manifest: boot · Loads boot contract and runtime mode.
- Kernel → Context load: init · Initializes context for runtime startup.
- Kernel → Skill router: route tools · Dispatches tool and function calls.
- Agent loop → Reflection: reflect · Uses recent traces and memory to form hypotheses.
- Agent loop → Meta-evolve: evolve · Applies proposed self-changes through the mutation boundary.
- Agent loop → Eval bridge: evaluate · Sends builds to evaluation and ingests scores.
- Manifest → Mode control: policy · Defines runtime mode and boot order.
- Config → Agent loop: limits · Constrains cycle duration and retention.
- World model → Reflection: target · Defines what improvement means.
- Tool schemas → Skill router: contracts · Describes callable tools and routing metadata.
- Skill router → Tool use: expose · Makes execution tools available to the kernel.
- Skill router → Communication: expose · Makes communication tools available.
- Skill router → Reasoning: expose · Makes reasoning tools available.
- Skill router → Web research: expose · Makes research tools available.
- Skill router → Mission control: expose · Makes mission queue tools available.
- Context load → Memory store: load · Pages in persistent context and archives.
- Context load → Session store: hydrate · Loads current session state.
- Reflection → Memory store: read/write · Consumes experiences and stores hypotheses.
- Reflection → Session store: update · Writes current hypothesis for the cycle.
- Meta-eval → Session store: review · Reads proposals and writes verdicts.
- Meta-evolve → Forge: mutate · Delegates code edits, validation, and rollback.
- Forge → Snapshots: snapshot · Preserves prior code before mutation.
- Forge → Logs: record · Logs validation and rollback outcomes.
- Eval bridge → Eval generator: request · Triggers generation and execution of eval tasks.
- Eval generator → Sandboxes: run · Executes isolated task workspaces.
- Eval generator → Scoring: write · Stores generated scoring artifacts.
- Eval bridge → Scoring: read scores · Collects evaluation results.
- Eval bridge → Memory store: persist · Updates score history and learning records.
- Eval bridge → Session store: high water · Maintains regression protection state.
- Mode control → Commands: control · Applies queued operator directives for mode changes.
- Mission control → Commands: queue · Stores pending tasks and status changes.
- Identity → Session store: state · Tracks current identity configuration.
- Adapters → Agent loop: models · Provides LLM backends to the core loop.
